man pages section 1: User Commands

Exit Print View

Updated: July 2014
 
 

zshall (1)

Name

zshall - man page

Synopsis

Please see following description for synopsis

Description




User Commands                                           ZSHALL(1)



NAME
     zshall - the Z shell meta-man page

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

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

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

AUTHOR
     Zsh  was  originally  written  by Paul Falstad <pf@zsh.org>.
     Zsh is now maintained by  the  members  of  the  zsh-workers
     mailing list <zsh-workers@zsh.org>.  The development is cur-
     rently 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.

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

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




zsh 5.0.5          Last change: January 5, 2014                 1






User Commands                                           ZSHALL(1)



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

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

          The up-to-date source code is available  via  anonymous
          CVS  and  Git  from  Sourceforge.   See  http://source-
          forge.net/projects/zsh/  for  details.   A  summary  of
          instructions  for the CVS and Git archives can be found
          at http://zsh.sourceforget.net/.

MAILING LISTS
     Zsh has 3 mailing lists:

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

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

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

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

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

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

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

     The mailing lists are archived; the archives can be accessed
     via the administrative addresses  listed  above.   There  is
     also   a   hypertext   archive,  maintained  by  Geoff  Wing



zsh 5.0.5          Last change: January 5, 2014                 2






User Commands                                           ZSHALL(1)



     <gcw@zsh.org>, available at http://www.zsh.org/mla/.

THE ZSH FAQ
     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>.

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

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

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

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

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

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

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





zsh 5.0.5          Last change: January 5, 2014                 3






User Commands                                           ZSHALL(1)



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

     After  the first one or two arguments have been appropriated
     as 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 corre-
     sponding  letter  `-x' and the SH_WORD_SPLIT option by name.
     Options may be turned off by name by using +o instead of -o.
     -o  can  be stacked up with preceding single-letter options,
     so for example  `-xo  shwordsplit'  or  `-xoshwordsplit'  is
     equivalent to `-x -o shwordsplit'.

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

     The special GNU-style  option  `--version'  is  handled;  it
     sends  to  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  argu-
     ments  that  start  with  `-' or `+' to be treated as normal
     arguments, in two ways.  Firstly, a lone `-' (or `+') as  an



zsh 5.0.5          Last change: January 5, 2014                 4






User Commands                                           ZSHALL(1)



     argument by itself ends option processing.  Secondly, a spe-
     cial option `--' (or `+-'), which may be  specified  on  its
     own  (which  is  the standard POSIX usage) or may be stacked
     with preceding options (so `-x-' is equivalent to `-x  --').
     Options  are  not  permitted  to  be  stacked after `--' (so
     `-x-f' is an error), but note the GNU-style option form dis-
     cussed  above,  where  `--shwordsplit' is permitted and does
     not end option processing.

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

COMPATIBILITY
     Zsh tries to emulate sh or ksh when it is invoked as  sh  or
     ksh respectively; more precisely, it looks at the first let-
     ter of the name by which it was invoked, excluding any  ini-
     tial `r' (assumed to stand for `restricted'), and if that is
     `s' or `k' it will  emulate  sh  or  ksh.   Furthermore,  if
     invoked  as  su  (which  happens on certain systems when the
     shell is executed by the su command), the shell will try  to
     find an alternative name from the SHELL environment variable
     and perform 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,  MANPATH,
     manpath,  path,  prompt,  PROMPT, PROMPT2, PROMPT3, PROMPT4,
     psvar, status, watch.

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

     The  following options are set if the shell is invoked as sh
     or ksh: NO_BAD_PATTERN, NO_BANG_HIST, NO_BG_NICE, NO_EQUALS,
     NO_FUNCTION_ARGZERO,  GLOB_SUBST,  NO_GLOBAL_EXPORT, NO_HUP,
     INTERACTIVE_COMMENTS,  KSH_ARRAYS,  NO_MULTIOS,  NO_NOMATCH,
     NO_NOTIFY,         POSIX_BUILTINS,        NO_PROMPT_PERCENT,
     RM_STAR_SILENT, SH_FILE_EXPANSION,  SH_GLOB,  SH_OPTION_LET-
     TERS,   SH_WORD_SPLIT.    Additionally   the   BSD_ECHO  and
     IGNORE_BRACES options are set  if  zsh  is  invoked  as  sh.
     Also,   the  KSH_OPTION_PRINT,  LOCAL_OPTIONS,  PROMPT_BANG,
     PROMPT_SUBST and SINGLE_LINE_ZLE options are set if  zsh  is
     invoked as ksh.



zsh 5.0.5          Last change: January 5, 2014                 5






User Commands                                           ZSHALL(1)



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

     o    changing directories with the cd builtin

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

     o    specifying command names containing /

     o    specifying command pathnames using hash

     o    redirecting output to files

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

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

     o    using  the  ARGV0  parameter  to  override  argv[0] for
          external commands

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                 6






User Commands                                           ZSHALL(1)



     also   possible   for   a  file  in  $ZDOTDIR  to  re-enable
     GLOBAL_RCS. Both RCS and GLOBAL_RCS are set by default.

     Commands are then read from $ZDOTDIR/.zshenv.  If the  shell
     is  a  login shell, commands are read from /etc/zprofile and
     then $ZDOTDIR/.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.   Files  listed
     above  as being in /etc may be in another directory, depend-
     ing on the installation.

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

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


















zsh 5.0.5          Last change: January 5, 2014                 7






User Commands                                       ZSHROADMAP(1)



NAME
     zshroadmap - informal introduction to the zsh manual

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

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

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

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

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

     A  history  mechanism  for retrieving previously typed lines
     (most simply with the Up or Down arrow keys)  is  available;
     note  that,  unlike  other  shells,  zsh will not save these
     lines when the shell exits unless you set appropriate  vari-
     ables,  and  the number of history lines retained by default
     is quite small (30 lines).  See the description of the shell
     variables  (referred  to in the documentation as parameters)
     HISTFILE, HISTSIZE and SAVEHIST in zshparam(1).

     The shell now supports the UTF-8  character  set  (and  also
     others  if  supported  by  the  operating  system).  This is
     (mostly) handled transparently by the shell, but the  degree
     of support in terminal emulators is variable.  There is some
     discussion  of  this  in  the  shell  FAQ,   http://zsh.dot-
     src.org/FAQ/  .  Note in particular that for combining char-
     acters to be handled the option COMBINING_CHARS needs to  be
     set.  Because the shell is now more sensitive to the defini-
     tion of the character set, note that if  you  are  upgrading
     from  an  older  version of the shell you should ensure that



zsh 5.0.5          Last change: January 5, 2014                 1






User Commands                                       ZSHROADMAP(1)



     the appropriate variable, either LANG (to affect all aspects
     of  the  shell's  operation) or LC_CTYPE (to affect only the
     handling of character sets) is set to an appropriate  value.
     This  is  true even if you are using a single-byte character
     set including extensions of  ASCII  such  as  ISO-8859-1  or
     ISO-8859-15.   See  the  description  of  LC_CTYPE  in  zsh-
     param(1).

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

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

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

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

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

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

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

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




zsh 5.0.5          Last change: January 5, 2014                 2






User Commands                                       ZSHROADMAP(1)



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

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

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

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

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

     **   for matching over multiple directories

     ~, ^ the ability to exclude patterns from matching when  the
          EXTENDED_GLOB option is set

     (...)
          glob  qualifiers, included in parentheses at the end of
          the pattern, which select files by type (such as direc-
          tories) or attribute (such as size).

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

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

PROGRAMMING
     The  most convenient way of adding enhancements to the shell
     is typically by writing a shell function and  arranging  for
     it to be autoloaded.  Functions are described in the section



zsh 5.0.5          Last change: January 5, 2014                 3






User Commands                                       ZSHROADMAP(1)



     `Functions' in zshmisc(1).  Users changing from the C  shell
     and  its  relatives should notice that aliases are less used
     in zsh as they don't  perform  argument  substitution,  only
     simple text replacement.

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

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


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

     zcalc
          a calculator

     zargs
          a version of xargs that makes the find  command  redun-
          dant

     zmv  a  command  for  renaming  files by means of shell pat-
          terns.



ATTRIBUTES
     See  attributes(5)  for  descriptions   of   the   following
     attributes:

     +---------------+------------------+
     |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
     +---------------+------------------+
     |Availability   | shell/zsh        |
     +---------------+------------------+
     |Stability      | Volatile         |
     +---------------+------------------+
NOTES
     This   software   was   built   from   source  available  at
     https://java.net/projects/solaris-userland.   The   original
     community   source   was   downloaded   from    http://down-
     loads.source-
     forge.net/project/zsh/zsh/5.0.5/zsh-5.0.5.tar.bz2

     Further  information about this software can be found on the
     open source community website at http://www.zsh.org/.




zsh 5.0.5          Last change: January 5, 2014                 4






User Commands                                          ZSHMISC(1)



NAME
     zshmisc - everything and then some

SIMPLE COMMANDS & PIPELINES
     A simple command is a sequence of optional parameter assign-
     ments followed by blank-separated words, with optional redi-
     rections interspersed.  The first word is the command to  be
     executed,  and the remaining words, if any, are arguments to
     the command.  If a command  name  is  given,  the  parameter
     assignments modify the environment of the command when it is
     executed.  The value of a simple command is its exit status,
     or  128  plus  the  signal number if terminated by a signal.
     For example,

          echo foo

     is a simple command with arguments.

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

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                 1






User Commands                                          ZSHMISC(1)



     executed.  For example,

          dmesg | grep panic && print yes

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

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

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

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                 2






User Commands                                          ZSHMISC(1)



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

          The -c option clears the environment.

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

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

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

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

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

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

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

          More than one parameter name can appear before the list
          of words.  If N names are given, then on each execution



zsh 5.0.5          Last change: January 5, 2014                 3






User Commands                                          ZSHMISC(1)



          of the loop the next N words are assigned to the corre-
          sponding parameters.  If  there  are  more  names  than
          remaining  words, the remaining parameters are each set
          to the empty string.  Execution of the loop  ends  when
          there is no remaining word to assign to the first name.
          It is only possible for in to appear as the first  name
          in the list, else it will be treated as marking the end
          of the list.

     for (( [expr1] ; [expr2] ; [expr3] )) do list done
          The arithmetic expression expr1 is evaluated first (see
          the  section  `Arithmetic Evaluation').  The arithmetic
          expression expr2 is repeatedly evaluated until it eval-
          uates  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 evalu-
          ated 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  expres-
          sion,  which must evaluate to a number n.  list is then
          executed n times.

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

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

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

          If the list that is executed is terminated with ;|  the
          shell  continues  to  scan the patterns looking for the
          next  match,  executing  the  corresponding  list,  and
          applying  the rule for the corresponding terminator ;;,



zsh 5.0.5          Last change: January 5, 2014                 4






User Commands                                          ZSHMISC(1)



          ;& or ;|.  Note  that  word  is  not  re-expanded;  all
          applicable patterns are tested with the same word.

     select name [ in word ... term ] do list done
          where term is one or more newline or ; to terminate the
          words.  Print the set of words, each preceded by a num-
          ber.   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 interac-
          tive and that is active, or else  standard  input.   If
          this  line  consists of the number of one of the listed
          words, then the parameter name is set to the word  cor-
          responding  to this number.  If this line is empty, the
          selection list is printed again.  Otherwise, the  value
          of  the parameter name is set to null.  The contents of
          the line read from  standard  input  is  saved  in  the
          parameter  REPLY.   list is executed for each selection
          until a break or end-of-file is encountered.

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

     { list }
          Execute list.

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

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

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




zsh 5.0.5          Last change: January 5, 2014                 5






User Commands                                          ZSHMISC(1)



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

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

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

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

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

     function word ... [ () ] [ term ] { list }
     word ... () [ term ] { list }
     word ... () [ term ] command
          where term is one or more newline or ;.  Define a func-
          tion 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  func-
          tion  is the list between the { and }.  See the section
          `Functions'.

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



zsh 5.0.5          Last change: January 5, 2014                 6






User Commands                                          ZSHMISC(1)



     time [ pipeline ]
          The pipeline is executed,  and  timing  statistics  are
          reported on the standard error in the form specified 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  `Con-
          ditional Expressions' for a description of exp.

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

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

          works, but

               if true {  # Does not work!
                 print yes
               }


          does not, since the test is not suitably delimited.

     if list sublist
          A  short  form of the alternate `if'.  The same limita-
          tions on the form of list apply  as  for  the  previous
          form.

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




zsh 5.0.5          Last change: January 5, 2014                 7






User Commands                                          ZSHMISC(1)



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

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

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

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

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

     repeat word sublist
          This is a short form of repeat.

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

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

RESERVED WORDS
     The  following  words  are recognized as reserved words when
     used as the first word of a command unless  quoted  or  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 neither
     the IGNORE_BRACES option nor the IGNORE_CLOSE_BRACES  option
     is set.

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



zsh 5.0.5          Last change: January 5, 2014                 8






User Commands                                          ZSHMISC(1)



     illogical  behaviour  can be recovered by setting the option
     CONTINUE_ON_ERROR.

     Fatal errors found in non-interactive shells include:
     Failure to parse shell options passed when invoking the
          shell
     Failure to change options with the set builtin
     Parse errors of all sorts, including failures to parse
          mathematical expressions
     Failures to set or modify variable behaviour with typeset,
          local, declare, export, integer, float
     Execution of incorrectly positioned loop control structures
          (continue, break)
     Attempts to use regular expression with no regular expres-
          sion
          module available
     Disallowed operations when the RESTRICTED options is set
     Failure to create a pipe needed for a pipeline
     Failure to create a multio
     Failure to autoload a module needed for a declared shell
          feature
     Errors creating command or process substitutions
     Syntax errors in glob qualifiers
     File generation errors where not caught by the option
          BAD_PATTERN
     All bad patterns used for matching within case statements
     File generation failures where not caused by NO_MATCH or
     All file generation errors where the pattern was used to
          create a
          multio
     Memory errors where detected by the shell
     Invalid subscripts to shell variables
     Attempts to assign read-only variables
type
     Logical  errors  with  variables  such as assignment to the
          wrong
     Use of invalid variable names
     Errors in variable substitution syntax
     Failure to convert characters in $'...' expressions
          similar options

     If  the POSIX_BUILTINS option is set, more errors associated
     with shell builtin commands are treated as fatal, as  speci-
     fied by the POSIX standard.

COMMENTS
     In non-interactive 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  up  to  a
     newline to be ignored.




zsh 5.0.5          Last change: January 5, 2014                 9






User Commands                                          ZSHMISC(1)



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

     Alias  expansion is done on the shell input before any other
     expansion except history expansion.  Therefore, if an  alias
     is  defined for the word foo, alias expansion may be avoided
     by quoting part of the word, e.g. \foo.  Any form of quoting
     works,  although  there is nothing to prevent an alias being
     defined for the quoted form such as \foo as well.   For  use
     with  completion,  which  would  remove an initial backslash
     followed by a character that isn't special, it may  be  more
     convenient  to  quote  the  word  by  starting with a single
     quote, i.e. 'foo;  completion  will  automatically  add  the
     trailing single quote.

     There  is a commonly encountered problem with aliases illus-
     trated by the following code:

          alias echobar='echo bar'; echobar

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

     Note  also the unhelpful interaction of aliases and function
     definitions:

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

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

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




zsh 5.0.5          Last change: January 5, 2014                10






User Commands                                          ZSHMISC(1)



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

QUOTING
     A character may be  quoted  (that  is,  made  to  stand  for
     itself)  by preceding it with a `\'.  `\' followed by a new-
     line 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
     `$'.

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

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

     < word
          Open file word for reading as standard input.

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



zsh 5.0.5          Last change: January 5, 2014                11






User Commands                                          ZSHMISC(1)



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

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

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

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

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

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

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

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

     <<< word
          Perform  shell expansion on word and pass the result to
          standard  input.   This  is  known  as  a  here-string.



zsh 5.0.5          Last change: January 5, 2014                12






User Commands                                          ZSHMISC(1)



          Compare  the use of word in here-documents above, where
          word does not undergo shell expansion.

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

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

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

     >& word
     &> word
          (Except where `>& word' matches one of the  above  syn-
          taxes;  `&>'  can  always be used to avoid this ambigu-
          ity.)  Redirects  both  standard  output  and  standard
          error  (file  descriptor  2) in the manner of `> word'.
          Note that this does not have the same effect as `> word
          2>&1'  in  the  presence  of  multios  (see the section
          below).

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

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

     >>&| 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 redirec-
     tions are specified is  significant.   The  shell  evaluates
     each  redirection  in  terms  of the (file descriptor, file)
     association at the time of evaluation.  For example:





zsh 5.0.5          Last change: January 5, 2014                13






User Commands                                          ZSHMISC(1)



          ... 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  redi-
     rections  were  reversed, file descriptor 2 would be associ-
     ated with the terminal (assuming file descriptor 1 had been)
     and  then  file  descriptor  1 would be associated with file
     fname.

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

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

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

          ... {myfd}>&1

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                14






User Commands                                          ZSHMISC(1)



     file descriptor avoids the error.

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

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

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

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

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

          date >foo >bar

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

          date >foo | cat

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

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

          : > *

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





zsh 5.0.5          Last change: January 5, 2014                15






User Commands                                          ZSHMISC(1)



          echo exit 0 >> *.sh

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

          sort <foo <fubar

     or even

          sort <f{oo,ubar}

     is equivalent to `cat foo fubar | sort'.

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

     Note that a pipe is an implicit redirection; thus

          cat bar | sort <foo

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

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

          echo foo > bar > baz

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

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

          cat file >file1 >file2
          cat file1 file2

     Here,  it is possible that the second `cat' will not display
     the full contents of file1 and file2 (i.e. the original con-
     tents 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 par-
     ent  shell  does  not wait for the multios to finish writing
     data.  This means the command as shown can exit before file1
     and  file2  are  completely written.  As a workaround, it is
     possible to run the cat process as part  of  a  job  in  the



zsh 5.0.5          Last change: January 5, 2014                16






User Commands                                          ZSHMISC(1)



     current shell:

          { cat file } >file >file2

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

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

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

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

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

          < file

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

COMMAND EXECUTION
     If a command name contains no slashes, the shell attempts to
     locate it.  If there exists a shell function by  that  name,
     the  function  is invoked as described in the section `Func-
     tions'.  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  program.   The
     shell  will  execute  the specified interpreter on operating
     systems that do not handle this  executable  format  in  the



zsh 5.0.5          Last change: January 5, 2014                17






User Commands                                          ZSHMISC(1)



     kernel.

     If  no  external  command  is  found  but  a  function  com-
     mand_not_found_handler exists the shell executes this  func-
     tion  with  all command line arguments.  The function should
     return status zero if it successfully handled  the  command,
     or  non-zero  status  if  it failed.  In the latter case the
     standard handling is applied: `command not found' is printed
     to standard error and the shell exits with status 127.  Note
     that the handler is executed in a subshell forked to execute
     an  external  command,  hence  changes to directories, shell
     parameters, etc. have no effect on the main shell.

FUNCTIONS
     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 executed like com-
     mands with the arguments passed  as  positional  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
     caller.

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

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

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

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




zsh 5.0.5          Last change: January 5, 2014                18






User Commands                                          ZSHMISC(1)



     For each element in fpath, the shell looks for three  possi-
     ble  files,  the newest of which is used to load the defini-
     tion for the function:

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

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

     element/function.zwc
          A file created with zcompile, which is expected to con-
          tain 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 function.

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

     In summary, the order of searching is, first, in the parents
     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  function  that  is
     sought,  the  leftmost  in  the  fpath is chosen; and third,
     within a directory, the newer of either a compiled  function
     or an ordinary function definition is used.

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




zsh 5.0.5          Last change: January 5, 2014                19






User Commands                                          ZSHMISC(1)



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

     For example, suppose the autoload file func contains

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


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

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

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

     and

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

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

          eval "$(functions)"

     produces a reasonable result.  A  true  autoloaded  function
     can  be  identified  by the presence of the comment `# unde-
     fined' in the body, because all comments are discarded  from
     defined functions.





zsh 5.0.5          Last change: January 5, 2014                20






User Commands                                          ZSHMISC(1)



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

          autoload +X myfunc

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

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

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

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

     For example,

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

     outputs the following:

          I am inside with arguments this and that
          I am outside

     Note that function definitions with arguments that expand to
     nothing,  for  example  `name=; function $name { ... }', are
     not treated  as  anonymous  functions.   Instead,  they  are
     treated  as normal function definitions where the definition



zsh 5.0.5          Last change: January 5, 2014                21






User Commands                                          ZSHMISC(1)



     is silently discarded.

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

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

     chpwd
          Executed  whenever  the  current  working  directory is
          changed.

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

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

     preexec
          Executed  just  after  a  command  has been read and is
          about to be executed.   If  the  history  mechanism  is
          active (and the line was not discarded from the history
          buffer), the string that the user typed  is  passed  as
          the  first  argument,  otherwise it is an empty string.
          The actual command that  will  be  executed  (including
          expanded aliases) is passed in two different forms: the
          second argument is a single-line, size-limited  version
          of  the  command  (with  things  like  function  bodies



zsh 5.0.5          Last change: January 5, 2014                22






User Commands                                          ZSHMISC(1)



          elided); the third argument contains the full text that
          is being executed.

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

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

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

          A hook function may call `fc -p ...' to switch the his-
          tory  context so that the history is saved in a differ-
          ent file from the that in the global  HISTFILE  parame-
          ter.  This is handled specially: the history context is
          automatically restored after the processing of the his-
          tory line is finished.

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                23






User Commands                                          ZSHMISC(1)



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

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

          The return status from the  function  is  handled  spe-
          cially.   If  it is zero, the signal is assumed to have
          been handled, and execution continues normally.  Other-
          wise,  the shell will behave as interrupted except that
          the return status of the trap is retained.

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

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

          The  functions  TRAPZERR,  TRAPDEBUG  and  TRAPEXIT are
          never executed inside other traps.

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

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

     TRAPZERR
          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  function  TRAPERR  acts  the
          same  as  TRAPZERR  on systems where there is no SIGERR
          (this is the usual case).





zsh 5.0.5          Last change: January 5, 2014                24






User Commands                                          ZSHMISC(1)



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

          TRAPNAL() {
           # code
          }

     ('function traps') and

          trap '
           # code
          ' NAL

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

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

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

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

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

          [1] 1234

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

     If  a  job  is  started  with `&|' or `&!', then that job is
     immediately disowned.  After startup, it  does  not  have  a
     place  in  the job table, and is not subject to the job con-
     trol features described here.





zsh 5.0.5          Last change: January 5, 2014                25






User Commands                                          ZSHMISC(1)



     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  command,
     or run some other commands and then eventually bring the job
     back into the foreground with the foreground command fg.   A
     ^Z takes effect immediately and is like an interrupt in that
     pending output and unread input are  discarded  when  it  is
     typed.

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

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

     The same behaviour is found when the shell is executing code
     as  the  right  hand side of a pipeline or any complex shell
     construct such as if, for, etc., in order  that  the  entire
     block  of  code  can be managed as a single job.  Background
     jobs are normally allowed to produce output, but this can be
     disabled  by  giving  the command `stty tostop'.  If you set
     this tty option, then background jobs will suspend when they
     try  to  produce  output  like they do when they try to read
     input.

     When a command is suspended and continued later with the  fg
     or wait builtins, zsh restores tty modes that were in effect
     when it was 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:

     %number
          The job with the given number.
     %string
          Any job whose command line begins with string.



zsh 5.0.5          Last change: January 5, 2014                26






User Commands                                          ZSHMISC(1)



     %?string
          Any job whose command line contains string.
     %%   Current job.
     %+   Equivalent to `%%'.
     %-   Previous job.

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

     When the monitor mode is on, each background job  that  com-
     pletes triggers any trap set for CHLD.

     When  you  try  to leave the shell while jobs are running or
     suspended, you will be warned that `You have suspended (run-
     ning)  jobs'.  You may use the jobs command to see what they
     are.  If you do this or immediately try to exit  again,  the
     shell  will  not  warn you a second time; the suspended jobs
     will be terminated, and the running  jobs  will  be  sent  a
     SIGHUP signal, if the HUP option is set.

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

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

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

ARITHMETIC EVALUATION
     The shell can perform integer and floating point arithmetic,
     either  using  the builtin let, or via a substitution of the
     form $((...)).  For integers, the shell is usually  compiled
     to  use  8-byte precision where this is available, otherwise
     precision is 4 bytes.  This can be tested, for  example,  by



zsh 5.0.5          Last change: January 5, 2014                27






User Commands                                          ZSHMISC(1)



     giving the command `print - $(( 12345678901 ))'; if the num-
     ber appears unchanged, the precision is at  least  8  bytes.
     Floating point arithmetic always uses the `double' type with
     whatever corresponding precision is provided by the compiler
     and the library.

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

     For example, the following statement

          (( val = 2 + 1 ))

     is equivalent to

          let "val = 2 + 1"

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

     Integers  can  be in bases other than 10.  A leading `0x' or
     `0X' denotes hexadecimal.  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  num-
     ber  in  that base (for example, `16#ff' is 255 in hexadeci-
     mal).  The base# may also be omitted, in which case base  10
     is  used.  For backwards compatibility the form `[base]n' is
     also accepted.

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

     It is also possible to specify a base to be used for  output
     in  the  form  `[#base]', for example `[#16]'.  This is used
     when outputting arithmetical substitutions or when assigning
     to  scalar  parameters, but an explicitly defined integer or
     floating point parameter will not be affected.  If an  inte-
     ger  variable is implicitly defined by an arithmetic expres-
     sion, any base specified in this way  will  be  set  as  the
     variable's output arithmetic base as if the option `-i base'
     to the typeset builtin had been used.  The expression has no



zsh 5.0.5          Last change: January 5, 2014                28






User Commands                                          ZSHMISC(1)



     precedence and if it occurs more than once in a mathematical
     expression, the last encountered is used.  For clarity it is
     recommended  that  it  appear at the beginning of an expres-
     sion.  As an example:

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

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

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

     When an output base is specified using the `[#base]' syntax,
     an  appropriate  base prefix will be output if necessary, 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 parameter name.
     All numeric parts (before and after the decimal point and in
     the  exponent)  may  contain  underscores  after the leading
     digit for visual guidance; these are ignored in computation.

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

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

     + - ! ~ ++ --
          unary     plus/minus,    logical    NOT,    complement,
          {pre,post}{in,de}crement
     << >>
          bitwise shift left, right
     &    bitwise AND
     ^    bitwise XOR
     |    bitwise OR
     **   exponentiation



zsh 5.0.5          Last change: January 5, 2014                29






User Commands                                          ZSHMISC(1)



     * / %
          multiplication, division, modulus (remainder)
     + -  addition, subtraction
     < > <= >=
          comparison
     == !=
          equality and inequality
     &&   logical AND
     || ^^
          logical OR, XOR
     ? :  ternary operator
     = += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=
          assignment
     ,    comma operator

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                30






User Commands                                          ZSHMISC(1)



     for compatibility with other shells.

     Mathematical  functions  can  be  called  with  the   syntax
     `func(args)', where the function decides if the args is used
     as a string or a comma-separated list of arithmetic  expres-
     sions. 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 value of
     this character and an expression of the  form  `#foo'  gives
     the  value  of  the  first  character of the contents of the
     parameter foo.  Character values are according to the  char-
     acter  set used in the current locale; for multibyte charac-
     ter handling the option MULTIBYTE must be  set.   Note  that
     this  form  is  different from `$#foo', a standard parameter
     substitution which gives the length of  the  parameter  foo.
     `#\' is accepted instead of `##', but its use is deprecated.

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

          ((val2 = val1 * 2))

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

     An  internal integer representation of a named parameter can
     be specified with the integer builtin.   Arithmetic  evalua-
     tion 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 substitu-
     tion 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 inte-
     ger.




zsh 5.0.5          Last change: January 5, 2014                31






User Commands                                          ZSHMISC(1)



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

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

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

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

CONDITIONAL EXPRESSIONS
     A  conditional  expression is used with the [[ compound 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 file.

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

     -e file
          true if file exists.

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

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

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




zsh 5.0.5          Last change: January 5, 2014                32






User Commands                                          ZSHMISC(1)



     -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 letter
          option name.  (See the section `Specifying Options'.)

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

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

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

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

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

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

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

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




zsh 5.0.5          Last change: January 5, 2014                33






User Commands                                          ZSHMISC(1)



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

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

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

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

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

     string = pattern
     string == pattern
          true if string matches pattern.  The `==' form  is  the
          preferred  one.   The `=' form is for backward compati-
          bility and should be considered obsolete.

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

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

          If the option BASH_REMATCH is not set the scalar param-
          eter  MATCH  is  set  to the substring that matched the
          pattern and the integer parameters MBEGIN and  MEND  to
          the  index  of  the start and end, respectively, of the
          match in string, such that if string  is  contained  in
          variable  var the expression `${var[$MBEGIN,$MEND]}' is
          identical to  `$MATCH'.   The  setting  of  the  option
          KSH_ARRAYS  is respected.  Likewise, the array match is
          set to the substrings that matched parenthesised subex-
          pressions and the arrays mbegin and mend to the indices
          of the start and end positions,  respectively,  of  the
          substrings  within  string.   The arrays are not set if
          there were no parenthesised subexpresssions.  For exam-
          ple,  if the string `a short string' is matched against
          the regular expression `s(...)t',  then  (assuming  the
          option  KSH_ARRAYS  is  not set) MATCH, MBEGIN and MEND
          are `short', 3 and 7, respectively, while match, mbegin



zsh 5.0.5          Last change: January 5, 2014                34






User Commands                                          ZSHMISC(1)



          and mend are single entry arrays containing the strings
          `hor', `4' and `6, respectively.

          If  the  option   BASH_REMATCH   is   set   the   array
          BASH_REMATCH  is  set to the substring that matched the
          pattern followed by the substrings that matched  paren-
          thesised subexpressions within the pattern.

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

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

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

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

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

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

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

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

     ( exp )
          true if exp is true.

     ! exp
          true if exp is false.

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

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

     Normal  shell expansion is performed on the file, string and
     pattern arguments, but  the  result  of  each  expansion  is



zsh 5.0.5          Last change: January 5, 2014                35






User Commands                                          ZSHMISC(1)



     constrained  to  be  a single word, similar to the effect of
     double quotes.  Filename generation is not performed on  any
     form  of argument to conditions.  However, pattern metachar-
     acters are active for the pattern  arguments;  the  patterns
     are the same as those used for filename generation, see zsh-
     expn(1), but there is no special behaviour of `/'  nor  ini-
     tial dots, and no glob qualifiers are allowed.

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

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

     For example, the following:

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

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

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

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

     Certain  escape  sequences  may  be recognised in the prompt
     string.

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

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

SIMPLE PROMPT ESCAPES




zsh 5.0.5          Last change: January 5, 2014                36






User Commands                                          ZSHMISC(1)



  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  fol-
          low the `%' to specify how many components of the host-
          name are desired.  With a  negative  integer,  trailing
          components of the hostname are shown.

     %n   $USERNAME.

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

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

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

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

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

     %~   As  %d  and  %/,  but  if the current working directory



zsh 5.0.5          Last change: January 5, 2014                37






User Commands                                          ZSHMISC(1)



          starts with $HOME, that part is replaced by a `~'. Fur-
          thermore,  if  it  has a named directory as its prefix,
          that part is replaced by a `~' followed by the name  of
          the  directory,  but only if the result is shorter than
          the full path; see Dynamic and Static named directories
          in zshexpn(1).

     %h
     %!   Current history event number.

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

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

     %j   The number of jobs.

     %L   The current value of $SHLVL.

     %N   The name of the script, sourced file, or shell function
          that  zsh is currently executing, whichever was started
          most recently.  If there is none, this is equivalent to
          the  parameter  $0.   An  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.

     %x   The name of the file containing the  source  code  cur-
          rently  being executed.  This behaves as %N except that
          function and eval command names are not shown,  instead
          the file where they were defined.

     %c
     %.
     %C   Trailing  component  of  the current working directory.
          An integer may follow the `%' to get more than one com-
          ponent.  Unless `%C' is used, tilde contraction is per-
          formed 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  lat-
          ter two sequences.

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

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

     %t



zsh 5.0.5          Last change: January 5, 2014                38






User Commands                                          ZSHMISC(1)



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

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

     %w   The date in day-dd format.

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

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

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

          The GNU extension that a `-' between the % and the for-
          mat  character  causes  a  leading  zero or space to be
          stripped is handled directly by the shell for the  for-
          mat  characters d, f, H, k, l, m, M, S and y; any other
          format characters are provided to strftime()  with  any
          leading  `-', present, so the handling is system depen-
          dent.  Further GNU  extensions  are  not  supported  at
          present.

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

     %E   Clear to end of line.

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                39






User Commands                                          ZSHMISC(1)



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

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

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

          Multiple uses of %G accumulate in the obvious  fashion;
          the  position of the %G is unimportant.  Negative inte-
          gers are not handled.

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

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

     %(x.true-text.false-text)
          Specifies a ternary expression.  The character  follow-
          ing  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 expres-
          sions.

          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:




zsh 5.0.5          Last change: January 5, 2014                40






User Commands                                          ZSHMISC(1)



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

     %<string<
     %>string>
     %[xstring]
          Specifies truncation behaviour for the remainder of the
          prompt  string.  The third, deprecated, form is equiva-
          lent to `%xstringx', i.e. x may be  `<'  or  `>'.   The
          numeric  argument,  which  in the third form may appear
          immediately after the `[', specifies the  maximum  per-
          mitted  length  of the various strings that can be dis-
          played in the prompt.  The string will be displayed  in
          place of the truncated portion of any string; note this
          does not undergo prompt expansion.

          The forms with `<' truncate at the left of the  string,
          and  the  forms  with  `>' truncate at the right of the
          string.  For  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



zsh 5.0.5          Last change: January 5, 2014                41






User Commands                                          ZSHMISC(1)



          also subject to standard print processing, in  addition
          to  any  backslashes removed by a double quoted string:
          the worst case is therefore `print -P "%<\\\\<<..."'.

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

          The part of the prompt string to be truncated  runs  to
          the  end  of  the  string,  or  to  the end of the next
          enclosing group of the `%(' construct, or to  the  next
          truncation encountered at the same grouping level (i.e.
          truncations inside a `%('  are  separate),  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.



ATTRIBUTES
     See  attributes(5)  for  descriptions   of   the   following
     attributes:

     +---------------+------------------+
     |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
     +---------------+------------------+
     |Availability   | shell/zsh        |
     +---------------+------------------+
     |Stability      | Volatile         |
     +---------------+------------------+
NOTES
     This   software   was   built   from   source  available  at
     https://java.net/projects/solaris-userland.   The   original
     community   source   was   downloaded   from    http://down-
     loads.source-
     forge.net/project/zsh/zsh/5.0.5/zsh-5.0.5.tar.bz2

     Further  information about this software can be found on the
     open source community website at http://www.zsh.org/.











zsh 5.0.5          Last change: January 5, 2014                42






User Commands                                          ZSHEXPN(1)



NAME
     zshexpn - zsh expansion and substitution

DESCRIPTION
     The following types of expansions are performed in the indi-
     cated order in five steps:

     History Expansion
          This is performed only in interactive shells.

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

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

     Filename Expansion
          If the SH_FILE_EXPANSION option is set,  the  order  of
          expansion  is  modified  for  compatibility with sh and
          ksh.  In that  case  filename  expansion  is  performed
          immediately after alias 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
     detail.

HISTORY EXPANSION
     History expansion allows you to use words from previous com-
     mand lines in the command line you are typing.  This simpli-
     fies spelling corrections and the repetition of  complicated
     commands or arguments.

     Immediately  before  execution, each command is saved in the
     history list, the size of which is controlled by  the  HIST-
     SIZE  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  his-
     tory  number  that you may see in your prompt (see EXPANSION
     OF PROMPT SEQUENCES in zshmisc(1)) is the number that is  to



zsh 5.0.5          Last change: January 5, 2014                 1






User Commands                                          ZSHEXPN(1)



     be assigned to the next command.

  Overview
     A  history  expansion begins with the first character of the
     histchars parameter, which is `!' by default, and may  occur
     anywhere  on  the  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 Designators'); if neither of
     these designators is present, no history expansion occurs.

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

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

     For example, `!' is the event designator  for  the  previous
     command,  so  `!!:1'  always refers to the first word of the
     previous command, and `!!$' always refers to the  last  word
     of  the previous command.  With CSH_JUNKIE_HISTORY set, then
     `!:1' and `!$' function in the same  manner  as  `!!:1'  and
     `!!$',  respectively.   Conversely, if CSH_JUNKIE_HISTORY is
     unset, then `!:1' and `!$'  refer  to  the  first  and  last
     words,  respectively,  of  the  same event referenced by the
     nearest other history reference preceding them on  the  cur-
     rent 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  pre-
     cisely,   the   sequence   `^foo^bar^'  is  synonymous  with
     `!!:s^foo^bar^', hence  other  modifiers  (see  the  section
     `Modifiers')  may  follow  the  final  `^'.   In particular,
     `^foo^bar^:G' performs a global substitution.

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



zsh 5.0.5          Last change: January 5, 2014                 2






User Commands                                          ZSHEXPN(1)



     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 character
     by setting the histchars parameter.

     !    Start a history expansion, except when  followed  by  a
          blank, newline, `=' or `('.  If followed immediately 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  expan-
          sion repeats the previous command.

     !n   Refer to command-line n.

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

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

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

     !{...}
          Insulate  a  history reference from adjacent characters
          (if necessary).

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

     0    The first input word (command).
     n    The nth argument.
     ^    The first argument.  That is, 1.



zsh 5.0.5          Last change: January 5, 2014                 3






User Commands                                          ZSHEXPN(1)



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

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

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

     a    Turn a file name into an absolute path:   prepends  the
          current  directory,  if necessary, and resolves any use
          of `..' and `.' in the path.  Note that the transforma-
          tion  takes  place  even if the file or any intervening
          directories do not exist.

     A    As `a', but also resolve use of  symbolic  links  where
          possible.   Note  that resolution of `..' occurs before
          resolution of symbolic links.  This call is  equivalent
          to  a  unless  your system has the realpath system call
          (modern systems do).

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

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

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

     l    Convert the words to all lowercase.

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




zsh 5.0.5          Last change: January 5, 2014                 4






User Commands                                          ZSHEXPN(1)



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

     Q    Remove  one level of quotes from the substituted words.

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

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

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

          See further notes on this form of substitution below.

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

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

     u    Convert the words to all uppercase.

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

     The s/l/r/ substitution works as follows.   By  default  the
     left-hand  side of substitutions are not patterns, but char-
     acter strings.  Any character can be used as  the  delimiter
     in  place  of `/'.  A backslash quotes the delimiter charac-
     ter.  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



zsh 5.0.5          Last change: January 5, 2014                 5






User Commands                                          ZSHEXPN(1)



     delimiter  if a newline immediately follows r; the rightmost
     `?' in a context scan can similarly be  omitted.   Note  the
     same  record  of  the  last l and r is maintained across all
     forms of expansion.

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

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

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

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

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

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

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

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




zsh 5.0.5          Last change: January 5, 2014                 6






User Commands                                          ZSHEXPN(1)



     F:expr:
          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  han-
          dled specially, see above.

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

     In the case of the < or > forms, the shell runs the commands
     in  list as a subprocess of the job executing the shell com-
     mand line.  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 sup-
     ports  named  pipes  (FIFOs), the command argument will be a
     named pipe.  If the form with > is selected then writing  on
     this  special  file  will  provide  input for list.  If < is
     used, then the file passed as an argument will be  connected
     to the output of the list process.  For example,

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

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

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




zsh 5.0.5          Last change: January 5, 2014                 7






User Commands                                          ZSHEXPN(1)



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

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

     Also  note  that  the previous example can be more compactly
     and 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 lat-
     ter 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  follow-
     ing  command cannot rely on the results being complete.  The
     problem and solution are the same as described in  the  sec-
     tion  MULTIOS  in zshmisc(1).  Hence in a simplified version
     of the example above:

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                 8






User Commands                                          ZSHEXPN(1)



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

          (mycmd =(myoutput)) &!

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

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

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

     outputs something resembling the following

          File /tmp/zsh6nU0kS:
          This be the verse

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

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

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

     In the expansions discussed below that  require  a  pattern,
     the  form  of the pattern is the same as that used for file-
     name generation;  see  the  section  `Filename  Generation'.
     Note that these patterns, along with the replacement text of
     any  substitutions,  are  themselves  subject  to  parameter
     expansion,  command  substitution, and arithmetic expansion.
     In addition to the following operations, the colon modifiers
     described in the section `Modifiers' in the section `History



zsh 5.0.5          Last change: January 5, 2014                 9






User Commands                                          ZSHEXPN(1)



     Expansion' can be  applied:   for  example,  ${i:s/foo/bar/}
     performs  string  substitution on the expansion of parameter
     $i.

     ${name}
          The value, if any, of the  parameter  name  is  substi-
          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; exceptions, which only apply
          if the option KSH_ARRAYS is not set, are a single  sub-
          script or any colon modifiers appearing after the name,
          or any of the characters `^',  `=',  `~',  `#'  or  `+'
          appearing  before  the  name, all of which work with or
          without braces.

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

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

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

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

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

     ${name?word}



zsh 5.0.5          Last change: January 5, 2014                10






User Commands                                          ZSHEXPN(1)



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

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

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

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                11






User Commands                                          ZSHEXPN(1)



     ${name:*arrayname}
          Similar to the preceding subsitution, but in the  oppo-
          site  sense, so that entries present in both the origi-
          nal substitution  and  as  elements  of  arrayname  are
          retained and others removed.

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

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

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

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

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

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

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

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




zsh 5.0.5          Last change: January 5, 2014                12






User Commands                                          ZSHEXPN(1)



          all have the same effect, extracting the string  start-
          ing  at  the fourth character of $foo if the substution
          would otherwise return a scalar, or the array  starting
          at  the  fourth  element if $foo would return an array.
          Note  that  with  the  option  KSH_ARRAYS  $foo  always
          returns  a  scalar (regardless of the use of the offset
          syntax) and a form such as  $foo[*]:3  is  required  to
          extract elements of an array named foo.

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

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

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

          The pattern may begin with a `#',  in  which  case  the
          pattern  must match at the start of the string, or `%',
          in which case it must match at the end of  the  string,
          or `#%' in which case the pattern must match the entire
          string.  The repl may be an empty string, in which case
          the  final `/' may also be omitted.  To quote the final
          `/' in other cases it should be preceded  by  a  single
          backslash;  this  is  not  necessary  if the `/' occurs



zsh 5.0.5          Last change: January 5, 2014                13






User Commands                                          ZSHEXPN(1)



          inside a substituted parameter.   Note  also  that  the
          `#',  `%' and `#% are not active if they occur inside a
          substituted parameter, even at the start.

          The first `/' may be preceded by a `:', in  which  case
          the  match  will  only succeed if it matches the entire
          word.  Note also the effect of the I  and  S  parameter
          expansion  flags  below;  however, the flags M, R, B, E
          and N are not useful.

          For example,

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

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

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

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

          Internally, each such expansion is converted  into  the
          equivalent  list  for  brace  expansion.  E.g., ${^var}
          becomes  {$var[1],$var[2],...},  and  is  processed  as
          described  in  the section `Brace Expansion' below.  If
          word splitting is also in effect the $var[N] may  them-
          selves be split into different list elements.

     ${=spec}
          Perform    word   splitting   using   the   rules   for
          SH_WORD_SPLIT  during  the  evaluation  of  spec,   but



zsh 5.0.5          Last change: January 5, 2014                14






User Commands                                          ZSHEXPN(1)



          regardless  of  whether the parameter appears in double
          quotes; if the `='  is  doubled,  turn  it  off.   This
          forces  parameter  expansions to be split into separate
          words before substitution, using IFS  as  a  delimiter.
          This is done by default in most other shells.

          Note  that  splitting is applied to word in the assign-
          ment forms of spec before the  assignment  to  name  is
          performed.   This  affects  the result of array assign-
          ments with the A flag.

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

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

     If a ${...} type parameter expression or a $(...) type  com-
     mand  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 opera-
     tions:  ${${foo#head}%tail} substitutes the  value  of  $foo
     with  both  `head' and `tail' deleted.  The form with $(...)
     is often useful in  combination  with  the  flags  described
     next; see the examples below.  Each name or nested ${...} in
     a parameter expansion may also be followed  by  a  subscript
     expression  as described in Array Parameters in zshparam(1).

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

  Parameter Expansion Flags
     If the opening brace is  directly  followed  by  an  opening



zsh 5.0.5          Last change: January 5, 2014                15






User Commands                                          ZSHEXPN(1)



     parenthesis, the string up to the matching closing parenthe-
     sis 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 sup-
     ported:

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

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

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

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

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

     a    Sort in array index order; when combined with `O'  sort
          in  reverse array index order.  Note that `a' is there-
          fore equivalent to the default but `Oa' is  useful  for
          obtaining an array's elements in reverse order.

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



zsh 5.0.5          Last change: January 5, 2014                16






User Commands                                          ZSHEXPN(1)



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

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

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

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

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

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

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

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

     L    Convert all letters in the result to lower case.

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



zsh 5.0.5          Last change: January 5, 2014                17






User Commands                                          ZSHEXPN(1)



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

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

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

          If  used  with  a nested parameter or command substitu-
          tion, 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 characters that are special to the shell  in  the
          resulting   words   with  backslashes;  unprintable  or
          invalid characters are quoted using the  $'\NNN'  form,
          with separate quotes for each octet.

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

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

     Q    Remove one level of quotes from the resulting words.

     t    Use a string describing the type of the parameter where
          the value of the parameter would usually  appear.  This
          string consists of keywords separated by hyphens (`-').
          The first keyword in  the  string  describes  the  main



zsh 5.0.5          Last change: January 5, 2014                18






User Commands                                          ZSHEXPN(1)



          type,  it  can  be one of `scalar', `array', `integer',
          `float' or `association'. The other  keywords  describe
          the type in more detail:

          local
               for local parameters

          left for left justified parameters

          right_blanks
               for right justified parameters with leading blanks

          right_zeros
               for right justified parameters with leading zeros

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

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

          readonly
               for readonly parameters

          tag  for tagged parameters

          export
               for exported parameters

          unique
               for arrays which keep only the first occurrence of
               duplicated values

          hide for parameters with the `hide' flag

          special
               for special parameters defined by the shell

     u    Expand only the first occurrence of each unique word.

     U    Convert all letters in the result to upper case.

     v    Used with k, substitute (as two consecutive words) both
          the key and the value of each  associative  array  ele-
          ment.  Used with subscripts, force values to be substi-
          tuted even if the subscript form refers to  indices  or
          keys.

     V    Make any special characters in the resulting words vis-
          ible.



zsh 5.0.5          Last change: January 5, 2014                19






User Commands                                          ZSHEXPN(1)



     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,  e
          and  #  flags  or  the  pattern  matching forms such as
          `${name#pattern}'  are  reported.   Without  the  flag,
          errors are silently ignored.

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

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

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

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

     ~    Force  string  arguments to any of the flags below that
          follow within the parentheses to  be  treated  as  pat-
          terns.   Compare  with  a  ~ outside parentheses, which
          forces the entire substituted string to be treated as a
          pattern.  Hence, for example,
          [[ "?" = ${(~j.|.)array} ]]
     with  the  EXTENDED_GLOB  option set succeeds if and only if
     $array contains the string `?' as an element.  The  argument
     may  be  repeated  to  toggle the behaviour; its effect only
     lasts to the end of the parenthesised group.

     j:string:
          Join the words of arrays together  using  string  as  a



zsh 5.0.5          Last change: January 5, 2014                20






User Commands                                          ZSHEXPN(1)



          separator.   Note  that this occurs before field split-
          ting by the s:string: flag or the SH_WORD_SPLIT option.

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

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

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

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

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                21






User Commands                                          ZSHEXPN(1)



          immediately to the right of the string to be padded.

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

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

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

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

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

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

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




zsh 5.0.5          Last change: January 5, 2014                22






User Commands                                          ZSHEXPN(1)



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

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

     I:expr:
          Search the exprth match (where expr evaluates to a num-
          ber).  This only applies when searching for substrings,
          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 match.

          The exprth match is counted such that there  is  either
          one  or zero matches from each starting position in the
          string, although for global substitution matches  over-
          lapping  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 order.

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

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

     M    Include the matched portion in the result.

     N    Include the length of the match in the result.

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




zsh 5.0.5          Last change: January 5, 2014                23






User Commands                                          ZSHEXPN(1)



  Rules
     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 responsibil-
     ity for any brain damage which may occur during the  reading
     of the following rules.

     1. Nested substitution
          If  multiple nested ${...} forms are present, substitu-
          tion 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 substitution will return either a scalar or
          an array as determined by the flags, possibly  adjusted
          for  quoting.  All the following steps take place where
          applicable at all levels of substitution.   Note  that,
          unless  the  `(P)'  flag  is present, the flags and any
          subscripts apply directly to the value  of  the  nested
          substitution;  for  example,  the  expansion  ${${foo}}
          behaves exactly the same as ${foo}.

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

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

     3. Parameter subscripting
          If  the  value is a raw parameter reference with a sub-
          script, such as ${var[3]}, the effect  of  subscripting
          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



zsh 5.0.5          Last change: January 5, 2014                24






User Commands                                          ZSHEXPN(1)



          subscript.  Thus if var is an  array,  ${var[1][2]}  is
          the   second   character   of   the   first  word,  but
          ${var[2,4][2]} is the entire  third  word  (the  second
          word  of  the  range  of  words two through four of the
          original array).  Any number of subscripts may  appear.
          Flags  such  as  (k)  and (v) which alter the result of
          subscripting are applied.

     4. Parameter name replacement
          The effect of any (P) flag, which treats the  value  so
          far as a parameter name and replaces it with the corre-
          sponding value, is applied.

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

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

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

     8. Character evaluation
          Any  (#)  flag is applied, evaluating the result so far
          numerically as a character.

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

     10. Forced joining
          If  the  `(j)'  flag  is  present,  or no `(j)' flag is
          present but the string is to be split as given by  rule



zsh 5.0.5          Last change: January 5, 2014                25






User Commands                                          ZSHEXPN(1)



          11.,  and  joining  did  not take place at step 5., 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.

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

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

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

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

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

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                26






User Commands                                          ZSHEXPN(1)



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

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

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

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

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

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

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

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

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

     "${(@)${foo}[1]}"
          This produces the result b.  First, the inner substitu-
          tion "${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 subscript picks the first
          character.



zsh 5.0.5          Last change: January 5, 2014                27






User Commands                                          ZSHEXPN(1)



     "${${(@)foo}[1]}"
          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 "${foo[1]}".

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

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

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

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

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

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

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

     An expression of the form `{n1..n2}', where n1  and  n2  are
     integers,  is  expanded  to  every  number between n1 and n2
     inclusive.  If either number begins with  a  zero,  all  the



zsh 5.0.5          Last change: January 5, 2014                28






User Commands                                          ZSHEXPN(1)



     resulting numbers will be padded with leading zeroes to that
     minimum width, but for negative numbers the -  character  is
     also  included in the width.  If the numbers are in decreas-
     ing order the resulting sequence will also be in  decreasing
     order.

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

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

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

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

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

     A `~' by itself is replaced by the value of  $HOME.   A  `~'
     followed  by  a  `+'  or  a  `-'  is  replaced by current or



zsh 5.0.5          Last change: January 5, 2014                29






User Commands                                          ZSHEXPN(1)



     previous working directory, 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.

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

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

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





zsh 5.0.5          Last change: January 5, 2014                30






User Commands                                          ZSHEXPN(1)



          reply=(s 16)

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

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                31






User Commands                                          ZSHEXPN(1)



            fi
            return 0
          }

  Static named directories
     A `~' followed by anything not already covered consisting of
     any number of alphanumeric characters or  underscore  (`_'),
     hyphen  (`-'),  or  dot (`.') is looked up as a named direc-
     tory, and replaced by the value of that named  directory  if
     found.  Named directories are typically home directories for
     users on the system.  They may also be defined if  the  text
     after  the `~' is the name of a string shell parameter whose
     value begins with a `/'.  Note that trailing slashes will be
     removed  from the path to the directory (though the original
     parameter is not modified).

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

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

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

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

     If the option MAGIC_EQUAL_SUBST is set, any  unquoted  shell
     argument  in the form `identifier=expression' becomes eligi-
     ble for file expansion as described in  the  previous  para-
     graph.  Quoting the first `=' also inhibits this.





zsh 5.0.5          Last change: January 5, 2014                32






User Commands                                          ZSHEXPN(1)



FILENAME GENERATION
     If  a word contains an unquoted instance of one of the char-
     acters `*', `(', `|', `<', `[', 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
     unchanged.

     In  filename  generation,  the character `/' must be matched
     explicitly; also, a `.' must be matched  explicitly  at  the
     beginning  of a pattern or after a `/', unless the GLOB_DOTS
     option is set.  No filename generation pattern  matches  the
     files  `.' or `..'.  In other instances of pattern 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 charac-
          ters by a `-'.  A `-' or `]' may be matched by  includ-
          ing  it  as the first character in the list.  There are
          also several named classes of characters, in  the  form
          `[:name:]'  with the following meanings.  The first set
          use the macros provided by the operating system to test
          for  the  given  character  combinations, including any
          modifications  due  to  local  language  settings,  see
          ctype(3):

          [:alnum:]
               The character is alphanumeric

          [:alpha:]
               The character is alphabetic

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

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




zsh 5.0.5          Last change: January 5, 2014                33






User Commands                                          ZSHEXPN(1)



          [:cntrl:]
               The character is a control character

          [:digit:]
               The character is a decimal digit

          [:graph:]
               The character is a printable character other  than
               whitespace

          [:lower:]
               The character is a lowercase letter

          [:print:]
               The character is printable

          [:punct:]
               The  character  is  printable but neither alphanu-
               meric nor whitespace

          [:space:]
               The character is whitespace

          [:upper:]
               The character is an uppercase letter

          [:xdigit:]
               The character is a hexadecimal digit

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

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

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

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

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

          Note  that  the square brackets are additional to those
          enclosing the whole set of characters, so to test for a



zsh 5.0.5          Last change: January 5, 2014                34






User Commands                                          ZSHEXPN(1)



          single  alphanumeric  character you need `[[:alnum:]]'.
          Named character sets can be used alongside other types,
          e.g. `[[:alpha:]0-9]'.

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

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

          Be  careful when using other wildcards adjacent to pat-
          terns 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 group-
          ing.  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  avail-
          able.

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

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

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




zsh 5.0.5          Last change: January 5, 2014                35






User Commands                                          ZSHEXPN(1)



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

     x#   (Requires  EXTENDED_GLOB  to  be set.)  Matches zero or
          more occurrences of the pattern x.  This  operator  has
          high precedence; `12#' is equivalent to `1(2#)', rather
          than `(12)#'.  It is an error for an  unquoted  `#'  to
          follow   something   which  cannot  be  repeated;  this
          includes an empty string, a pattern already 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.  (Note the potential
          clash with glob qualifiers in the form  `1(2##)'  which
          should therefore be avoided.)

  ksh-like Glob Operators
     If  the  KSH_GLOB  option is set, the effects of parentheses
     can be 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  `(...)#',
          except that recursive directory searching is  not  sup-
          ported.)

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

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

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



zsh 5.0.5          Last change: January 5, 2014                36






User Commands                                          ZSHEXPN(1)



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

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

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

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

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

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

          For example,

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



zsh 5.0.5          Last change: January 5, 2014                37






User Commands                                          ZSHEXPN(1)



          prints `string with a'.  Note that the first  parenthe-
          sis is before the (#b) and does not create a backrefer-
          ence.

          Backreferences work with all forms of pattern  matching
          other than filename generation, but note that when per-
          forming  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  fol-
          lowed  by  `#'  or  `##'.   Only  the last match of the
          parenthesis is remembered: for example, in `[[  abab  =
          (#b)([ab])#  ]]',  only  the  final  `b'  is  stored in
          match[1].  Thus extra parentheses may be  necessary  to
          match   the   complete   segment:   for   example,  use
          `X((ab|cd)#)Y' to match a whole string of  either  `ab'
          or  `cd'  between  `X'  and  `Y',  using  the  value of
          $match[1] rather than $match[2].

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

          Pattern matching with backreferences is slightly slower
          than without.

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

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



zsh 5.0.5          Last change: January 5, 2014                38






User Commands                                          ZSHEXPN(1)



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

          For example,

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

          forces  all  the  matches (i.e. all vowels) into upper-
          case, printing `vEldt jynx grImps wAqf zhO bUck'.

          Unlike backreferences, there is no  speed  penalty  for
          using  match references, other than the extra substitu-
          tions 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 suc-
          ceeds only at the end of the test string;  they  corre-
          spond  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 seg-
          ment `test' in any  of  the  following  strings:  test,
          test/at/start, at/end/test, in/test/middle.

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





zsh 5.0.5          Last change: January 5, 2014                39






User Commands                                          ZSHEXPN(1)



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

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

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

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

     For example, the test string fooxx can  be  matched  by  the
     pattern  (#i)FOOXX,  but  not by (#l)FOOXX, (#i)FOO(#I)XX or
     ((#i)FOOX)X.  The string (#ia2)readme specifies  case-insen-
     sitive 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 let-
     ters inside [...] groups, in  other  words  (#i)[a-z]  still
     matches  only  lowercase  letters.   Finally, note that when
     examining whole  paths  case-insensitively  every  directory
     must  be  searched for all files which match, so that a pat-
     tern 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:




zsh 5.0.5          Last change: January 5, 2014                40






User Commands                                          ZSHEXPN(1)



     1.   Different characters, as in fooxbar and fooybar.

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

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

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

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

     Non-literal parts of the pattern must match exactly, includ-
     ing  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  sepa-
     rately  for  non-contiguous  strings in the pattern, so that
     (ab|cd)ef is two errors from aebf.

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

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

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



zsh 5.0.5          Last change: January 5, 2014                41






User Commands                                          ZSHEXPN(1)



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

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

          ls (*/)#bar

     or

          ls **/bar

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

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

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

     If the option EXTENDED_GLOB is set, a different  syntax  for
     glob  qualifiers is available, namely `(#qx)' where x is any
     of the same glob qualifiers used in the other  format.   The
     qualifiers  must  still  appear  at  the end of the pattern.
     However, with this syntax multiple glob  qualifiers  may  be
     chained  together.  They are treated as a logical AND of the
     individual sets of flags.  Also, as the syntax is  unambigu-
     ous,  the expression will be treated as glob qualifiers just
     as long any parentheses contained within  it  are  balanced;
     appearance  of  `|',  `(' or `~' does not negate the effect.
     Note that qualifiers will be recognised in this form even if
     a  bare glob qualifier exists at the end of the pattern, for
     example `*(#q*)(.)' will recognise executable regular  files
     if both options are set; however, mixed syntax should proba-
     bly be avoided for the sake of clarity.



zsh 5.0.5          Last change: January 5, 2014                42






User Commands                                          ZSHEXPN(1)



     A qualifier may be any one of the following:

     /    directories

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

     .    plain files

     @    symbolic links

     =    sockets

     p    named pipes (FIFOs)

     *    executable plain files (0100)

     %    device files (character or block special)

     %b   block special files

     %c   character special files

     r    owner-readable files (0400)

     w    owner-writable files (0200)

     x    owner-executable files (0100)

     A    group-readable files (0040)

     I    group-writable files (0020)

     E    group-executable files (0010)

     R    world-readable files (0004)

     W    world-writable files (0002)

     X    world-executable files (0001)

     s    setuid files (04000)

     S    setgid files (02000)

     t    files with the sticky bit (01000)

     fspec
          files  with  access rights matching spec. This spec may
          be a octal number optionally preceded by a `=', a  `+',
          or  a  `-'.  If  none of these characters is given, the



zsh 5.0.5          Last change: January 5, 2014                43






User Commands                                          ZSHEXPN(1)



          behavior is the same  as  for  `='.  The  octal  number
          describes  the  mode  bits  to be expected, if combined
          with a `=', the value given must match  the  file-modes
          exactly,  with  a  `+',  at least the bits in the given
          number must be set in the file-modes, and with  a  `-',
          the  bits  in  the number must not be set. Giving a `?'
          instead of a octal digit anywhere in the number ensures
          that  the  corresponding bits in the file-modes are not
          checked, this is only useful in combination with `='.

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

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

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

          In the first form, the first character  after  the  `e'
          will be used as a separator and anything up to the next
          matching separator will be taken  as the  string;  `[',



zsh 5.0.5          Last change: January 5, 2014                44






User Commands                                          ZSHEXPN(1)



          `{',  and  `<'  match  `]', `}', and `>', respectively,
          while any other character  matches  itself.  Note  that
          expansions must be quoted in the string to prevent them
          from being expanded before globbing is done.  string is
          then  executed  as  shell code.  The string globqual is
          appended to the array zsh_eval_context the duration  of
          execution.

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

          For example, suppose a directory contains a single file
          `lonely'.           Then         the         expression
          `*(e:'reply=(${REPLY}{1,2})':)' will  cause  the  words
          `lonely1' and `lonely2' to be inserted into the command
          line.  Note the quoting of string.

          The form +cmd has the same effect,  but  no  delimiters
          appear  around cmd.  Instead, cmd is taken as the long-
          est sequence of characters following  the  +  that  are
          alphanumeric  or underscore.  Typically cmd will be the
          name of a shell function that contains the  appropriate
          test.  For example,

               nt() { [[ $REPLY -nt $NTREF ]] }
               NTREF=reffile
               ls -l *(+nt)

          lists  all  files in the directory that have been modi-
          fied more recently than reffile.

     ddev files on the device dev

     l[-|+]ct
          files having a link count less  than  ct  (-),  greater
          than ct (+), or equal to ct

     U    files owned by the effective user ID

     G    files owned by the effective group ID

     uid  files  owned by user ID id if that is a number.  Other-
          wise, id specifies a user name: the character after the
          `u' will be taken as a separator and the string between
          it and the next matching separator will be taken  as  a
          user  name.   The starting separators `[', `{', and `<'



zsh 5.0.5          Last change: January 5, 2014                45






User Commands                                          ZSHEXPN(1)



          match the final separators `]', `}', and  `>',  respec-
          tively;   any  other  character  matches  itself.   The
          selected files are those owned by this user.  For exam-
          ple,  `u:foo:'  or `u[foo]' selects files owned by user
          `foo'.

     gid  like uid but with group IDs or names

     a[Mwhms][-|+]n
          files accessed exactly  n  days  ago.   Files  accessed
          within  the  last  n days are selected using a negative
          value for n (-n).  Files accessed more than n days  ago
          are selected by a positive n value (+n).  Optional unit
          specifiers `M', `w', `h', `m' or `s' (e.g. `ah5') cause
          the  check  to  be  performed with months (of 30 days),
          weeks, hours,  minutes  or  seconds  instead  of  days,
          respectively.    An  explicit  `d'  for  days  is  also
          allowed.

          Any fractional  part  of  the  difference  between  the
          access  time  and  the  current part in the appropriate
          units is ignored  in  the  comparison.   For  instance,
          `echo  *(ah-5)'  would  echo  files accessed within the
          last five hours, while `echo *(ah+5)' would echo  files
          accessed  at  least  six  hours  ago, as times strictly
          between five and six hours are treated as five hours.

     m[Mwhms][-|+]n
          like the file access qualifier, except that it uses the
          file modification time.

     c[Mwhms][-|+]n
          like the file access qualifier, except that it uses the
          file inode change time.

     L[+|-]n
          files less than n bytes (-), more than n bytes (+),  or
          exactly n bytes in length.

          If  this  flag is directly followed by a `k' (`K'), `m'
          (`M'), or `p' (`P') (e.g. `Lk-50') the  check  is  per-
          formed  with  kilobytes,  megabytes,  or blocks (of 512
          bytes) instead.  In this case a  file  is  regarded  as
          "exactly"  the  size if the file size rounded up to the
          next unit is equal to the test  size.   Hence  `*(Lm1)'
          matches  files  from 1 byte up to 1 Megabyte inclusive.
          Note also that the set of files "less  than"  the  test
          size  only  includes  files  that  would  not match the
          equality test; hence `*(Lm-1)' only  matches  files  of
          zero size.

     ^    negates all qualifiers following it



zsh 5.0.5          Last change: January 5, 2014                46






User Commands                                          ZSHEXPN(1)



     -    toggles  between making the qualifiers work on symbolic
          links (the default) and the files they point to

     M    sets the MARK_DIRS option for the current pattern

     T    appends a trailing qualifier  mark  to  the  filenames,
          analogous  to  the  LIST_TYPES  option, for the current
          pattern (overrides M)

     N    sets the NULL_GLOB option for the current pattern

     D    sets the GLOB_DOTS option for the current pattern

     n    sets the NUMERIC_GLOB_SORT option for the current  pat-
          tern

     oc   specifies  how the names of the files should be sorted.
          If c is n they are sorted by name (the default); if  it
          is  L they are sorted depending on the size (length) of
          the files; if l they are sorted by the number of links;
          if  a,  m, or c they are sorted by the time of the last
          access, modification, or inode change respectively;  if
          d,  files  in subdirectories appear before those in the
          current directory at each level of the search  --  this
          is  best  combined  with  other  criteria,  for example
          `odon' to sort on  names  for  files  within  the  same
          directory; if N, no sorting is performed.  Note that a,
          m, and c compare the  age  against  the  current  time,
          hence  the first name in the list is the youngest file.
          Also note that the modifiers  ^  and  -  are  used,  so
          `*(^-oL)' gives a list of all files sorted by file size
          in descending  order,  following  any  symbolic  links.
          Unless  oN is used, multiple order specifiers may occur
          to resolve ties.

          oe and o+ are special cases; they are each followed  by
          shell  code,  delimited as for the e glob qualifier and
          the + glob qualifier  respectively  (see  above).   The
          code is executed for each matched file with the parame-
          ter REPLY set to the name of  the  file  on  entry  and
          globsort appended to zsh_eval_context.  The code should
          modify the parameter REPLY in some fashion.  On return,
          the  value of the parameter is used instead of the file
          name as the string on which to sort.  Unlike other sort
          operators, oe and o+ may be repeated, but note that the
          maximum number of sort operators of any kind  that  may
          appear in any glob expression is 12.

     Oc   like  `o', but sorts in descending order; i.e. `*(^oc)'
          is the same as `*(Oc)' and  `*(^Oc)'  is  the  same  as
          `*(oc)';  `Od'  puts  files  in  the  current directory
          before those in subdirectories at  each  level  of  the



zsh 5.0.5          Last change: January 5, 2014                47






User Commands                                          ZSHEXPN(1)



          search.

     [beg[,end]]
          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 parameter subscript-
          ing  they  may  be negative to make them count from the
          last match backward. E.g.: `*(-OL[1,3])' gives  a  list
          of the names of the three largest files.

     Pstring
          The  string  will  be prepended to each glob match as a
          separate word.  string is delimited in the same way  as
          arguments to the e glob qualifier described above.  The
          qualifier can be repeated; the words are prepended sep-
          arately so that the resulting command line contains the
          words in the same order they were given in the list  of
          glob qualifiers.

          A  typical  use for this is to prepend an option before
          all occurrences of a file name; for example,  the  pat-
          tern `*(P:-f:)' produces the command line arguments `-f
          file1 -f file2 ...'

     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').
     Each modifier must be introduced by a  separate  `:'.   Note
     also  that the result after modification does not have to be
     an existing file.  The name of any existing file can be fol-
     lowed  by  a  modifier of the form `(:..)' even if no actual
     filename generation is performed,  although  note  that  the
     presence  of the parentheses causes the entire expression to
     be subjected to any global pattern matching options such  as
     NULL_GLOB. Thus:

          ls *(-/)

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





zsh 5.0.5          Last change: January 5, 2014                48






User Commands                                          ZSHEXPN(1)



          ls *(%W)

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

          ls *(W,X)

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

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

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

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

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

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

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



ATTRIBUTES
     See   attributes(5)   for   descriptions  of  the  following
     attributes:

     +---------------+------------------+
     |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
     +---------------+------------------+
     |Availability   | shell/zsh        |
     +---------------+------------------+
     |Stability      | Volatile         |
     +---------------+------------------+
NOTES
     This  software  was   built   from   source   available   at
     https://java.net/projects/solaris-userland.    The  original
     community   source   was   downloaded   from    http://down-
     loads.source-
     forge.net/project/zsh/zsh/5.0.5/zsh-5.0.5.tar.bz2

     Further information about this software can be found on  the



zsh 5.0.5          Last change: January 5, 2014                49






User Commands                                          ZSHEXPN(1)



     open source community website at http://www.zsh.org/.






















































zsh 5.0.5          Last change: January 5, 2014                50






User Commands                                         ZSHPARAM(1)



NAME
     zshparam - zsh parameters

DESCRIPTION
     A parameter has a name, a value, and a number of attributes.
     A name may be any sequence of  alphanumeric  characters  and
     underscores,  or  the  single characters `*', `@', `#', `?',
     `-', `$', or `!'.  The value may be a scalar (a string),  an
     integer,  an  array (indexed numerically), or an associative
     array (an unordered set  of  name-value  pairs,  indexed  by
     name).   To  declare the type of a parameter, or to assign a
     scalar or integer value to  a  parameter,  use  the  typeset
     builtin.

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

          name=value

     If the integer attribute, -i, is set for name, the value  is
     subject to arithmetic evaluation.  Furthermore, by replacing
     `=' with `+=', a parameter can be added or appended to.  See
     the  section  `Array  Parameters'  for  additional  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.

     In the parameter lists that follow, the mark `<S>' indicates
     that  the  parameter  is special.  Special parameters cannot
     have their type changed or their readonly  attribute  turned
     off,  and if a special parameter is unset, then later recre-
     ated, the special properties will be retained.  `<Z>'  indi-
     cates  that the parameter does not exist when the shell ini-
     tializes in sh or ksh emulation mode.

ARRAY PARAMETERS
     To assign an array value, write one of:

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

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

          typeset -a name

     Associative  arrays  must  be declared before assignment, by
     using:



zsh 5.0.5          Last change: January 5, 2014                 1






User Commands                                         ZSHPARAM(1)



          typeset -A name

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

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

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

     To create an empty array (including associative arrays), use
     one of:

          set -A name
          name=()

  Array Subscripts
     Individual elements of an array may be selected using a sub-
     script.   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 sur-
     rounded 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.

     If the  KSH_ARRAYS  option  is  not  set,  then  by  default
     accesses to an array element with a subscript that evaluates
     to zero return an empty string, while an  attempt  to  write
     such  an  element is treated as an error.  For backward com-
     patibility the KSH_ZERO_SUBSCRIPT option can be set to cause
     subscript  values 0 and 1 to be equivalent; see the descrip-
     tion of the option in zshoptions(1).

     The same subscripting syntax is used for associative arrays,
     except that no arithmetic expansion is applied to exp.  How-
     ever, the parsing rules  for  arithmetic  expressions  still
     apply, which affects the way that certain special characters
     must be protected from interpretation.  See Subscript  Pars-
     ing below for details.

     A subscript of the form `[*]' or `[@]' evaluates to all ele-
     ments of an array; there is no difference  between  the  two
     except  when  they appear within double quotes.  `"$foo[*]"'
     evaluates to `"$foo[1] $foo[2]  ..."',  whereas  `"$foo[@]"'



zsh 5.0.5          Last change: January 5, 2014                 2






User Commands                                         ZSHPARAM(1)



     evaluates  to  `"$foo[1]"  "$foo[2]"  ...'.  For associative
     arrays, `[*]' or `[@]' evaluate to all  the  values,  in  no
     particular  order.   Note  that this does not substitute the
     keys; see the documentation for the `k' flag under Parameter
     Expansion Flags in zshexpn(1) for complete details.  When an
     array parameter is referenced as `$name' (with no subscript)
     it  evaluates to `$name[*]', unless the KSH_ARRAYS option is
     set in which case it evaluates to `${name[0]}' (for an asso-
     ciative  array,  this  means the value of the key `0', which
     may not exist even if there are values for other keys).

     A subscript of the form `[exp1,exp2]' selects  all  elements
     in  the  range  exp1 to exp2, inclusive. (Associative arrays
     are unordered, and so do not support ranges.) If one of  the
     subscripts  evaluates to a negative number, say -n, then the
     nth element from  the  end  of  the  array  is  used.   Thus
     `$foo[-3]'  is  the  third element from the end of the array
     foo, and `$foo[1,-1]' is the same as `$foo[*]'.

     Subscripting may also be performed on non-array  values,  in
     which   case  the  subscripts  specify  a  substring  to  be
     extracted.  For example, if FOO is  set  to  `foobar',  then
     `echo $FOO[2,5]' prints `ooba'.

  Array Element Assignment
     A  subscript  may  be used on the left side of an assignment
     like so:

          name[exp]=value

     In this form of assignment the element or range specified by
     exp  is  replaced  by  the expression on the right side.  An
     array (but not an  associative  array)  may  be  created  by
     assignment  to  a  range or element.  Arrays do not nest, so
     assigning a parenthesized list of values to  an  element  or
     range  changes the number of elements in the array, shifting
     the other elements to accommodate the new values.  (This  is
     not supported for associative arrays.)

     This  syntax  also  works as an argument to the typeset com-
     mand:

          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 brack-
     ets from being interpreted as filename generation operators.
     The noglob precommand modifier could be used instead.

     To delete an element of an ordinary array,  assign  `()'  to
     that element.  To delete an element of an associative array,



zsh 5.0.5          Last change: January 5, 2014                 3






User Commands                                         ZSHPARAM(1)



     use the unset command:

          unset "name[exp]"

  Subscript Flags
     If the opening bracket, or the comma in a range, in any sub-
     script  expression is directly followed by an opening paren-
     thesis, the string up to the matching closing one is consid-
     ered to be a list of flags, as in `name[(flags)exp]'.

     The  flags  s,  n  and  b take an argument; the delimiter is
     shown below as `:', but any character, or the matching pairs
     `(...)', `{...}', `[...]', or `<...>', may be used, but note
     that `<...>' can only be used if the subscript is  inside  a
     double   quoted   expression  or  a  parameter  substitution
     enclosed in braces as otherwise  the  expression  is  inter-
     preted as a redirection.

     The flags currently understood are:

     w    If the parameter subscripted is a scalar then this flag
          makes subscripting work on words instead of characters.
          The  default  word  separator is whitespace.  This flag
          may not be used with the i or I flag.

     s:string:
          This gives the string that  separates  words  (for  use
          with  the  w flag).  The delimiter character : is arbi-
          trary; see above.

     p    Recognize  the  same  escape  sequences  as  the  print
          builtin  in  the  string  argument  of a subsequent `s'
          flag.

     f    If the parameter subscripted is a scalar then this flag
          makes subscripting work on lines instead of characters,
          i.e. with elements separated by newlines.   This  is  a
          shorthand for `pws:\n:'.

     r    Reverse subscripting: if this flag is given, the exp is
          taken as a pattern and the result is the first matching
          array  element,  substring or word (if the parameter is
          an array, if it is a scalar, or if it is a  scalar  and
          the  `w'  flag  is given, respectively).  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 possible if  the  parameter  is
          not an associative array.  If the parameter is an asso-
          ciative array, only the value part of each pair is com-
          pared to the pattern, and the result is that value.





zsh 5.0.5          Last change: January 5, 2014                 4






User Commands                                         ZSHPARAM(1)



          If  a  search  through  an  ordinary  array failed, the
          search sets the subscript to one past the  end  of  the
          array,  and  hence ${array[(r)pattern]} will substitute
          the empty string.  Thus the success of a search can  be
          tested by using the (i) flag, for example (assuming the
          option KSH_ARRAYS is not in effect):

               [[ ${array[(i)pattern]} -le ${#array} ]]

          If KSH_ARRAYS is in effect, the -le should be  replaced
          by -lt.

     R    Like  `r',  but  gives the last match.  For associative
          arrays, gives all possible matches.  May  be  used  for
          assigning  to  ordinary  array  elements,  but  not for
          assigning to associative arrays.  On failure, for  nor-
          mal arrays this has the effect of returning the element
          corresponding to subscript 0; this is empty unless  one
          of  the  options KSH_ARRAYS or KSH_ZERO_SUBSCRIPT is in
          effect.

          Note that in subscripts with both `r' and  `R'  pattern
          characters are active even if they were substituted for
          a parameter (regardless of the  setting  of  GLOB_SUBST
          which  controls  this  feature in normal pattern match-
          ing).  The flag `e' can be  added  to  inhibit  pattern
          matching.  As this flag does not inhibit other forms of
          substitution, care is still required; using a parameter
          to hold the key has the desired effect:

               key2='original key'
               print ${array[(Re)$key2]}

     i    Like  `r',  but  gives  the index of the match instead;
          this may not be combined with a  second  argument.   On
          the  left side of an assignment, behaves like `r'.  For
          associative arrays, the key part of each pair  is  com-
          pared  to the pattern, and the first matching key found
          is the result.  On failure substitutes  the  length  of
          the  array plus one, as discussed under the description
          of `r', or the empty string for an associative array.

     I    Like `i', but gives the index of the last match, or all
          possible  matching  keys  in  an associative array.  On
          failure substitutes 0, or the empty string for an asso-
          ciative array.  This flag is best when testing for val-
          ues or keys that do not exist.

     k    If used in a subscript on an  associative  array,  this
          flag causes the keys to be interpreted as patterns, and
          returns the value for the first key found where exp  is
          matched by the key.  Note this could be any such key as



zsh 5.0.5          Last change: January 5, 2014                 5






User Commands                                         ZSHPARAM(1)



          no ordering of associative  arrays  is  defined.   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'.

     n:expr:
          If  combined with `r', `R', `i' or `I', makes them give
          the nth or nth last match (if  expr  evaluates  to  n).
          This  flag  is  ignored  when the array is associative.
          The delimiter character : is arbitrary; see above.

     b:expr:
          If combined with `r', `R', `i' or `I', makes them begin
          at  the nth or nth last element, word, or character (if
          expr evaluates to n).  This flag is  ignored  when  the
          array  is  associative.   The  delimiter character : is
          arbitrary; see above.

     e    This flag causes any pattern  matching  that  would  be
          performed on the subscript to use plain string matching
          instead.   Hence  `${array[(re)*]}'  matches  only  the
          array  element whose value is *.  Note that other forms
          of substitution such as parameter substitution are  not
          inhibited.

          This flag can also be used to force * or @ to be inter-
          preted as a single key rather than as  a  reference  to
          all  values.   It may be used for either purpose on the
          left side of an assignment.

     See Parameter Expansion Flags  (zshexpn(1))  for  additional
     ways to manipulate the results of array subscripting.

  Subscript Parsing
     This  discussion  applies  mainly  to  associative array key
     strings and to patterns used for reverse  subscripting  (the
     `r', `R', `i', etc. flags), but it may also affect parameter
     substitutions that appear as part of an  arithmetic  expres-
     sion in an ordinary subscript.

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

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


     This adds a new key/value pair if the  key  is  not  already
     present,  and  replaces the value for the existing key if it



zsh 5.0.5          Last change: January 5, 2014                 6






User Commands                                         ZSHPARAM(1)



     is.

     The basic rule to remember when writing a subscript  expres-
     sion  is that all text between the opening `[' and the clos-
     ing `]' 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  dou-
     ble-quoted strings or inside other subscript expressions (or
     both!), so the rules have two important differences.

     The first difference is that brackets  (`['  and  `]')  must
     appear  as  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 pro-
     tect parentheses or braces are removed during parsing.  This
     is  because  parameter  expansions may be surrounded by bal-
     anced braces, and subscript flags are introduced by balanced
     parentheses.

     The  second  difference  is  that  a  double-quote (`"') may
     appear as part of a subscript expression without being  pre-
     ceded  by a backslash, and therefore that the two characters
     `\"' remain as two characters in the subscript (in true dou-
     ble-quoting,  `\"'  becomes  `"').   However, because of the
     standard shell quoting rules, any double-quotes that  appear
     must occur in balanced pairs unless preceded by a backslash.
     This makes it more difficult to write a subscript expression
     that  contains an odd number of double-quote characters, but
     the reason for this difference is so that when  a  subscript
     expression  appears inside true double-quotes, one can still
     write `\"' (rather than `\\\"') for `"'.

     To use an odd number of double quotes as a key in an assign-
     ment,  use the typeset builtin and an enclosing pair of dou-
     ble quotes; to refer to the value of  that  key,  again  use
     double quotes:

          typeset -A aa
          typeset "aa[one\"two\"three\"quotes]"=QQQ
          print "$aa[one\"two\"three\"quotes]"



zsh 5.0.5          Last change: January 5, 2014                 7






User Commands                                         ZSHPARAM(1)



     It is important to note that the quoting rules do not change
     when a parameter expansion with a subscript is nested inside
     another  subscript expression.  That is, it is not necessary
     to use additional backslashes  within  the  inner  subscript
     expression;  they  are removed only once, from the innermost
     subscript outwards.  Parameters are also expanded  from  the
     innermost  subscript first, as each expansion is encountered
     left to right in the outer expression.

     A further complication arises from a way in which  subscript
     parsing  is  not different from double quote parsing.  As in
     true double-quoting, the sequences `\*', and `\@' remain  as
     two  characters  when they appear in a subscript expression.
     To use a literal `*' or `@' as an associative array key, the
     `e' flag must be used:

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

     A  last  detail must be considered when reverse subscripting
     is performed.  Parameters appearing in the subscript expres-
     sion  are first expanded and then the complete expression is
     interpreted as a pattern.   This  has  two  effects:  first,
     parameters behave as if GLOB_SUBST were on (and it cannot be
     turned off); second, backslashes are interpreted twice, once
     when  parsing the array subscript and again when parsing the
     pattern.  In a reverse subscript, it's necessary to use four
     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  back-
     slashes, brackets, parentheses, etc., are seen only when the
     complete expression is converted to a pattern.  To match the
     value  of  a  parameter  literally  in  a reverse subscript,
     rather than as a pattern, use `${(q)name}' (see  zshexpn(1))
     to quote the expanded value.

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

     One  final  note,  not directly related to subscripting: the
     numeric names of positional parameters (described below) are
     parsed  specially,  so  for example `$2foo' is equivalent to
     `${2}foo'.  Therefore, to use subscript syntax to extract  a
     substring from a positional parameter, the expansion must be
     surrounded by braces; for example, `${2[3,5]}' evaluates  to
     the  third through fifth characters of the second positional
     parameter, but `$2[3,5]'  is  the  entire  second  parameter



zsh 5.0.5          Last change: January 5, 2014                 8






User Commands                                         ZSHPARAM(1)



     concatenated with the filename generation pattern `[3,5]'.

POSITIONAL PARAMETERS
     The positional parameters provide access to the command-line
     arguments of a shell function, shell script,  or  the  shell
     itself;  see  the section `Invocation', and also the section
     `Functions'.  The parameter n, where n is a number,  is  the
     nth  positional  parameter.  The parameter `$0' is a special
     case, see the section `Parameters Set By The Shell'.

     The parameters *, @ and argv are arrays containing  all  the
     positional  parameters; thus `$argv[n]', etc., is equivalent
     to  simply  `$n'.   Note  that  the  options  KSH_ARRAYS  or
     KSH_ZERO_SUBSCRIPT  apply  to  these arrays as well, so with
     either of those options set, `${argv[0]}' is  equivalent  to
     `$1' and so on.

     Positional  parameters  may  be  changed  after the shell or
     function starts by using the set builtin,  by  assigning  to
     the  argv  array,  or  by  direct  assignment  of  the  form
     `n=value' where n is the number of the positional  parameter
     to be changed.  This also creates (with empty values) any of
     the positions from 1 to n that do not already  have  values.
     Note  that, because the positional parameters form an array,
     an array 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 necessary to accommo-
     date the new values.

LOCAL PARAMETERS
     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 outer-
     most scope.

     Local parameters disappear when their scope ends.  unset can
     be  used  to  delete a parameter while it is still in scope;
     any outer parameter of the same name remains hidden.

     Special parameters may also be made local; they retain their
     special   attributes  unless  either  the  existing  or  the
     newly-created parameter has the -h (hide)  attribute.   This
     may  have  unexpected effects: there is no default value, so
     if there is no assignment at the point the variable is  made



zsh 5.0.5          Last change: January 5, 2014                 9






User Commands                                         ZSHPARAM(1)



     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.

PARAMETERS SET BY THE SHELL
     The following parameters are automatically set by the shell:

     ! <S>
          The process ID of the last command started in the back-
          ground  with  &, or put into the background with the bg
          builtin.

     # <S>
          The number of positional parameters in  decimal.   Note
          that  some  confusion may occur with the syntax $#param
          which substitutes the length of  param.   Use  ${#}  to
          resolve   ambiguities.   In  particular,  the  sequence
          `$#-...' in an arithmetic expression is interpreted  as
          the length of the parameter -, q.v.

     ARGC <S> <Z>
          Same as #.

     $ <S>
          The process ID of this shell.  Note that this indicates
          the original shell started by invoking  zsh;  all  pro-
          cesses  forked  from the shells without executing a new
          program, such as subshells started by (...), substitute
          the same value.

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



zsh 5.0.5          Last change: January 5, 2014                10






User Commands                                         ZSHPARAM(1)



     @ <S>
          Same as argv[@], even when argv is not set.

     ? <S>
          The exit status returned by the last command.

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

     status <S> <Z>
          Same as ?.

     pipestatus <S> <Z>
          An  array  containing the exit statuses returned by all
          commands in the last pipeline.

     _ <S>
          The last argument of the previous command.  Also,  this
          parameter  is  set  in the environment of every command
          executed to the full pathname of the command.

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

     EGID <S>
          The  effective  group  ID of the shell process.  If you
          have sufficient privileges, you may change  the  effec-
          tive group ID of the shell process by assigning to this
          parameter.  Also (assuming sufficient privileges),  you
          may  start  a single command with a different effective
          group ID by `(EGID=gid; command)'

     EUID <S>
          The effective user ID of the  shell  process.   If  you
          have  sufficient  privileges, you may change the effec-
          tive user ID of the shell process by assigning to  this
          parameter.   Also (assuming sufficient privileges), you
          may start a single command with a  different  effective
          user ID by `(EUID=uid; command)'

     ERRNO <S>
          The  value  of  errno (see errno(3)) as set by the most
          recently failed system  call.   This  value  is  system
          dependent  and  is intended for debugging purposes.  It
          is also useful with the zsh/system module which  allows
          the number to be turned into a name or message.

     GID <S>



zsh 5.0.5          Last change: January 5, 2014                11






User Commands                                         ZSHPARAM(1)



          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  sin-
          gle  command  under  a different group ID by `(GID=gid;
          command)'

     HISTCMD
          The current  history  line  number  in  an  interactive
          shell,  in  other words the line number for the command
          that caused $HISTCMD to be read.

     HOST The current hostname.

     LINENO <S>
          The line number of the current line within the  current
          script, sourced file, or shell function being executed,
          whichever was started most recently.  Note that in  the
          case  of  shell functions the line number refers to the
          function as it appeared in the original definition, not
          necessarily as displayed by the functions builtin.

     LOGNAME
          If  the  corresponding variable is not set in the envi-
          ronment of the shell, it is initialized  to  the  login
          name  corresponding  to the current login session. This
          parameter is exported by default but this can  be  dis-
          abled using the typeset builtin.

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

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

     OPTARG <S>
          The  value of the last option argument processed by the
          getopts command.

     OPTIND <S>
          The index of the last option argument processed by  the
          getopts command.

     OSTYPE
          The operating system, as determined at compile time.

     PPID <S>
          The  process ID of the parent of the shell.  As for $$,
          the value indicates the parent of  the  original  shell
          and does not change in subshells.



zsh 5.0.5          Last change: January 5, 2014                12






User Commands                                         ZSHPARAM(1)



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

     RANDOM <S>
          A pseudo-random integer from 0 to 32767,  newly  gener-
          ated  each time this parameter is referenced.  The ran-
          dom number generator  can  be  seeded  by  assigning  a
          numeric value to RANDOM.

          The  values  of RANDOM form an intentionally-repeatable
          pseudo-random sequence; subshells that reference RANDOM
          will  result  in  identical pseudo-random values unless
          the value of RANDOM is referenced or seeded in the par-
          ent shell in between subshell invocations.

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

          Unlike other special parameters, the type of  the  SEC-
          ONDS  parameter  can  be changed using the typeset com-
          mand.  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   value   is  available  to  microsecond  accuracy,
          although the  shell  may  show  more  or  fewer  digits
          depending on the use of typeset.  See the documentation
          for the builtin  typeset  in  zshbuiltins(1)  for  more
          details.

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

     signals
          An array containing the names of the signals.

     TRY_BLOCK_ERROR <S>
          In  an  always  block,  indicates whether the preceding
          list of code caused an error.  The value is 1 to  indi-
          cate  an error, 0 otherwise.  It may be reset, clearing
          the error condition.   See  Complex  Commands  in  zsh-
          misc(1)

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

     TTYIDLE <S>
          The idle time of the tty associated with the  shell  in
          seconds or -1 if there is no such tty.

     UID <S>



zsh 5.0.5          Last change: January 5, 2014                13






User Commands                                         ZSHPARAM(1)



          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 (assum-
          ing sufficient privileges), you may start a single com-
          mand 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 privileges,  you
          may change the username (and also the user ID and group
          ID) of the shell by assigning to this parameter.   Also
          (assuming  sufficient privileges), you may start a sin-
          gle command under a different username (and user ID and
          group ID) by `(USERNAME=username; command)'

     VENDOR
          The vendor, as determined at compile time.

     zsh_eval_context <S> <Z> (ZSH_EVAL_CONTEXT <S>)
          An  array (colon-separated list) indicating the context
          of shell code that is being run.  Each time a piece  of
          shell  code that is stored within the shell is executed
          a string is temporarily appended to the array to  indi-
          cate  the  type  of  operation that is being performed.
          Read in order the array  gives  an  indication  of  the
          stack of operations being performed with the most imme-
          diate context last.

          Note that the variable does  not  give  information  on
          syntactic  context such as pipelines or subshells.  Use
          $ZSH_SUBSHELL to detect subshells.

          The context is one of the following:
          cmdarg
               Code specified by the -c  option  to  the  command
               line that invoked the shell.

          cmdsubst
               Command  substitution  using  the  `...` or $(...)
               construct.

          equalsubst
               File substitution using the =(...) construct.

          eval Code executed by the eval builtin.

          evalautofunc
               Code executed with the KSH_AUTOLOAD  mechanism  in
               order to define an autoloaded function.

          fc   Code  from  the  shell  history executed by the -e
               option to the fc builtin.



zsh 5.0.5          Last change: January 5, 2014                14






User Commands                                         ZSHPARAM(1)



          file Lines of code being read directly from a file, for
               example by the source builtin.

          filecode
               Lines  of code being read from a .zwc file instead
               of directly from the source file.

          globqual
               Code executed by the e or + glob qualifier.

          globsort
               Code executed to order files by the o glob  quali-
               fier.

          insubst
               File substitution using the <(...) construct.

          loadautofunc
               Code  read  directly  from  a  file  to  define an
               autoloaded function.

          outsubst
               File substitution using the >(...) construct.

          sched
               Code executed by the sched builtin.

          shfunc
               A shell function.

          stty Code passed to stty by the STTY environment  vari-
               able.   Normally  this  is  passed directly to the
               system's stty command, so this value  is  unlikely
               to be seen in practice.

          style
               Code  executed as part of a style retrieved by the
               zstyle builtin from the zsh/zutil module.

          toplevel
               The highest execution level of a script or  inter-
               active shell.

          trap Code  executed  as  a  trap  defined  by  the trap
               builtin.  Traps defined as functions have the con-
               text  shfunc.   As traps are asynchronous they may
               have a different hierarchy from other code.

          zpty Code  executed  by  the  zpty  builtin  from   the
               zsh/zpty module.

          zregexparse-guard



zsh 5.0.5          Last change: January 5, 2014                15






User Commands                                         ZSHPARAM(1)



               Code  executed  as a guard by the zregexparse com-
               mand from the zsh/zutil module.

          zregexparse-action
               Code executed as an action by the zregexparse com-
               mand from the zsh/zutil module.

     ZSH_NAME
          Expands  to  the basename of the command used to invoke
          this instance of zsh.

     ZSH_PATCHLEVEL
          The revision string  for  the  version  number  of  the
          ChangeLog  file  in the zsh distribution.  This is most
          useful in order to keep track of versions of the  shell
          during  development  between releases; hence most users
          should not use it and should instead rely on  $ZSH_VER-
          SION.

     zsh_scheduled_events
          See  the  section  `The  zsh/sched  Module'  in zshmod-
          ules(1).

     ZSH_SUBSHELL
          Readonly integer.   Initially  zero,  incremented  each
          time the shell forks to create a subshell for executing
          code.  Hence `(print $ZSH_SUBSHELL)' and `print $(print
          $ZSH_SUBSHELL)'  output  1,  while  `( (print $ZSH_SUB-
          SHELL) )' outputs 2.

     ZSH_VERSION
          The version number of the release of zsh.

PARAMETERS USED BY THE SHELL
     The following parameters are used by the shell.

     In cases where there are two parameters with an  upper-  and
     lowercase  form of the same name, such as path and PATH, the
     lowercase form is an array  and  the  uppercase  form  is  a
     scalar  with  the  elements  of the array joined together by
     colons.  These are similar to tied  parameters  created  via
     `typeset  -T'.   The normal use for the colon-separated form
     is for exporting to the environment, while the array form is
     easier  to manipulate within the shell.  Note that unsetting
     either of the pair will unset the other; they  retain  their
     special properties when recreated, and recreating one of the
     pair will recreate the other.

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



zsh 5.0.5          Last change: January 5, 2014                16






User Commands                                         ZSHPARAM(1)



     BAUD The rate in bits per second at which data  reaches  the
          terminal.  The line editor will use this value in order
          to compensate for a slow terminal by  delaying  updates
          to  the  display  until necessary.  If the parameter is
          unset or the value is zero the  compensation  mechanism
          is turned off.  The parameter is not set by default.

          This  parameter  may  be profitably set in some circum-
          stances, e.g.  for slow modems dialing into a  communi-
          cations  server,  or  on  a slow wide area network.  It
          should be set to the baud rate of the slowest  part  of
          the link for best performance.

     cdpath <S> <Z> (CDPATH <S>)
          An array (colon-separated list) of directories specify-
          ing the search path for the cd command.

     COLUMNS <S>
          The number of columns for this terminal session.   Used
          for printing select lists and for the line editor.

     CORRECT_IGNORE
          If set, is treated as a pattern during spelling correc-
          tion.  Any potential correction that matches  the  pat-
          tern  is  ignored.   For  example, if the value is `_*'
          then completion functions (which, by  convention,  have
          names  beginning  with  `_')  will  never be offered as
          spelling corrections.  The pattern does  not  apply  to
          the  correction  of  file names, as applied by the COR-
          RECT_ALL option (so with the example just  given  files
          beginning with `_' in the current directory would still
          be completed).

     DIRSTACKSIZE
          The maximum size of the  directory  stack,  by  default
          there is no limit.  If the stack gets larger than this,
          it will be truncated  automatically.   This  is  useful
          with the AUTO_PUSHD option.

     ENV  If  the  ENV  environment  variable  is set when zsh is
          invoked as sh or ksh, $ENV is sourced after the profile
          scripts.   The  value  of ENV is subjected to parameter
          expansion, command substitution, and arithmetic  expan-
          sion 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.   If  FCEDIT  is
          not  set,  the parameter EDITOR is used; if that is not
          set either, a builtin default, usually vi, is used.

     fignore <S> <Z> (FIGNORE <S>)



zsh 5.0.5          Last change: January 5, 2014                17






User Commands                                         ZSHPARAM(1)



          An array (colon separated list) containing the suffixes
          of  files  to  be  ignored  during filename completion.
          However, if completion only generates files  with  suf-
          fixes in this list, then these files are completed any-
          way.

     fpath <S> <Z> (FPATH <S>)
          An array (colon separated list) of directories specify-
          ing  the  search  path  for function definitions.  This
          path is searched when a function with the -u  attribute
          is referenced.  If an executable file is found, then it
          is read and executed in the current environment.

     histchars <S>
          Three characters used by the shell's history and  lexi-
          cal  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 `#').

          The  characters must be in the ASCII character set; any
          attempt  to  set  histchars  to   characters   with   a
          locale-dependent meaning will be rejected with an error
          message.

     HISTCHARS <S> <Z>
          Same as histchars.  (Deprecated.)

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

     HISTORY_IGNORE
          If  set,  is  treated  as a pattern at the time history
          files are written.  Any potential  history  entry  that
          matches  the  pattern  is skipped.  For example, if the
          value is `fc *' then commands that invoke the  interac-
          tive  history  editor  are never written to the history
          file (compare the HIST_NO_STORE option  or  the  zshad-
          dhistory  hook, either of which would prevent such com-
          mands from being added to the  interactive  history  at
          all).

     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 sav-
          ing duplicated history events.

     HOME <S>



zsh 5.0.5          Last change: January 5, 2014                18






User Commands                                         ZSHPARAM(1)



          The  default  argument for the cd command.  This is not
          set automatically by the shell in sh, ksh or csh emula-
          tion,  but  it  is typically present in the environment
          anyway, and if it becomes set it has its usual  special
          behaviour.

     IFS <S>
          Internal  field separators (by default space, tab, new-
          line 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 charac-
          ter.

          If the parameter is unset, the default is  used.   Note
          this  has a different effect from setting the parameter
          to an empty string.

     KEYBOARD_HACK
          This variable defines a character to  be  removed  from
          the  end  of  the  command  line before interpreting it
          (interactive shells only). It is intended  to  fix  the
          problem with keys placed annoyingly close to return and
          replaces the SUNKEYBOARDHACK option which did this  for
          backquotes only.  Should the chosen character be one of
          singlequote, doublequote or backquote, there must  also
          be  an  odd  number of them on the command line for the
          last one to be removed.

          For  backward  compabitility,  if  the  SUNKEYBOARDHACK
          option  is  explicitly  set, the value of KEYBOARD_HACK
          reverts to backquote.   If  the  option  is  explicitly
          unset, this variable is set to empty.

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

     LANG <S>
          This  variable  determines  the locale category for any
          category  not  specifically  selected  via  a  variable
          starting with `LC_'.

     LC_ALL <S>
          This   variable  overrides  the  value  of  the  `LANG'



zsh 5.0.5          Last change: January 5, 2014                19






User Commands                                         ZSHPARAM(1)



          variable and the value of any of  the  other  variables
          starting with `LC_'.

     LC_COLLATE <S>
          This  variable determines the locale category for char-
          acter  collation  information  within  ranges  in  glob
          brackets and for sorting.

     LC_CTYPE <S>
          This  variable determines the locale category for char-
          acter handling functions.  If the MULTIBYTE  option  is
          in  effect this variable or LANG should contain a value
          that reflects the character set in use, even if it is a
          single-byte character set, unless only the 7-bit subset
          (ASCII) is used.  For example, if the character set  is
          ISO-8859-1,  a  suitable  value might be en_US.iso88591
          (certain  Linux   distributions)   or   en_US.ISO8859-1
          (MacOS).

     LC_MESSAGES <S>
          This variable determines the language in which messages
          should be written.  Note that zsh does not use  message
          catalogs.

     LC_NUMERIC <S>
          This  variable  affects the decimal point character and
          thousands  separator  character   for   the   formatted
          input/output functions and string conversion functions.
          Note that zsh ignores this setting when parsing  float-
          ing point mathematical expressions.

     LC_TIME <S>
          This  variable  determines the locale category for date
          and time formatting in prompt escape sequences.

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

     LISTMAX
          In the line editor, the number of matches to list with-
          out asking first. If the value is  negative,  the  list
          will  be  shown  if  it  spans at most as many lines as
          given by the absolute value.  If set to zero, the shell
          asks  only  if  the top of the listing would scroll off
          the screen.

     LOGCHECK
          The interval in seconds between checks for login/logout
          activity using the watch parameter.

     MAIL If  this  parameter is set and mailpath is not set, the



zsh 5.0.5          Last change: January 5, 2014                20






User Commands                                         ZSHPARAM(1)



          shell looks for mail in the specified file.

     MAILCHECK
          The interval in seconds between checks for new mail.

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

     manpath <S> <Z> (MANPATH <S> <Z>)
          An array (colon-separated list) whose value is not used
          by the shell.  The manpath array can  be  useful,  how-
          ever,  since  setting  it  also  sets MANPATH, and vice
          versa.

     match
     mbegin
     mend Arrays set by the shell when the  b  globbing  flag  is
          used  in  pattern matches.  See the subsection Globbing
          flags in the documentation for Filename  Generation  in
          zshexpn(1).

     MATCH
     MBEGIN
     MEND Set  by  the  shell when the m globbing flag is used in
          pattern matches.  See the subsection Globbing flags  in
          the  documentation  for  Filename  Generation  in  zsh-
          expn(1).

     module_path <S> <Z> (MODULE_PATH <S>)
          An array (colon-separated  list)  of  directories  that
          zmodload  searches  for  dynamically  loadable modules.
          This is initialized to  a  standard  pathname,  usually
          `/usr/local/lib/zsh/$ZSH_VERSION'.                 (The
          `/usr/local/lib'  part  varies  from  installation   to
          installation.)   For security reasons, any value set in
          the environment when  the  shell  is  started  will  be
          ignored.

          These  parameters  only  exist if the installation sup-
          ports dynamic module loading.

     NULLCMD <S>
          The command name to assume if a redirection  is  speci-
          fied  with  no  command.   Defaults to cat.  For sh/ksh



zsh 5.0.5          Last change: January 5, 2014                21






User Commands                                         ZSHPARAM(1)



          behavior, change this to  :.   For  csh-like  behavior,
          unset  this  parameter;  the  shell will print an error
          message if null commands are entered.

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

     POSTEDIT <S>
          This  string  is output whenever the line editor exits.
          It usually contains termcap strings to reset the termi-
          nal.

     PROMPT <S> <Z>
     PROMPT2 <S> <Z>
     PROMPT3 <S> <Z>
     PROMPT4 <S> <Z>
          Same as PS1, PS2, PS3 and PS4, respectively.

     prompt <S> <Z>
          Same as PS1.

     PROMPT_EOL_MARK
          When  the  PROMPT_CR and PROMPT_SP options are set, the
          PROMPT_EOL_MARK parameter can be used to customize  how
          the  end  of  partial  lines are shown.  This parameter
          undergoes prompt  expansion,  with  the  PROMPT_PERCENT
          option set.  If not set, the default behavior is equiv-
          alent to the value `%B%S%#%s%b'.

     PS1 <S>
          The primary prompt string, printed before a command  is
          read.   It undergoes a special form of expansion before
          being displayed; see EXPANSION OF PROMPT  SEQUENCES  in
          zshmisc(1).  The default is `%m%# '.

     PS2 <S>
          The secondary prompt, printed when the shell needs more
          information to complete a command.  It is  expanded  in
          the same way as PS1.  The default is `%_> ', which dis-
          plays any shell constructs or quotation marks which are
          currently being processed.

     PS3 <S>
          Selection  prompt  used  within  a  select loop.  It is
          expanded in the same way as PS1.  The default is `?# '.

     PS4 <S>
          The  execution  trace  prompt.   Default is `+%N:%i> ',
          which displays the name of the current shell  structure



zsh 5.0.5          Last change: January 5, 2014                22






User Commands                                         ZSHPARAM(1)



          and the line number within it.  In sh or ksh emulation,
          the default is `+ '.

     psvar <S> <Z> (PSVAR <S>)
          An array (colon-separated list) whose elements  can  be
          used in PROMPT strings.  Setting psvar also sets PSVAR,
          and vice versa.

     READNULLCMD <S>
          The command name to assume if a single input  redirect-
          ion is specified with no command.  Defaults to more.

     REPORTTIME
          If nonnegative, commands whose combined user and system
          execution times (measured in seconds) are greater  than
          this  value  have  timing  statistics printed for them.
          Output is suppressed for commands executed  within  the
          line  editor, including completion; commands explicitly
          marked with the time keyword still cause the summary to
          be printed in this case.

     REPLY
          This parameter is reserved by convention to pass string
          values between shell scripts and shell builtins in sit-
          uations where a function call or redirection are impos-
          sible or undesirable.  The read builtin and the  select
          complex  command may set REPLY, and filename generation
          both sets and examines its value when  evaluating  cer-
          tain  expressions.   Some modules also employ REPLY for
          similar purposes.

     reply
          As REPLY, but for array values rather than strings.

     RPROMPT <S>
     RPS1 <S>
          This prompt is displayed on the right-hand side of  the
          screen  when  the  primary prompt is being displayed on
          the left.  This does not work  if  the  SINGLE_LINE_ZLE
          option  is set.  It is expanded in the same way as PS1.

     RPROMPT2 <S>
     RPS2 <S>
          This prompt is displayed on the right-hand side of  the
          screen  when the secondary prompt is being displayed on
          the left.  This does not work  if  the  SINGLE_LINE_ZLE
          option  is set.  It is expanded in the same way as PS2.

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




zsh 5.0.5          Last change: January 5, 2014                23






User Commands                                         ZSHPARAM(1)



     SPROMPT <S>
          The  prompt used for spelling correction.  The sequence
          `%R' expands  to  the  string  which  presumably  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 environment,
          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 sus-
          pended. If the command is suspended and continued later
          with  the  fg  or  wait  builtins it will see the modes
          specified by STTY, as if it were not  suspended.   This
          (intentionally)  does  not apply if the command is con-
          tinued via `kill -CONT'.  STTY is ignored if  the  com-
          mand is run in the background, or if it is in the envi-
          ronment of the shell but not explicitly assigned to  in
          the  input  line.  This  avoids  running  stty at every
          external command by  accidentally  exporting  it.  Also
          note that STTY should not be used for window size spec-
          ifications; these will not be local to the command.

     TERM <S>
          The type of terminal in use.  This is used when looking
          up termcap sequences.  An assignment to 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 terminal type in order for the
          new settings to take effect.

     TERMINFO <S>
          A reference to a compiled description of the  terminal,
          used  by the `terminfo' library when the system has it;
          see terminfo(5).  If set,  this  causes  the  shell  to
          reinitialise   the   terminal,  making  the  workaround
          `TERM=$TERM' unnecessary.

     TIMEFMT
          The format of process time reports with the  time  key-
          word.  The default is `%J  %U user %S system %P cpu %*E
          total'.  Recognizes  the  following  escape  sequences,
          although  not  all may be available on all systems, and
          some that are available may not be useful:

          %%   A `%'.
          %U   CPU seconds spent in user mode.
          %S   CPU seconds spent in kernel mode.
          %E   Elapsed time in seconds.
          %P   The CPU percentage, computed as (100*%U+%S)/%E.
          %W   Number of times the process was swapped.



zsh 5.0.5          Last change: January 5, 2014                24






User Commands                                         ZSHPARAM(1)



          %X   The average amount in (shared) text space used  in
               kilobytes.
          %D   The  average amount in (unshared) data/stack space
               used in kilobytes.
          %K   The total space used (%X+%D) in kilobytes.
          %M   The  maximum memory the process had in use at  any
               time in megabytes.
          %F   The number of major page faults (page needed to be
               brought from disk).
          %R   The number of minor page faults.
          %I   The number of input operations.
          %O   The number of output operations.
          %r   The number of socket messages received.
          %s   The number of socket messages sent.
          %k   The number of signals received.
          %w   Number of voluntary context switches (waits).
          %c   Number of involuntary context switches.
          %J   The name of this job.

          A star may be inserted between  the  percent  sign  and
          flags 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 issuing a prompt. If
          there is a trap on SIGALRM, it will be executed  and  a
          new  alarm  is  scheduled  using the value of the TMOUT
          parameter after executing the trap.  If no trap is set,
          and  the idle time of the terminal is not less than the
          value of the TMOUT parameter, zsh  terminates.   Other-
          wise  a  new  alarm is scheduled to TMOUT seconds after
          the last keypress.

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

     watch <S> <Z> (WATCH <S>)
          An  array (colon-separated list) of login/logout events
          to report.  If it contains the single word `all',  then
          all  login/logout  events are reported.  If it contains
          the single word `notme', then all events  are  reported
          as  with `all' except $USERNAME.  An entry in this list
          may consist of a username, an `@' followed by a  remote
          hostname,  and  a `%' followed by a line (tty).  Any or
          all of these components may be present in an entry;  if
          a  login/logout  event  matches  all  of  them,  it  is



zsh 5.0.5          Last change: January 5, 2014                25






User Commands                                         ZSHPARAM(1)



          reported.

     WATCHFMT
          The format of login/logout reports if the watch parame-
          ter is set.  Default is `%n has %a %l from %m'.  Recog-
          nizes the following escape sequences:

          %n   The name of the user that logged in/out.

          %a   The observed action, i.e. "logged on"  or  "logged
               off".

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

          %M   The full hostname of the remote host.

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

               NOTE: The `%m' and `%M' escapes will work only  if
               there  is  a  host  name field in the utmp on your
               machine.  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.

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

          %T   The time, in 24-hour format.

          %w   The date in `day-dd' format.

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

          %D   The date in `yy-mm-dd' format.

          %(x:true-text:false-text)
               Specifies  a  ternary  expression.   The character
               following the x is arbitrary; the  same  character
               is used to separate the text for the "true" result
               from that for the "false" result.  Both the  sepa-
               rator  and  the  right  parenthesis may be escaped



zsh 5.0.5          Last change: January 5, 2014                26






User Commands                                         ZSHPARAM(1)



               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.

               If the result is `true',  then  the  true-text  is
               formatted   according   to  the  rules  above  and
               printed,  and  the  false-text  is  skipped.    If
               `false',   the   true-text   is  skipped  and  the
               false-text is formatted and  printed.   Either  or
               both  of the branches may be empty, but both sepa-
               rators must be present in any case.

     WORDCHARS <S>
     A list of non-alphanumeric characters considered part  of  a
     word by the line editor.

     ZBEEP
     If set, this gives a string of characters, which can use all
     the same codes as the bindkey command as  described  in  the
     zsh/zle  module  entry in zshmodules(1), that will be output
     to the 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 precedence over the NOBEEP option.

     ZDOTDIR
     The  directory  to  search  for shell startup files (.zshrc,
     etc), if not $HOME.

     ZLE_LINE_ABORTED
     This parameter is set by  the  line  editor  when  an  error
     occurs.   It  contains the line that was being edited at the
     point of the error.  `print -zr -- $ZLE_LINE_ABORTED' can be
     used to recover the line.  Only the most recent line of this
     kind is remembered.

     ZLE_REMOVE_SUFFIX_CHARS
     ZLE_SPACE_SUFFIX_CHARS
     These parameters are used by the line  editor.   In  certain
     circumstances  suffixes  (typically space or slash) added by
     the completion system will be removed automatically,  either
     because  the  next  editing  command  was  not an insertable



zsh 5.0.5          Last change: January 5, 2014                27






User Commands                                         ZSHPARAM(1)



     character, or because the character was marked as  requiring
     the suffix to be removed.

     These variables can contain the sets of characters that will
     cause the suffix to be removed.  If  ZLE_REMOVE_SUFFIX_CHARS
     is  set,  those  characters  will  cause  the  suffix  to be
     removed; if ZLE_SPACE_SUFFIX_CHARS is set, those  characters
     will cause the suffix to be removed and replaced by a space.

     If ZLE_REMOVE_SUFFIX_CHARS is not set, the default behaviour
     is equivalent to:

          ZLE_REMOVE_SUFFIX_CHARS=$' \t\n;&|'

     If  ZLE_REMOVE_SUFFIX_CHARS  is set but is empty, no charac-
     ters  have  this  behaviour.   ZLE_SPACE_SUFFIX_CHARS  takes
     precedence, so that the following:

          ZLE_SPACE_SUFFIX_CHARS=$'&|'

     causes  the  characters `&' and `|' to remove the suffix but
     to replace it with a space.

     To  illustrate  the  difference,  suppose  that  the  option
     AUTO_REMOVE_SLASH  is  in  effect  and the directory DIR has
     just been completed, with an appended /, following which the
     user  types  `&'.   The  default  result  is  `DIR&'.   With
     ZLE_REMOVE_SUFFIX_CHARS set but without  including  `&'  the
     result  is  `DIR/&'.   With  ZLE_SPACE_SUFFIX_CHARS  set  to
     include `&' the result is `DIR &'.

     Note that certain completions may provide their  own  suffix
     removal  or replacement behaviour which overrides the values
     described here.  See the completion system documentation  in
     zshcompsys(1).

     ZLE_RPROMPT_INDENT <S>
     If  set, used to give the indentation between the right hand
     side of the right prompt in the line editor as given by RPS1
     or  RPROMPT  and  the right hand side of the screen.  If not
     set, the value 1 is used.

     Typically this will be used to set the value to  0  so  that
     the  prompt  appears  flush  with the right hand side of the
     screen.  This is not the default as many  terminals  do  not
     handle this correctly, in particular when the prompt appears
     at the extreme bottom right of the screen.   Recent  virtual
     terminals  are  more  likely  to handle this case correctly.
     Some experimentation is necessary.






zsh 5.0.5          Last change: January 5, 2014                28






User Commands                                         ZSHPARAM(1)



ATTRIBUTES
     See  attributes(5)  for  descriptions   of   the   following
     attributes:

     +---------------+------------------+
     |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
     +---------------+------------------+
     |Availability   | shell/zsh        |
     +---------------+------------------+
     |Stability      | Volatile         |
     +---------------+------------------+
NOTES
     This   software   was   built   from   source  available  at
     https://java.net/projects/solaris-userland.   The   original
     community   source   was   downloaded   from    http://down-
     loads.source-
     forge.net/project/zsh/zsh/5.0.5/zsh-5.0.5.tar.bz2

     Further  information about this software can be found on the
     open source community website at http://www.zsh.org/.



































zsh 5.0.5          Last change: January 5, 2014                29






User Commands                                       ZSHOPTIONS(1)



NAME
     zshoptions - zsh options

SPECIFYING 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 `unsetopt
     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 `notify').

     Some options also have one  or  more  single  letter  names.
     There  are  two  sets  of single letter options: one used by
     default, and another used to emulate sh/ksh (used  when  the
     SH_OPTION_LETTERS option is set).  The single letter options
     can be used on the shell command  line,  or  with  the  set,
     setopt  and  unsetopt  builtins, as normal Unix options pre-
     ceded 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 inver-
     sion  of that name refers to the option being on.  For exam-
     ple, `+n' is the short name of `exec', and `-n' is the short
     name of its inversion, `noexec'.

     In strings of single letter options supplied to the shell at
     startup, trailing whitespace will be  ignored;  for  example
     the  string  `-f     ' will be treated just as `-f', but the
     string `-f i' is an error.  This  is  because  many  systems
     which  implement  the  `#!' mechanism for calling scripts do
     not strip trailing whitespace.

DESCRIPTION OF OPTIONS
     In the following list, options set by default in all  emula-
     tions are marked <D>; those set by default only in csh, ksh,
     sh, or zsh emulations are  marked  <C>,  <K>,  <S>,  <Z>  as
     appropriate.  When listing options (by `setopt', `unsetopt',
     `set -o' or `set +o'), those turned on by default appear  in
     the list prefixed with `no'.  Hence (unless KSH_OPTION_PRINT
     is set), `setopt'  shows  all  options  whose  settings  are
     changed from the default.

  Changing Directories
     AUTO_CD (-J)
          If a command is issued that can't be executed as a nor-
          mal command, and the command is the name  of  a  direc-
          tory, perform the cd command to that directory.




zsh 5.0.5          Last change: January 5, 2014                 1






User Commands                                       ZSHOPTIONS(1)



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

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

     CHASE_DOTS
          When changing to a directory containing a path  segment
          `..'  which would otherwise be treated as canceling the
          previous 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 the current  working
          directory  would  be removed), instead resolve the path
          to the physical directory.  This option  is  overridden
          by CHASE_LINKS.

          For  example,  suppose /foo/bar is a link to the direc-
          tory  /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 sym-
          bolic links in the path will also be resolved.

     CHASE_LINKS (-w)
          Resolve symbolic links to their true values when chang-
          ing 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 seg-
          ment is a symbolic link.

     POSIX_CD
          Modifies the behaviour of cd, chdir and pushd  commands
          to  make  them more compatible with the POSIX standard.
          The behaviour with the option unset is described in the
          documentation for the cd builtin in zshbuiltins(1).  If
          the option is set, the shell does not test for directo-
          ries  beneath the local directory (`.') until after all
          directories in cdpath have been tested.

          Also, if the option is set, the conditions under  which
          the shell prints the new directory after changing to it
          are modified.  It is no longer restricted  to  interac-
          tive  shells  (although printing of the directory stack
          with pushd is still limited to interactive shells); and
          any  use  of a component of CDPATH, including a `.' but
          excluding an empty component that is otherwise  treated
          as `.', causes the directory to be printed.



zsh 5.0.5          Last change: January 5, 2014                 2






User Commands                                       ZSHOPTIONS(1)



     PUSHD_IGNORE_DUPS
          Don't  push  multiple copies of the same directory onto
          the directory stack.

     PUSHD_MINUS
          Exchanges the meanings of `+' and `-' when used with  a
          number to specify a directory in the stack.

     PUSHD_SILENT (-E)
          Do not print the directory stack after pushd or popd.

     PUSHD_TO_HOME (-D)
          Have pushd with no arguments act like `pushd $HOME'.

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

     ALWAYS_TO_END
          If a completion is performed with the cursor  within  a
          word,  and a full completion is inserted, the cursor is
          moved to the end of the word.  That is, the  cursor  is
          moved  to  the end of the word if either a single match
          is inserted or menu completion is performed.

     AUTO_LIST (-9) <D>
          Automatically list choices on an ambiguous  completion.

     AUTO_MENU <D>
          Automatically use menu completion after the second con-
          secutive request for completion, for example by  press-
          ing  the  tab key repeatedly. This option is overridden
          by MENU_COMPLETE.

     AUTO_NAME_DIRS
          Any parameter that is set to the  absolute  name  of  a
          directory  immediately  becomes  a name for that direc-
          tory, that will be used by the `%~' and related  prompt
          sequences,  and  will  be  available when completion is
          performed on a word starting with `~'.  (Otherwise, the
          parameter must be used in the form `~param' first.)

     AUTO_PARAM_KEYS <D>
          If a parameter name was completed and a following char-
          acter (normally a space)  automatically  inserted,  and
          the  next  character typed is one of those that have to
          come directly after the name (like `}', `:', etc.), the
          automatically  added  character is deleted, so that the
          character typed comes immediately after  the  parameter



zsh 5.0.5          Last change: January 5, 2014                 3






User Commands                                       ZSHOPTIONS(1)



          name.  Completion in a brace expansion is affected sim-
          ilarly: the added character is a  `,',  which  will  be
          removed if `}' is typed next.

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

     AUTO_REMOVE_SLASH <D>
          When  the last character resulting from a completion is
          a slash and the next character typed is a  word  delim-
          iter, a slash, or a character that ends a command (such
          as a semicolon or an ampersand), remove the slash.

     BASH_AUTO_LIST
          On an ambiguous completion, automatically list  choices
          when the completion function is called twice in succes-
          sion.  This takes precedence over AUTO_LIST.  The  set-
          ting  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_COM-
          PLETE,  since  repeated  completion  calls  immediately
          cycle through the list in that case.

     COMPLETE_ALIASES
          Prevents  aliases on the command line from being inter-
          nally substituted before completion is attempted.   The
          effect is to make the alias a distinct command for com-
          pletion purposes.

     COMPLETE_IN_WORD
          If unset, the cursor is set to the end of the  word  if
          completion  is  started.  Otherwise  it stays there and
          completion is done from both ends.

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

          Note that when the pattern matcher  is  used,  matching
          control  (for  example,  case-insensitive  or  anchored
          matching) cannot be used.  This limitation only applies
          when  the current word contains a pattern; simply turn-
          ing on the GLOB_COMPLETE  option  does  not  have  this



zsh 5.0.5          Last change: January 5, 2014                 4






User Commands                                       ZSHOPTIONS(1)



          effect.

     HASH_LIST_ALL <D>
          Whenever a command completion or spelling correction is
          attempted, make sure the entire command path is  hashed
          first.   This  makes  the  first  completion slower but
          avoids false reports of spelling errors.

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

     LIST_BEEP <D>
          Beep on an ambiguous completion.  More accurately, this
          forces the completion widgets to return status 1 on  an
          ambiguous 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.

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

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

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

     MENU_COMPLETE (-Y)
          On  an  ambiguous completion, instead of listing possi-
          bilities or beeping, insert  the  first  match  immedi-
          ately.  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 direction. This option
          overrides AUTO_MENU.

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



zsh 5.0.5          Last change: January 5, 2014                 5






User Commands                                       ZSHOPTIONS(1)



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

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

     BRACE_CCL
          Expand expressions in braces which would not  otherwise
          undergo  brace expansion to a lexically ordered list of
          all the characters.  See the section `Brace Expansion'.

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

     CASE_MATCH <D>
          Make regular expressions  using  the  zsh/regex  module
          (including matches with =~) sensitive to case.

     CSH_NULL_GLOB <C>
          If  a  pattern  for filename generation has no matches,
          delete the pattern  from  the  argument  list;  do  not
          report  an  error  unless all the patterns in a command
          have no matches.  Overrides NOMATCH.

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

     EXTENDED_GLOB
          Treat  the  `#', `~' and `^' characters as part of pat-
          terns  for  filename  generation,  etc.   (An   initial
          unquoted  `~'  always  produces  named directory expan-
          sion.)

     FORCE_FLOAT
          Constants in arithmetic evaluation will be  treated  as
          floating point even without the use of a decimal point.
          Integers in any base will be converted.




zsh 5.0.5          Last change: January 5, 2014                 6






User Commands                                       ZSHOPTIONS(1)



     GLOB (+F, ksh: +f) <D>
          Perform filename generation (globbing).  (See the  sec-
          tion `Filename Generation'.)

     GLOB_ASSIGN <C>
          If  this  option is set, filename generation (globbing)
          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 assignments  of  the  form  `name=(value)'  (e.g.
          `foo=(*)')  and  this  form is recommended for clarity;
          with this option set, it is  not  possible  to  predict
          whether the result will be an array or a scalar.

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

     GLOB_SUBST <C> <K> <S>
          Treat any characters resulting from parameter expansion
          as  being eligible for file expansion and filename gen-
          eration, and any characters resulting from command sub-
          stitution  as  being  eligible for filename generation.
          Braces (and commas in between) do not  become  eligible
          for expansion.

     HIST_SUBST_PATTERN
          Substitutions using the :s and :& history modifiers are
          performed  with  pattern  matching  instead  of  string
          matching.   This  occurs wherever history modifiers are
          valid, including glob qualifiers and  parameters.   See
          the section Modifiers in zshexpn(1).

     IGNORE_BRACES (-I) <S>
          Do not perform brace expansion.  For historical reasons
          this    also    includes    the    effect    of     the
          IGNORE_CLOSE_BRACES option.

     IGNORE_CLOSE_BRACES
          When  neither  this  option nor IGNORE_BRACES is set, a
          sole close brace character `}' is syntactically signif-
          icant  at  any  point  on a command line.  This has the
          effect that no semicolon or newline is necessary before
          the  brace terminating a function or current shell con-
          struct.  When either option is set, a closing brace  is
          syntactically  significant  only  in  command position.
          Unlike IGNORE_BRACES,  this  option  does  not  disable
          brace expansion.




zsh 5.0.5          Last change: January 5, 2014                 7






User Commands                                       ZSHOPTIONS(1)



          For  example, with both options unset a function may be
          defined in the following fashion:

               args() { echo $# }

          while if either option is set, this does not  work  and
          something equivalent to the following is required:

               args() { echo $#; }

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

     MAGIC_EQUAL_SUBST
          All  unquoted  arguments  of the form `anything=expres-
          sion' appearing after the command  name  have  filename
          expansion  (that is, where expression has a leading `~'
          or `=') performed on expression as if it were a parame-
          ter  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 assign-
          ment.   For  example,  in  echo  foo=~/bar:~/rod,  both
          occurrences  of  ~  would  be replaced.  Note that this
          happens anyway with typeset and similar statements.

          This option respects the  setting  of  the  KSH_TYPESET
          option.  In other words, if both options are in effect,
          arguments looking like  assignments  will  not  undergo
          word splitting.

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

     MULTIBYTE <C> <K> <Z>
          Respect multibyte characters  when  found  in  strings.
          When this option is set, strings are examined using the
          system library to determine how many bytes form a char-
          acter,  depending  on the current locale.  This affects
          the way characters are  counted  in  pattern  matching,
          parameter values and various delimiters.

          The  option  is on by default if the shell was compiled
          with MULTIBYTE_SUPPORT except in sh  emulation;  other-
          wise  it  is off by default and has no effect if turned
          on.  The mode is off in sh emulation for  compatibility
          but for interactive use may need to be turned on if the
          terminal interprets multibyte characters.





zsh 5.0.5          Last change: January 5, 2014                 8






User Commands                                       ZSHOPTIONS(1)



          If the option is off a single byte is always treated as
          a  single  character.   This setting is designed purely
          for examining strings known to  contain  raw  bytes  or
          other  values that may not be characters in the current
          locale.  It is not necessary to unset the option merely
          because  the  character set for the current locale does
          not contain multibyte characters.

          The option does not affect the shell's  editor,   which
          always  uses  the locale to determine multibyte charac-
          ters.  This is because the character set  displayed  by
          the terminal emulator is independent of shell settings.

     NOMATCH (+3) <C> <Z>
          If a pattern for filename generation  has  no  matches,
          print  an error, instead of leaving it unchanged in the
          argument list.  This also applies to file expansion  of
          an initial `~' or `='.

     NULL_GLOB (-G)
          If  a  pattern  for filename generation has no matches,
          delete the pattern from the argument  list  instead  of
          reporting an error.  Overrides NOMATCH.

     NUMERIC_GLOB_SORT
          If  numeric filenames are matched by a filename genera-
          tion pattern, sort  the  filenames  numerically  rather
          than lexicographically.

     RC_EXPAND_PARAM (-P)
          Array  expansions  of the form `foo${xx}bar', where the
          parameter xx is set to (a b c),  are  substituted  with
          `fooabar  foobbar foocbar' instead of the default `fooa
          b cbar'.  Note that an empty array will therefore cause
          all arguments to be removed.

     REMATCH_PCRE <Z>
          If  set, regular expression matching with the =~ opera-
          tor will use Perl-Compatible Regular  Expressions  from
          the  PCRE  library,  if available.  If not set, regular
          expressions will use the extended  regexp  syntax  pro-
          vided by the system libraries.

     SH_GLOB <K> <S>
          Disables  the  special meaning of `(', `|', `)' and '<'
          for globbing the result of parameter and  command  sub-
          stitutions,  and  in  some other places where the shell
          accepts patterns.  If SH_GLOB is set  but  KSH_GLOB  is
          not,  the  shell  allows the interpretation of subshell
          expressions enclosed in parentheses in some cases where
          there  is no space before the opening parenthesis, e.g.
          !(true) is interpreted as if there were a  space  after



zsh 5.0.5          Last change: January 5, 2014                 9






User Commands                                       ZSHOPTIONS(1)



          the !.  This option is set by default if zsh is invoked
          as sh or ksh.

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

     WARN_CREATE_GLOBAL
          Print a warning message when a global parameter is cre-
          ated in a function by an assignment.  This often  indi-
          cates that a parameter has not been declared local when
          it should have been.   Parameters  explicitly  declared
          global  from  within a function using typeset -g do not
          cause a warning.  Note that there is no warning when  a
          local  parameter  is  assigned to in a nested function,
          which may also indicate an error.

  History
     APPEND_HISTORY <D>
          If this is set, zsh sessions will append their  history
          list to the history file, rather than replace it. Thus,
          multiple parallel zsh sessions will all  have  the  new
          entries  from  their history lists added to the history
          file, in the order that they exit.  The file will still
          be  periodically  re-written to trim it when the number
          of lines grows 20% beyond the value specified by $SAVE-
          HIST (see also the HIST_SAVE_BY_COPY option).

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

     EXTENDED_HISTORY <C>
          Save each command's  beginning  timestamp  (in  seconds
          since  the  epoch) and the duration (in seconds) to the
          history file.  The format of this prefixed data is:

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

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

     HIST_EXPIRE_DUPS_FIRST
          If  the internal history needs to be trimmed to add the
          current command line, setting this  option  will  cause
          the  oldest  history  event  that has a duplicate to be



zsh 5.0.5          Last change: January 5, 2014                10






User Commands                                       ZSHOPTIONS(1)



          lost before losing a unique event from the  list.   You
          should be sure to set the value of HISTSIZE to a larger
          number than SAVEHIST in order to give you some room for
          the  duplicated  events,  otherwise  this  option  will
          behave just like HIST_IGNORE_ALL_DUPS once the  history
          fills up with unique events.

     HIST_FCNTL_LOCK
          When  writing out the history file, by default zsh uses
          ad-hoc file locking to avoid known problems with  lock-
          ing  on some operating systems.  With this option lock-
          ing is done by means of the system's fcntl call,  where
          this  method is available.  On recent operating systems
          this may  provide  better  performance,  in  particular
          avoiding  history  corruption  when files are stored on
          NFS.

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

     HIST_IGNORE_ALL_DUPS
          If a new command line being added to the  history  list
          duplicates  an  older one, the older command is removed
          from the list (even if it is not the previous event).

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

     HIST_IGNORE_SPACE (-g)
          Remove  command  lines  from  the history list when the
          first character on the line is a space, or when one  of
          the  expanded  aliases  contains a leading space.  Only
          normal aliases (not global or suffix aliases) have this
          behaviour.  Note that the command lingers in the inter-
          nal history until the next command is entered before it
          vanishes,  allowing  you  to  briefly reuse or edit the
          line.  If you want to make it vanish right away without
          entering  another  command,  type  a  space  and  press
          return.

     HIST_LEX_WORDS
          By default, shell history that is read in from files is
          split  into  words on all white space.  This means that
          arguments with quoted whitespace are not correctly han-
          dled,  with the consequence that references to words in
          history lines that have been read from a  file  may  be
          inaccurate.   When  this  option  is set, words read in
          from a history file are divided up in a similar fashion
          to  normal  shell command line handling.  Although this



zsh 5.0.5          Last change: January 5, 2014                11






User Commands                                       ZSHOPTIONS(1)



          produces more accurately delimited words, if  the  size
          of  the  history file is large this can be slow.  Trial
          and error is necessary to decide.

     HIST_NO_FUNCTIONS
          Remove function  definitions  from  the  history  list.
          Note  that the function lingers in the internal history
          until the next command is entered before  it  vanishes,
          allowing you to briefly reuse or edit the definition.

     HIST_NO_STORE
          Remove  the  history  (fc  -l) command from the history
          list when invoked.  Note that the  command  lingers  in
          the  internal history until the next command is entered
          before it vanishes, allowing you to  briefly  reuse  or
          edit the line.

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

     HIST_SAVE_BY_COPY <D>
          When the history file is re-written, we normally  write
          out  a  copy  of  the file named $HISTFILE.new and then
          rename it over the old one.  However, if this option is
          unset,  we  instead  truncate  the old history file and
          write out the new version in-place.  If one of the his-
          tory-appending options is enabled, this option only has
          an effect when the enlarged history file  needs  to  be
          re-written  to trim it down to size.  Disable this only
          if you have special needs, as doing so makes it  possi-
          ble  to  lose  history  entries if zsh gets interrupted
          during the save.

          When writing out a copy of the history file,  zsh  pre-
          serves  the  old  file's permissions and group informa-
          tion, but will refuse to write out a  new  file  if  it
          would change the history file's owner.

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

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

     INC_APPEND_HISTORY
          This  options works like APPEND_HISTORY except that new
          history lines are added to the $HISTFILE  incrementally



zsh 5.0.5          Last change: January 5, 2014                12






User Commands                                       ZSHOPTIONS(1)



          (as  soon  as  they  are  entered), rather than waiting
          until the shell exits.  The file will still be periodi-
          cally  re-written  to  trim it when the number of lines
          grows 20% beyond the value specified by $SAVEHIST  (see
          also the HIST_SAVE_BY_COPY option).

     SHARE_HISTORY <K>

          This  option both imports new commands from the history
          file,  and  also  causes  your  typed  commands  to  be
          appended to the history file (the latter is like speci-
          fying INC_APPEND_HISTORY).  The history lines are  also
          output  with  timestamps  ala  EXTENDED_HISTORY  (which
          makes it easier to find the  spot  where  we  left  off
          reading the file after it gets re-written).

          By   default,   history  movement  commands  visit  the
          imported lines as well as the local lines, but you  can
          toggle  this  on and off with the set-local-history zle
          binding.  It is also possible to create  a  zle  widget
          that  will make some commands ignore imported commands,
          and some include them.

          If you find that you want more control over  when  com-
          mands  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'.

  Initialisation
     ALL_EXPORT (-a, ksh: -a)
          All  parameters  subsequently defined are automatically
          exported.

     GLOBAL_EXPORT (<Z>)
          If this option is set,  passing  the  -x  flag  to  the
          builtins  declare, float, integer, readonly and typeset
          (but not local) will  also  set  the  -g  flag;   hence
          parameters exported to the environment will not be made
          local to  the  enclosing  function,  unless  they  were
          already  or  the  flag  +g is given explicitly.  If the
          option is unset, exported parameters will be made local
          in just the same way as any other parameter.

          This  option is set by default for backward compatibil-
          ity; 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 behaviour.

     GLOBAL_RCS (-d) <D>
          If  this   option   is   unset,   the   startup   files



zsh 5.0.5          Last change: January 5, 2014                13






User Commands                                       ZSHOPTIONS(1)



          /etc/zprofile, /etc/zshrc, /etc/zlogin and /etc/zlogout
          will not be run.  It can be disabled and re-enabled  at
          any time, including inside local startup files (.zshrc,
          etc.).

     RCS (+f) <D>
          After /etc/zshenv is sourced  on  startup,  source  the
          .zshenv,  /etc/zprofile, .zprofile, /etc/zshrc, .zshrc,
          /etc/zlogin, .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  oth-
          ers  will  not be; it can be set at any time to prevent
          the remaining startup files after the currently execut-
          ing one from being sourced.

  Input/Output
     ALIASES <D>
          Expand aliases.

     CLOBBER (+C, ksh: +C) <D>
          Allows  `>' redirection to truncate existing files, and
          `>>' to create files.  Otherwise `>!' or `>|'  must  be
          used to truncate a file, and `>>!' or `>>|' to create a
          file.

     CORRECT (-0)
          Try to correct the spelling of  commands.   Note  that,
          when  the  HASH_LIST_ALL option is not set or when some
          directories in the path  are  not  readable,  this  may
          falsely report spelling errors the first time some com-
          mands are used.

          The shell variable CORRECT_IGNORE may be set to a  pat-
          tern  to match words that will never be offered as cor-
          rections.

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

     DVORAK
          Use  the Dvorak keyboard instead of the standard qwerty
          keyboard as a basis for examining spelling mistakes for
          the  CORRECT and CORRECT_ALL options and the spell-word
          editor command.

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

     IGNORE_EOF (-7)
          Do not exit on end-of-file.  Require the use of exit or



zsh 5.0.5          Last change: January 5, 2014                14






User Commands                                       ZSHOPTIONS(1)



          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 printing the
          normal warning message.  This  works  only  for  normal
          widgets, not for completion widgets.

     INTERACTIVE_COMMENTS (-k) <K> <S>
          Allow comments even in interactive shells.

     HASH_CMDS <D>
          Note  the location of each command the first time it is
          executed.  Subsequent invocations of the  same  command
          will  use  the  saved location, avoiding a path search.
          If this option is unset, no path  hashing  is  done  at
          all.   However,  when  CORRECT  is  set, commands whose
          names do not appear in the functions  or  aliases  hash
          tables  are  hashed in order to avoid reporting them as
          spelling errors.

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

     HASH_EXECUTABLES_ONLY
          When  hashing  commands because of HASH_COMMANDS, check
          that the file to be hashed is actually  an  executable.
          This option is unset by default as if the path contains
          a large number of commands, or consists of many  remote
          files,  the  additional  tests  can  take  a long time.
          Trial and error is needed to show  if  this  option  is
          beneficial.

     MAIL_WARNING (-U)
          Print  a  warning  message  if  a  mail  file  has been
          accessed since the shell last checked.

     PATH_DIRS (-Q)
          Perform a  path  search  even  on  command  names  with
          slashes  in  them.   Thus if `/usr/local/bin' is in the
          user's path, and he or she types `X11/xinit', the  com-
          mand   `/usr/local/bin/X11/xinit'   will   be  executed
          (assuming it exists).   Commands  explicitly  beginning
          with  `/',  `./'  or  `../' are not subject to the path
          search.  This also applies to the `.' builtin.





zsh 5.0.5          Last change: January 5, 2014                15






User Commands                                       ZSHOPTIONS(1)



          Note that subdirectories of the current  directory  are
          always searched for executables specified in this form.
          This takes place before any search  indicated  by  this
          option,  and  regardless  of whether `.' or the current
          directory appear in the command search path.

     PATH_SCRIPT <K> <S>
          If this option is not set, a script passed as the first
          non-option  argument to the shell must contain the name
          of the file to open.  If this option is  set,  and  the
          script does not specify a directory path, the script is
          looked for first in the current directory, then in  the
          command path.  See the section INVOCATION in zsh(1).

     PRINT_EIGHT_BIT
          Print  eight  bit  characters  literally  in completion
          lists, etc.  This option is not necessary if your  sys-
          tem  correctly  returns  the  printability of eight bit
          characters (see ctype(3)).

     PRINT_EXIT_VALUE (-1)
          Print the exit value of  programs  with  non-zero  exit
          status.   This is only available at the command line in
          interactive shells.

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

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

     RM_STAR_WAIT
          If querying the user before executing  `rm  *'  or  `rm
          path/*',  first  wait  ten  seconds and ignore anything
          typed in that time.  This avoids the problem of reflex-
          ively  answering  `yes'  to  the  query when one didn't
          really mean it.  The  wait  and  query  can  always  be
          avoided by expanding the `*' in ZLE (with tab).

     SHORT_LOOPS <C> <Z>
          Allow  the  short forms of for, repeat, select, if, and
          function constructs.

     SUN_KEYBOARD_HACK (-L)
          If a line ends with a backquote, and there are  an  odd
          number  of  backquotes on the line, ignore the trailing
          backquote.  This is useful on some keyboards where  the
          return  key  is  too  small, and the backquote key lies



zsh 5.0.5          Last change: January 5, 2014                16






User Commands                                       ZSHOPTIONS(1)



          annoyingly close to it.  As an alternative the variable
          KEYBOARD_HACK  lets  you  choose  the  character  to be
          removed.

  Job Control
     AUTO_CONTINUE
          With this option set, stopped  jobs  that  are  removed
          from  the job table with the disown builtin command are
          automatically sent a CONT signal to make them  running.

     AUTO_RESUME (-W)
          Treat  single  word simple commands without redirection
          as candidates for resumption of an existing job.

     BG_NICE (-6) <C> <Z>
          Run all background jobs  at  a  lower  priority.   This
          option is set by default.

     CHECK_JOBS <Z>
          Report  the  status  of  background  and suspended jobs
          before exiting a  shell  with  job  control;  a  second
          attempt  to exit the shell will succeed.  NO_CHECK_JOBS
          is best used only in combination with NO_HUP, else such
          jobs will be killed automatically.

          The  check is omitted if the commands run from the pre-
          vious command line included a `jobs' command, since  it
          is  assumed the user is aware that there are background
          or suspended jobs.  A `jobs' command run  from  one  of
          the hook functions defined in the section SPECIAL FUNC-
          TIONS in zshmisc(1) is not counted for this purpose.

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

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

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

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

     POSIX_JOBS <K> <S>
          This option makes job control more compliant  with  the
          POSIX standard.




zsh 5.0.5          Last change: January 5, 2014                17






User Commands                                       ZSHOPTIONS(1)



          When the option is not set, the MONITOR option is unset
          on entry to subshells, so that job control is no longer
          active.  When the option is set, the MONITOR option and
          job control remain active in  the  subshell,  but  note
          that  the  subshell has no access to jobs in the parent
          shell.

          When the option is not set, jobs put in the  background
          or foreground with bg or fg are displayed with the same
          information that would be reported by jobs.   When  the
          option  is  set,  only the text is printed.  The output
          from jobs itself is not affected by the option.

          When the option is not set, job  information  from  the
          parent shell is saved for output within a subshell (for
          example, within a pipeline).  When the option  is  set,
          the  output  of  jobs  is  empty until a job is started
          within the subshell.

          When the option is set, it becomes possible to use  the
          wait  builtin  to  wait for the last job started in the
          background (as given  by  $!)  even  if  that  job  has
          already  exited.   This  works  even  if  the option is
          turned on  temporarily  around  the  use  of  the  wait
          builtin.

  Prompting
     PROMPT_BANG <K>
          If  set,  `!' is treated specially in prompt expansion.
          See EXPANSION OF PROMPT SEQUENCES in zshmisc(1).

     PROMPT_CR (+V) <D>
          Print a carriage return just before printing  a  prompt
          in   the  line  editor.   This  is  on  by  default  as
          multi-line editing is only possible if the editor knows
          where the start of the line appears.

     PROMPT_SP <D>
          Attempt  to  preserve  a partial line (i.e. a line that
          did not end with a newline)  that  would  otherwise  be
          covered  up  by the command prompt due to the PROMPT_CR
          option.  This works by outputting  some  cursor-control
          characters,  including  a series of spaces, that should
          make the terminal wrap to the next line when a  partial
          line  is  present (note that this is only successful if
          your terminal has automatic margins, which is typical).

          When  a  partial line is preserved, by default you will
          see an inverse+bold character at the end of the partial
          line:   a  "%" for a normal user or a "#" for root.  If
          set, the shell parameter PROMPT_EOL_MARK can be used to
          customize how the end of partial lines are shown.



zsh 5.0.5          Last change: January 5, 2014                18






User Commands                                       ZSHOPTIONS(1)



          NOTE: if the PROMPT_CR option is not set, enabling this
          option will have no  effect.   This  option  is  on  by
          default.

     PROMPT_PERCENT <C> <Z>
          If  set,  `%' is treated specially in prompt expansion.
          See EXPANSION OF PROMPT SEQUENCES in zshmisc(1).

     PROMPT_SUBST <K> <S>
          If set, parameter expansion, command  substitution  and
          arithmetic expansion are performed in prompts.  Substi-
          tutions within prompts do not affect the  command  sta-
          tus.

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

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

     C_PRECEDENCES
          This  alters  the precedence of arithmetic operators to
          be more like C and  other  programming  languages;  the
          section  ARITHMETIC  EVALUATION  in  zshmisc(1)  has an
          explicit list.

     DEBUG_BEFORE_CMD
          Run the DEBUG trap before each command; otherwise it is
          run after each command.  Setting this option mimics the
          behaviour of ksh 93; with the option unset  the  behav-
          iour is that of ksh 88.

     ERR_EXIT (-e, ksh: -e)
          If  a  command  has a non-zero exit status, execute the
          ZERR trap, if set, and exit.  This  is  disabled  while
          running initialization scripts.

          The  behaviour is also disabled inside DEBUG traps.  In
          this case the option is handled specially: it is  unset
          on  entry  to the trap.  If the option DEBUG_BEFORE_CMD
          is set, as it is by default, and the option ERR_EXIT is



zsh 5.0.5          Last change: January 5, 2014                19






User Commands                                       ZSHOPTIONS(1)



          found  to  have  been set on exit, then the command for
          which the DEBUG trap is being executed is skipped.  The
          option is restored after the trap exits.

          Exiting  due  to ERR_EXIT has certain interactions with
          asynchronous jobs noted in the section JOBS in in  zsh-
          misc(1).

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

     EVAL_LINENO <Z>
          If set, line numbers of expressions evaluated using the
          builtin  eval  are  tracked separately of the enclosing
          environment.  This applies both to the parameter LINENO
          and the line number output by the prompt escape %i.  If
          the option is set, the prompt escape %N will output the
          string  `(eval)' instead of the script or function name
          as an indication.   (The two prompt escapes  are  typi-
          cally  used  in the parameter PS4 to be output when the
          option XTRACE is set.)  If EVAL_LINENO  is  unset,  the
          line  number  of  the surrounding script or function is
          retained during the evaluation.

     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.

     FUNCTION_ARGZERO <C> <Z>
          When executing a shell function or sourcing  a  script,
          set  $0 temporarily to the name of the function/script.

     LOCAL_OPTIONS <K>
          If this option is set at the point  of  return  from  a
          shell function, most options (including this one) which
          were in force upon entry to the function are  restored;
          options  that  are  not  restored  are  PRIVILEGED  and
          RESTRICTED.  Otherwise, only this option and the XTRACE
          and  PRINT_EXIT_VALUE  options  are restored.  Hence if
          this is explicitly unset by a shell function the  other
          options in force at the point of return will remain so.
          A shell function can  also  guarantee  itself  a  known
          shell configuration with a formulation like `emulate -L
          zsh'; the -L activates LOCAL_OPTIONS.



zsh 5.0.5          Last change: January 5, 2014                20






User Commands                                       ZSHOPTIONS(1)



     LOCAL_PATTERNS
          If this option is set at the point  of  return  from  a
          shell  function,  the state of pattern disables, as set
          with the builtin command `disable -p', is  restored  to
          what  it was when the function was entered.  The behav-
          iour of  this  option  is  similar  to  the  effect  of
          LOCAL_OPTIONS  on  options;  hence  `emulate -L sh' (or
          indeed any other emulation with the  -L  option)  acti-
          vates LOCAL_PATTERNS.

     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.   How-
          ever, 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 normal handling of SIGINT after the func-
          tion exits.

     MULTI_FUNC_DEF <Z>
          Allow definitions of multiple functions at once in  the
          form  `fn1  fn2...()';  if  the option is not set, this
          causes a parse error.  Definition of multiple functions
          with  the function keyword is always allowed.  Multiple
          function definitions are not often used and  can  cause
          obscure errors.

     MULTIOS <Z>
          Perform  implicit  tees  or cats when multiple redirec-
          tions are attempted (see the section `Redirection').

     OCTAL_ZEROES <S>
          Interpret any integer constant beginning with  a  0  as
          octal,  per  IEEE  Std  1003.2-1992  (ISO 9945-2:1993).
          This is not enabled by default as  it  causes  problems
          with  parsing  of,  for  example, date and time strings
          with leading zeroes.

          Sequences of digits indicating a numeric base  such  as
          the `08' component in `08#77' are always interpreted as
          decimal, regardless of leading zeroes.

     PIPE_FAIL



zsh 5.0.5          Last change: January 5, 2014                21






User Commands                                       ZSHOPTIONS(1)



          By default, when  a  pipeline  exits  the  exit  status
          recorded  by  the shell and returned by the shell vari-
          able $? reflects that of the  rightmost  element  of  a
          pipeline.   If  this  option  is  set,  the exit status
          instead reflects the status of the rightmost element of
          the pipeline that was non-zero, or zero if all elements
          exited with zero status.

     SOURCE_TRACE
          If  set,  zsh  will  print  an  informational   message
          announcing  the name of each file it loads.  The format
          of the output is similar to that for the XTRACE option,
          with  the  message <sourcetrace>.  A file may be loaded
          by the shell itself when it starts up  and  shuts  down
          (Startup/Shutdown  Files) or by the use of the `source'
          and `dot' builtin commands.

     TYPESET_SILENT
          If this is unset, executing any of the `typeset' family
          of  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 parameter.  If the option
          is set, they will only be  shown  when  parameters  are
          selected  with  the  `-m'  option.   The option `-p' is
          available whether or not the option is set.

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

     XTRACE (-x, ksh: -x)
          Print commands and their arguments  as  they  are  exe-
          cuted.   The  output  is proceded by the value of $PS4,
          formatted as described  in  the  section  EXPANSION  OF
          PROMPT SEQUENCES in zshmisc(1).

  Shell Emulation
     BASH_REMATCH
          When  set,  matches performed with the =~ operator will
          set the BASH_REMATCH array  variable,  instead  of  the
          default  MATCH  and match variables.  The first element
          of the  BASH_REMATCH  array  will  contain  the  entire
          matched  text  and  subsequent  elements  will  contain
          extracted substrings.  This  option  makes  more  sense
          when KSH_ARRAYS is also set, so that the entire matched
          portion is stored at index 0 and the first substring is
          at  index  1.   Without this option, the MATCH variable
          contains the entire matched text and  the  match  array
          variable contains substrings.

     BSD_ECHO <S>
          Make  the  echo builtin compatible with the BSD echo(1)
          command.  This disables backslashed escape sequences in



zsh 5.0.5          Last change: January 5, 2014                22






User Commands                                       ZSHOPTIONS(1)



          echo strings unless the -e option is specified.

     CONTINUE_ON_ERROR
          If a fatal error is encountered (see the section ERRORS
          in zshmisc(1)), and the code is running  in  a  script,
          the  shell  will resume execution at the next statement
          in the script at the top level, in other words  outside
          all  functions  or  shell  constructs such as loops and
          conditions.  This mimics the behaviour  of  interactive
          shells,  where  the shell returns to the line editor to
          read a new command; it was the normal behaviour in ver-
          sions of zsh before 5.0.1.

     CSH_JUNKIE_HISTORY <C>
          A  history  reference  without  an event specifier will
          always refer to the  previous  command.   Without  this
          option,  such  a  history  reference refers to the same
          event as the previous history reference, defaulting  to
          the previous command.

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

     CSH_JUNKIE_QUOTES <C>
          Changes the rules for single- and double-quoted text to
          match  that  of  csh.  These require that embedded new-
          lines 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 substi-
          tutions are only expanded once, and cannot be nested.

     CSH_NULLCMD <C>
          Do not use the values of NULLCMD and  READNULLCMD  when
          running  redirections  with no command.  This make such
          redirections fail (see the section `Redirection').

     KSH_ARRAYS <K> <S>
          Emulate ksh array handling as closely as possible.   If
          this  option  is  set, array elements are numbered from
          zero, an array parameter without  subscript  refers  to
          the  first  element  instead  of  the  whole array, and
          braces   are   required   to   delimit   a    subscript
          (`${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 function itself.
          (By default, the function is defined to the contents of
          the file.  However, the most common ksh-style case - of



zsh 5.0.5          Last change: January 5, 2014                23






User Commands                                       ZSHOPTIONS(1)



          the file containing only a  simple  definition  of  the
          function - is always handled in the ksh-compatible man-
          ner.)

     KSH_OPTION_PRINT <K>
          Alters the way options settings are printed: instead of
          separate  lists  of  set and unset options, all options
          are shown, marked `on' if they are in  the  non-default
          state, `off' otherwise.

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

     KSH_ZERO_SUBSCRIPT
          Treat  use  of  a  subscript  of value zero in array or
          string expressions as a reference to the first element,
          i.e.  the  element  that  usually  has the subscript 1.
          Ignored if KSH_ARRAYS is also set.

          If neither this option nor KSH_ARRAYS is set,  accesses
          to an element of an array or string with subscript zero
          return an empty element or string,  while  attempts  to
          set  element  zero of an array or string are treated as
          an error.  However, attempts to set an otherwise  valid
          subscript  range  that includes zero will succeed.  For
          example, if KSH_ZERO_SUBSCRIPT is not set,

               array[0]=(element)

          is an error, while

               array[0,1]=(element)

          is not and will replace the first element of the array.

          This option is for compatibility with older versions of
          the shell and is not recommended in new code.

     POSIX_ALIASES <K> <S>
          When this option is set, reserved words are not  candi-
          dates  for  alias  expansion:   it is still possible to
          declare any of them as an alias,  but  the  alias  will
          never be expanded.  Reserved words are described in the
          section RESERVED WORDS in zshmisc(1).

          Alias expansion takes place while text is  being  read;
          hence  when  this option is set it does not take effect



zsh 5.0.5          Last change: January 5, 2014                24






User Commands                                       ZSHOPTIONS(1)



          until the end of any function or other piece  of  shell
          code  parsed  as one unit.  Note this may cause differ-
          ences from other shells even  when  the  option  is  in
          effect.   For example, when running a command with `zsh
          -c', or even `zsh -o posixaliases -c', the entire  com-
          mand argument is parsed as one unit, so aliases defined
          within the argument are not  available  even  in  later
          lines.  If in doubt, avoid use of aliases in non-inter-
          active code.

     POSIX_BUILTINS <K> <S>
          When this option is set the command builtin can be used
          to  execute  shell builtin commands.  Parameter assign-
          ments specified  before  shell  functions  and  special
          builtins  are  kept  after the command completes unless
          the  special  builtin  is  prefixed  with  the  command
          builtin.   Special  builtins are ., :, break, continue,
          declare, eval, exit, export, integer, local,  readonly,
          return, set, shift, source, times, trap and unset.

          In  addition,  various error conditions associated with
          the above builtins  or  exec  cause  a  non-interactive
          shell to exit and an interactive shell to return to its
          top-level processing.

     POSIX_IDENTIFIERS <K> <S>
          When this option is set, only the ASCII characters a to
          z,  A  to  Z,  0  to 9 and _ may be used in identifiers
          (names of shell parameters and modules).

          When the option is unset and multibyte  character  sup-
          port  is enabled (i.e. it is compiled in and the option
          MULTIBYTE is set), then additionally  any  alphanumeric
          characters  in  the  local character set may be used in
          identifiers.  Note that scripts and  functions  written
          with  this feature are not portable, and also that both
          options must be set before the script  or  function  is
          parsed; setting them during execution is not sufficient
          as the syntax variable=value has already been parsed as
          a command rather than an assignment.

          If multibyte character support is not compiled into the
          shell this option is ignored; all octets with  the  top
          bit  set may be used in identifiers.  This is non-stan-
          dard but is the traditional zsh behaviour.

     POSIX_STRINGS <K> <S>
          This option affects processing of quoted strings.  Cur-
          rently  it  only  affects the behaviour of null charac-
          ters, i.e. character 0 in the  portable  character  set
          corresponding to US ASCII.




zsh 5.0.5          Last change: January 5, 2014                25






User Commands                                       ZSHOPTIONS(1)



          When  this  option is not set, null characters embedded
          within strings of the form $'...' are treated as  ordi-
          nary characters. The entire string is maintained within
          the shell and output to files where necessary, although
          owing  to  restrictions  of  the  library interface the
          string is truncated  at  the  null  character  in  file
          names, environment variables, or in arguments to exter-
          nal programs.

          When this option is set, the $'...' expression is trun-
          cated at the null character.  Note that remaining parts
          of the same string beyond the termination of the quotes
          are not trunctated.

          For  example,  the  command  line argument a$'b\0c'd is
          treated with the option off as  the  characters  a,  b,
          null, c, d, and with the option on as the characters a,
          b, d.

     POSIX_TRAPS <K> <S>
          When the is option is set, the usual zsh  behaviour  of
          executing  traps  for EXIT on exit from shell functions
          is suppressed.  In that case, manipulating  EXIT  traps
          always  alters  the  global trap for exiting the shell;
          the LOCAL_TRAPS option is ignored for the EXIT trap.

     SH_FILE_EXPANSION <K> <S>
          Perform filename expansion (e.g., ~  expansion)  before
          parameter  expansion,  command substitution, arithmetic
          expansion and  brace  expansion.   If  this  option  is
          unset, it is performed after brace expansion, so things
          like `~$USERNAME' and `~{pfalstad,rc}' will work.

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

     SH_OPTION_LETTERS <K> <S>
          If this option is set the shell tries to interpret sin-
          gle letter options (which are used with set and setopt)
          like ksh does.  This also affects the value  of  the  -
          special parameter.

     SH_WORD_SPLIT (-y) <K> <S>
          Causes  field  splitting  to  be  performed on unquoted
          parameter expansions.  Note that this option has  noth-
          ing  to  do  with  word  splitting.   (See  the section
          `Parameter Expansion'.)

     TRAPS_ASYNC
          While waiting for a program to exit, handle signals and



zsh 5.0.5          Last change: January 5, 2014                26






User Commands                                       ZSHOPTIONS(1)



          run traps immediately.  Otherwise the trap is run after
          a child process has exited.  Note this does not  affect
          the  point  at  which  traps are run for any case other
          than when the shell is waiting for a child process.

  Shell State
     INTERACTIVE (-i, ksh: -i)
          This is an interactive shell.  This option is set  upon
          initialisation  if the standard input is a tty and com-
          mands are being read from  standard  input.   (See  the
          discussion of SHIN_STDIN.)  This heuristic may be over-
          ridden by specifying a state for  this  option  on  the
          command  line.   The  value  of this option can only be
          changed via flags supplied at invocation of the  shell.
          It cannot be changed once zsh is running.

     LOGIN (-l, ksh: -l)
          This  is  a login shell.  If this option is not explic-
          itly set, the shell becomes a login shell if the  first
          character  of the argv[0] passed to the shell is a `-'.

     PRIVILEGED (-p, ksh: -p)
          Turn on privileged mode. This is enabled  automatically
          on  startup  if  the  effective  user (group) ID is not
          equal to the real user (group) ID.  Turning this option
          off  causes  the effective user and group IDs to be set
          to the real user and group IDs.  This  option  disables
          sourcing user startup files.  If zsh is invoked as `sh'
          or `ksh' with this  option  set,  /etc/suid_profile  is
          sourced  (after  /etc/profile  on  interactive shells).
          Sourcing ~/.profile is disabled and the contents of the
          ENV  variable is ignored. This option cannot be changed
          using the -m option of setopt and unsetopt, and  chang-
          ing  it  inside  a  function always changes it globally
          regardless of the LOCAL_OPTIONS option.

     RESTRICTED (-r)
          Enables restricted mode.  This option cannot be changed
          using unsetopt, and setting it inside a function always
          changes it globally  regardless  of  the  LOCAL_OPTIONS
          option.  See the section `Restricted Shell'.

     SHIN_STDIN (-s, ksh: -s)
          Commands  are being read from the standard input.  Com-
          mands 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  posi-
          tional  parameter.  Note that setting or unsetting this
          option on the command line does not necessarily  affect
          the  state  the  option  will  have  while the shell is



zsh 5.0.5          Last change: January 5, 2014                27






User Commands                                       ZSHOPTIONS(1)



          running - that is purely an indicator of whether on not
          commands  are  actually being read from standard input.
          The value of this option can only be changed via  flags
          supplied  at  invocation  of  the  shell.  It cannot be
          changed once zsh is running.

     SINGLE_COMMAND (-t, ksh: -t)
          If the shell is reading from standard input,  it  exits
          after  a  single  command has been executed.  This also
          makes the shell non-interactive, unless the INTERACTIVE
          option  is  explicitly  set  on  the command line.  The
          value of this option can only be changed via flags sup-
          plied at invocation of the shell.  It cannot be changed
          once zsh is running.

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

     COMBINING_CHARS
          Assume that the terminal displays combining  characters
          correctly.   Specifically, if a base alphanumeric char-
          acter is followed by one or more zero-width punctuation
          characters,  assume that the zero-width characters will
          be displayed as modifications  to  the  base  character
          within  the same width.  Not all terminals handle this.
          If this option is not set,  zero-width  characters  are
          displayed separately with special mark-up.

          If  this  option  is  set,  the pattern test [[:WORD:]]
          matches  a  zero-width  punctuation  character  on  the
          assumption  that  it  will be used as part of a word in
          combination with a word character.  Otherwise the  base
          shell does not handle combining characters specially.

     EMACS
          If ZLE is loaded, turning on this option has the equiv-
          alent effect of `bindkey  -e'.   In  addition,  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  provided for compatibility;
          bindkey is the recommended interface.

     OVERSTRIKE
          Start up the line editor in overstrike mode.

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

          Note  that although this is on by default in ksh emula-
          tion it only provides  superficial  compatibility  with



zsh 5.0.5          Last change: January 5, 2014                28






User Commands                                       ZSHOPTIONS(1)



          the  ksh  line  editor and reduces the effectiveness of
          the zsh line editor.  As it has no effect on shell syn-
          tax,  many  users  may wish to disable this option when
          using ksh emulation interactively.

     VI   If ZLE is loaded, turning on this option has the equiv-
          alent  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  provided  for  compatibility;
          bindkey is the recommended interface.

     ZLE (-Z)
          Use the zsh line editor.  Set by default in interactive
          shells connected to a terminal.

OPTION ALIASES
     Some options have  alternative  names.   These  aliases  are
     never  used  for  output,  but  can be used just like normal
     option names when specifying options to the shell.

     BRACE_EXPAND
          NO_IGNORE_BRACES (ksh and bash compatibility)

     DOT_GLOB
          GLOB_DOTS (bash compatibility)

     HASH_ALL
          HASH_CMDS (bash compatibility)

     HIST_APPEND
          APPEND_HISTORY (bash compatibility)

     HIST_EXPAND
          BANG_HIST (bash compatibility)

     LOG  NO_HIST_NO_FUNCTIONS (ksh compatibility)

     MAIL_WARN
          MAIL_WARNING (bash compatibility)

     ONE_CMD
          SINGLE_COMMAND (bash compatibility)

     PHYSICAL
          CHASE_LINKS (ksh and bash compatibility)

     PROMPT_VARS
          PROMPT_SUBST (bash compatibility)

     STDIN
          SHIN_STDIN (ksh compatibility)



zsh 5.0.5          Last change: January 5, 2014                29






User Commands                                       ZSHOPTIONS(1)



     TRACK_ALL
          HASH_CMDS (ksh compatibility)

SINGLE LETTER OPTIONS
  Default set
     -0   CORRECT
     -1   PRINT_EXIT_VALUE
     -2   NO_BAD_PATTERN
     -3   NO_NOMATCH
     -4   GLOB_DOTS
     -5   NOTIFY
     -6   BG_NICE
     -7   IGNORE_EOF
     -8   MARK_DIRS
     -9   AUTO_LIST
     -B   NO_BEEP
     -C   NO_CLOBBER
     -D   PUSHD_TO_HOME
     -E   PUSHD_SILENT
     -F   NO_GLOB
     -G   NULL_GLOB
     -H   RM_STAR_SILENT
     -I   IGNORE_BRACES
     -J   AUTO_CD
     -K   NO_BANG_HIST
     -L   SUN_KEYBOARD_HACK
     -M   SINGLE_LINE_ZLE
     -N   AUTO_PUSHD
     -O   CORRECT_ALL
     -P   RC_EXPAND_PARAM
     -Q   PATH_DIRS
     -R   LONG_LIST_JOBS
     -S   REC_EXACT
     -T   CDABLE_VARS
     -U   MAIL_WARNING
     -V   NO_PROMPT_CR
     -W   AUTO_RESUME
     -X   LIST_TYPES
     -Y   MENU_COMPLETE
     -Z   ZLE
     -a   ALL_EXPORT
     -e   ERR_EXIT
     -f   NO_RCS
     -g   HIST_IGNORE_SPACE
     -h   HIST_IGNORE_DUPS
     -i   INTERACTIVE
     -k   INTERACTIVE_COMMENTS
     -l   LOGIN
     -m   MONITOR
     -n   NO_EXEC
     -p   PRIVILEGED
     -r   RESTRICTED



zsh 5.0.5          Last change: January 5, 2014                30






User Commands                                       ZSHOPTIONS(1)



     -s   SHIN_STDIN
     -t   SINGLE_COMMAND
     -u   NO_UNSET
     -v   VERBOSE
     -w   CHASE_LINKS
     -x   XTRACE
     -y   SH_WORD_SPLIT

  sh/ksh emulation set
     -C   NO_CLOBBER
     -T   TRAPS_ASYNC
     -X   MARK_DIRS
     -a   ALL_EXPORT
     -b   NOTIFY
     -e   ERR_EXIT
     -f   NO_GLOB
     -i   INTERACTIVE
     -l   LOGIN
     -m   MONITOR
     -n   NO_EXEC
     -p   PRIVILEGED
     -r   RESTRICTED
     -s   SHIN_STDIN
     -t   SINGLE_COMMAND
     -u   NO_UNSET
     -v   VERBOSE
     -x   XTRACE

  Also note
     -A   Used by set for setting arrays
     -b   Used on the command line to specify end of option  pro-
          cessing
     -c   Used on the command line to specify a single command
     -m   Used by setopt for pattern-matching option setting
     -o   Used in all places to allow use of long option names
     -s   Used by set to sort positional parameters



ATTRIBUTES
     See   attributes(5)   for   descriptions  of  the  following
     attributes:

     +---------------+------------------+
     |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
     +---------------+------------------+
     |Availability   | shell/zsh        |
     +---------------+------------------+
     |Stability      | Volatile         |
     +---------------+------------------+
NOTES
     This  software  was   built   from   source   available   at



zsh 5.0.5          Last change: January 5, 2014                31






User Commands                                       ZSHOPTIONS(1)



     https://java.net/projects/solaris-userland.    The  original
     community   source   was   downloaded   from    http://down-
     loads.source-
     forge.net/project/zsh/zsh/5.0.5/zsh-5.0.5.tar.bz2

     Further information about this software can be found on  the
     open source community website at http://www.zsh.org/.
















































zsh 5.0.5          Last change: January 5, 2014                32






User Commands                                      ZSHBUILTINS(1)



NAME
     zshbuiltins - zsh built-in commands

SHELL BUILTIN COMMANDS
     Some  shell  builtin  commands  take options as described in
     individual entries; these are often referred to in the  list
     below  as  `flags'  to  avoid  confusion with shell options,
     which may also have an effect on the  behaviour  of  builtin
     commands.  In this introductory section, `option' always has
     the meaning of an option to a command that should be  famil-
     iar to most command line users.

     Typically,  options  are single letters preceded by a hyphen
     (-).  Options that take an argument accept it either immedi-
     ately  following the option letter or after white space, for
     example `print -C3 *' or `print  -C  3  *'  are  equivalent.
     Arguments  to  options  are not the same as arguments to the
     command;  the  documentation  indicates  which   is   which.
     Options  that  do  not take an argument may be combined in a
     single word, for example `print -ca *' and `print -c  -a  *'
     are equivalent.

     Some  shell  builtin  commands  also take options that begin
     with `+' instead of `-'.  The list below makes  clear  which
     commands these are.

     Options  (together  with their individual arguments, if any)
     must appear in a group before any non-option arguments; once
     the  first  non-option  argument has been found, option pro-
     cessing is terminated.

     All builtin commands other than precommand  modifiers,  even
     those  that  have no options, can be given the argument `--'
     to terminate option processing.   This  indicates  that  the
     following  words  are non-option arguments, but is otherwise
     ignored.  This is useful in cases  where  arguments  to  the
     command  may  begin  with `-'.  For historical reasons, most
     builtin commands also recognize a single `-' in  a  separate
     word  for  this purpose; note that this is less standard and
     use of `-- is recommended.

     - simple command
          See the section `Precommand Modifiers'.

     . file [ arg ... ]
          Read commands from file and execute them in the current
          shell environment.

          If  file  does  not contain a slash, or if PATH_DIRS is
          set, the shell looks in the components of $path to find
          the  directory  containing  file.  Files in the current
          directory are not read unless `.' appears somewhere  in



zsh 5.0.5          Last change: January 5, 2014                 1






User Commands                                      ZSHBUILTINS(1)



          $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  posi-
          tional  parameters;  the  old positional parameters are
          restored when the file is done executing.  If file  was
          not  found  the return status is 127; if file was found
          but contained a syntax error the return status is  126;
          else  the  return status is the exit status of the last
          command executed.

     : [ arg ... ]
          This command does  nothing,  although  normal  argument
          expansions is performed which may have effects on shell
          parameters.  A zero exit status is returned.

     alias [ {+|-}gmrsL ] [ name[=value] ... ]
          For each name with a  corresponding  value,  define  an
          alias  with  that  value.   A  trailing  space in value
          causes the next word to be checked for alias expansion.
          If  the  -g  flag  is  present,  define a global alias;
          global aliases are expanded even if they do  not  occur
          in command position.

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

               alias -s ps=gv

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

          For  each  name with no value, print the value of name,
          if any.  With no arguments, print all currently defined
          aliases  other  than suffix aliases.  If the -m flag is
          given the arguments are taken as patterns (they  should
          be  quoted  to  preserve them from being interpreted as
          glob patterns), and the aliases matching these patterns
          are  printed.  When printing aliases and one of the -g,
          -r or -s flags is present,  restrict  the  printing  to



zsh 5.0.5          Last change: January 5, 2014                 2






User Commands                                      ZSHBUILTINS(1)



          global, regular or suffix aliases, respectively; a reg-
          ular alias is one which is neither a global nor a  suf-
          fix  alias.    Using  `+' instead of `-', or ending the
          option list with a single `+', prevents the  values  of
          the aliases from being printed.

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

          For more on aliases, include common problems,  see  the
          section ALIASING in zshmisc(1).

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

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

          The flag +X attempts to load each name as an autoloaded
          function,  but does not execute it.  The exit status is
          zero (success)  if  the  function  was  not  previously
          defined  and  a definition for it was found.  This does
          not replace any existing definition  of  the  function.
          The  exit  status  is nonzero (failure) if the function
          was already defined or when no  definition  was  found.
          In  the  latter case the function remains undefined and
          marked for autoloading.  If  ksh-style  autoloading  is
          enabled, the function created will contain the contents
          of the file plus a call to the function itself appended
          to  it, thus giving normal ksh autoloading behaviour on
          the first call to the function.  If the -m flag is also
          given  each  name is treated as a pattern and all func-
          tions already marked for autoload that match  the  pat-
          tern are loaded.

          With the -w flag, the names are taken as names of files
          compiled with the zcompile builtin, and  all  functions
          defined in them are marked for autoloading.

          The  flags -z and -k mark the function to be autoloaded
          using  the  zsh  or  ksh  style,  as  if   the   option
          KSH_AUTOLOAD were unset or were set, respectively.  The
          flags override the setting of the option  at  the  time



zsh 5.0.5          Last change: January 5, 2014                 3






User Commands                                      ZSHBUILTINS(1)



          the function is loaded.

          Note  that  the  autoload  command  makes no attempt to
          ensure the shell options set during the loading or exe-
          cution  of  the  file  have  any particular value.  For
          this, the emulate command can be used:

               emulate zsh -c 'autoload -Uz func'

          arranges that when func  is  loaded  the  shell  is  in
          native  zsh  emulation,  and  this  emulation  is  also
          applied when func is run.

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

     bindkey
          See the section `Zle Builtins' in zshzle(1).

     break [ n ]
          Exit  from  an  enclosing  for, while, until, select or
          repeat loop.  If n is specified, then  break  n  levels
          instead of just one.

     builtin name [ args ... ]
          Executes the builtin name, with the given args.

     bye  Same as exit.

     cap  See  the section `The zsh/cap Module' in zshmodules(1).

     cd [ -qsLP ] [ arg ]
     cd [ -qsLP ] old new
     cd [ -qsLP ] {+|-}n
          Change the  current  directory.   In  the  first  form,
          change the current directory to arg, or to the value of
          $HOME if arg is not specified.  If arg is  `-',  change
          to the previous directory.

          Otherwise,  if  arg  begins  with  a  slash, attempt to
          change to the directory given by arg.

          If arg does not  begin  with  a  slash,  the  behaviour
          depends  on whether the current directory `.' occurs in
          the list of directories contained in the shell  parame-
          ter cdpath.  If it does not, first attempt to change to
          the directory arg under the current directory,  and  if
          that  fails but cdpath is set and contains at least one
          element attempt to change to the  directory  arg  under
          each  component of cdpath in turn until successful.  If



zsh 5.0.5          Last change: January 5, 2014                 4






User Commands                                      ZSHBUILTINS(1)



          `.' occurs in cdpath, then cdpath is searched  strictly
          in  order  so that `.' is only tried at the appropriate
          point.

          The order of testing cdpath is modified if  the  option
          POSIX_CD  is set, as described in the documentation for
          the option.

          If no directory is found,  the  option  CDABLE_VARS  is
          set,  and  a  parameter  named  arg  exists whose value
          begins with a slash, treat its value as the  directory.
          In  that  case,  the  parameter  is  added to the named
          directory hash table.

          The second form of cd substitutes the  string  new  for
          the  string  old  in the name of the current directory,
          and tries to change to this new directory.

          The third form of cd extracts an entry from the  direc-
          tory stack, and changes to that directory.  An argument
          of the form `+n' identifies a stack entry  by  counting
          from  the  left  of the list shown by the dirs command,
          starting with zero.   An  argument  of  the  form  `-n'
          counts  from  the  right.  If the PUSHD_MINUS option is
          set, the meanings of `+' and `-' in  this  context  are
          swapped.

          If  the  -q (quiet) option is specified, the hook func-
          tion chpwd and the functions in the  array  chpwd_func-
          tions  are  not called.  This is useful for calls to cd
          that do not change the environment seen by an  interac-
          tive user.

          If the -s option is specified, cd refuses to change the
          current directory if the given pathname  contains  sym-
          links.   If  the  -P option is given or the CHASE_LINKS
          option is set, symbolic links  are  resolved  to  their
          true  values.  If the -L option is given symbolic links
          are  retained  in  the  directory  (and  not  resolved)
          regardless of the state of the CHASE_LINKS option.

     chdir
          Same as cd.

     clone
          See  the  section  `The  zsh/clone  Module'  in zshmod-
          ules(1).

     command [ -pvV ] simple command
          The simple command argument is  taken  as  an  external
          command  instead  of  a function or builtin and is exe-
          cuted. If the POSIX_BUILTINS option  is  set,  builtins



zsh 5.0.5          Last change: January 5, 2014                 5






User Commands                                      ZSHBUILTINS(1)



          will also be executed but certain special properties of
          them are suppressed. The -p flag causes a default  path
          to  be  searched  instead of that in $path. With the -v
          flag, command is similar to whence and with -V,  it  is
          equivalent to whence -v.

          See also the section `Precommand Modifiers'.

     comparguments
          See  the  section  `The zsh/computil Module' in zshmod-
          ules(1).

     compcall
          See the section `The  zsh/compctl  Module'  in  zshmod-
          ules(1).

     compctl
          See  the  section  `The  zsh/compctl Module' in zshmod-
          ules(1).

     compdescribe
          See the section `The zsh/computil  Module'  in  zshmod-
          ules(1).

     compfiles
          See  the  section  `The zsh/computil Module' in zshmod-
          ules(1).

     compgroups
          See the section `The zsh/computil  Module'  in  zshmod-
          ules(1).

     compquote
          See  the  section  `The zsh/computil Module' in zshmod-
          ules(1).

     comptags
          See the section `The zsh/computil  Module'  in  zshmod-
          ules(1).

     comptry
          See  the  section  `The zsh/computil Module' in zshmod-
          ules(1).

     compvalues
          See the section `The zsh/computil  Module'  in  zshmod-
          ules(1).

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



zsh 5.0.5          Last change: January 5, 2014                 6






User Commands                                      ZSHBUILTINS(1)



     declare
          Same as typeset.

     dirs [ -c ] [ arg ... ]
     dirs [ -lpv ]
          With no arguments, print the contents of the  directory
          stack.   Directories  are  added to this stack with the
          pushd command, and removed with the  cd  or  popd  com-
          mands.   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 (see Dynamic and Static  named
               directories in zshexpn(1)).

          -p   print directory entries one per line.

          -v   number the directories in the stack when printing.

     disable [ -afmprs ] name ...
          Temporarily disable the named hash  table  elements  or
          patterns.   The default is to disable builtin commands.
          This allows you to use an  external  command  with  the
          same  name  as a builtin command.  The -a option causes
          disable to act on regular or global  aliases.   The  -s
          option causes disable to act on suffix aliases.  The -f
          option causes disable to act on shell  functions.   The
          -r  options  causes  disable  to act on reserved words.
          Without 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 corre-
          sponding  hash  table  matching these patterns are dis-
          abled.  Disabled objects can be enabled with the enable
          command.

          With  the  option -p, name ... refer to elements of the
          shell's pattern syntax  as  described  in  the  section
          `Filename  Generation'.   Certain  elements can be dis-
          abled separately, as given below.

          Note that patterns not allowed by the current  settings
          for the options EXTENDED_GLOB, KSH_GLOB and SH_GLOB are
          never enabled, regardless of  the  setting  here.   For
          example,  if EXTENDED_GLOB is not active, the pattern ^
          is ineffective even if `disable -p "^"'  has  not  been
          issued.   The  list below indicates any option settings
          that restrict the use of the  pattern.   It  should  be



zsh 5.0.5          Last change: January 5, 2014                 7






User Commands                                      ZSHBUILTINS(1)



          noted  that  setting  SH_GLOB  has  a wider effect then
          merely disabling patterns as  certain  expressions,  in
          particular those involving parentheses, are parsed dif-
          ferently.

          The following patterns may be disabled; all the strings
          need  quoting  on the command line to prevent them from
          being interpreted immediately as patterns and the  pat-
          terns are shown below in single quotes as a reminder.
          '?'  The   pattern  character  ?  wherever  it  occurs,
               including  when  preceding  a   parenthesis   with
               KSH_GLOB.

          '*'  The   pattern  character  *  wherever  it  occurs,
               including recursive globbing and when preceding  a
               parenthesis with KSH_GLOB.

          '['  Character classes.

          '<' (NO_SH_GLOB)
               Numeric ranges.

          '|' (NO_SH_GLOB)
               Alternation  in grouped patterns, case statements,
               or KSH_GLOB parenthesised expressions.

          '(' (NO_SH_GLOB)
               Grouping using single parentheses.  Disabling this
               does  not  disable  the  use  of  parentheses  for
               KSH_GLOB where they are introduced  by  a  special
               character,  nor  for  glob qualifiers (use `setopt
               NO_BARE_GLOB_QUAL' to disable glob qualifiers that
               use parentheses only).

          '~' (EXTENDED_GLOB)
               Exclusion in the form A~B.

          '^' (EXTENDED_GLOB)
               Exclusion in the form A^B.

          '#' (EXTENDED_GLOB)
               The  pattern  character # wherever it occurs, both
               for repetition of a previous pattern and for indi-
               cating globbing flags.

          '?(' (KSH_GLOB)
               The  grouping form ?(...).  Note this is also dis-
               abled if '?' is disabled.

          '*(' (KSH_GLOB)
               The grouping form *(...).  Note this is also  dis-
               abled if '*' is disabled.



zsh 5.0.5          Last change: January 5, 2014                 8






User Commands                                      ZSHBUILTINS(1)



          '+(' (KSH_GLOB)
               The grouping form +(...).

          '!(' (KSH_GLOB)
               The grouping form !(...).

          '@(' (KSH_GLOB)
               The grouping form @(...).

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

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

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

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

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



zsh 5.0.5          Last change: January 5, 2014                 9






User Commands                                      ZSHBUILTINS(1)



     echotc
          See the section `The  zsh/termcap  Module'  in  zshmod-
          ules(1).

     echoti
          See  the  section  `The zsh/terminfo Module' in zshmod-
          ules(1).

     emulate [ -LR ] [ {zsh|sh|ksh|csh} [ flags ... ] ]
          Without any argument print current emulation mode.

          With single argument set up zsh options to emulate  the
          specified shell as much as possible.  csh will never be
          fully emulated.  If the argument  is  not  one  of  the
          shells  listed  above,  zsh  will be used as a default;
          more precisely, the tests performed on the argument are
          the  same  as  those used to determine the emulation at
          startup based on the shell name, see the  section  COM-
          PATIBILITY  in  zsh(1)  .  In addition to setting shell
          options, the command also restores the  pristine  state
          of pattern enables, as if all patterns had been enabled
          using enable -p.

          If the emulate command occurs inside  a  function  that
          has been marked for execution tracing with functions -t
          then the xtrace option will be turned on regardless  of
          emulation  mode  or other options.  Note that code exe-
          cuted inside the function by the  .,  source,  or  eval
          commands  is not considered to be running directly from
          the function, hence does not provoke this behaviour.

          If the -R switch is given,  all  settable  options  are
          reset to their default value corresponding to the spec-
          ified  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 switch is
          given, the options  LOCAL_OPTIONS,  LOCAL_PATTERNS  and
          LOCAL_TRAPS will be set as well, causing the effects of
          the emulate command  and  any  setopt,  disable  -p  or
          enable -p, and trap commands to be local to the immedi-
          ately surrounding  shell  function,  if  any;  normally
          these  options  are  turned  off in all emulation modes
          except ksh. The -L switch is  mutually  exclusive  with
          the use of -c in flags.

          The  flags  may  be  any  of  the invocation-time flags
          described in the section INVOCATION in  zsh(1),  except
          that  `-o  EMACS'  and  `-o VI' may not be used.  Flags
          such as `+r'/`+o RESTRICTED' may be prohibited in  some
          circumstances.




zsh 5.0.5          Last change: January 5, 2014                10






User Commands                                      ZSHBUILTINS(1)



          If  -c arg appears in flags, arg is evaluated while the
          requested emulation is temporarily in effect.  In  this
          case the emulation mode and all options are restored to
          their previous values before emulate returns.   The  -R
          switch  may  precede  the name of the shell to emulate;
          note this has a meaning distinct from including  -R  in
          flags.

          Use of -c enables `sticky' emulation mode for functions
          defined within the evaluated expression:  the emulation
          mode is associated thereafter with the function so that
          whenever  the  function  is  executed   the   emulation
          (respecting  the -R switch, if present) and all options
          are set (and pattern disables cleared) before entry  to
          the function, and the state is restored after exit.  If
          the function is called when  the  sticky  emulation  is
          already  in effect, either within an `emulate shell -c'
          expression or within another  function  with  the  same
          sticky  emulation,  entry and exit from the function do
          not cause options to be altered (except due to standard
          processing  such  as  the  LOCAL_OPTIONS option).  This
          also applies to functions marked  for  autoload  within
          the  sticky  emulation;  the appropriate set of options
          will be applied at the point the function is loaded  as
          well as when it is run.

          For example:

               emulate sh -c 'fni() { setopt cshnullglob; }
               fno() { fni; }'
               fno


          The  two  functions fni and fno are defined with sticky
          sh emulation.  fno is then  executed,  causing  options
          associated with emulations to be set to their values in
          sh.  fni then calls fno; because fno is also marked for
          sticky  sh  emulation,  no option changes take place on
          entry to or exit from it.  Hence  the  option  cshnull-
          glob,  turned  off  by  sh emulation, will be turned on
          within fni and remain on on return  to  fno.   On  exit
          from  fno,  the  emulation mode and all options will be
          restored to the state they were in before entry to  the
          temporary emulation.

          The documentation above is typically sufficient for the
          intended purpose of executing code designed  for  other
          shells  in a suitable environment.  More detailed rules
          follow.
          1.   The sticky emulation environment provided by `emu-
               late  shell  -c'  is identical to that provided by
               entry to a function marked for sticky emulation as



zsh 5.0.5          Last change: January 5, 2014                11






User Commands                                      ZSHBUILTINS(1)



               a consequence of being defined in such an environ-
               ment.  Hence, for example, the sticky emulation is
               inherited by subfunctions defined within functions
               with sticky emulation.
          2.   No change of options takes place on  entry  to  or
               exit from functions that are not marked for sticky
               emulation, other than those  that  would  normally
               take  place,  even  if  those functions are called
               within sticky emulation.
          3.   No special  handling  is  provided  for  functions
               marked  for  autoload nor for functions present in
               wordcode created by the zcompile command.
          4.   The presence or absence of the -R switch  to  emu-
               late  corresponds  to  different  sticky emulation
               modes, so for example `emulate sh -c', `emulate -R
               sh  -c'  and `emulate csh -c' are treated as three
               distinct sticky emulations.
          5.   Difference in shell options supplied  in  addition
               to the basic emulation also mean the sticky emula-
               tions are different, so for example  `emulate  zsh
               -c'  and `emulate zsh -o cbases -c' are treated as
               distinct sticky emulations.

     enable [ -afmprs ] name ...
          Enable the named hash table elements,  presumably  dis-
          abled  earlier  with disable.  The default is to enable
          builtin commands.  The -a option causes enable  to  act
          on  regular  or  global  aliases.  The -s option causes
          enable to act on suffix aliases.  The -f option  causes
          enable to act on shell functions.  The -r option causes
          enable to act on reserved words.  Without arguments all
          enabled hash table elements from the corresponding hash
          table are printed.  With the -m flag the arguments  are
          taken as patterns (should be quoted) and all hash table
          elements from the  corresponding  hash  table  matching
          these  patterns  are  enabled.   Enabled objects can be
          disabled with the disable builtin command.

          enable -p reenables patterns disabled with disable  -p.
          Note  that  it  does not override globbing options; for
          example, `enable -p "~"' does  not  cause  the  pattern
          character  ~  to  be  active  unless  the EXTENDED_GLOB
          option is also set.  To enable  all  possible  patterns
          (so  that  they may be invidually disabled with disable
          -p), use `setopt EXTENDED_GLOB KSH_GLOB NO_SH_GLOB'.

     eval [ arg ... ]
          Read the arguments as input to the  shell  and  execute
          the  resulting command(s) in the current shell process.
          The return status is the same as if  the  commands  had
          been  executed  directly  by the shell; if there are no
          args or they contain no commands  (i.e.  are  an  empty



zsh 5.0.5          Last change: January 5, 2014                12






User Commands                                      ZSHBUILTINS(1)



          string or whitespace) the return status is zero.

     exec [ -cl ] [ -a argv0 ] simple command
          Replace  the  current  shell  with  an external command
          rather than forking.  With -c  clear  the  environment;
          with  -l prepend - to the argv[0] string of the command
          executed (to simulate a login shell); with -a argv0 set
          the  argv[0]  string  of the command executed.  See the
          section `Precommand Modifiers'.

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

          See  notes  at  the  end of the section JOBS in in zsh-
          misc(1) for some possibly  unexpected  interactions  of
          the exit command with jobs.

     export [ name[=value] ... ]
          The  specified names are marked for automatic export to
          the  environment  of  subsequently  executed  commands.
          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 status of 1.

     fc [ -e ename ] [ -m match ] [ old=new ... ] [ first [ last
          ] ]
     fc -l [ -nrdfEiD ] [ -t timefmt ] [ -m match ]
           [ old=new ... ] [ first [ last ] ]
     fc -p [ -a ] [ filename [ histsize [ savehistsize ] ] ]
     fc -P
     fc -ARWI [ filename ]
          Select a range of commands from first to last from  the
          history  list.   The  arguments  first  and last may be
          specified as a number or as a string.  A negative  num-
          ber  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 containing these history
          events.  If ename  is  not  given,  the  value  of  the



zsh 5.0.5          Last change: January 5, 2014                13






User Commands                                      ZSHBUILTINS(1)



          parameter  FCEDIT is used; if that is not set the value
          of the parameter EDITOR is used; if that is not  set  a
          builtin  default,  usually  `vi'  is used.  If ename is
          `-', no editor is invoked.  When editing  is  complete,
          the edited command is executed.

          If  first  is  not specified, it will be set to -1 (the
          most recent event), or to -16 if the -l flag is  given.
          If  last  is not specified, it will be set to first, or
          to -1 if the -l flag is given.

          The flag -r reverses the order of the commands and  the
          flag -n suppresses command numbers when listing.

          Also when listing,
          -d   prints timestamps for each command
          -f   prints  full  time-date stamps in the US `MM/DD/YY
               hh:mm' format
          -E   prints  full  time-date  stamps  in  the  European
               `dd.mm.yyyy hh:mm' format
          -i   prints    full   time-date   stamps   in   ISO8601
               `yyyy-mm-dd hh:mm' format
          -t fmt
               prints time and date stamps in the  given  format;
               fmt  is  formatted with the strftime function with
               the zsh extensions described  for  the  %D{string}
               prompt  format  in the section EXPANSION OF PROMPT
               SEQUENCES in zshmisc(1).  The resulting  formatted
               string must be no more than 256 characters or will
               not be printed.
          -D   prints elapsed times; may be combined with one  of
               the options above.

          `fc  -p'  pushes  the current history list onto a stack
          and switches to a new history list.  If the  -a  option
          is  also specified, this history list will be automati-
          cally popped when the current function scope is exited,
          which  is  a  much better solution than creating a trap
          function to call `fc -P' manually.  If no arguments are
          specified, the history list is left empty, $HISTFILE is
          unset, and $HISTSIZE  &  $SAVEHIST  are  set  to  their
          default values.  If one argument is given, $HISTFILE is
          set to that filename, $HISTSIZE &  $SAVEHIST  are  left
          unchanged,  and  the  history  file  is  read in (if it
          exists) to initialize the new list.  If a second  argu-
          ment  is  specified,  $HISTSIZE & $SAVEHIST are instead
          set to the single specified numeric value.  Finally, if
          a  third  argument  is specified, $SAVEHIST is set to a
          separate value from $HISTSIZE.  You are free to  change
          these  environment values for the new history list how-
          ever you desire in order to manipulate the new  history
          list.



zsh 5.0.5          Last change: January 5, 2014                14






User Commands                                      ZSHBUILTINS(1)



          `fc  -P'  pops  the  history list back to an older list
          saved by `fc -p'.  The current list  is  saved  to  its
          $HISTFILE  before it is destroyed (assuming that $HIST-
          FILE and $SAVEHIST are set appropriately,  of  course).
          The  values  of $HISTFILE, $HISTSIZE, and $SAVEHIST are
          restored to the  values  they  had  when  `fc  -p'  was
          called.   Note  that this restoration can conflict with
          making these variables "local", so your best bet is  to
          avoid  local  declarations for these variables in func-
          tions that use `fc -p'.  The one other  guaranteed-safe
          combination is declaring these variables to be local at
          the top of your function and using the automatic option
          (-a)  with  `fc -p'.  Finally, note that it is legal to
          manually pop a push marked for automatic popping if you
          need to do so before the function exits.

          `fc  -R' reads the history from the given file, `fc -W'
          writes the history out to the given file, and  `fc  -A'
          appends the history out to the given file.  If no file-
          name is specified, the $HISTFILE is assumed.  If the -I
          option  is  added to -R, only those events that are not
          already contained within the internal history list  are
          added.   If  the  -I  option is added to -A or -W, only
          those  events  that  are  new  since  last  incremental
          append/write  to the history file are appended/written.
          In any case, the created file will have  no  more  than
          $SAVEHIST entries.

     fg [ job ... ]
     job ...
          Bring each specified job in turn to the foreground.  If
          no job is specified, resume the current job.

     float [ {+|-}EFHghlprtux ] [ -LRZ [ n ]] [ name[=value] ...
          ]
          Equivalent  to  typeset -E, except that options irrele-
          vant to floating point numbers are not permitted.

     functions [ {+|-}UXkmtTuz ] [ name ... ]
     functions -M mathfn [ min [ max [ shellfn ] ] ]
     functions -M [ -m pattern ... ]
     functions +M [ -m ] mathfn
          Equivalent to typeset -f, with the exception of the  -M
          option.   Use of the -M option may not be combined with
          any of the options handled by typeset -f.

          functions -M mathfn defines mathfn as  the  name  of  a
          mathematical function recognised in all forms of arith-
          metical expressions; see the section `Arithmetic Evalu-
          ation'  in  zshmisc(1).  By default mathfn may take any
          number of comma-separated arguments.  If min is  given,
          it  must have exactly min args; if min and max are both



zsh 5.0.5          Last change: January 5, 2014                15






User Commands                                      ZSHBUILTINS(1)



          given, it must have at least min and at most max  args.
          max may be -1 to indicate that there is no upper limit.

          By default the function is implemented by a shell func-
          tion of the same name; if shellfn is specified it gives
          the name of  the  corresponding  shell  function  while
          mathfn  remains  the  name used in arithmetical expres-
          sions.  The name of the function in $0 is  mathfn  (not
          shellfn  as  would  usually  be the case), provided the
          option FUNCTION_ARGZERO is in effect.   The  positional
          parameters  in  the  shell  function  correspond to the
          arguments  of  the  mathematical  function  call.   The
          result  of  the  last arithmetical expression evaluated
          inside the shell function (even if it is  a  form  that
          normally only returns a status) gives the result of the
          mathematical function.

          functions  -M  with  no  arguments   lists   all   such
          user-defined  functions  in  the same form as a defini-
          tion.  With the additional option  -m  and  a  list  of
          arguments,  all  functions  whose mathfn matches one of
          the pattern arguments are listed.

          function +M removes the list of mathematical functions;
          with the additional option -m the arguments are treated
          as patterns and all functions whose mathfn matches  the
          pattern  are  removed.   Note  that  the shell function
          implementing the behaviour is not  removed  (regardless
          of whether its name coincides with mathfn).

          For example, the following prints the cube of 3:

               zmath_cube() { (( $1 * $1 * $1 )) }
               functions -M cube 1 1 zmath_cube
               print $(( cube(3) ))

     getcap
          See  the section `The zsh/cap Module' in zshmodules(1).

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

     getopts optstring name [ arg ... ]
          Checks  the  args  for  legal options.  If the args are
          omitted, use the positional parameters.  A valid option
          argument  begins  with a `+' or a `-'.  An argument not
          beginning with a `+' or a `-', or  the  argument  `--',
          ends  the  options.  Note that a single `-' is not con-
          sidered a valid option  argument.   optstring  contains
          the  letters  that  getopts recognizes.  If a letter is
          followed by a `:', that option  requires  an  argument.



zsh 5.0.5          Last change: January 5, 2014                16






User Commands                                      ZSHBUILTINS(1)



          The  options  can  be  separated  from  the argument by
          blanks.

          Each time it is invoked, getopts places the option let-
          ter  it  finds  in  the shell parameter name, prepended
          with a `+' when arg begins with a `+'.   The  index  of
          the next arg is stored in OPTIND.  The option argument,
          if any, is stored in OPTARG.

          The first option to  be  examined  may  be  changed  by
          explicitly  assigning to OPTIND.  OPTIND has an initial
          value of 1, and is normally reset to 1 upon exit from a
          shell  function.   OPTARG  is not reset and retains its
          value from the most recent call to getopts.  If  either
          of  OPTIND  or  OPTARG  is explicitly unset, it remains
          unset, and the index or option argument is not  stored.
          The option itself is still stored in name in this case.

          A leading `:' in optstring causes getopts to store  the
          letter of any invalid option in OPTARG, and to set name
          to `?' for an unknown option and to `:' when a required
          argument  is  missing.  Otherwise, getopts sets name to
          `?' and prints an  error  message  when  an  option  is
          invalid.   The exit status is nonzero when there are no
          more options.

     hash [ -Ldfmrv ] [ name[=value] ] ...
          hash can be used to directly modify the contents of the
          command hash table, and the named directory hash table.
          Normally one would modify  these  tables  by  modifying
          one's  PATH (for the 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 full.

          The -r option causes the selected hash table to be emp-
          tied.  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 directory hash table this  adds
          all  users' home directories.  These two options cannot
          be used with any arguments.

          The -m option causes the arguments to be taken as  pat-
          terns  (which should be quoted) and the elements of the
          hash table matching those patterns are  printed.   This



zsh 5.0.5          Last change: January 5, 2014                17






User Commands                                      ZSHBUILTINS(1)



          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 path-
          name `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 appropri-
          ate value is in the normal manner for that hash  table.
          If  an  appropriate value can't be found, then the hash
          table will be unchanged.

          The -v option causes hash table entries to be listed as
          they  are  added  by explicit specification.  If has no
          effect if used with -f.

          If the -L flag is present, then each hash  table  entry
          is printed in the form of a call to hash.

     history
          Same as fc -l.

     integer [ {+|-}Hghilprtux ] [ -LRZ [ n ]] [ name[=value] ...
          ]
          Equivalent to typeset -i, except that  options  irrele-
          vant to integers are not permitted.

     jobs [ -dlprs ] [ job ... ]
     jobs -Z string
          Lists  information about each given job, or all jobs if
          job is omitted.  The -l flag lists process IDs, and the
          -p flag lists process groups.  If the -r flag is speci-
          fied 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  envi-
          ronment  space with the given string, truncated if nec-
          essary 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



zsh 5.0.5          Last change: January 5, 2014                18






User Commands                                      ZSHBUILTINS(1)



          given  jobs  or processes.  Signals are given by number
          or by names, with or without the `SIG' prefix.  If  the
          signal being sent is not `KILL' or `CONT', then the job
          will be sent a `CONT' signal if  it  is  stopped.   The
          argument  job can be the process ID of a job not in the
          job list.  In the second form, kill -l, if sig  is  not
          specified  the signal names are listed.  Otherwise, for
          each sig that is a name, the corresponding signal  num-
          ber is listed.  For each sig that is a signal number or
          a number representing the  exit  status  of  a  process
          which was terminated or stopped by a signal the name of
          the signal is printed.

          On some systems, alternative signal names  are  allowed
          for  a  few  signals.  Typical examples are SIGCHLD and
          SIGCLD or SIGPOLL and SIGIO, assuming  they  correspond
          to  the same signal number.  kill -l will only list the
          preferred form, however kill -l alt will  show  if  the
          alternative  form  corresponds to a signal number.  For
          example, under Linux kill -l IO and kill -l  POLL  both
          output  29, hence kill -IO and kill -POLL have the same
          effect.

          Many systems will allow process IDs to be  negative  to
          kill  a  process  group  or  zero  to  kill the current
          process group.

     let arg ...
          Evaluate each arg as an arithmetic expression.  See the
          section  `Arithmetic  Evaluation'  in  zshmisc(1) for a
          description of arithmetic expressions.  The exit status
          is  0 if the value of the last expression is nonzero, 1
          if it is zero, and 2 if an error occurred.

     limit [ -hs ] [ resource [ limit ] ] ...
          Set or display resource limits.  Unless the -s flag  is
          given,  the  limit  applies  only  the  children of the
          shell.  If -s is given  without  other  arguments,  the
          resource limits of the current shell is set to the pre-
          viously set resource limits of the children.

          If limit is not  specified,  print  the  current  limit
          placed  on  resource,  otherwise  set  the limit to the
          specified value.  If the -h flag  is  given,  use  hard
          limits  instead  of  soft  limits.   If  no resource is
          given, print all limits.

          When looping over multiple resources,  the  shell  will
          abort  immediately  if  it detects a badly formed argu-
          ment.  However, if it fails to set  a  limit  for  some
          other reason it will continue trying to set the remain-
          ing limits.



zsh 5.0.5          Last change: January 5, 2014                19






User Commands                                      ZSHBUILTINS(1)



          resource can be one of:

          addressspace
               Maximum amount of address space used.
          aiomemorylocked
               Maximum amount of memory locked  in  RAM  for  AIO
               operations.
          aiooperations
               Maximum number of AIO operations.
          cachedthreads
               Maximum number of cached threads.
          coredumpsize
               Maximum size of a core dump.
          cputime
               Maximum CPU seconds per process.
          datasize
               Maximum  data  size  (including  stack)  for  each
               process.
          descriptors
               Maximum value for a file descriptor.
          filesize
               Largest single file allowed.
          kqueues
               Maximum number of kqueues allocated.
          maxproc
               Maximum number of processes.
          maxpthreads
               Maximum number of threads per process.
          memorylocked
               Maximum amount of memory locked in RAM.
          memoryuse
               Maximum resident set size.
          msgqueue
               Maximum number of bytes in POSIX message queues.
          posixlocks
               Maximum number of POSIX locks per user.
          pseudoterminals
               Maximum number of pseudo-terminals.
          resident
               Maximum resident set size.
          sigpending
               Maximum number of pending signals.
          sockbufsize
               Maximum size of all socket buffers.
          stacksize
               Maximum stack size for each process.
          swapsize
               Maximum amount of swap used.
          vmemorysize
               Maximum amount of virtual memory.





zsh 5.0.5          Last change: January 5, 2014                20






User Commands                                      ZSHBUILTINS(1)



          Which of these resource limits are available depends on
          the  system.   resource can be abbreviated to any unam-
          biguous prefix.  It can also be an integer, which  cor-
          responds to the integer defined for the resource by the
          operating system.

          If argument corresponds to a number which is out of the
          range  of  the resources configured into the shell, the
          shell will try to read or write the limit  anyway,  and
          will  report an error if this fails.  As the shell does
          not store such resources internally, an attempt to  set
          the limit will fail unless the -s option is present.

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

          nh   hours
          nk   kilobytes (default)
          nm   megabytes or minutes
          [mm:]ss
               minutes and seconds

          The limit command is not made available by default when
          the shell starts in a mode emulating another shell.  It
          can be made available with  the  command  `zmodload  -F
          zsh/rlimits b:limit'.

     local  [ {+|-}AEFHUahlprtux ] [ -LRZi [ 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
          shell.

     noglob simple command
          See the section `Precommand Modifiers'.

     popd [ [-q] {+|-}n ]
          Remove an entry from the directory stack, and perform a
          cd  to  the  new  top directory.  With no argument, the
          current top entry is removed.  An argument of the  form
          `+n' identifies a stack 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



zsh 5.0.5          Last change: January 5, 2014                21






User Commands                                      ZSHBUILTINS(1)



          of `+' and `-' in this context are swapped.

          If  the  -q (quiet) option is specified, the hook func-
          tion chpwd and the functions in the array  $chpwd_func-
          tions  are  not  called, and the new directory stack is
          not printed.  This is useful for calls to popd that  do
          not change the environment seen by an interactive user.

     print [ -abcDilmnNoOpPrsSz ] [ -u n ] [ -f format ] [ -C
          cols ]
       [ -R [ -en ]] [ arg ... ]
          With  the  `-f'  option  the  arguments  are printed as
          described by printf.  With no flags or  with  the  flag
          `-',  the  arguments are printed on the standard output
          as described by echo, with the  following  differences:
          the  escape  sequence  `\M-x'  metafies the character x
          (sets the highest bit), `\C-x' produces a control char-
          acter  (`\C-@'  and  `\C-?' give the characters NUL and
          delete), and `\E' is a synonym for `\e'.   Finally,  if
          not  in  an  escape sequence, `\' escapes the following
          character and is not printed.

          -a   Print  arguments  with  the  column   incrementing
               first.  Only useful with the -c and -C options.

          -b   Recognize all the escape sequences defined for the
               bindkey command, see zshzle(1).

          -c   Print the arguments in columns.  Unless -a is also
               given,  arguments  are printed with the row incre-
               menting first.

          -C cols
               Print the arguments in cols columns.  Unless -a is
               also  given,  arguments  are  printed with the row
               incrementing first.

          -D   Treat the arguments as paths, replacing  directory
               prefixes   with  ~  expressions  corresponding  to
               directory names, as appropriate.

          -i   If given together with -o or -O, sorting  is  per-
               formed 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.




zsh 5.0.5          Last change: January 5, 2014                22






User Commands                                      ZSHBUILTINS(1)



          -n   Do not add a newline to the output.

          -N   Print  the  arguments  separated and terminated by
               nulls.

          -o   Print the arguments sorted in ascending order.

          -O   Print the arguments sorted in descending order.

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

          -P   Perform  prompt expansion (see EXPANSION OF PROMPT
               SEQUENCES in zshmisc(1)).

          -r   Ignore the escape conventions of echo.

          -R   Emulate the  BSD  echo  command,  which  does  not
               process  escape  sequences  unless  the -e flag is
               given.  The -n flag suppresses the  trailing  new-
               line.   Only  the  -e  and -n flags are recognized
               after -R; all  other  arguments  and  options  are
               printed.

          -s   Place  the  results in the history list instead of
               on the standard  output.   Each  argument  to  the
               print  command  is treated as a single word in the
               history, regardless of its content.

          -S   Place the results in the history list  instead  of
               on  the standard output.  In this case only a sin-
               gle argument is allowed; it  will  be  split  into
               words  as  if  it  were a full shell command line.
               The effect is similar to reading the line  from  a
               history   file   with  the  HIST_LEX_WORDS  option
               active.

          -u n Print the arguments to file descriptor n.

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

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

     printf format [ arg ... ]
          Print  the arguments according to the format specifica-
          tion. Formatting rules are the same as used in  C.  The
          same escape sequences as for echo are recognised in the
          format. All C conversion specifications ending  in  one
          of  csdiouxXeEfgGn  are  handled.  In addition to this,
          `%b' can be  used  instead  of  `%s'  to  cause  escape



zsh 5.0.5          Last change: January 5, 2014                23






User Commands                                      ZSHBUILTINS(1)



          sequences in the argument to be recognised and `%q' can
          be used to quote the argument in such a way that allows
          it to be reused as shell input. With the numeric format
          specifiers, if the corresponding argument starts with a
          quote  character,  the  numeric  value of the following
          character is used as the number to print otherwise  the
          argument  is evaluated as an arithmetic expression. See
          the section `Arithmetic Evaluation' in zshmisc(1) for a
          description  of  arithmetic expressions. With `%n', the
          corresponding argument is taken as an identifier  which
          is created as an integer parameter.

          Normally, conversion specifications are applied to each
          argument in order but they can explicitly  specify  the
          nth  argument  is  to be used by replacing `%' by `%n$'
          and `*' by `*n$'.  It is recommended that  you  do  not
          mix  references  of this explicit style with the normal
          style and the handling of such mixed styles may be sub-
          ject to future change.

          If arguments remain unused after formatting, the format
          string is reused until all  arguments  have  been  con-
          sumed.  With  the print builtin, this can be suppressed
          by using the -r option. If more arguments are  required
          by  the  format than have been specified, the behaviour
          is as if zero or an empty string had been specified  as
          the argument.

     pushd [ -qsLP ] [ arg ]
     pushd [ -qsLP ] old new
     pushd [ -qsLP ] {+|-}n
          Change  the current directory, and push the old current
          directory onto the directory stack.  In the first form,
          change  the  current  directory  to arg.  If arg is not
          specified, change to the second directory on the  stack
          (that  is,  exchange the top two entries), or change to
          $HOME if the PUSHD_TO_HOME option is set or if there is
          only  one entry on the stack.  Otherwise, arg is inter-
          preted as it would be by cd.  The meaning  of  old  and
          new in the second form is also the same as for cd.

          The  third  form of pushd changes directory by rotating
          the directory list.  An argument of the form `+n' iden-
          tifies  a  stack entry by counting from the left of the
          list shown by the dirs command, starting with zero.  An
          argument  of  the  form `-n' counts from the right.  If
          the PUSHD_MINUS option is set, the meanings of `+'  and
          `-' in this context are swapped.

          If  the  -q (quiet) option is specified, the hook func-
          tion chpwd and the functions in the array  $chpwd_func-
          tions  are  not  called, and the new directory stack is



zsh 5.0.5          Last change: January 5, 2014                24






User Commands                                      ZSHBUILTINS(1)



          not printed.  This is useful for calls to pushd that do
          not change the environment seen by an interactive user.

          If the option -q is not specified and the shell  option
          PUSHD_SILENT  is  not  set, the directory stack will be
          printed after a pushd is performed.

          The options -s, -L and -P have the same meanings as for
          the cd builtin.

     pushln [ arg ... ]
          Equivalent to print -nz.

     pwd [ -rLP ]
          Print  the  absolute  pathname  of  the current working
          directory.  If the -r or the -P flag is  specified,  or
          the  CHASE_LINKS  option  is set and the -L flag is not
          given, the  printed  path  will  not  contain  symbolic
          links.

     r    Same as fc -e -.

     read [ -rszpqAclneE ] [ -t [ num ] ] [ -k [ num ] ] [ -d
          delim ]
      [ -u n ] [ name[?prompt] ] [ name ...  ]
          Read one line and break it into fields using the  char-
          acters  in  $IFS  as separators, except as noted below.
          The first field is assigned to the first name, the sec-
          ond  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 sig-
               nify line continuation and backslashes in the line
               don't  quote  the  following character and are not
               removed.

          -s   Don't echo back characters  if  reading  from  the
               terminal.   Currently  does  not  work with the -q
               option.

          -q   Read only one character from the terminal and  set
               name  to  `y' if this character was `y' or `Y' and
               to `n' otherwise.  With this flag set  the  return
               status  is  zero  only if the character was `y' or
               `Y'.  This option may be used with a  timeout;  if
               the  read  times  out,  or encounters end of file,
               status 2 is returned.  Input is read from the ter-
               minal  unless  one  of  -u or -p is present.  This
               option may also be used within zle widgets.

          -k [ num ]



zsh 5.0.5          Last change: January 5, 2014                25






User Commands                                      ZSHBUILTINS(1)



               Read  only  one  (or  num)  characters.   All  are
               assigned  to  the  first name, without word split-
               ting.  This flag is ignored when  -q  is  present.
               Input  is  read from the terminal unless one of -u
               or -p is present.  This option may  also  be  used
               within zle widgets.

               Note  that  despite the mnemonic `key' this option
               does read full characters, which  may  consist  of
               multiple bytes if the option MULTIBYTE is set.

          -z   Read  one  entry  from the editor buffer stack and
               assign it to the first name, without  word  split-
               ting.   Text  is pushed onto the stack with `print
               -z' or with push-line from the  line  editor  (see
               zshzle(1)).   This  flag is ignored when the -k or
               -q flags are present.

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

          -c
          -l   These  flags  are  allowed only if called inside a
               function used for completion (specified  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 ignored.

          -n   Together  with -c, the number of the word the cur-
               sor is on is read.  With  -l,  the  index  of  the
               character the cursor is on is read.  Note that the
               command name is word number 1,  not  word  0,  and
               that  when  the  cursor is at the end of the line,
               its character index is the length of the line plus
               one.

          -u n Input is read from file descriptor n.

          -p   Input is read from the coprocess.

          -d delim
               Input  is  terminated  by  the  first character of
               delim instead of by newline.

          -t [ num ]



zsh 5.0.5          Last change: January 5, 2014                26






User Commands                                      ZSHBUILTINS(1)



               Test if input is available  before  attempting  to
               read.   If  num  is  present, it must begin with a
               digit and will be evaluated to give  a  number  of
               seconds,  which may be a floating point number; in
               this case the read  times  out  if  input  is  not
               available   within  this  time.   If  num  is  not
               present, it is taken to  be  zero,  so  that  read
               returns  immediately if no input is available.  If
               no input is available, return status 1 and do  not
               set any variables.

               This option is not available when reading from the
               editor buffer with -z,  when  called  from  within
               completion with -c or -l, with -q which clears the
               input queue before reading, or  within  zle  where
               other mechanisms should be used to test for input.

               Note that read does not attempt to alter the input
               processing  mode.   The  default mode is canonical
               input, in which an entire line is read at a  time,
               so  usually `read -t' will not read anything until
               an entire line  has  been  typed.   However,  when
               reading  from  the  terminal with -k input is pro-
               cessed 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 interactive.

          The  value  (exit  status)  of  read  is  1   when   an
          end-of-file is encountered, or when -c or -l is present
          and the command is not called from a compctl  function,
          or as described for -q.  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.

     readonly
          Same as typeset -r.

     rehash
          Same as hash -r.

     return [ n ]



zsh 5.0.5          Last change: January 5, 2014                27






User Commands                                      ZSHBUILTINS(1)



          Causes a shell function or `.' script to return to  the
          invoking  script with the return status specified by n.
          If n is omitted, the return status is that of the  last
          command executed.

          If  return  was executed from a trap in a TRAPNAL func-
          tion, 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 state-
          ment `return $((128+$1))' will return the  same  status
          as if the signal had not been trapped.

     sched
          See  the  section  `The  zsh/sched  Module'  in zshmod-
          ules(1).

] ] [ arg ... ]
     set [ {+|-}options | {+|-}o [ option_name ] ] ... [ {+|-}A [
          name
          Set the options for the shell and/or set the positional
          parameters,  or  declare  and  set an array.  If the -s
          option is given, it causes the specified  arguments  to
          be  sorted  before  assigning  them  to  the positional
          parameters (or to the array name if -A is used).   With
          +s sort arguments in descending order.  For the meaning
          of the other flags, see zshoptions(1).   Flags  may  be
          specified  by  name  using  the -o option. If no option
          name is supplied with -o, the current option states are
          printed:   see the description of setopt below for more
          information on the format.  With +o they are printed in
          a form that can be used as input to the shell.

          If  the  -A  flag is specified, name is set to an array
          containing the given args; if no name is specified, all
          arrays are printed together with their values.

          If +A is used and name is an array, the given arguments
          will 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



zsh 5.0.5          Last change: January 5, 2014                28






User Commands                                      ZSHBUILTINS(1)



          values for the array.  This means that

               set -A array -x -- foo

          sets array to `-x -- foo' if KSH_ARRAYS is not set, but
          sets  the  array to foo and turns on the option `-x' if
          it is set.

          If the -A flag is not present, but there are  arguments
          beyond  the options, the positional parameters are set.
          If the option list (if any) is terminated by `--',  and
          there  are no further arguments, the positional parame-
          ters will be unset.

          If no arguments and no `--' are given, then  the  names
          and  values  of all parameters are printed on the stan-
          dard output.  If the only argument is `+', the names of
          all parameters are printed.

          For historical reasons, `set -' is treated as `set +xv'
          and `set - args' as `set +xv -- args' when in any other
          emulation mode than zsh's native mode.

     setcap
          See  the section `The zsh/cap Module' in zshmodules(1).

     setopt [ {+|-}options | {+|-}o option_name ] [ name ... ]
          Set the options for the shell.  All  options  specified
          either with flags or by name are set.

          If  no arguments are supplied, the names of all options
          currently set are printed.  The form is chosen so as to
          minimize  the  differences from the default options for
          the current  emulation  (the  default  emulation  being
          native  zsh,  shown  as <Z> in zshoptions(1)).  Options
          that are on by default for the emulation are shown with
          the prefix no only if they are off, while other options
          are shown without the prefix no and only  if  they  are
          on.   In  addition  to options changed from the default
          state by the user, any options activated  automatically
          by  the  shell (for example, SHIN_STDIN or INTERACTIVE)
          will be shown in the list.  The format is further modi-
          fied by the option KSH_OPTION_PRINT, however the ratio-
          nale for choosing options with or without the no prefix
          remains the same in this case.

          If the -m flag is given the arguments are taken as pat-
          terns (which should be  quoted  to  protect  them  from
          filename  expansion), and all options with names match-
          ing these patterns are set.





zsh 5.0.5          Last change: January 5, 2014                29






User Commands                                      ZSHBUILTINS(1)



          Note that a bad option name does not cause execution of
          subsequent  shell code to be aborted; this is behaviour
          is different from that of `set -o'.   This  is  because
          set is regarded as a special builtin by the POSIX stan-
          dard, but setopt is not.

     shift [ n ] [ name ... ]
          The positional parameters ${n+1} ... are renamed to  $1
          ...,  where n is an arithmetic expression that defaults
          to 1.  If any names are  given  then  the  arrays  with
          these  names  are  shifted  instead  of  the positional
          parameters.

     source file [ arg ... ]
          Same as `.',  except  that  the  current  directory  is
          always  searched  and  is always searched first, before
          directories in $path.

     stat See the section `The zsh/stat Module' in zshmodules(1).

     suspend [ -f ]
          Suspend  the execution of the shell (send it a SIGTSTP)
          until it receives a SIGCONT.  Unless the -f  option  is
          given, this will refuse to suspend a login shell.

     test [ arg ... ]
     [ [ arg ... ] ]
          Like the system version of test.  Added for compatibil-
          ity; use conditional expressions instead (see the  sec-
          tion  `Conditional Expressions').  The main differences
          between the conditional expression syntax and the  test
          and  [  builtins  are:   these commands are not handled
          syntactically, so for example an empty variable  expan-
          sion may cause an argument to be omitted; syntax errors
          cause status 2 to be returned instead of a shell error;
          and   arithmetic  operators  expect  integer  arguments
          rather than arithmetic expressions.

          The command attempts to implement POSIX and its  exten-
          sions  where  these are specified.  Unfortunately there
          are intrinsic ambiguities in the syntax; in  particular
          there  is  no  distinction  between  test operators and
          strings that resemble them.  The standard  attempts  to
          resolve  these  for  small  numbers of arguments (up to
          four); for five or more arguments compatibility  cannot
          be relied on.  Users are urged wherever possible to use
          the `[[' test syntax which does not have these ambigui-
          ties.

     times
          Print  the  accumulated  user  and system times for the
          shell and for processes run from the shell.



zsh 5.0.5          Last change: January 5, 2014                30






User Commands                                      ZSHBUILTINS(1)



     trap [ arg ] [ sig ... ]
          arg is a series of commands (usually quoted to  protect
          it  from  immediate evaluation by the shell) to be read
          and executed when the shell receives any of the signals
          specified  by  one  or  more sig args.  Each sig can be
          given as a number, or as the name of  a  signal  either
          with  or  without the string SIG in front (e.g. 1, HUP,
          and SIGHUP are all the same signal).

          If arg is `-', then the specified signals are reset  to
          their  defaults,  or,  if  no sig args are present, all
          traps are reset.

          If arg is an empty string, then the  specified  signals
          are  ignored  by  the  shell  (and  by  the commands it
          invokes).

          If arg is omitted but one or more sig args are provided
          (i.e.   the  first argument is a valid signal number or
          name), the effect is the same as if arg had been speci-
          fied as `-'.

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

          If sig is ZERR then arg will  be  executed  after  each
          command  with  a  nonzero exit status.  ERR is an alias
          for ZERR on systems that have no SIGERR signal (this is
          the usual case).

          If  sig  is DEBUG then arg will be executed before each
          command if the option DEBUG_BEFORE_CMD is set (as it is
          by  default),  else  after each command.  Here, a `com-
          mand' is what is described as a `sublist' in the  shell
          grammar, see the section SIMPLE COMMANDS & PIPELINES in
          zshmisc(1).  If DEBUG_BEFORE_CMD is set  various  addi-
          tional  features  are available.  First, it is possible
          to  skip  the  next  command  by  setting  the   option
          ERR_EXIT; see the description of the ERR_EXIT option in
          zshoptions(1).  Also, the shell parameter ZSH_DEBUG_CMD
          is set to the string corresponding to the command to be
          executed following the trap.  Note that this string  is
          reconstructed  from  the internal format and may not be
          formatted the same  way  as  the  original  text.   The
          parameter is unset after the trap is executed.

          If  sig is 0 or EXIT and the trap statement is executed
          inside the body of a function, then the command arg  is
          executed after the function completes.  The value of $?
          at the start of execution is the  exit  status  of  the
          shell or the return status of the function exiting.  If
          sig is 0 or EXIT and the trap statement is not executed



zsh 5.0.5          Last change: January 5, 2014                31






User Commands                                      ZSHBUILTINS(1)



          inside  the body of a function, then the command arg is
          executed when  the  shell  terminates;  the  trap  runs
          before any zshexit hook functions.

          ZERR,  DEBUG,  and  EXIT  traps are not executed inside
          other traps.  ZERR and DEBUG traps are kept within sub-
          shells, while other traps are reset.

          Note  that  traps  defined  with  the  trap builtin are
          slightly different from those defined as `TRAPNAL ()  {
          ...  }', as the latter have their own function environ-
          ment (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

               TRAPDEBUG() { print $LINENO; }

          will always print the number zero.

          Alternative signal names are allowed as described under
          kill above.  Defining a trap under either  name  causes
          any trap under an alternative name to be removed.  How-
          ever, it is  recommended  that  for  consistency  users
          stick exclusively to one name or another.

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

     ttyctl -fu
          The  -f  option  freezes  the tty, and -u unfreezes it.
          When the tty is frozen, no changes made to the tty set-
          tings  by  external  programs  will  be  honored by the
          shell, except for changes in the size  of  the  screen;
          the  shell will simply reset the settings to their pre-
          vious values as soon as each command exits or  is  sus-
          pended.  Thus, stty and similar programs have no effect
          when the tty is frozen.   Without  options  it  reports
          whether the terminal is frozen or not.

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

... ]
     typeset [ {+|-}AEFHUafghklprtuxmz ] [ -LRZi [ n ]] [
          name[=value]
]
     typeset -T [ {+|-}Urux ] [ -LRZ [ n ]] SCALAR[=value] array



zsh 5.0.5          Last change: January 5, 2014                32






User Commands                                      ZSHBUILTINS(1)



          [ sep
          Set  or display attributes and values for shell parame-
          ters.

          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 zshparam(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 inte-
          gers.   Unless  the  option  KSH_TYPESET is set, normal
          expansion rules apply to assignment arguments, so value
          may be split into separate words; if the option is set,
          assignments which can be recognised when  expansion  is
          performed are treated as single words.  For example the
          command typeset vbl=$(echo one two) is treated as  hav-
          ing  one  argument if KSH_TYPESET is set, but otherwise
          is treated as having the two arguments vbl=one and two.

          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 command and an assign-
          ment (which will be printed separately for  arrays  and
          associative  arrays),  regardless  of  other  flags and
          options.  Note  that  the  -h  flag  on  parameters  is
          respected; no value will be shown for these parameters.

          If the -T option is given, two or three arguments  must
          be  present  (an  exception  is that zero arguments are
          allowed to show the list of parameters created in  this
          fashion).   The  first two are the name of a scalar and
          an array parameter (in that order) that  will  be  tied
          together  in  the  manner  of  $PATH  and  $path.   The
          optional third argument is a single-character separator
          which will be used to join the elements of the array to
          form the scalar; if absent, a colon is  used,  as  with
          $PATH.   Only  the  first character of the separator is
          significant;  any  remaining  characters  are  ignored.
          Only  the  scalar  parameter may be assigned an initial



zsh 5.0.5          Last change: January 5, 2014                33






User Commands                                      ZSHBUILTINS(1)



          value.  Both the scalar and the array may otherwise  be
          manipulated as normal.  If one is unset, the other will
          automatically be unset too.  There is no way of untying
          the variables without unsetting them, or converting the
          type of one of them with another  typeset  command;  +T
          does  not  work,  assigning  an  array  to SCALAR is an
          error, and assigning a scalar to array sets it to be  a
          single-element array.  Note that both `typeset -xT ...'
          and `export -T ...' work, but only the scalar  will  be
          marked  for export.  Setting the value using the scalar
          version causes a split on all separators (which  cannot
          be  quoted).   It  is possible to use the same two tied
          variables with a different separator character in which
          case the variables remain joined as before but the sep-
          arator is changed.  This flag has a  different  meaning
          when used with -f; see below.

          The  -g  (global)  flag  is treated specially: it means
          that any resulting parameter will not be restricted  to
          local  scope.  Note that this does not necessarily mean
          that the parameter will be global,  as  the  flag  will
          apply to any existing parameter (even if unset) from an
          enclosing function.  This  flag  does  not  affect  the
          parameter  after  creation, hence it has no effect when
          listing existing parameters, nor does the flag +g  have
          any effect except in combination with -m (see below).

          If  no  name  is  present,  the names and values of all
          parameters are printed.  In  this  case  the  attribute
          flags  restrict  the  display  to only those parameters
          that have  the  specified  attributes,  and  using  `+'
          rather than `-' to introduce the flag suppresses print-
          ing of the values of parameters when there is no param-
          eter  name.   Also, if the last option is the word `+',
          then names are printed but values are not.

          If the -m flag is given the name arguments are taken as
          patterns  (which  should be quoted).  With no attribute
          flags, all parameters (or functions with the  -f  flag)
          with matching names are printed (the shell option TYPE-
          SET_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



zsh 5.0.5          Last change: January 5, 2014                34






User Commands                                      ZSHBUILTINS(1)



          parameter (array, association, exported, integer, read-
          only).   If  +m  is  used with attribute flags, and all
          those flags are introduced with +, the matching parame-
          ter names are printed but their values are not.

          Attribute flags that transform the final value (-L, -R,
          -Z, -l, u) are only applied to the  expanded  value  at
          the  point  of  a  parameter expansion expression using
          `$'.   They  are  not  applied  when  a  parameter   is
          retrieved internally by the shell for any purpose.

          The following attribute flags may be specified:

          -A   The  names  refer to associative array parameters;
               see `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.  If n is zero, the width is  determined  by
               the  width  of  the value of the first assignment.
               In the case of numeric parameters, the  length  of
               the  complete  value  assigned to the parameter is
               used to determine the width, not  the  value  that
               would be output.

               The width is the count of characters, which may be
               multibyte characters if the MULTIBYTE option is in
               effect.  Note that the screen width of the charac-
               ter  is  not  taken  into  account;  if  this   is
               required,  use  padding  with  parameter expansion
               flags ${(ml...)...}  as  described  in  `Parameter
               Expansion Flags' in zshexpn(1).

               When  the  parameter  is expanded, it is filled on
               the right with blanks or truncated if necessary to
               fit  the field.  Note truncation can lead to unex-
               pected results with numeric  parameters.   Leading
               zeros are removed if the -Z flag is also set.

          -R   Similar  to -L, except that right justification is
               used; when the parameter is expanded, the field is
               left filled with blanks or truncated from the end.
               May not be combined with the -Z flag.

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

          -Z   Specially  handled  if set along with the -L flag.



zsh 5.0.5          Last change: January 5, 2014                35






User Commands                                      ZSHBUILTINS(1)



               Otherwise, similar  to  -R,  except  that  leading
               zeros  are  used  for padding instead of blanks if
               the first non-blank character is a digit.  Numeric
               parameters  are specially handled: they are always
               eligible for padding with zeroes, and  the  zeroes
               are  inserted  at an appropriate place in the out-
               put.

          -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  parame-
               ters.   No  assignments  can be made, and the only
               other valid flags are -t, -T, -k, -u, -U  and  -z.
               The  flag  -t  turns on execution tracing for this
               function; the flag -T does the same, but turns off
               tracing  on  any  function called from the present
               one, unless that function also has the  -t  or  -T
               flag.   The  -u and -U flags cause the function to
               be marked for autoloading; -U  also  causes  alias
               expansion  to  be  suppressed when the function is
               loaded.  The fpath parameter will be  searched  to
               find  the function definition when the function is
               first referenced; see the section `Functions'. The
               -k  and -z flags make the function be loaded using
               ksh-style or zsh-style  autoloading  respectively.
               If   neither   is   given,   the  setting  of  the
               KSH_AUTOLOAD option determines how the function is
               loaded.

          -h   Hide:  only  useful  for special parameters (those
               marked `<S>' in the table in zshparam(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
               special effect when made local.  Thus after `type-
               set -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  parameter
               using  `typeset  +h special', where the local copy
               of special  will  retain  its  special  properties
               regardless  of  having  the  -h attribute.  Global
               special parameters loaded from shell modules (cur-
               rently those in zsh/mapfile and zsh/parameter) are



zsh 5.0.5          Last change: January 5, 2014                36






User Commands                                      ZSHBUILTINS(1)



               automatically given the -h attribute to avoid name
               clashes.

          -H   Hide  value:  specifies that typeset will not dis-
               play the  value  of  the  parameter  when  listing
               parameters;  the  display  for  such parameters is
               always as if the `+' flag had been given.  Use  of
               the parameter is in other respects normal, and the
               option does not apply if the parameter  is  speci-
               fied  by  name,  or by pattern with the -m option.
               This is on by default for the  parameters  in  the
               zsh/parameter and zsh/mapfile modules.  Note, how-
               ever, 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  arithmetic  base,
               otherwise  it  is  determined by the first assign-
               ment.  Bases from 2 to 36 inclusive are allowed.

          -E   Use an internal  double-precision  floating  point
               representation.   On  output  the variable will be
               converted to scientific notation.  If n is nonzero
               it  defines  the  number of significant figures to
               display; the default is ten.

          -F   Use an internal  double-precision  floating  point
               representation.   On  output  the variable will be
               converted to fixed-point decimal notation.   If  n
               is nonzero it defines the number of digits to dis-
               play after the decimal point; the default is  ten.

          -l   Convert  the  result  to  lower  case whenever the
               parameter is expanded.  The value is not converted
               when assigned.

          -r   The given names are marked readonly.  Note that if
               name  is  a  special   parameter,   the   readonly
               attribute  can  be  turned  on, but cannot then be
               turned off.

          -t   Tags the named parameters.  Tags have  no  special
               meaning  to  the shell.  This flag has a different
               meaning when used with -f; see above.

          -u   Convert the result  to  upper  case  whenever  the
               parameter is expanded.  The value is not converted
               when assigned.  This flag has a different  meaning
               when used with -f; see above.

          -x   Mark  for  automatic  export to the environment of
               subsequently executed  commands.   If  the  option



zsh 5.0.5          Last change: January 5, 2014                37






User Commands                                      ZSHBUILTINS(1)



               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.

     ulimit [ [ -SHacdfiklmnpqsTtvwx | -N resource [ limit ] ...
          ]
          Set or display resource limits of  the  shell  and  the
          processes started by the shell.  The value of limit can
          be a number in the unit specified below or one  of  the
          values  `unlimited',  which  removes  the  limit on the
          resource, or `hard', which uses the  current  value  of
          the hard limit on the resource.

          By default, only soft limits are manipulated. If the -H
          flag is given use hard limits instead of  soft  limits.
          If  the  -S flag is given together with the -H flag set
          both hard and soft limits.

          If no options are used, the file  size  limit  (-f)  is
          assumed.

          If  limit is omitted the current value of the specified
          resources are printed.  When  more  than  one  resource
          value  is  printed,  the limit name and unit is printed
          before each value.

          When looping over multiple resources,  the  shell  will
          abort  immediately  if  it detects a badly formed argu-
          ment.  However, if it fails to set  a  limit  for  some
          other reason it will continue trying to set the remain-
          ing limits.

          Not all the following resources are  supported  on  all
          systems.   Running  ulimit  -a will show which are sup-
          ported.

          -a   Lists all of the current resource limits.
          -b   Socket buffer size in bytes (N.B. not kilobytes)
          -c   512-byte blocks on the size of core dumps.
          -d   Kilobytes on the size of the data segment.
          -f   512-byte blocks on the size of files written.
          -i   The number of pending signals.
          -k   The number of kqueues allocated.
          -l   Kilobytes on the size of locked-in memory.
          -m   Kilobytes on the size of physical memory.
          -n   open file descriptors.
          -p   The number of pseudo-terminals.
          -q   Bytes in POSIX message queues.
          -s   Kilobytes on the size of the stack.
          -T   The number of simultaneous  threads  available  to



zsh 5.0.5          Last change: January 5, 2014                38






User Commands                                      ZSHBUILTINS(1)



               the user.
          -t   CPU seconds to be used.
          -u   The number of processes available to the user.
          -v   Kilobytes  on the size of virtual memory.  On some
               systems this refers to the limit  called  `address
               space'.
          -w   Kilobytes on the size of swapped out memory.
          -x   The number of locks on files.

          A resource may also be specified by integer in the form
          `-N resource', where resource corresponds to the  inte-
          ger  defined  for the resource by the operating system.
          This may be used to set the limits for resources  known
          to the shell which do not correspond to option letters.
          Such limits will be shown by number in  the  output  of
          `ulimit -a'.

          The  number  may  alternatively  be out of the range of
          limits compiled into the shell.  The shell will try  to
          read  or  write  the  limit  anyway, and will report an
          error if this fails.

     umask [ -S ] [ mask ]
          The umask is set to mask.  mask can be either an  octal
          number  or  a  symbolic value as described in chmod(1).
          If mask is omitted, the current value is printed.   The
          -S  option  causes the mask to be printed as a symbolic
          value.  Otherwise, the mask is printed as an octal num-
          ber.   Note  that  in the symbolic form the permissions
          you specify are those which  are  to  be  allowed  (not
          denied) to the users specified.

     unalias
          Same as unhash -a.

     unfunction
          Same as unhash -f.

     unhash [ -adfms ] name ...
          Remove the element named name from an internal hash ta-
          ble.  The default is remove elements from  the  command
          hash table.  The -a option causes unhash to remove reg-
          ular or global aliases; note  when  removing  a  global
          aliases  that the argument must be quoted to prevent it
          from being expanded before being passed to the command.
          The  -s  option causes unhash to remove suffix aliases.
          The -f option causes unhash to remove shell  functions.
          The  -d  options causes unhash to remove named directo-
          ries.  If the -m flag is given the arguments are  taken
          as  patterns (should be quoted) and all elements of the
          corresponding hash table with matching  names  will  be
          removed.



zsh 5.0.5          Last change: January 5, 2014                39






User Commands                                      ZSHBUILTINS(1)



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

          The  unlimit  command  is not made available by default
          when the shell  starts  in  a  mode  emulating  another
          shell.   It  can  be  made  available  with the command
          `zmodload -F zsh/rlimits b:unlimit'.

     unset [ -fmv ] name ...
          Each named parameter is unset.  Local parameters remain
          local  even  if  unset; they appear unset within scope,
          but the previous value will  still  reappear  when  the
          scope ends.

          Individual elements of associative array parameters may
          be unset by  using  subscript  syntax  on  name,  which
          should  be  quoted (or the entire command prefixed with
          noglob) to protect the subscript from filename  genera-
          tion.

          If  the -m flag is specified the arguments are taken as
          patterns (should be quoted)  and  all  parameters  with
          matching  names  are  unset.   Note that this cannot be
          used when unsetting associative array elements, as  the
          subscript will be treated as part of the pattern.

          The  -v  flag specifies that name refers to parameters.
          This is the default behaviour.

          unset -f is equivalent to unfunction.

     unsetopt [ {+|-}options | {+|-}o option_name ] [ name ... ]
          Unset the options for the shell.  All options specified
          either  with  flags  or by name are unset.  If no argu-
          ments are supplied, the names of all options  currently
          unset  are  printed.  If the -m flag is given the argu-
          ments are taken as patterns (which should be quoted  to
          preserve them from being interpreted as glob patterns),
          and all options with names matching these patterns  are
          unset.

     vared
          See the section `Zle Builtins' in zshzle(1).

     wait [ job ... ]
          Wait  for  the  specified jobs or processes.  If job is
          not given then all currently active child processes are
          waited for.  Each job can be either a job specification



zsh 5.0.5          Last change: January 5, 2014                40






User Commands                                      ZSHBUILTINS(1)



          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 dis-
               played,  which  would  otherwise not happen unless
               the -c flag were used.

          -p   Do a path search for name even if it is an  alias,
               reserved word, shell function or builtin.

          -a   Do a search for all occurrences of name throughout
               the command path.  Normally only the first  occur-
               rence is printed.

          -m   The  arguments  are  taken  as patterns (should be
               quoted), and the information is displayed for each
               command matching one of these patterns.

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

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

     which [ -wpams ] name ...
          Equivalent to whence -c.

     zcompile [ -U ] [ -z | -k ] [ -R | -M ] file [ name ... ]
     zcompile -ca [ -m ] [ -R | -M ] file [ name ... ]
     zcompile -t file [ name ... ]
          This builtin command can be used to  compile  functions
          or scripts, storing the compiled form in a file, and to
          examine  files  containing  the  compiled  form.   This
          allows faster autoloading of functions and execution of
          scripts by avoiding parsing of the text when the  files



zsh 5.0.5          Last change: January 5, 2014                41






User Commands                                      ZSHBUILTINS(1)



          are read.

          The  first form (without the -c, -a or -t options) cre-
          ates 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 func-
          tion file when the function is autoloaded; see the sec-
          tion   `Autoloading  Functions'  in  zshmisc(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  functions  into
          file.   For  -c,  the names must be functions currently
          defined in the shell, not those marked for autoloading.
          Undefined functions that are marked for autoloading may
          be written by using the -a option, in  which  case  the
          fpath  is  searched  and the contents of the 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  as
          if the KSH_AUTOLOAD option were unset.

          The reason for handling loaded and not-yet-loaded func-
          tions with different options is  that  some  definition
          files   for   autoloading  define  multiple  functions,
          including the function with the same name as the  file,
          and, at the end, call that function.  In such cases the
          output of `zcompile -c' does not include the additional
          functions  defined  in the file, and any other initial-
          ization code in the file is lost.  Using `zcompile  -a'
          captures all this extra information.

          If  the  -m option is combined with -c or -a, the names
          are used as patterns  and  all  functions  whose  names
          match one of these patterns will be written. If no name
          is given, the definitions of  all  functions  currently
          defined or marked as autoloaded will be written.

          The  third form, with the -t option, examines an exist-
          ing compiled  file.   Without  further  arguments,  the



zsh 5.0.5          Last change: January 5, 2014                42






User Commands                                      ZSHBUILTINS(1)



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

          Other options:

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

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

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

          -M   The  compiled file is mapped into the shell's mem-
               ory 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.

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

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




zsh 5.0.5          Last change: January 5, 2014                43






User Commands                                      ZSHBUILTINS(1)



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

     zformat
          See the  section  `The  zsh/zutil  Module'  in  zshmod-
          ules(1).

     zftp See the section `The zsh/zftp Module' in zshmodules(1).

     zle  See the section `Zle Builtins' in zshzle(1).

     zmodload [ -dL ] [ ... ]
     zmodload -F [ -lLme -P param ] module [+-]feature...
     zmodload -e [ -A ] [ ... ]
     zmodload [ -a [ -bcpf [ -I ] ] ] [ -iL ] ...
     zmodload -u [ -abcdpf [ -I ] ] [ -iL ] ...
     zmodload -A [ -L ] [ modalias[=module] ... ]
     zmodload -R modalias ...
          Performs operations relating to zsh's loadable modules.
          Loading of modules while the shell is running (`dynami-
          cal loading') is not available on  all  operating  sys-
          tems, 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 com-
          mands.  Forms with arguments are:

          zmodload [ -i ] name ...
          zmodload -u [ -i ] name ...
               In the simplest case, zmodload loads a binary mod-
               ule.   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  the
               duplicate  module is ignored.  If zmodload detects
               an inconsistency, such as an invalid  module  name
               or  circular  dependency  list,  the  current code
               block  is  aborted.     Hence   `zmodload   module
               2>/dev/null'  is sufficient to test whether a mod-
               ule is available.  If it is available, the  module
               is  loaded if necessary, while if it is not avail-
               able, non-zero status is silently  returned.   The
               option -i is accepted for compatibility but has no



zsh 5.0.5          Last change: January 5, 2014                44






User Commands                                      ZSHBUILTINS(1)



               effect.

               The named module is searched for in the same way a
               command  is,  using $module_path instead of $path.
               However, the path search is  performed  even  when
               the  module  name contains a `/', which it usually
               does.  There is no way to prevent the path search.

               If the module supports features (see below), zmod-
               load tries to enable all features when  loading  a
               module.  If the module was successfully loaded but
               not  all  features  could  be  enabled,   zmodload
               returns status 2.

               With  -u, zmodload unloads modules.  The same name
               must be given that was given when the  module  was
               loaded,  but it is not necessary for the module to
               exist in the file  system.   The  -i  option  sup-
               presses   the  error  if  the  module  is  already
               unloaded (or was never loaded).

               Each module has a boot  and  a  cleanup  function.
               The module will not be loaded if its boot function
               fails.  Similarly a module can only be unloaded if
               its cleanup function runs successfully.

          zmodload -F [ -almLe -P param ] module [+-]feature...
               zmodload -F allows more selective control over the
               features provided by  modules.   With  no  options
               apart  from -F, the module named module is loaded,
               if it was not already loaded, and the list of fea-
               tures  is  set  to the required state.  If no fea-
               tures are specified, the module is loaded,  if  it
               was  not already loaded, but the state of features
               is unchanged.  Each feature may be preceded by a +
               to turn the feature on, or - to turn it off; the +
               is assumed if neither character is  present.   Any
               feature  not  explicitly  mentioned is left in its
               current state; if the module  was  not  previously
               loaded  this  means  any such features will remain
               disabled.  The return status is zero if  all  fea-
               tures  were  set,  1 if the module failed to load,
               and 2 if some features could not be set (for exam-
               ple,  a  parameter couldn't be added because there
               was a different parameter of the  same  name)  but
               the module was loaded.

               The  standard  features  are builtins, conditions,
               parameters and math functions; these are indicated
               by the prefix `b:', `c:' (`C:' for an infix condi-
               tion), `p:' and `f:',  respectively,  followed  by
               the name that the corresponding feature would have



zsh 5.0.5          Last change: January 5, 2014                45






User Commands                                      ZSHBUILTINS(1)



               in the shell.  For example, `b:strftime' indicates
               a  builtin named strftime and p:EPOCHSECONDS indi-
               cates a parameter named EPOCHSECONDS.  The  module
               may provide other (`abstract') features of its own
               as indicated by its documentation; these  have  no
               prefix.

               With -l or -L, features provided by the module are
               listed.   With  -l  alone,  a  list  of   features
               together  with  their states is shown, one feature
               per line.  With -L alone, a  zmodload  -F  command
               that would cause enabled features of the module to
               be turned on is shown.  With -lL,  a  zmodload  -F
               command  that  would  cause all the features to be
               set to their current state is shown.   If  one  of
               these  combinations  is  given the option -P param
               then the parameter param is set  to  an  array  of
               features,  either  features  together  with  their
               state or (if -L alone is given) enabled  features.

               With the option -L the module name may be omitted;
               then a list of all enabled features for  all  mod-
               ules  providing features is printed in the form of
               zmodload -F commands.  If -l is  also  given,  the
               state  of  both  enabled  and disabled features is
               output in that form.

               A set of features may be provided together with -l
               or  -L  and  a  module name; in that case only the
               state of those features is considered.  Each  fea-
               ture  may  be preceded by + or - but the character
               has no effect.  If no set of features is provided,
               all features are considered.

               With  -e,  the command first tests that the module
               is loaded; if it is not, status 1 is returned.  If
               the  module  is loaded, the list of features given
               as an argument is  examined.   Any  feature  given
               with no prefix is simply tested to see if the mod-
               ule provides it; any feature given with a prefix +
               or  -  is  tested to see if is provided and in the
               given state.  If the tests on all features in  the
               list succeed, status 0 is returned, else status 1.

               With -m, each entry in the given list of  features
               is  taken  as  a pattern to be matched against the
               list of features provided by the module.  An  ini-
               tial  +  or  - must be given explicitly.  This may
               not be combined with the -a  option  as  autoloads
               must be specified explicitly.





zsh 5.0.5          Last change: January 5, 2014                46






User Commands                                      ZSHBUILTINS(1)



               With  -a, the given list of features is marked for
               autoload from the specified module, which may  not
               yet  be  loaded.   An optional + may appear before
               the feature name.  If the feature is prefixed with
               -,  any existing autoload is removed.  The options
               -l  and  -L  may  be  used  to   list   autoloads.
               Autoloading  is  specific  to individual features;
               when the module is loaded only the requested  fea-
               ture  is enabled.  Autoload requests are preserved
               if the module is subsequently  unloaded  until  an
               explicit `zmodload -Fa module -feature' is issued.
               It is not an error to request an  autoload  for  a
               feature of a module that is already loaded.

               When the module is loaded each autoload is checked
               against the features actually provided by the mod-
               ule;  if  the feature is not provided the autoload
               request is deleted.  A warning message is  output;
               if the module is being loaded to provide a differ-
               ent feature,  and  that  autoload  is  successful,
               there  is  no  effect on the status of the current
               command.  If the module is already loaded  at  the
               time when zmodload -Fa is run, an error message is
               printed and status 1 returned.

               zmodload -Fa can be used with the -l, -L,  -e  and
               -P  options  for listing and testing the existence
               of autoloadable features.   In  this  case  -l  is
               ignored if -L is specified.  zmodload -FaL with no
               module name lists autoloads for all modules.

               Note that  only  standard  features  as  described
               above  can  be  autoloaded; other features require
               the module to be loaded before enabling.

          zmodload -d [ -L ] [ name ]
          zmodload -d name dep ...
          zmodload -ud name [ dep ... ]
               The -d option can be used to specify module depen-
               dencies.  The modules named in the second and sub-
               sequent arguments will be loaded before the module
               named in the first argument.

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

               If -d and  -u  are  both  used,  dependencies  are
               removed.   If  only  one  argument  is  given, all



zsh 5.0.5          Last change: January 5, 2014                47






User Commands                                      ZSHBUILTINS(1)



               dependencies for that module are removed.

          zmodload -ab [ -L ]
          zmodload -ab [ -i ] name [ builtin ... ]
          zmodload -ub [ -i ] builtin ...
               The -ab option defines  autoloaded  builtins.   It
               defines the specified builtins.  When any of those
               builtins is called, the module  specified  in  the
               first  argument is loaded and all its features are
               enabled (for selective  control  of  features  use
               `zmodload -F -a' as described above).  If only the
               name is given, one builtin is  defined,  with  the
               same  name as the module.  -i suppresses the error
               if the builtin is already defined  or  autoloaded,
               but  not  if  another  builtin of the same name is
               already defined.

               With -ab and no arguments, all autoloaded builtins
               are  listed,  with  the module name (if different)
               shown in parentheses after the builtin name.   The
               -L  option  changes this format to a list of zmod-
               load -a commands.

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

               Autoload requests are retained if  the  module  is
               subsequently  unloaded until an explicit `zmodload
               -ub builtin' is issued.

          zmodload -ac [ -IL ]
          zmodload -ac [ -iI ] name [ cond ... ]
          zmodload -uc [ -iI ] cond ...
               The -ac option is used to define autoloaded condi-
               tion codes. The cond strings give the names of the
               conditions defined by the module. The optional  -I
               option  is  used  to define infix condition names.
               Without this option  prefix  condition  names  are
               defined.

               If given no condition names, all defined names are
               listed (as a series of zmodload commands if the -L
               option is given).

               The  -uc option removes definitions for autoloaded
               conditions.

          zmodload -ap [ -L ]
          zmodload -ap [ -i ] name [ parameter ... ]



zsh 5.0.5          Last change: January 5, 2014                48






User Commands                                      ZSHBUILTINS(1)



          zmodload -up [ -i ] parameter ...
               The -p option is like the -b and -c  options,  but
               makes   zmodload  work  on  autoloaded  parameters
               instead.

          zmodload -af [ -L ]
          zmodload -af [ -i ] name [ function ... ]
          zmodload -uf [ -i ] function ...
               The -f option is like the -b, -p, and -c  options,
               but  makes  zmodload work on autoloaded math func-
               tions 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.   If  arguments  are  provided,  nothing is
               printed; the return status is set to zero  if  all
               strings  given  as  arguments  are names of loaded
               modules and to one if at least on  string  is  not
               the  name of a loaded module.  This can be used to
               test for the availability of things implemented by
               modules.   In this case, any aliases are automati-
               cally resolved and the -A flag is not used.

          zmodload -A [ -L ] [ modalias[=module] ... ]
               For each argument, if both modalias and module are
               given, define modalias to be an alias for the mod-
               ule module.  If the module modalias is ever subse-
               quently  requested,  either via a call to zmodload
               or implicitly, the shell will attempt to load mod-
               ule  instead.   If  module  is not given, show the
               definition  of  modalias.   If  no  arguments  are
               given,  list  all  defined  module  aliases.  When
               listing, if the -L flag was also given,  list  the
               definition  as  a zmodload command to recreate the
               alias.

               The existence of aliases for modules is completely
               independent  of whether the name resolved is actu-
               ally loaded as a module: while the  alias  exists,
               loading  and  unloading the module under any alias
               has exactly the same effect as using the  resolved
               name,  and  does not affect the connection between
               the alias and  the  resolved  name  which  can  be
               removed either by zmodload -R or by redefining the
               alias.  Chains of aliases (i.e.  where  the  first



zsh 5.0.5          Last change: January 5, 2014                49






User Commands                                      ZSHBUILTINS(1)



               resolved  name  is  itself  an alias) are valid so
               long as these are not circular.   As  the  aliases
               take  the  same  format  as module names, they may
               include path separators:  in this case,  there  is
               no  requirement  for any part of the path named to
               exist as the alias will be  resolved  first.   For
               example,  `any/old/alias' is always a valid alias.

               Dependencies added to aliased modules are actually
               added  to the resolved module; these remain if the
               alias is removed.  It is valid to create an  alias
               whose  name  is  one of the standard shell modules
               and which resolves to a  different  module.   How-
               ever, if a module has dependencies, it will not be
               possible to use the module name as an alias as the
               module will already be marked as a loadable module
               in its own right.

               Apart from the above, aliases can be used  in  the
               zmodload   command   anywhere   module  names  are
               required.  However, aliases will not be  shown  in
               lists of loaded modules with a bare `zmodload'.

          zmodload -R modalias ...
               For  each  modalias  argument  that was previously
               defined as a module alias via zmodload -A,  delete
               the  alias.   If  any was not defined, an error is
               caused and the remainder of the line is ignored.

          Note that zsh makes no distinction between modules that
          were  linked into the shell and modules that are loaded
          dynamically. In both cases this builtin command has  to
          be used to make available the builtins and other things
          defined by modules (unless the module is autoloaded  on
          these  definitions). This is true even for systems that
          don't support dynamic loading of modules.

     zparseopts
          See the  section  `The  zsh/zutil  Module'  in  zshmod-
          ules(1).

     zprof
          See  the  section  `The  zsh/zprof  Module'  in zshmod-
          ules(1).

     zpty See the section `The zsh/zpty Module' in zshmodules(1).

     zregexparse
          See  the  section  `The  zsh/zutil  Module'  in zshmod-
          ules(1).

     zsocket



zsh 5.0.5          Last change: January 5, 2014                50






User Commands                                      ZSHBUILTINS(1)



          See the section `The zsh/net/socket Module' in  zshmod-
          ules(1).

     zstyle
          See  the  section  `The  zsh/zutil  Module'  in zshmod-
          ules(1).

     ztcp See the section `The  zsh/net/tcp  Module'  in  zshmod-
          ules(1).



ATTRIBUTES
     See   attributes(5)   for   descriptions  of  the  following
     attributes:

     +---------------+------------------+
     |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
     +---------------+------------------+
     |Availability   | shell/zsh        |
     +---------------+------------------+
     |Stability      | Volatile         |
     +---------------+------------------+
NOTES
     This  software  was   built   from   source   available   at
     https://java.net/projects/solaris-userland.    The  original
     community   source   was   downloaded   from    http://down-
     loads.source-
     forge.net/project/zsh/zsh/5.0.5/zsh-5.0.5.tar.bz2

     Further information about this software can be found on  the
     open source community website at http://www.zsh.org/.























zsh 5.0.5          Last change: January 5, 2014                51






User Commands                                           ZSHZLE(1)



NAME
     zshzle - zsh command line editor

DESCRIPTION
     If the ZLE option is set (which it is by default in interac-
     tive shells) and the shell input is attached to  the  termi-
     nal, 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 sec-
     ond, single line mode, is used if TERM is invalid  or  inca-
     pable  of  moving  the  cursor up, or if the SINGLE_LINE_ZLE
     option is set.  This mode is similar to  ksh,  and  uses  no
     termcap  sequences.  If TERM is "emacs", the ZLE option will
     be unset by default.

     The parameters BAUD, COLUMNS, and LINES are also used by the
     line  editor.   See  Parameters  Used  By  The Shell in zsh-
     param(1).

     The parameter zle_highlight is also used by the line editor;
     see  Character  Highlighting below.  Highlighting of special
     characters and the region between the cursor  and  the  mark
     (as  set  with set-mark-command in Emacs mode) is enabled by
     default; consult this reference for more information.  Iras-
     cible  conservatives will wish to know that all highlighting
     may be disabled by the following setting:

          zle_highlight=(none)

KEYMAPS
     A keymap in ZLE contains  a  set  of  bindings  between  key
     sequences  and  ZLE commands.  The empty key sequence cannot
     be bound.

     There can be any number of keymaps at  any  time,  and  each
     keymap  has  one  or more names.  If all of a keymap's names
     are deleted, it disappears.  bindkey can be used to  manipu-
     late keymap names.

     Initially, there are six keymaps:

     emacs
          EMACS emulation
     viins
          vi emulation - insert mode
     vicmd
          vi emulation - command mode
     isearch
          incremental search mode
     command



zsh 5.0.5          Last change: January 5, 2014                 1






User Commands                                           ZSHZLE(1)



          read a command name
     .safe
          fallback keymap

     The `.safe' keymap is special.  It can never be altered, and
     the name can never be removed.  However, it can be linked to
     other names, which can be removed.  In the future other spe-
     cial keymaps may be added; users should  avoid  using  names
     beginning with `.' for their own keymaps.

     In  addition  to  these  names, either `emacs' or `viins' is
     also linked to the name `main'.  If one  of  the  VISUAL  or
     EDITOR  environment  variables  contain the string `vi' when
     the shell starts up then it will be  `viins',  otherwise  it
     will be `emacs'.  bindkey's -e and -v options provide a con-
     venient way to override this default choice.

     When the editor starts up, it will select the `main' keymap.
     If that keymap doesn't exist, it will use `.safe' instead.

     In   the  `.safe'  keymap,  each  single  key  is  bound  to
     self-insert, except for ^J (line feed) and ^M (return) which
     are bound to accept-line.  This is deliberately not pleasant
     to use; if you are using it, it means you deleted  the  main
     keymap, and you should put it back.

  Reading Commands
     When ZLE is reading a command from the terminal, it may read
     a sequence that is bound to some command and is also a  pre-
     fix  of a longer bound string.  In this case ZLE will wait a
     certain time to see if more characters are typed, and if not
     (or  they don't match any longer string) it will execute the
     binding.  This timeout is defined by the KEYTIMEOUT  parame-
     ter;  its  default  is  0.4 sec.  There is no timeout if the
     prefix string is not itself bound to a command.

     The key timeout is also applied  when  ZLE  is  reading  the
     bytes  from  a  multibyte character string when it is in the
     appropriate mode.  (This requires that the  shell  was  com-
     piled with multibyte mode enabled; typically also the locale
     has characters with the UTF-8 encoding, although any  multi-
     byte  encoding  known to the operating system is supported.)
     If the second or a subsequent byte is not  read  within  the
     timeout period, the shell acts as if ? were typed and resets
     the input state.

     As well as ZLE commands, key sequences can be bound to other
     strings,  by  using  `bindkey  -s'.  When such a sequence is
     read, the replacement string is pushed back  as  input,  and
     the  command  reading  process starts again using these fake
     keystrokes.  This input can itself invoke  further  replace-
     ment  strings, but in order to detect loops the process will



zsh 5.0.5          Last change: January 5, 2014                 2






User Commands                                           ZSHZLE(1)



     be stopped if there are twenty such replacements  without  a
     real command being read.

     A  key  sequence typed by the user can be turned into a com-
     mand name for use in user-defined widgets with the read-com-
     mand widget, described below.

ZLE BUILTINS
     The  ZLE module contains three related builtin commands. The
     bindkey command manipulates keymaps and  key  bindings;  the
     vared command invokes ZLE on the value of a shell parameter;
     and the zle command manipulates editing widgets  and  allows
     command  line access to ZLE commands from within shell func-
     tions.

     bindkey [ options ] -l [ -L ] [ keymap ... ]
     bindkey [ options ] -d
     bindkey [ options ] -D keymap ...
     bindkey [ options ] -A old-keymap new-keymap
     bindkey [ options ] -N new-keymap [ old-keymap ]
     bindkey [ options ] -m
     bindkey [ options ] -r in-string ...
     bindkey [ options ] -s in-string out-string ...
     bindkey [ options ] in-string command ...
     bindkey [ options ] [ in-string ]
          bindkey's options can be divided into three categories:
          keymap  selection  for  the  current command, operation
          selection, and others.  The  keymap  selection  options
          are:

          -e   Selects  keymap  `emacs' for any operations by the
               current command, and also links `emacs' to  `main'
               so  that  it  is selected by default the next time
               the editor starts.

          -v   Selects keymap `viins' for any operations  by  the
               current  command, and also links `viins' to `main'
               so that it is selected by default  the  next  time
               the editor starts.

          -a   Selects  keymap  `vicmd' for any operations by the
               current command.

          -M keymap
               The  keymap  specifies  a  keymap  name  that   is
               selected  for  any  operations by the current com-
               mand.

          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:



zsh 5.0.5          Last change: January 5, 2014                 3






User Commands                                           ZSHZLE(1)



          -l   List  all  existing keymap names; if any arguments
               are given, list just those keymaps.

               If the -L option is also used, list in the form of
               bindkey  commands  to  create or link the keymaps.
               `bindkey -lL main' shows which keymap is linked to
               `main', if any, and hence if the standard emacs or
               vi emulation is in effect.  This option  does  not
               show the .safe keymap because it cannot be created
               in that fashion; however, neither is `bindkey  -lL
               .safe'  reported  as  an  error, it simply outputs
               nothing.

          -d   Delete all  existing  keymaps  and  reset  to  the
               default state.

          -D keymap ...
               Delete the named keymaps.

          -A old-keymap new-keymap
               Make  the new-keymap name an alias for old-keymap,
               so that both names refer to the same keymap.   The
               names  have  equal standing; if either is deleted,
               the other remains.  If there is already  a  keymap
               with the new-keymap name, it is deleted.

          -N new-keymap [ old-keymap ]
               Create  a  new  keymap,  named  new-keymap.   If a
               keymap already has that name, it is  deleted.   If
               an  old-keymap  name  is  given, the new keymap is
               initialized to be a duplicate of it, otherwise the
               new keymap will be empty.

          To  use  a newly created keymap, it should be linked to
          main.  Hence the sequence of commands to create and use
          a  new keymap `mymap' initialized from the emacs keymap
          (which remains unchanged) is:

               bindkey -N mymap emacs
               bindkey -A mymap main

          Note that while `bindkey -A newmap main' will work when
          newmap  is  emacs or viins, it will not work for vicmd,
          as switching from vi insert  to  command  mode  becomes
          impossible.

          The following operations act on the `main' keymap if no
          keymap selection option was given:

          -m   Add the built-in set of meta-key bindings  to  the
               selected  keymap.   Only  keys that are unbound or
               bound to self-insert are affected.



zsh 5.0.5          Last change: January 5, 2014                 4






User Commands                                           ZSHZLE(1)



          -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 pre-
               fixes.  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  cur-
               sor  keys),  but  leave the binding for the escape
               character itself (probably vi-cmd-mode).  This  is
               incompatible with the option -R.

          -s in-string out-string ...
               Bind  each  in-string  to  each  out-string.  When
               in-string is typed, out-string will be pushed back
               and  treated as input to the line editor.  When -R
               is also used, interpret the in-strings as  ranges.

          in-string command ...
               Bind  each  in-string to each command.  When -R is
               used, interpret the in-strings as ranges.

          [ in-string ]
               List key bindings.  If an in-string is  specified,
               the  binding of that string in the selected keymap
               is 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 bind-
               ings.





zsh 5.0.5          Last change: January 5, 2014                 5






User Commands                                           ZSHZLE(1)



     When the -R option is used as noted  above,  a  valid  range
     consists  of  two  characters,  with an optional `-' between
     them.  All characters between the two specified,  inclusive,
     are bound as specified.

     For  either  in-string  or  out-string, the following escape
     sequences are recognised:

     \a   bell character
     \b   backspace
     \e, \E
          escape
     \f   form feed
     \n   linefeed (newline)
     \r   carriage return
     \t   horizontal tab
     \v   vertical tab
     \NNN character code in octal
     \xNN character code in hexadecimal
     \M[-]X
          character with meta bit set
     \C[-]X
          control character
     ^X   control character

     In all other cases, `\'  escapes  the  following  character.
     Delete  is written as `^?'.  Note that `\M^?' and `^\M?' are
     not the same, and that (unlike emacs), the  bindings  `\M-X'
     and  `\eX' are entirely distinct, although they are initial-
     ized to the same bindings by `bindkey -m'.

     vared [ -Aache ] [ -p prompt ] [ -r rprompt ]
       [ -M main-keymap ] [ -m vicmd-keymap ]
       [ -i init-widget ] [ -f finish-widget ]
       [ -t tty ] name
     The value of the parameter name  is  loaded  into  the  edit
     buffer,  and  the  line  editor is invoked.  When the editor
     exits, name is set to the string value returned by the  edi-
     tor.  When the -c flag is given, the parameter is created if
     it doesn't already exist.  The -a flag may be given with  -c
     to  create  an  array parameter, or the -A flag to create an
     associative array.  If the type  of  an  existing  parameter
     does  not  match  the  type  to be created, the parameter is
     unset and recreated.

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



zsh 5.0.5          Last change: January 5, 2014                 6






User Commands                                           ZSHZLE(1)



     Individual elements of existing array or  associative  array
     parameters  may be edited by using subscript syntax on name.
     New elements are created automatically, even without -c.

     If the -p flag is given, the following string will be  taken
     as  the  prompt  to  display at the left.  If the -r flag is
     given, the following string gives the prompt to  display  at
     the  right.  If the -h flag is specified, the history can be
     accessed from ZLE. If the -e flag is given, typing ^D  (Con-
     trol-D)  on  an  empty line causes vared to exit immediately
     with a non-zero return value.

     The -M option gives a keymap to link to the main keymap dur-
     ing editing, and the -m option gives a keymap to link to the
     vicmd keymap during editing.   For  vi-style  editing,  this
     allows  a  pair of keymaps to override viins and vicmd.  For
     emacs-style editing, only -M is normally needed but  the  -m
     option  may  still  be  used.  On exit, the previous keymaps
     will be restored.

     Vared calls the usual `zle-line-init' and  `zle-line-finish'
     hooks before and after it takes control. Using the -i and -f
     options, it is possible to replace these with  other  custom
     widgets.

     If  `-t  tty' is given, tty is the name of a terminal device
     to be used instead of the default /dev/tty.  If tty does not
     refer to a terminal an error is reported.

     zle
     zle -l [ -L | -a ] [ string ... ]
     zle -D widget ...
     zle -A old-widget new-widget
     zle -N widget [ function ]
     zle -C widget completion-widget function
     zle -R [ -c ] [ display-string ] [ string ... ]
     zle -M string
     zle -U string
     zle -K keymap
     zle -F [ -L | -w ] [ fd [ handler ] ]
     zle -I
     zle -T [ tc function | -r tc | -L ]
     zle widget [ -n num ] [ -Nw ] [ -K keymap ] args ...
     The  zle builtin performs a number of different actions con-
     cerning ZLE.

     With no options and no arguments,  only  the  return  status
     will be set.  It is zero if ZLE is currently active and wid-
     gets  could  be  invoked  using  this  builtin  command  and
     non-zero  otherwise.   Note  that even if non-zero status is
     returned, zle may still be active as part of the  completion
     system; this does not allow direct calls to ZLE widgets.



zsh 5.0.5          Last change: January 5, 2014                 7






User Commands                                           ZSHZLE(1)



     Otherwise,  which  operation  it  performs  depends  on  its
     options:

     -l [ -L | -a ]
          List all existing  user-defined  widgets.   If  the  -L
          option  is  used,  list  in the form of zle commands to
          create the widgets.

          When combined with the -a option, all widget names  are
          listed, including the builtin ones. In this case the -L
          option is ignored.

          If at least one string is given, and -a is  present  or
          -L  is  not  used, nothing will be printed.  The return
          status will be zero if all strings are names of  exist-
          ing  widgets and non-zero if at least one string is not
          a name of a defined widget.  If -a is also present, all
          widget  names  are  used  for  the comparison including
          builtin widgets, else  only  user-defined  widgets  are
          used.

          If  at least one string is present and the -L option is
          used, user-defined  widgets  matching  any  string  are
          listed  in  the form of zle commands to create the wid-
          gets.

     -D widget ...
          Delete the named widgets.

     -A old-widget new-widget
          Make the new-widget name an alias  for  old-widget,  so
          that  both  names  refer to the same widget.  The names
          have equal standing; if either is  deleted,  the  other
          remains.   If  there  is  already  a  widget  with  the
          new-widget name, it is deleted.

     -N widget [ function ]
          Create a user-defined widget.  If there  is  already  a
          widget  with  the  specified  name,  it is overwritten.
          When the new widget is invoked from within the  editor,
          the specified shell function is called.  If no function
          name is specified, it defaults to the same name as  the
          widget.   For further information, see the section Wid-
          gets in zshzle(1).

     -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   comple-
          tion-widget.  To  generate  the  completions, the shell
          function function will be called.  For further informa-
          tion, see zshcompwid(1).



zsh 5.0.5          Last change: January 5, 2014                 8






User Commands                                           ZSHZLE(1)



     -R [ -c ] [ display-string ] [ string ... ]
          Redisplay  the  command line; this is to be called from
          within a user-defined widget to allow changes to become
          visible.   If  a display-string is given and not empty,
          this is shown in the status line (immediately below the
          line being edited).

          If the optional strings are given they are listed below
          the prompt in the same  way  as  completion  lists  are
          printed.  If  no strings are given but the -c option is
          used such a list is cleared.

          Note that this option is only useful for  widgets  that
          do  not  exit  immediately  after  using it because the
          strings displayed  will  be  erased  immediately  after
          return from the widget.

          This  command can safely be called outside user defined
          widgets;  if  zle  is  active,  the  display  will   be
          refreshed,  while if zle is not active, the command has
          no effect.  In this case there will usually be no other
          arguments.

          The status is zero if zle was active, else one.

     -M string
          As  with  the  -R  option, the string will be displayed
          below the command  line;  unlike  the  -R  option,  the
          string  will  not  be put into the status line but will
          instead be printed normally  below  the  prompt.   This
          means that the string will still be displayed after the
          widget returns (until it is overwritten  by  subsequent
          commands).

     -U string
          This pushes the characters in the string onto the input
          stack of ZLE.  After the widget currently executed fin-
          ishes  ZLE  will  behave  as  if  the characters in the
          string were typed by the user.

          As ZLE uses a stack, if this option is used  repeatedly
          the last string pushed onto the stack will be processed
          first.  However, the characters in each string will  be
          processed  in  the  order  in  which they appear in the
          string.

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

          This  keymap  selection  affects  the interpretation of
          following keystrokes within  this  invocation  of  ZLE.



zsh 5.0.5          Last change: January 5, 2014                 9






User Commands                                           ZSHZLE(1)



          Any  following invocation (e.g., the next command line)
          will start as usual with the `main' keymap selected.

     -F [ -L | -w ] [ fd [ handler ] ]
          Only available if  your  system  supports  one  of  the
          `poll'  or  `select'  system calls; most modern systems
          do.

          Installs handler (the name of a shell function) to han-
          dle  input  from  file  descriptor  fd.   When  zle  is
          attempting to read data, it will examine both the  ter-
          minal  and  the  list of handled fd's.  If data becomes
          available on a handled fd, zle will call  handler  with
          the fd which is ready for reading as the only argument.
          If the handler produces  output  to  the  terminal,  it
          should  call `zle -I' before doing so (see below).  The
          handler should not attempt to read from  the  terminal.
          Note that zle makes no attempt to check whether this fd
          is actually readable when installing the handler.   The
          user  must make their own arrangements for handling the
          file descriptor when zle is not active.

          If the option -w is also given, the handler is  instead
          a  line  editor widget, typically a shell function made
          into a widget using zle -N.  In that case  handler  can
          use  all  the  facilities  of zle to update the current
          editing line.  Note, however, that as handling fd takes
          place  at  a  low level changes to the display will not
          automatically appear; the widget should call zle -R  to
          force redisplay.

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

          If no handler is given, but an fd is present, any  han-
          dler  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  sup-
          plied,  a  list  of handlers is printed in a form which
          can be stored for later execution.

          An fd (but not a handler) may optionally be given  with
          the -L option; in this case, the function will list the
          handler if any, else silently return status 1.

          Note that  this  feature  should  be  used  with  care.
          Activity  on one of the fd's which is not properly han-
          dled can cause the terminal to become unusable.




zsh 5.0.5          Last change: January 5, 2014                10






User Commands                                           ZSHZLE(1)



          Here is a simple example of using this feature.  A con-
          nection  to a remote TCP port is created using the ztcp
          command; see the description of the zsh/net/tcp  module
          in  zshmodules(1).   Then  a handler is installed which
          simply prints out any data which arrives on  this  con-
          nection.   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
                 tcpfd=$REPLY
                 handler() {
                   zle -I
                   local line
                   if ! read -r line <&$1; then
                     # select marks this fd if we reach EOF,
                     # so handle this specially.
                     print "[Read on fd $1 failed, removing.]" >&2
                     zle -F $1
                     return 1
                   fi
                   print -r - $line
                 }
                 zle -F $tcpfd handler
               fi

     -I   Unusually, this option is most useful outside  ordinary
          widget  functions, though it may be used within if nor-
          mal output to the terminal is required.  It invalidates
          the current zle display in preparation for output; typ-
          ically 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  editor;  the  display  will
          only  be invalidated the first time to minimise disrup-
          tion.



zsh 5.0.5          Last change: January 5, 2014                11






User Commands                                           ZSHZLE(1)



          Note that there are normally better ways of  manipulat-
          ing the display from within zle widgets; see, for exam-
          ple, `zle -R' above.

          The returned status is zero  if  zle  was  invalidated,
          even  though  this  may have been by a previous call to
          `zle -I' or by a system notification.  To test if a zle
          widget may be called at this point, execute zle with no
          arguments and examine the return status.

     -T   This is used to add, list or remove internal  transfor-
          mations on the processing performed by the line editor.
          It is typically used only for debugging or testing  and
          is therefore of little interest to the general user.

          `zle  -T  transformation func' specifies that the given
          transformation (see below) is effected by  shell  func-
          tion func.

          `zle  -Tr transformation' removes the given transforma-
          tion if it was present (it is  not  an  error  if  none
          was).

          `zle  -TL' can be used to list all transformations cur-
          rently in operation.

          Currently the only transformation is tc.  This is  used
          instead  of  outputting  termcap codes to the terminal.
          When the transformation is in operation the shell func-
          tion is passed the termcap code that would be output as
          its first argument; if the operation required a numeric
          argument,  that  is  passed  as a second argument.  The
          function should set the shell  variable  REPLY  to  the
          transformed  termcap  code.   Typically this is used to
          produce some simply formatted version of the  code  and
          optional  argument for debugging or testing.  Note that
          this transformation is not applied to other  non-print-
          ing characters such as carriage returns and newlines.

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

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

          With  the option -K, keymap will be used as the current
          keymap  during  the  execution  of  the  widget.    The



zsh 5.0.5          Last change: January 5, 2014                12






User Commands                                           ZSHZLE(1)



          previous keymap will be restored when the widget exits.

          Normally, calling a widget in this way does not set the
          special  parameter  WIDGET  and  related parameters, so
          that the environment appears as if the top-level widget
          called  by the user were still active.  With the option
          -w, WIDGET and related parameters are  set  to  reflect
          the widget being executed by the zle call.

          Any  further  arguments  will  be passed to the widget;
          note that as standard argument handling  is  performed,
          any general argument list should be preceded by --.  If
          it is a shell function, these are passed down as  posi-
          tional  parameters; for builtin widgets it is up to the
          widget in question what it does with  them.   Currently
          arguments  are  only  handled by the incremental-search
          commands, the history-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.

WIDGETS
     All  actions  in  the  editor are performed by `widgets'.  A
     widget's job is simply to perform some  small  action.   The
     ZLE  commands that key sequences in keymaps are bound to are
     in fact widgets.  Widgets can be user-defined or built in.

     The standard widgets built into ZLE are listed  in  Standard
     Widgets  below.   Other  built-in  widgets can be defined by
     other modules (see zshmodules(1)).  Each built-in widget has
     two names: its normal canonical name, and the same name pre-
     ceded by a `.'.  The  `.'  name  is  special:  it  can't  be
     rebound to a different widget.  This makes the widget avail-
     able even when its usual name has been redefined.

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



zsh 5.0.5          Last change: January 5, 2014                13






User Commands                                           ZSHZLE(1)



USER-DEFINED WIDGETS
     User-defined  widgets, being implemented as shell functions,
     can execute any normal shell command.   They  can  also  run
     other  widgets  (whether built-in or user-defined) using the
     zle builtin command.  The standard input of the function  is
     closed  to  prevent  external  commands from unintentionally
     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 tem-
     porarily inaccessible, but will return when the widget func-
     tion  exits.   These  special  parameters in fact have local
     scope, like parameters created in a function using local.

     Inside completion widgets and  traps  called  while  ZLE  is
     active, these parameters are available read-only.

     BUFFER (scalar)
          The entire contents of the edit buffer.  If it is writ-
          ten 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 redis-
          play); read-only.

     CONTEXT (scalar)
          The context in which zle was called  to  read  a  line;
          read-only.  One of the values:
     start
          The start of a command line (at prompt PS1).

     cont A continuation to a command line (at prompt PS2).

     select
          In a select loop.

     vared
          Editing a variable in vared.

     CURSOR (integer)
     The  offset  of the cursor, within the edit buffer.  This is
     in the range 0 to $#BUFFER, and is by  definition  equal  to
     $#LBUFFER.   Attempts  to move the cursor outside the buffer
     will result in the cursor being moved to the appropriate end
     of the buffer.



zsh 5.0.5          Last change: January 5, 2014                14






User Commands                                           ZSHZLE(1)



     CUTBUFFER (scalar)
     The  last  item  cut  using one of the `kill-' commands; the
     string which the next yank would insert in the line.   Later
     entries  in  the  kill ring are in the array killring.  Note
     that the command `zle  copy-region-as-kill  string'  can  be
     used to set the text of the cut buffer from a shell function
     and cycle the kill ring in the  same  way  as  interactively
     killing text.

     HISTNO (integer)
     The  current  history  number.   Setting  this  has the same
     effect as moving up or down in the  history  to  the  corre-
     sponding  history  line.  An attempt to set it is ignored if
     the line is not stored in the history.  Note this is not the
     same as the parameter HISTCMD, which always gives the number
     of the history line being added to the main shell's history.
     HISTNO refers to the line being retrieved within zle.

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

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

     killring (array)
     The array of previously killed items, with the most recently
     killed  first.  This gives the items that would be retrieved
     by a yank-pop in the same order.  Note,  however,  that  the
     most  recently killed item is in $CUTBUFFER; $killring shows
     the array of previous entries.

     The default size for the kill ring  is  eight,  however  the
     length may be changed by normal array operations.  Any empty
     string in the kill ring is ignored by the yank-pop  command,
     hence  the  size  of  the array effectively sets the maximum
     length of the  kill  ring,  while  the  number  of  non-zero
     strings  gives  the current length, both as seen by the user
     at the command line.

     LASTABORTEDSEARCH (scalar)
     The last search string used by an  interactive  search  that
     was  aborted  by  the  user (status 3 returned by the search
     widget).

     LASTSEARCH (scalar)
     The last  search  string  used  by  an  interactive  search;
     read-only.  This is set even if the search failed (status 0,
     1 or 2 returned by the search widget), but  not  if  it  was
     aborted by the user.

     LASTWIDGET (scalar)



zsh 5.0.5          Last change: January 5, 2014                15






User Commands                                           ZSHZLE(1)



     The name of the last widget that was executed; read-only.

     LBUFFER (scalar)
     The  part  of the buffer that lies to the left of the cursor
     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 $RBUFFER.

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

     NUMERIC (integer)
     The numeric argument. If no numeric argument was given, this
     parameter  is  unset. When this is set inside a widget func-
     tion, 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  dis-
     play a complete line, a newline must be appended explicitly.
     The text is reset on each new invocation (but not  recursive
     invocation) of zle.

     POSTDISPLAY (scalar)
     Text  to  be  displayed  after  the end of the editable text
     buffer.  This does not have to be a complete line;  to  dis-
     play  a  complete  line, a newline must be prepended explic-
     itly.  The text is reset on each  new  invocation  (but  not
     recursive invocation) of zle.

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

     REGION_ACTIVE (integer)



zsh 5.0.5          Last change: January 5, 2014                16






User Commands                                           ZSHZLE(1)



     Indicates if the region is  currently  active.   It  can  be
     assigned  0  or  1  to  deactivate  and  activate the region
     respectively; see Character Highlighting below.

     region_highlight (array)
     Each element of this array may  be  set  to  a  string  that
     describes  highlighting  for an arbitrary region of the com-
     mand line that will take effect the next  time  the  command
     line is redisplayed.  Highlighting of the non-editable parts
     of the command line in PREDISPLAY and POSTDISPLAY are possi-
     ble, but note that the P flag is needed for character index-
     ing to include PREDISPLAY.

     Each string consists of the following parts:

     Optionally, a `P' to signify that the start and end offset
          that
          follow include any string set by the PREDISPLAY special
          parameter; this is  needed  if  the  predisplay  string
          itself is to be highlighted.  Whitespace may follow the
          `P'.
     A start offset in the same units as CURSOR, terminated by
          whitespace.
     An end offset in the same units as CURSOR, terminated by
          whitespace.
     A highlight specification in the same format as
          used for contexts in the parameter  zle_highlight,  see
          Character  Highlighting below; for example, standout or
          fg=red,bold.

     For example,

          region_highlight=("P0 20 bold")

     specifies that the  first  twenty  characters  of  the  text
     including  any  predisplay  string  should be highlighted in
     bold.

     Note that the effect of region_highlight is  not  saved  and
     disappears as soon as the line is accepted.

     UNDO_CHANGE_NO (integer)
     A  number  representing  the state of the undo history.  The
     only use of this is passing as an argument to the undo  wid-
     get in order to undo back to the recorded point.  Read-only.

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

     WIDGETFUNC (scalar)
     The  name  of  the  shell  function that implements a widget
     defined with either zle -N or zle -C.  In the  former  case,



zsh 5.0.5          Last change: January 5, 2014                17






User Commands                                           ZSHZLE(1)



     this  is  the  second  argument  to  the zle -N command that
     defined the widget, or the first argument if  there  was  no
     second argument.  In the latter case this is the third argu-
     ment  to  the  zle  -C  command  that  defined  the  widget.
     Read-only.

     WIDGETSTYLE (scalar)
     Describes  the  implementation  behind the completion widget
     currently being executed; the second argument that  followed
     zle  -C  when the widget was defined.  This is the name of a
     builtin completion widget.  For widgets defined with zle  -N
     this is set to the empty string.  Read-only.

     ZLE_STATE (scalar)
     Contains  a  set  of space-separated words that describe the
     current zle state.

     Currently, the states shown are the insert mode  as  set  by
     the overwrite-mode or vi-replace widgets and whether history
     commands will visit imported entries as  controlled  by  the
     set-local-history  widget.   The string contains `insert' if
     characters to be inserted on the command line move  existing
     characters  to  the right or `overwrite' if characters to be
     inserted overwrite existing characters. It contains  `local-
     history'  if  only local history commands will be visited or
     `globalhistory' if imported history commands  will  also  be
     visited.

     The  substrings  are sorted in alphabetical order so that if
     you  want  to  test  for  two  specific  substrings   in   a
     future-proof way, you can do match by doing:

          if [[ $ZLE_STATE == *insert*globalhistory* ]]; then ...; fi

  Special Widgets
     There  are  a  few user-defined widgets which are special to
     the shell.  If they do  not  exist,  no  special  action  is
     taken.   The  environment  provided is identical to that for
     any other editing widget.

     zle-isearch-exit
          Executed at the end of incremental search at the  point
          where  the  isearch prompt is removed from the display.
          See zle-isearch-update for an example.

     zle-isearch-update
          Executed within incremental search when the display  is
          about  to  be  redrawn.   Additional  output  below the
          incremental search prompt can  be  generated  by  using
          `zle -M' within the widget.  For example,





zsh 5.0.5          Last change: January 5, 2014                18






User Commands                                           ZSHZLE(1)



               zle-isearch-update() { zle -M "Line $HISTNO"; }
               zle -N zle-isearch-update

          Note the line output by `zle -M' is not deleted on exit
          from incremental search.   This  can  be  done  from  a
          zle-isearch-exit widget:

               zle-isearch-exit() { zle -M ""; }
               zle -N zle-isearch-exit

     zle-line-init
          Executed  every time the line editor is started to read
          a new line of input.  The following  example  puts  the
          line editor into vi command mode when it starts up.

               zle-line-init() { zle -K vicmd; }
               zle -N zle-line-init

          (The  command  inside  the  function  sets  the  keymap
          directly; it is equivalent to zle vi-cmd-mode.)

     zle-line-finish
          This is similar to zle-line-init but is executed  every
          time  the  line  editor  has finished reading a line of
          input.

     zle-history-line-set
          Executed when the history line changes.

     zle-keymap-select
          Executed every time the keymap changes, i.e.  the  spe-
          cial  parameter  KEYMAP  is  set  to a different value,
          while the line  editor  is  active.   Initialising  the
          keymap  when  the line editor starts does not cause the
          widget to be called.

          The value $KEYMAP within the function reflects the  new
          keymap.  The old keymap is passed as the sole argument.

          This can be used for detecting switches between the  vi
          command (vicmd) and insert (usually main) keymaps.

STANDARD WIDGETS
     The  following  is  a  list of all the standard widgets, and
     their default bindings in emacs mode, vi command mode and vi
     insert  mode  (the  `emacs',  `vicmd'  and  `viins' keymaps,
     respectively).

     Note that cursor keys are bound  to  movement  keys  in  all
     three  keymaps;  the shell assumes that the cursor keys send
     the key sequences reported by the terminal-handling  library
     (termcap  or terminfo).  The key sequences shown in the list



zsh 5.0.5          Last change: January 5, 2014                19






User Commands                                           ZSHZLE(1)



     are those based on the VT100, common on many  modern  termi-
     nals,  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 parame-
     ter, see zshparam(1).

  Movement
     vi-backward-blank-word (unbound) (B) (unbound)
          Move  backward  one  word, where a word is defined as a
          series of non-blank characters.

     backward-char (^B ESC-[D) (unbound) (unbound)
          Move backward one character.

     vi-backward-char (unbound) (^H h ^?) (ESC-[D)
          Move backward one character, without changing lines.

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

     emacs-backward-word
          Move to the beginning of the previous word.

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

     beginning-of-line (^A) (unbound) (unbound)
          Move to the beginning of the line.  If already  at  the
          beginning  of  the  line,  move to the beginning of the
          previous line, if any.

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

     end-of-line (^E) (unbound) (unbound)
          Move  to the end of the line.  If already at the end of
          the line, move to the end of the next line, if any.

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

     vi-forward-blank-word (unbound) (W) (unbound)
          Move forward one word, where a word  is  defined  as  a
          series of non-blank characters.

     vi-forward-blank-word-end (unbound) (E) (unbound)
          Move  to the end of the current word, or, if at the end
          of the current word, to the end of the next word, where



zsh 5.0.5          Last change: January 5, 2014                20






User Commands                                           ZSHZLE(1)



          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  editor's
          idea  of a word is specified with the WORDCHARS parame-
          ter.

     emacs-forward-word
          Move to the end of the next word.

     vi-forward-word-end (unbound) (e) (unbound)
          Move to the end of the next word.

     vi-goto-column (ESC-|) (|) (unbound)
          Move to the column specified by the numeric argument.

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

     vi-goto-mark-line (unbound) (') (unbound)
          Move to beginning of the line containing the  specified
          mark.



zsh 5.0.5          Last change: January 5, 2014                21






User Commands                                           ZSHZLE(1)



     vi-repeat-find (unbound) (;) (unbound)
          Repeat the last vi-find command.

     vi-rev-repeat-find (unbound) (,) (unbound)
          Repeat  the last vi-find command in the opposite direc-
          tion.

  History Control
     beginning-of-buffer-or-history (ESC-<) (unbound) (unbound)
          Move to the beginning of  the  buffer,  or  if  already
          there, move to the first event in the history list.

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

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

     down-line-or-history (^N ESC-[B) (j) (ESC-[B)
          Move  down  a  line in the buffer, or if already at the
          bottom line, move to the  next  event  in  the  history
          list.

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

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

          If called from a function by the zle command with argu-
          ments,  the  first  argument is taken as the string for
          which to search, rather than  the  first  word  in  the
          buffer.

     down-history (unbound) (^N) (unbound)
          Move to the next event in the history list.

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

     end-of-buffer-or-history (ESC->) (unbound) (unbound)
          Move  to  the  end  of the buffer, or if already there,
          move to the last event in the history list.



zsh 5.0.5          Last change: January 5, 2014                22






User Commands                                           ZSHZLE(1)



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

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

     vi-fetch-history (unbound) (G) (unbound)
          Fetch  the  history line specified by the numeric argu-
          ment.  This defaults to the current history line  (i.e.
          the one that isn't history yet).

     history-incremental-search-backward (^R ^Xr) (unbound)
          (unbound)
          Search backward incrementally for a  specified  string.
          The  search  is  case-insensitive  if the search string
          does not have uppercase letters and no numeric argument
          was given.  The string may begin with `^' to anchor the
          search to the beginning of the line.  When called  from
          a user-defined function returns the following statuses:
          0, if the search succeeded; 1, if the search failed; 2,
          if  the search term was a bad pattern; 3, if the search
          was aborted by the send-break command.

          A restricted set of editing functions is  available  in
          the  mini-buffer.   Keys  are  looked up in the special
          isearch keymap, and if not  found  there  in  the  main
          keymap  (note  that  by  default  the isearch keymap is
          empty).  An interrupt signal, as defined  by  the  stty
          setting, will stop the search and go back to the origi-
          nal line.  An undefined key will have the same  effect.
          Note  that  the  following always perform the same task
          within incremental searches and cannot be  replaced  by
          user  defined  widgets, nor can the set of functions be
          extended.  The supported functions are:

          accept-and-hold
          accept-and-infer-next-history
          accept-line
          accept-line-and-down-history
               Perform the usual function after exiting incremen-
               tal  search.   The  command line displayed is exe-
               cuted.

          backward-delete-char
          vi-backward-delete-char
               Back up one place in the search history.   If  the
               search has been repeated this does not immediately
               erase a character in the minibuffer.

          accept-search
               Exit incremental  search,  retaining  the  command



zsh 5.0.5          Last change: January 5, 2014                23






User Commands                                           ZSHZLE(1)



               line  but performing no further action.  Note that
               this function is not bound by default and  has  no
               effect outside incremental search.

          backward-delete-word
          backward-kill-word
          vi-backward-kill-word
               Back up one character in the minibuffer; if multi-
               ple searches have been performed since the charac-
               ter  was inserted the search history is rewound to
               the point just before the character  was  entered.
               Hence  this  has  the  effect  of  repeating back-
               ward-delete-char.

          clear-screen
               Clear the screen, remaining in incremental  search
               mode.

          history-incremental-search-backward
               Find  the  next  occurrence of the contents of the
               mini-buffer.

          history-incremental-search-forward
               Invert the sense of the search.

          magic-space
               Inserts a non-magical space.

          quoted-insert
          vi-quoted-insert
               Quote the character to insert into the minibuffer.

          redisplay
               Redisplay the command line, remaining in incremen-
               tal search mode.

          vi-cmd-mode
               Toggle between the `main' and `vicmd' keymaps; the
               `main'  keymap (insert mode) will be selected ini-
               tially.

          vi-repeat-search
          vi-rev-repeat-search
               Repeat the search.  The direction of the search is
               indicated in the mini-buffer.

          Any  character  that  is  not bound to one of the above
          functions, or self-insert or  self-insert-unmeta,  will
          cause  the  mode  to  be exited.  The character is then
          looked up and executed in the keymap in effect at  that
          point.




zsh 5.0.5          Last change: January 5, 2014                24






User Commands                                           ZSHZLE(1)



          When  called from a widget function by the zle command,
          the incremental search commands can take a string argu-
          ment.  This will be treated as a string of keys, as for
          arguments to the bindkey command, and used  as  initial
          input  for  the  command.  Any characters in the string
          which are unused by  the  incremental  search  will  be
          silently ignored.  For example,

               zle history-incremental-search-backward forceps

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

     history-incremental-search-forward (^S ^Xs) (unbound)
          (unbound)
          Search  forward  incrementally  for a specified string.
          The search is case-insensitive  if  the  search  string
          does not have uppercase letters and no numeric argument
          was given.  The string may begin with `^' to anchor the
          search  to  the  beginning  of the line.  The functions
          available in the mini-buffer are the same as  for  his-
          tory-incremental-search-backward.

     history-incremental-pattern-search-backward
     history-incremental-pattern-search-forward
          These  widgets  behave  similarly  to the corresponding
          widgets with no -pattern, but the search  string  typed
          by  the  user  is  treated as a pattern, respecting the
          current settings of the various options affecting  pat-
          tern  matching.   See FILENAME GENERATION in zshexpn(1)
          for a description of patterns.  If no numeric  argument
          was  given  lowercase  letters in the search string may
          match uppercase letters in the history.  The string may
          begin with `^' to anchor the search to the beginning of
          the line.

          The prompt changes to indicate an invalid pattern; this
          may simply indicate the pattern is not yet complete.

          Note that only non-overlapping matches are reported, so
          an expression with wildcards may return  fewer  matches
          on a line than are visible by inspection.

     history-search-backward (ESC-P ESC-p) (unbound) (unbound)
          Search  backward  in  the  history for a line beginning
          with the first word in the buffer.

          If called from a function by the zle command with argu-
          ments,  the  first  argument is taken as the string for
          which to search, rather than  the  first  word  in  the
          buffer.




zsh 5.0.5          Last change: January 5, 2014                25






User Commands                                           ZSHZLE(1)



     vi-history-search-backward (unbound) (/) (unbound)
          Search  backward in the history for a specified string.
          The string may begin with `^' to anchor the  search  to
          the beginning of the line.

          A  restricted  set of editing functions is available in
          the mini-buffer.  An interrupt signal,  as  defined  by
          the stty setting,  will stop the search.  The functions
          available in the mini-buffer  are:  accept-line,  back-
          ward-delete-char,     vi-backward-delete-char,    back-
          ward-kill-word,  vi-backward-kill-word,   clear-screen,
          redisplay, quoted-insert and vi-quoted-insert.

          vi-cmd-mode  is  treated  the  same as accept-line, and
          magic-space is treated as a space.  Any other character
          that  is not bound to self-insert or self-insert-unmeta
          will beep and be ignored. If  the  function  is  called
          from  vi  command  mode,  the  bindings  of the current
          insert mode will be used.

          If called from a function by the zle command with argu-
          ments,  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 argu-
          ments,  the  first  argument is taken as the string for
          which to search, rather than  the  first  word  in  the
          buffer.

     vi-history-search-forward (unbound) (?) (unbound)
          Search  forward  in the history for a specified string.
          The string may begin with `^' to anchor the  search  to
          the  beginning  of the line. The functions available in
          the  mini-buffer  are   the   same   as   for   vi-his-
          tory-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 cur-
          rent 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



zsh 5.0.5          Last change: January 5, 2014                26






User Commands                                           ZSHZLE(1)



          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  be  used in the same way to pick a word
          from that event.

          When called  from  a  shell  function  invoked  from  a
          user-defined  widget, the command can take one to three
          arguments.  The first argument specifies a history off-
          set  which  applies to successive calls to this widget:
          if it is -1, the default behaviour is used, while if it
          is  1,  successive calls will move forwards through the
          history.  The value 0 can be used to indicate that  the
          history  line examined by the previous execution of the
          command will be reexamined.  Note that negative numbers
          should  be preceded by a `--' argument to avoid confus-
          ing them with options.

          If two arguments are given, the  second  specifies  the
          word on the command line in normal array index notation
          (as a more natural alternative to the prefix argument).
          Hence  1 is the first word, and -1 (the default) is the
          last word.

          If a third argument is given, its value is ignored, but
          it  is used to signify that the history offset is rela-
          tive to the current history line, rather than  the  one
          remembered    after   the   previous   invocations   of
          insert-last-word.

          For example, the default behaviour of the command  cor-
          responds 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



zsh 5.0.5          Last change: January 5, 2014                27






User Commands                                           ZSHZLE(1)



          line, move to the previous event in the history list.

     vi-up-line-or-history (unbound) (-) (unbound)
          Move  up a line in the buffer, or if already at the top
          line, move to the previous event in the  history  list.
          Then move to the first non-blank character on the line.

     up-line-or-search
          Move up a line in the buffer, or if already at the  top
          line,  search backward in the history for a line begin-
          ning with the first word in the buffer.

          If called from a function by the zle command with argu-
          ments,  the  first  argument is taken as the string for
          which to search, rather than  the  first  word  in  the
          buffer.

     up-history (unbound) (^P) (unbound)
          Move to the previous event in the history list.

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

     set-local-history
          By   default,   history  movement  commands  visit  the
          imported lines as well as the local lines. This  widget
          lets  you  toggle  this  on and off, or set it with the
          numeric argument. Zero  for  both  local  and  imported
          lines and nonzero for only local lines.

  Modifying Text
     vi-add-eol (unbound) (A) (unbound)
          Move to the end of the line and enter insert mode.

     vi-add-next (unbound) (a) (unbound)
          Enter  insert  mode  after the current cursor position,
          without changing lines.

     backward-delete-char (^H ^?) (unbound) (unbound)
          Delete the character behind the cursor.

     vi-backward-delete-char (unbound) (X) (^H)
          Delete the character behind the cursor, without  chang-
          ing  lines.   If in insert mode, this won't delete past
          the point where insert mode was last entered.

     backward-delete-word
          Delete the word behind the cursor.

     backward-kill-line



zsh 5.0.5          Last change: January 5, 2014                28






User Commands                                           ZSHZLE(1)



          Kill from the beginning of the line to the cursor posi-
          tion.

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

          If called from a ZLE widget function in the  form  `zle
          copy-region-as-kill  string'  then string will be taken
          as the text to copy to the kill  buffer.   The  cursor,
          the  mark and the text on the command line are not used
          in this case.

     copy-prev-word (ESC-^_) (unbound) (unbound)
          Duplicate the word to the left of the cursor.

     copy-prev-shell-word
          Like copy-prev-word, but the word  is  found  by  using
          shell parsing, whereas copy-prev-word looks for blanks.
          This makes a difference when the  word  is  quoted  and
          contains spaces.

     vi-delete (unbound) (d) (unbound)
          Read  a  movement  command  from the keyboard, and kill
          from the cursor position to the endpoint of  the  move-
          ment.   If  the  command is vi-delete, kill the current
          line.

     delete-char
          Delete the character under the cursor.



zsh 5.0.5          Last change: January 5, 2014                29






User Commands                                           ZSHZLE(1)



     vi-delete-char (unbound) (x) (unbound)
          Delete the character under the  cursor,  without  going
          past the end of the line.

     delete-word
          Delete the current word.

     down-case-word (ESC-L ESC-l) (unbound) (unbound)
          Convert the current word to all lowercase and move past
          it.

     kill-word (ESC-D ESC-d) (unbound) (unbound)
          Kill the current word.

     gosmacs-transpose-chars
          Exchange the two characters behind the cursor.

     vi-indent (unbound) (>) (unbound)
          Indent a number of lines.

     vi-insert (unbound) (i) (unbound)
          Enter insert mode.

     vi-insert-bol (unbound) (I) (unbound)
          Move to the first non-blank character on the  line  and
          enter insert mode.

     vi-join (^X^J) (J) (unbound)
          Join the current line with the next one.

     kill-line (^K) (unbound) (unbound)
          Kill  from  the  cursor  to  the  end  of the line.  If
          already on the end of the line, kill the newline  char-
          acter.

     vi-kill-line (unbound) (unbound) (^U)
          Kill  from  the cursor back to wherever insert mode was
          last entered.

     vi-kill-eol (unbound) (D) (unbound)
          Kill from the cursor to the end of the line.

     kill-region
          Kill from the cursor to the mark.

     kill-buffer (^X^K) (unbound) (unbound)
          Kill the entire buffer.

     kill-whole-line (^U) (unbound) (unbound)
          Kill the current line.

     vi-match-bracket (^X^B) (%) (unbound)



zsh 5.0.5          Last change: January 5, 2014                30






User Commands                                           ZSHZLE(1)



          Move to the bracket character (one of  {},  ()  or  [])
          that  matches  the one under the cursor.  If the cursor
          is not on a bracket  character,  move  forward  without
          going past the end of the line to find one, and then go
          to the matching bracket.

     vi-open-line-above (unbound) (O) (unbound)
          Open a line above the cursor and enter insert mode.

     vi-open-line-below (unbound) (o) (unbound)
          Open a line below the cursor and enter insert mode.

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

     overwrite-mode (^X^O) (unbound) (unbound)
          Toggle between overwrite mode and insert mode.

     vi-put-before (unbound) (P) (unbound)
          Insert the contents of the kill buffer before the  cur-
          sor.   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 cur-
          sor.  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  liter-
          ally.  An interrupt character will not be inserted.

     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 `'' character at
          the beginning and the end, and convert all `''  charac-
          ters to `'\'''.

     quote-region (ESC-") (unbound) (unbound)
          Quote the region from the cursor to the mark.

     vi-replace (unbound) (R) (unbound)



zsh 5.0.5          Last change: January 5, 2014                31






User Commands                                           ZSHZLE(1)



          Enter overwrite mode.

     vi-repeat-change (unbound) (.) (unbound)
          Repeat  the last vi mode text modification.  If a count
          was used with the modification, it is remembered.  If a
          count is given to this command, it overrides the remem-
          bered 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 character
          read from the keyboard.

ters and some control characters)
     self-insert  (printable  characters) (unbound) (printable
          charac-
          Insert  a character into the buffer at the cursor posi-
          tion.

     self-insert-unmeta (ESC-^I ESC-^J ESC-^M) (unbound)
          (unbound)
          Insert  a character into the buffer after stripping the
          meta bit and converting ^M to ^J.

     vi-substitute (unbound) (s) (unbound)
          Substitute the next character(s).

     vi-swap-case (unbound) (~) (unbound)
          Swap the case of the character  under  the  cursor  and
          move past it.

     transpose-chars (^T) (unbound) (unbound)
          Exchange  the  two characters to the left of the cursor
          if at end of line, else exchange  the  character  under
          the cursor with the character to the left.

     transpose-words (ESC-T ESC-t) (unbound) (unbound)
          Exchange the current word with the one before it.

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

     up-case-word (ESC-U ESC-u) (unbound) (unbound)
          Convert  the current word to all caps and move past it.

     yank (^Y) (unbound) (unbound)
          Insert the contents of the kill buffer  at  the  cursor
          position.

     yank-pop (ESC-y) (unbound) (unbound)
          Remove  the text just yanked, rotate the kill-ring (the



zsh 5.0.5          Last change: January 5, 2014                32






User Commands                                           ZSHZLE(1)



          history of previously killed text)  and  yank  the  new
          top.  Only works following yank or yank-pop.

     vi-yank (unbound) (y) (unbound)
          Read a movement command from the keyboard, and copy the
          region from the cursor position to the endpoint of  the
          movement  into  the  kill  buffer.   If  the command is
          vi-yank, copy the current line.

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

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

  Arguments
     digit-argument (ESC-0..ESC-9) (1-9) (unbound)
          Start  a  new  numeric  argument, or add to the current
          one.   See  also  vi-digit-or-beginning-of-line.   This
          only works if bound to a key sequence ending in a deci-
          mal digit.

          Inside a widget  function,  a  call  to  this  function
          treats  the  last  key of the key sequence which called
          the widget as the digit.

     neg-argument (ESC--) (unbound) (unbound)
          Changes the sign of the following argument.

     universal-argument
          Multiply the argument of the next command by 4.  Alter-
          natively,  if  this  command  is followed by an integer
          (positive or negative), use that as  the  argument  for
          the next command.  Thus digits cannot be repeated using
          this command.  For  example,  if  this  command  occurs
          twice,  followed immediately by forward-char, move for-
          ward sixteen spaces; if instead it is followed  by  -2,
          then forward-char, move backward two spaces.

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

     argument-base
          Use the existing numeric argument as  a  numeric  base,
          which  must  be in the range 2 to 36 inclusive.  Subse-
          quent use of digit-argument and universal-argument will
          input  a new prefix in the given base.  The usual hexa-
          decimal  convention  is  used:  the  letter  a   or   A



zsh 5.0.5          Last change: January 5, 2014                33






User Commands                                           ZSHZLE(1)



          corresponds  to  10,  and  so  on.   Arguments in bases
          requiring digits from 10 upwards are more  conveniently
          input with universal-argument, since ESC-a etc. are not
          usually bound to digit-argument.

          The function can be used with a command argument inside
          a  user-defined  widget.   The  following code sets the
          base to 16 and lets the user input a hexadecimal  argu-
          ment until a key out of the digit range is typed:

               zle argument-base 16
               zle universal-argument

  Completion
     accept-and-menu-complete
          In  a  menu  completion,  insert the current completion
          into the buffer, and advance to the next possible  com-
          pletion.

     complete-word
          Attempt completion on the current word.

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

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

     expand-or-complete (TAB) (unbound) (TAB)
          Attempt  shell  expansion on the current word.  If that
          fails, attempt completion.

     expand-or-complete-prefix
          Attempt shell expansion on the current word up to  cur-
          sor.

     expand-history (ESC-space ESC-!) (unbound) (unbound)
          Perform history expansion on the edit buffer.

     expand-word (^X*) (unbound) (unbound)
          Attempt shell expansion on the current word.

     list-choices (ESC-^D) (^D =) (^D)
          List possible completions for the current word.

     list-expand (^Xg ^XG) (^G) (^G)
          List the expansion of the current word.

     magic-space
          Perform  history  expansion and insert a space into the



zsh 5.0.5          Last change: January 5, 2014                34






User Commands                                           ZSHZLE(1)



          buffer.  This is intended to be bound to space.

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

     menu-expand-or-complete
          Like expand-or-complete, except that menu completion is
          used.

     reverse-menu-complete
          Perform menu  completion,  like  menu-complete,  except
          that  if a menu completion is already in progress, move
          to the previous completion rather than the next.

     end-of-list
          When a previous completion displayed a list  below  the
          prompt,  this  widget  can  be  used to move the prompt
          below the list.

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

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

     accept-line (^J ^M) (^J ^M) (^J ^M)
          Finish  editing  the  buffer.  Normally this causes the
          buffer to be executed as a shell command.

     accept-line-and-down-history (^O) (unbound) (unbound)
          Execute the current line, and  push  the  next  history
          event on the buffer stack.

     auto-suffix-remove
          If  the  previous  action added a suffix (space, slash,
          etc.) to the word on the command line, remove it.  Oth-
          erwise do nothing.  Removing the suffix ends any active
          menu completion or menu selection.

          This widget is intended to be called from  user-defined
          widgets to enforce a desired suffix-removal behavior.

     auto-suffix-retain
          If  the  previous  action added a suffix (space, slash,
          etc.) to the word on the command line, force it  to  be
          preserved.  Otherwise do nothing.  Retaining the suffix
          ends any active menu completion or menu selection.



zsh 5.0.5          Last change: January 5, 2014                35






User Commands                                           ZSHZLE(1)



          This widget is intended to be called from  user-defined
          widgets to enforce a desired suffix-preservation behav-
          ior.

     beep Beep, unless the BEEP option is unset.

     vi-cmd-mode (^X^V) (unbound) (^[)
          Enter command mode; that is, select the `vicmd' keymap.
          Yes, this is bound by default in emacs mode.

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

     clear-screen (^L ESC-^L) (^L) (^L)
          Clear the screen and redraw the prompt.

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

     exchange-point-and-mark (^X^X) (unbound) (unbound)
          Exchange the cursor position (point) with the  position
          of  the  mark.   Unless  a  negative prefix argument is
          given, the region between point and mark  is  activated
          so  that it can be highlighted.  If a zero prefix argu-
          ment is given, the region is activated  but  point  and
          mark are not swapped.

     execute-named-cmd (ESC-x) (:) (unbound)
          Read  the  name of an editor command and execute it.  A
          restricted set of editing functions is available in the
          mini-buffer.  Keys are looked up in the special command
          keymap, and if not found there in the main keymap.   An
          interrupt  signal, as defined by the stty setting, will
          abort the function.  Note  that  the  following  always
          perform  the  same  task  within the executed-named-cmd
          environment and cannot be replaced by user defined wid-
          gets,  nor  can  the set of functions be extended.  The
          allowed functions are:  backward-delete-char,  vi-back-
          ward-delete-char,        clear-screen,       redisplay,
          quoted-insert,  vi-quoted-insert,   backward-kill-word,
          vi-backward-kill-word,  kill-whole-line,  vi-kill-line,
          backward-kill-line, list-choices,  delete-char-or-list,
          complete-word,   accept-line,   expand-or-complete  and
          expand-or-complete-prefix.

          kill-region kills the last  word,  and  vi-cmd-mode  is
          treated  the  same  as  accept-line.  The space and tab
          characters, if not bound to  one  of  these  functions,
          will  complete the name and then list the possibilities



zsh 5.0.5          Last change: January 5, 2014                36






User Commands                                           ZSHZLE(1)



          if the AUTO_LIST option is set.   Any  other  character
          that  is not bound to self-insert or self-insert-unmeta
          will beep and be ignored.  The bindings of the  current
          insert mode will be used.

          Currently  this  command may not be redefined or called
          by name.

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

          Currently  this  command may not be redefined or called
          by name.

     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  INTERAC-
          TIVE_COMMENTS  option  must be set for this to have any
          usefulness.

     vi-pound-insert
          If there is no # character at the beginning of the cur-
          rent  line,  add one.  If there is one, remove it.  The
          INTERACTIVE_COMMENTS option must be  set  for  this  to
          have any usefulness.

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

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

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



zsh 5.0.5          Last change: January 5, 2014                37






User Commands                                           ZSHZLE(1)



     read-command
          Only useful from a user-defined widget.  A keystroke is
          read just as in normal operation, but  instead  of  the
          command  being  executed  the  name of the command that
          would be executed is  stored  in  the  shell  parameter
          REPLY.   This  can  be used as the argument of a future
          zle command.  If the key sequence is not bound,  status
          1  is  returned;  typically,  however,  REPLY is set to
          undefined-key to indicate a useless key sequence.

     recursive-edit
          Only useful from a user-defined widget.  At this  point
          in  the  function, the editor regains control until one
          of the standard widgets which would normally cause  zle
          to exit (typically an accept-line caused by hitting the
          return key) is executed.  Instead, control  returns  to
          the   user-defined  widget.   The  status  returned  is
          non-zero if the return was caused by an error, but  the
          function  still  continues executing and hence may tidy
          up.  This makes it safe for the user-defined widget  to
          alter the command line or key bindings temporarily.

          The  following widget, caps-lock, serves as an example.
               self-insert-ucase() {
                 LBUFFER+=${(U)KEYS[-1]}
               }

               integer stat

               zle -N self-insert self-insert-ucase
               zle -A caps-lock save-caps-lock
               zle -A accept-line caps-lock

               zle recursive-edit
               stat=$?

               zle -A .self-insert self-insert
               zle -A save-caps-lock caps-lock
               zle -D save-caps-lock

               (( stat )) && zle send-break

               return $stat

          This causes typed letters to  be  inserted  capitalised
          until  either  accept-line  (i.e.  typically the return
          key) is typed or the caps-lock widget is invoked again;
          the  later  is  handled by saving the old definition of
          caps-lock as save-caps-lock and then  rebinding  it  to
          invoke accept-line.  Note that an error from the recur-
          sive edit is detected as a non-zero return  status  and
          propagated by using the send-break widget.



zsh 5.0.5          Last change: January 5, 2014                38






User Commands                                           ZSHZLE(1)



     redisplay (unbound) (^R) (^R)
          Redisplays the edit buffer.

     reset-prompt (unbound) (unbound) (unbound)
          Force  the  prompts  on  both the left and right of the
          screen to  be  re-expanded,  then  redisplay  the  edit
          buffer.  This reflects changes both to the prompt vari-
          ables themselves and changes in the  expansion  of  the
          values  (for  example, changes in time or directory, or
          changes to the value of variables referred  to  by  the
          prompt).

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

     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 cur-
          rent line; in this case the aborted line  is  available
          in the shell variable ZLE_LINE_ABORTED.

     run-help (ESC-H ESC-h) (unbound) (unbound)
          Push  the buffer onto the buffer stack, and execute the
          command `run-help cmd', where cmd is the  current  com-
          mand.  run-help is normally aliased to man.

     vi-set-buffer (unbound) (") (unbound)
          Specify  a  buffer to be used in the following command.
          There are 35 buffers that  can  be  specified:  the  26
          `named'  buffers "a to "z and the nine `queued' buffers
          "1 to "9.  The named buffers can also be  specified  as
          "A to "Z.

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

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

     vi-set-mark (unbound) (m) (unbound)
          Set the specified mark at the cursor position.

     set-mark-command (^@) (unbound) (unbound)
          Set  the mark at the cursor position.  If called with a



zsh 5.0.5          Last change: January 5, 2014                39






User Commands                                           ZSHZLE(1)



          negative prefix argument, do not set the mark but deac-
          tivate  the  region so that it is no longer highlighted
          (it is still usable for other purposes).  Otherwise the
          region is marked as active.

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

     undefined-key
          This  command  is  executed when a key sequence that is
          not bound to any  command  is  typed.   By  default  it
          beeps.

     undo (^_ ^Xu ^X^U) (unbound) (unbound)
          Incrementally  undo  the  last text modification.  When
          called from a user-defined widget,  takes  an  optional
          argument  indicating  a previous state of the undo his-
          tory as returned by the UNDO_CHANGE_NO variable;  modi-
          fications are undone until that state is reached.

     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 current cur-
          sor position within the buffer and the  column  of  the
          cursor in the current line.

     where-is
          Read  the name of an editor command and print the list-
          ing of key sequences that invoke the specified command.
          A  restricted  set of editing functions is available in
          the mini-buffer.  Keys are looked  up  in  the  special
          command  keymap,  and  if  not  found there in the main
          keymap.

     which-command (ESC-?) (unbound) (unbound)
          Push the buffer onto the buffer stack, and execute  the
          command  `which-command  cmd'. where cmd is the current
          command.  which-command is normally aliased to  whence.

     vi-digit-or-beginning-of-line (unbound) (0) (unbound)
          If  the last command executed was a digit as part of an
          argument, continue the  argument.   Otherwise,  execute
          vi-beginning-of-line.

CHARACTER HIGHLIGHTING




zsh 5.0.5          Last change: January 5, 2014                40






User Commands                                           ZSHZLE(1)



     The  line  editor has the ability to highlight characters or
     regions of the line that  have  a  particular  significance.
     This  is controlled by the array parameter zle_highlight, if
     it has been set by the user.

     If the parameter contains the single entry  none  all  high-
     lighting  is  turned  off.   Note  the  parameter  is  still
     expected to be an array.

     Otherwise each entry of the array should consist of  a  word
     indicating  a context for highlighting, then a colon, then a
     comma-separated list of the types of highlighting  to  apply
     in that context.

     The contexts available for highlighting are the following:

     default
          Any  text  within  the command line not affected by any
          other highlighting.  Text outside the editable area  of
          the command line is not affected.

     isearch
          When  one  of the incremental history search widgets is
          active, the area of the command  line  matched  by  the
          search string or pattern.

     region
          The  region  between the cursor (point) and the mark as
          set with set-mark-command.  The region  is  only  high-
          lighted   if  it  is  active,  which  is  the  case  if
          set-mark-command or  exchange-point-and-mark  has  been
          called and the line has not been subsequently modified.
          The region can be deactivated by calling  set-mark-com-
          mand with a negative prefix argument, or reactivated by
          calling  exchange-point-and-mark  with  a  zero  prefix
          argument.   Note  that  whether  or  not  the region is
          active has no effect on its use within widgets, it sim-
          ply determines whether it is highlighted.

     special
          Individual  characters  that  have  no direct printable
          representation but are shown in a special manner by the
          line editor.  These characters are described below.

     suffix
          This  context is used in completion for characters that
          are marked as suffixes that will be removed if the com-
          pletion  ends  at  that point, the most obvious example
          being a slash (/) after a directory  name.   Note  that
          suffix removal is configurable; the circumstances under
          which the suffix will be removed may differ for differ-
          ent completions.



zsh 5.0.5          Last change: January 5, 2014                41






User Commands                                           ZSHZLE(1)



     zle_highlight  may contain additional fields for controlling
     how terminal sequences to change colours are  output.   Each
     of  the following is followed by a colon and a string in the
     same form as for key bindings.  This will not  be  necessary
     for  the vast majority of terminals as the defaults shown in
     parentheses are widely used.

     fg_start_code (\e[3)
          The start of the escape  sequence  for  the  foreground
          colour.   This is followed by an ASCII digit represent-
          ing the colour.

     fg_default_code (9)
          The number to use instead of the colour  to  reset  the
          default foreground colour.

     fg_end_code (m)
          The  end  of  the  escape  sequence  for the foreground
          colour.

     bg_start_code (\e[4)
          The start of the escape  sequence  for  the  background
          colour.   This is followed by an ASCII digit represent-
          ing the colour.

     bg_default_code (9)
          The number to use instead of the colour  to  reset  the
          default background colour.

     bg_end_code (m)
          The  end  of  the  escape  sequence  for the background
          colour.

     The available types of highlighting are the following.  Note
     that not all types of highlighting are available on all ter-
     minals:

     none No highlighting is applied to the given context.  It is
          not useful for this to appear with other types of high-
          lighting; it is used to override a default.

     fg=colour
          The foreground colour should be set to colour, a  deci-
          mal  integer  or  the  name  of  one  of the eight most
          widely-supported colours.

          Not all terminals support this and, of those  that  do,
          not  all  provide facilities to test the support, hence
          the user should decide  based  on  the  terminal  type.
          Most  terminals  support the colours black, red, green,
          yellow, blue, magenta, cyan and white, which can be set
          by  name.   In addition. default may be used to set the



zsh 5.0.5          Last change: January 5, 2014                42






User Commands                                           ZSHZLE(1)



          terminal's default  foreground  colour.   Abbreviations
          are allowed; b or bl selects black.  Some terminals may
          generate additional colours if the  bold  attribute  is
          also present.

          On  recent  terminals and on systems with an up-to-date
          terminal database the number of colours  supported  may
          be tested by the command `echotc Co'; if this succeeds,
          it indicates a limit on the  number  of  colours  which
          will  be  enforced  by  the line editor.  The number of
          colours is in any case limited to 256 (i.e. the range 0
          to 255).

          Colour is also known as color.

     bg=colour
          The  background  colour  should be set to colour.  This
          works similarly to the foreground  colour,  except  the
          background   is   not  usually  affected  by  the  bold
          attribute.

     bold The characters in the given context are shown in a bold
          font.  Not all terminals distinguish bold fonts.

     standout
          The  characters  in  the given context are shown in the
          terminal's standout mode.  The actual  effect  is  spe-
          cific  to the terminal; on many terminals it is inverse
          video.  On some such terminals, where the  cursor  does
          not blink it appears with standout mode negated, making
          it less than clear where the cursor  actually  is.   On
          such  terminals one of the other effects may be prefer-
          able for highlighting the  region  and  matched  search
          string.

     underline
          The  characters  in  the given context are shown under-
          lined.  Some terminals show the foreground in a differ-
          ent colour instead; in this case whitespace will not be
          highlighted.

     The characters described above as `special' are as  follows.
     The  formatting  described  here  is  used  irrespective  of
     whether the characters are highlighted:

     ASCII control characters
          Control characters in the ASCII range are shown as  `^'
          followed by the base character.

     Unprintable multibyte characters
          This  item  applies  to  control  characters not in the
          ASCII range, plus other characters as follows.  If  the



zsh 5.0.5          Last change: January 5, 2014                43






User Commands                                           ZSHZLE(1)



          MULTIBYTE option is in effect, multibyte characters not
          in the ASCII character set that are reported as  having
          zero width are treated as combining characters when the
          option COMBINING_CHARS is on.  If the option is off, or
          if  a  character appears where a combining character is
          not valid, the character is treated as unprintable.

          Unprintable multibyte characters are shown as  a  hexa-
          decimal  number  between angle brackets.  The number is
          the code point of the character in the  wide  character
          set;  this  may or may not be Unicode, depending on the
          operating system.

     Invalid multibyte characters
          If the MULTIBYTE option is in effect, any  sequence  of
          one  or more bytes that does not form a valid character
          in the current character set is treated as a series  of
          bytes each shown as a special character.  This case can
          be distinguished from other unprintable  characters  as
          the  bytes  are  represented  as two hexadecimal digits
          between angle brackets, as distinct from  the  four  or
          eight  digits  that are used for unprintable characters
          that are nonetheless valid  in  the  current  character
          set.

          Not  all systems support this: for it to work, the sys-
          tem's representation of wide characters  must  be  code
          values  from the Universal Character Set, as defined by
          IS0 10646 (also known as Unicode).

     Wrapped double-width characters
          When a double-width character appears in the final col-
          umn  of  a  line, it is instead shown on the next line.
          The empty space left in the original position is  high-
          lighted as a special character.

     If zle_highlight is not set or no value applies to a partic-
     ular context, the defaults applied are equivalent to

          zle_highlight=(region:standout special:standout
          suffix:bold isearch:underline)

     i.e. both the region and special  characters  are  shown  in
     standout mode.

     Within widgets, arbitrary regions may be highlighted by set-
     ting  the  special  array  parameter  region_highlight;  see
     above.

ATTRIBUTES
     See   attributes(5)   for   descriptions  of  the  following
     attributes:



zsh 5.0.5          Last change: January 5, 2014                44






User Commands                                           ZSHZLE(1)



     +---------------+------------------+
     |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
     +---------------+------------------+
     |Availability   | shell/zsh        |
     +---------------+------------------+
     |Stability      | Volatile         |
     +---------------+------------------+
NOTES
     This  software  was   built   from   source   available   at
     https://java.net/projects/solaris-userland.    The  original
     community   source   was   downloaded   from    http://down-
     loads.source-
     forge.net/project/zsh/zsh/5.0.5/zsh-5.0.5.tar.bz2

     Further information about this software can be found on  the
     open source community website at http://www.zsh.org/.







































zsh 5.0.5          Last change: January 5, 2014                45






User Commands                                       ZSHCOMPWID(1)



NAME
     zshcompwid - zsh completion widgets

DESCRIPTION
     The shell's programmable completion mechanism can be manipu-
     lated in two ways; here the  low-level  features  supporting
     the newer, function-based mechanism are defined.  A complete
     set of shell functions based on these features is  described
     in  zshcompsys(1),  and  users with no interest in adding to
     that system (or, potentially, writing their own -- see  dic-
     tionary entry for `hubris') should skip the current section.
     The older system based on the  compctl  builtin  command  is
     described in zshcompctl(1).

     Completion  widgets  are defined by the -C option to the zle
     builtin command provided by the  zsh/zle  module  (see  zsh-
     zle(1)). For example,

          zle -C complete expand-or-complete completer

     defines  a  widget named `complete'.  The second argument is
     the name of any of the builtin widgets that  handle  comple-
     tions:   complete-word,  expand-or-complete,  expand-or-com-
     plete-prefix,    menu-complete,     menu-expand-or-complete,
     reverse-menu-complete, list-choices, or delete-char-or-list.
     Note that this will still work even if the widget  in  ques-
     tion has been re-bound.

     When  this  newly defined widget is bound to a key using the
     bindkey builtin command defined in the zsh/zle  module  (see
     zshzle(1)),  typing  that  key  will call the shell function
     `completer'. This function is responsible for generating the
     possible  matches  using  the  builtins described below.  As
     with other ZLE widgets, the  function  is  called  with  its
     standard input closed.

     Once  the  function  returns, the completion code takes over
     control again and treats the matches in the same  manner  as
     the  specified  builtin  widget, in this case expand-or-com-
     plete.

COMPLETION SPECIAL PARAMETERS
     The parameters  ZLE_REMOVE_SUFFIX_CHARS  and  ZLE_SPACE_SUF-
     FIX_CHARS  are used by the completion mechanism, but are not
     special.  See Parameters Used By The Shell in zshparam(1).

     Inside completion widgets, and  any  functions  called  from
     them,  some  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



zsh 5.0.5          Last change: January 5, 2014                 1






User Commands                                       ZSHCOMPWID(1)



     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 func-
     tion  exit  (including nested function calls from within the
     completion widget) to the values they had when the  function
     was entered.

     CURRENT
          This  is  the number of the current word, i.e. the word
          the cursor is currently on in the  words  array.   Note
          that this value is only correct if the ksharrays option
          is not set.

     IPREFIX
          Initially this will be set to the empty  string.   This
          parameter  functions  like PREFIX; it contains a string
          which precedes the one in PREFIX and is not  considered
          part  of  the  list of matches.  Typically, a string is
          transferred from the beginning of PREFIX to the end  of
          IPREFIX, for example:

               IPREFIX=${PREFIX%%\=*}=
               PREFIX=${PREFIX#*=}

          causes  the  part of the prefix up to and including the
          first equal sign not to be treated as part of a matched
          string.   This can be done automatically by the compset
          builtin, see below.

     ISUFFIX
          As IPREFIX, but for a suffix that should not be consid-
          ered  part of the matches; note that the ISUFFIX string
          follows the SUFFIX string.

     PREFIX
          Initially this will be set to the part of  the  current
          word  from the beginning of the word up to the position
          of the cursor; it may be altered to give a common  pre-
          fix for all matches.

     QIPREFIX
          This  parameter  is  read-only  and contains the quoted
          string up to the word being completed. E.g.  when  com-
          pleting  `"foo',  this  parameter  contains  the double
          quote. If the -q option of compset is used (see below),
          and  the original string was `"foo bar' with the cursor
          on the `bar', this parameter contains `"foo '.

     QISUFFIX
          Like QIPREFIX, but containing the suffix.

     SUFFIX



zsh 5.0.5          Last change: January 5, 2014                 2






User Commands                                       ZSHCOMPWID(1)



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

     compstate
          This is an associative array with various keys and val-
          ues that the completion code uses to exchange  informa-
          tion with the completion widget.  The keys are:

          all_quotes
               The  -q option of the compset builtin command (see
               below) allows a quoted string to  be  broken  into
               separate  words;  if the cursor is on one of those
               words,  that  word  will  be  completed,  possibly
               invoking  `compset -q' recursively.  With this key
               it is possible to test the types of quoted strings
               which  are  currently  broken  into  parts in this
               fashion.  Its value  contains  one  character  for
               each  quoting  level.  The characters are a single
               quote or a double quote for  strings  quoted  with
               these  characters,  a  dollars  sign  for  strings
               quoted with $'...' and a backslash for strings not
               starting  with a quote character.  The first char-
               acter in  the  value  always  corresponds  to  the
               innermost quoting level.

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

               array_value
                    when  completing inside the value of an array
                    parameter assignment; in this case the  words
                    array contains the words inside the parenthe-
                    ses.

               brace_parameter
                    when completing the name of a parameter in  a
                    parameter  expansion beginning with ${.  This
                    context will  also  be  set  when  completing
                    parameter  flags following ${(; the full com-
                    mand line argument is presented and the  han-
                    dler  must  test the value to be completed to
                    ascertain that this is the case.

               assign_parameter
                    when completing the name of a parameter in  a
                    parameter assignment.



zsh 5.0.5          Last change: January 5, 2014                 3






User Commands                                       ZSHCOMPWID(1)



               command
                    when  completing for a normal command (either
                    in command position or for an argument of the
                    command).

               condition
                    when  completing  inside  a  `[[...]]' condi-
                    tional expression; in  this  case  the  words
                    array contains only the words inside the con-
                    ditional expression.

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

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

               redirect
                    when completing after a redirection operator.

               subscript
                    when completing inside a parameter subscript.

               value
                    when  completing  the  value  of  a parameter
                    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  other-
               wise.

               If it was set when at least one match equal to the
               string on the line was  generated,  the  match  is
               accepted.

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

          ignored
               The number of words that were ignored because they
               matched  one  of  the  patterns  given with the -F
               option to the compadd builtin command.

          insert
               This controls the  manner  in  which  a  match  is
               inserted  into  the command line.  On entry to the
               widget function, if it is unset the  command  line



zsh 5.0.5          Last change: January 5, 2014                 4






User Commands                                       ZSHCOMPWID(1)



               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 com-
               pletion code may start menu completion (due to the
               AUTO_MENU option being set); if  set  to  menu  or
               automenu  menu  completion will be started for the
               matches currently generated (in  the  latter  case
               this  will  happen  because the AUTO_MENU is set).
               The value may also contain the string  `tab'  when
               the  completion  code would normally not really do
               completion, but only insert the TAB character.

               On exit it may be set to any of the  values  above
               (where  setting it to the empty string is the same
               as unsetting it), or to a number,  in  which  case
               the  match  whose number is given will be inserted
               into the command  line.   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 maxi-
               mum  selects  the  first. Unless the value of this
               key ends in a space, the match is inserted as in a
               menu   completion,   i.e.   without  automatically
               appending a space.

               Both menu and automenu may also specify the number
               of  the match to insert, given after a colon.  For
               example, `menu:2' says to start  menu  completion,
               beginning with the second match.

               Note  that  a value containing the substring `tab'
               makes the matches generated be  ignored  and  only
               the TAB be inserted.

               Finally,  it  may  also be set to all, which makes
               all matches generated be inserted into the line.

          insert_positions
               When the completion system inserts an  unambiguous
               string into the line, there may be multiple places
               where characters are missing or where the  charac-
               ter 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 com-
               mand line.

          last_prompt
               If this is set to a  non-empty  string  for  every
               match  added,  the  completion  code will move the
               cursor back to the previous prompt after the  list



zsh 5.0.5          Last change: January 5, 2014                 5






User Commands                                       ZSHCOMPWID(1)



               of completions has been displayed.  Initially this
               is    set    or    unset    according    to    the
               ALWAYS_LAST_PROMPT option.

          list This  controls  whether or how the list of matches
               will be displayed.  If it is unset or  empty  they
               will  never  be  listed;  if its value begins with
               list, they will always be  listed;  if  it  begins
               with  autolist  or  ambiguous, they will be listed
               when  the  AUTO_LIST  or  LIST_AMBIGUOUS   options
               respectively would normally cause them to be.

               If  the substring force appears in the value, this
               makes the list be shown even if there is only  one
               match.  Normally,  the list would be shown only if
               there are at least two matches.

               The value contains the  substring  packed  if  the
               LIST_PACKED  option  is  set. If this substring is
               given for all matches added to a group, this group
               will  show  the  LIST_PACKED behavior. The same is
               done for the LIST_ROWS_FIRST option with the  sub-
               string rows.

               Finally, if the value contains the string explana-
               tions, only the explanation strings, if any,  will
               be  listed  and  if it contains messages, only the
               messages (added with the  -x  option  of  compadd)
               will  be listed.  If it contains both explanations
               and messages both  kinds  of  explanation  strings
               will  be  listed.  It will be set appropriately on
               entry to a completion widget and  may  be  changed
               there.

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

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

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




zsh 5.0.5          Last change: January 5, 2014                 6






User Commands                                       ZSHCOMPWID(1)



          old_insert
               On entry to the widget this will  be  set  to  the
               number  of the match of an old list of completions
               that is currently inserted into the command  line.
               If no match has been inserted, this is unset.

               As  with old_list, the value of this key will only
               be used if it is the string keep. If it was set to
               this  value  by  the  widget  and there was an old
               match inserted into the command line,  this  match
               will  be  kept  and if the value of the insert key
               specifies that another match should  be  inserted,
               this will be inserted after the old one.

          old_list
               This  is set to yes if there is still a valid list
               of completions from a previous completion  at  the
               time  the widget is invoked.  This will usually be
               the case if and only if the previous editing oper-
               ation  was  a  completion  widget  or  one  of the
               builtin completion functions.  If there is a valid
               list and it is also currently shown on the screen,
               the value of this key is shown.

               After the widget has exited the value of this  key
               is  only used if it was set to keep.  In this case
               the completion code will continue to use this  old
               list.   If  the widget generated new matches, they
               will not be used.

          parameter
               The name of the parameter  when  completing  in  a
               subscript  or  in the value of a parameter assign-
               ment.

          pattern_insert
               Normally this is set to menu, which specifies that
               menu  completion  will  be  used whenever a set of
               matches was generated using pattern matching.   If
               it  is  set  to  any other non-empty string by the
               user and menu completion is not selected by  other
               option  settings, the code will instead insert any
               common prefix for the generated  matches  as  with
               normal completion.

          pattern_match
               Locally   controls  the  behaviour  given  by  the
               GLOB_COMPLETE option.  Initially it is set to  `*'
               if  and only if the option is set.  The completion
               widget may set it  to  this  value,  to  an  empty
               string  (which  has  the  same effect as unsetting
               it), or to any other non-empty string.  If  it  is



zsh 5.0.5          Last change: January 5, 2014                 7






User Commands                                       ZSHCOMPWID(1)



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

               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 single quote, a
               double  quote,  or  a  backtick).  Otherwise it is
               unset.

          quoting
               When completing inside single quotes, this is  set
               to  the  string  single; inside double quotes, the
               string double; inside backticks, the string  back-
               tick.  Otherwise it is unset.

          redirect
               The  redirection operator when completing in a re-
               direction position, i.e. one of <, >, etc.

          restore
               This is set to auto before a function is  entered,
               which  forces  the  special  parameters  mentioned
               above (words, CURRENT,  PREFIX,  IPREFIX,  SUFFIX,
               and ISUFFIX) to be restored to their previous val-
               ues when  the  function  exits.    If  a  function
               unsets  it  or  sets  it to any other string, they
               will not be restored.

          to_end
               Specifies the occasions on  which  the  cursor  is
               moved  to  the  end  of  a  string when a match is
               inserted.  On entry to a widget function,  it  may
               be  single if this will happen when a single unam-
               biguous match was inserted or  match  if  it  will
               happen  any time a match is inserted (for example,
               by menu completion;  this  is  likely  to  be  the
               effect of the ALWAYS_TO_END option).

               On exit, it may be set to single as above.  It may
               also be set to always, or to the empty  string  or
               unset;  in those cases the cursor will be moved to
               the end of the  string  always  or  never  respec-
               tively.  Any other string is treated as match.

          unambiguous



zsh 5.0.5          Last change: January 5, 2014                 8






User Commands                                       ZSHCOMPWID(1)



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

          unambiguous_cursor
               This gives the position the cursor would be placed
               at if the common prefix  in  the  unambiguous  key
               were  inserted, relative to the value of that key.
               The cursor would be placed  before  the  character
               whose index is given by this key.

          unambiguous_positions
               This  contains  all  positions where characters in
               the 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 unam-
               biguous key.

          vared
               If completion is called while editing a line using
               the vared builtin, the value of this key is set to
               the name of the parameter given as an argument  to
               vared.  This key is only set while a vared command
               is active.

     words
          This array contains the words present  on  the  command
          line currently being edited.

COMPLETION BUILTIN COMMANDS
     compadd [ -akqQfenUld12C ] [ -F array ]
     [ -P prefix ] [ -S suffix ]
     [ -p hidden-prefix ] [ -s hidden-suffix ]
     [ -i ignored-prefix ] [ -I ignored-suffix ]
     [ -W file-prefix ] [ -d array ]
     [ -J name ] [ -V name ] [ -X explanation ] [ -x message ]
     [ -r remove-chars ] [ -R remove-func ]
     [ -D array ] [ -O array ] [ -A array ]
     [ -E number ]
     [ -M match-spec ] [ -- ] [ words ... ]

          This  builtin  command  can  be  used  to  add  matches
          directly and control all the information the completion
          code stores with each possible match. The return status
          is zero if at least one match was added and non-zero if
          no matches were added.

          The  completion code breaks the string to complete into
          seven fields in the order:





zsh 5.0.5          Last change: January 5, 2014                 9






User Commands                                       ZSHCOMPWID(1)



               <ipre><apre><hpre><word><hsuf><asuf><isuf>

          The first field is an ignored  prefix  taken  from  the
          command  line,  the  contents  of the IPREFIX parameter
          plus the string given with the -i option. With  the  -U
          option, only the string from the -i option is used. The
          field <apre> is an optional 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 genera-
          tion  might  specify  a  common  path  prefix this way.
          <word> is the part of the match that should  appear  in
          the list of completions, i.e. one of the words given at
          the end of  the  compadd  command  line.  The  suffixes
          <hsuf>,  <asuf>  and  <isuf> correspond to the prefixes
          <hpre>, <apre> and <ipre> and are given by the  options
          -s, -S and -I, respectively.

          The supported flags are:

          -P prefix
               This  gives  a  string  to  be inserted before the
               given words.  The string given is  not  considered
               as  part of the match and any shell metacharacters
               in it will  not  be  quoted  when  the  string  is
               inserted.

          -S suffix
               Like  -P,  but gives a string to be inserted after
               the match.

          -p hidden-prefix
               This gives a string that should be  inserted  into
               the  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 command
               line just before any string given  with  the  `-P'
               option.   Without  `-P'  the  string  is  inserted
               before the string  given  with  `-p'  or  directly
               before the match.

          -I ignored-suffix
               Like -i, but gives an ignored suffix.



zsh 5.0.5          Last change: January 5, 2014                10






User Commands                                       ZSHCOMPWID(1)



          -a   With  this  flag  the  words are taken as names of
               arrays and the possible matches are their  values.
               If  only  some  elements of the arrays are needed,
               the words  may  also  contain  subscripts,  as  in
               `foo[2,-1]'.

          -k   With  this  flag  the  words are taken as names of
               associative arrays and the  possible  matches  are
               their keys.  As for -a, the words may also contain
               subscripts, as in `foo[(R)*bar*]'.

          -d array
               This adds per-match  display  strings.  The  array
               should  contain  one  element  per word given. The
               completion code will then display the  first  ele-
               ment  instead  of  the  first word, and so on. The
               array may be given as the name of an array parame-
               ter or directly as a space-separated list of words
               in parentheses.

               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.

          -o   This  option  only  has an effect if used together
               with the -d option.  If it is given, the order  of
               the  output  is  determined  by the match strings;
               otherwise it is determined by the display  strings
               (i.e. the strings given by the -d option).

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

          -V name
               Like -J but naming an unsorted group. These are in
               a  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



zsh 5.0.5          Last change: January 5, 2014                11






User Commands                                       ZSHCOMPWID(1)



               all  duplicates  be  kept.  Again, groups with and
               without this flag are in different name spaces.

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

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

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

          -r remove-chars
               This  is  a  more versatile form of the -q option.
               The suffix given with -S or  the  slash  automati-
               cally  added  after completing directories will be
               automatically removed if the next character  typed
               inserts   one  of  the  characters  given  in  the
               remove-chars.  This string is parsed as a  charac-
               ters class and understands the backslash sequences
               used by  the  print  command.   For  example,  `-r
               "a-z\t"'  removes the suffix if the next character
               typed inserts a lower case character or a TAB, and
               `-r "^0-9"' removes the suffix if the next charac-
               ter 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 suf-
               fix has been inserted and the completion accepted,
               the  function remove-func will be called after the
               next character typed.  It is passed the length  of
               the  suffix as an argument and can use the special
               parameters available in ordinary  (non-completion)
               zle  widgets (see zshzle(1)) to analyse and modify
               the command line.

          -f   If this flag is given, all of  the  matches  built



zsh 5.0.5          Last change: January 5, 2014                12






User Commands                                       ZSHCOMPWID(1)



               from words are marked as being the names of files.
               They are not required to be actual filenames,  but
               if they are, and the option LIST_TYPES is set, the
               characters describing the types of  the  files  in
               the  completion  lists  will  be  shown. This also
               forces a slash to be added  when  the  name  of  a
               directory is completed.

          -e   This  flag can be used to tell the completion code
               that the matches added are parameter names  for  a
               parameter    expansion.   This   will   make   the
               AUTO_PARAM_SLASH and  AUTO_PARAM_KEYS  options  be
               used for the matches.

          -W file-prefix
               This  string  is a pathname that will be prepended
               to each of the matches formed by the  given  words
               together  with  any  prefix  specified  by  the -p
               option to form a complete  filename  for  testing.
               Hence  it  is  only useful if combined with the -f
               flag, as the tests  will  not  otherwise  be  per-
               formed.

          -F array
               Specifies  an  array  containing  patterns.  Words
               matching one of these patterns are  ignored,  i.e.
               not considered to be possible matches.

               The array may be the name of an array parameter or
               a list of literal patterns enclosed in parentheses
               and  quoted, as in `-F "(*?.o *?.h)"'. If the name
               of an array is given, the elements  of  the  array
               are taken as the patterns.

          -Q   This  flag  instructs  the  completion code not to
               quote any metacharacters in the words when insert-
               ing them into the command line.

          -M match-spec
               This gives local match specifications as described
               below in the  section  `Completion  Matching  Con-
               trol'.  This  option  may be given more than once.
               In this case all match-specs  given  are  concate-
               nated  with spaces between them to form the speci-
               fication 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



zsh 5.0.5          Last change: January 5, 2014                13






User Commands                                       ZSHCOMPWID(1)



               accepted and no matching will be done by the  com-
               pletion  code.  Normally this is used in functions
               that do the matching themselves.

          -O array
               If this option is given, the words are  not  added
               to  the  set  of  possible  completions.  Instead,
               matching is done as usual and  all  of  the  words
               given  as  arguments  that match the string on the
               command line will be stored in the array parameter
               whose name is given as array.

          -A array
               As  the -O option, except that instead of those of
               the words which match being stored in  array,  the
               strings  generated  internally  by  the completion
               code are stored.  For  example,  with  a  matching
               specification  of  `-M "L:|no="', the string `nof'
               on the command line and the string `foo' as one of
               the  words,  this option stores the string `nofoo'
               in the array, whereas the  -O  option  stores  the
               `foo' originally given.

          -D array
               As  with -O, the words are not added to the set of
               possible  completions.   Instead,  the  completion
               code  tests whether each word in turn matches what
               is on the line.  If the nth word does  not  match,
               the nth element of the array is removed.  Elements
               for which the corresponding word  is  matched  are
               retained.

          -C   This  option adds a special match which expands to
               all other matches when  inserted  into  the  line,
               even  those  that  are  added after this option is
               used.  Together with the -d option it is  possible
               to  specify  a  string that should be displayed in
               the list for this special match.  If no string  is
               given, it will be shown as a string containing the
               strings that  would  be  inserted  for  the  other
               matches, truncated to the width of the screen.

          -E   This  option  adds  number empty matches after the
               words have been added.  An empty  match  takes  up
               space  in  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
               completion lists (since empty matches can be given
               display  strings with the -d option).  And because
               all  but  one  empty  string  would  otherwise  be



zsh 5.0.5          Last change: January 5, 2014                14






User Commands                                       ZSHCOMPWID(1)



               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 argument) will
          be used.

     compset -p number
     compset -P [ number ] pattern
     compset -s number
     compset -S [ number ] pattern
     compset -n begin [ end ]
     compset -N beg-pat [ end-pat ]
     compset -q
          This command simplifies  modification  of  the  special
          parameters,  while  its  return  status allows tests on
          them to be carried out.

          The options are:

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

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

               Without the optional number, the longest match  is
               taken,  but if number is given, anything up to the
               numberth match is moved.  If the number  is  nega-
               tive,  the  numberth  longest  match is moved. For
               example, if PREFIX contains  the  string  `a=b=c',
               then  compset -P '*\=' will move the string `a=b='
               into the IPREFIX parameter, but compset -P 1 '*\='
               will move only the string `a='.

          -s number
               As  -p,  but  transfer  the last number characters
               from the value of SUFFIX to the front of the value
               of ISUFFIX.

          -S [ number ] pattern



zsh 5.0.5          Last change: January 5, 2014                15






User Commands                                       ZSHCOMPWID(1)



               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 beginth word is removed
               from the words array and the value of the  parame-
               ter CURRENT is decremented by begin.

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

               Both  begin and end may be negative to count back-
               wards from the last element of the words array.

          -N beg-pat [ end-pat ]
               If one of the elements of the words  array  before
               the  one  at  the  index given by the value of the
               parameter CURRENT matches the pattern beg-pat, all
               elements  up to and including the matching one are
               removed from the words array and the value of CUR-
               RENT  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 match-
               ing  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 test-
               ing  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, PRE-
               FIX, SUFFIX, QIPREFIX, and QISUFFIX  are  modified
               to reflect the word part that is completed.

          In all the above cases the return status is zero if the
          test succeeded and the  parameters  were  modified  and
          non-zero otherwise. This allows one to use this builtin
          in tests such as:



zsh 5.0.5          Last change: January 5, 2014                16






User Commands                                       ZSHCOMPWID(1)



               if compset -P '*\='; then ...

          This forces anything up to and including the last equal
          sign to be ignored by the completion code.

     compcall [ -TD ]
          This  allows  the  use  of completions defined with the
          compctl builtin from within  completion  widgets.   The
          list  of  matches  will  be  generated as if one of the
          non-widget completion functions  (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  com-
          pctl  -D  or  the  builtin  default) in the appropriate
          places, the -T and/or -D flags can be passed  to  comp-
          call.

          The  return  status  can  be used to test if a matching
          compctl definition was found. It is non-zero if a  com-
          pctl was found and zero otherwise.

          Note  that  this  builtin is defined by the zsh/compctl
          module.

COMPLETION CONDITION CODES
     The following additional condition codes for use within  the
     [[  ...  ]]  construct  are available in completion widgets.
     These work on the 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  special
     parameters are not modified.

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

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

     -after beg-pat
          true if the test of the -N option with only the beg-pat
          given would succeed.

     -between beg-pat end-pat
          true if the test for the -N option with  both  patterns
          would succeed.

COMPLETION MATCHING CONTROL
     It  is  possible  by  use  of  the  -M option of the compadd
     builtin command to specify how the characters in the  string



zsh 5.0.5          Last change: January 5, 2014                17






User Commands                                       ZSHCOMPWID(1)



     to  be  completed (referred to here as the command line) map
     onto the characters in the list of matches produced  by  the
     completion code (referred to here as the trial completions).
     Note that this is not used if the command  line  contains  a
     glob pattern and the GLOB_COMPLETE option is set or the pat-
     tern_match of the compstate special association is set to  a
     non-empty string.

     The  match-spec  given as the argument to the -M option (see
     `Completion Builtin Commands' above) consists of one or more
     matching   descriptions   separated   by  whitespace.   Each
     description consists of a letter followed  by  a  colon  and
     then  the  patterns  describing which character sequences on
     the line match which character sequences in the  trial  com-
     pletion.   Any  sequence  of  characters not handled in this
     fashion must match exactly, as usual.

     The forms of match-spec understood are as follows.  In  each
     case,  the form with an upper case initial character retains
     the string already typed on the command line  as  the  final
     result  of completion, while with a lower case initial char-
     acter the string on the command line  is  changed  into  the
     corresponding part of the trial completion.

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

     l:lanchor|lpat=tpat
     L:lanchor|lpat=tpat
     l:lanchor||ranchor=tpat
     L:lanchor||ranchor=tpat
     b:lpat=tpat
     B:lpat=tpat
          These  letters  are  for  patterns that are anchored by
          another 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  lan-
          chor.   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



zsh 5.0.5          Last change: January 5, 2014                18






User Commands                                       ZSHCOMPWID(1)



          trial  completion  or  the  word  on  the command line,
          respectively.

     r:lpat|ranchor=tpat
     R:lpat|ranchor=tpat
     r:lanchor||ranchor=tpat
     R:lanchor||ranchor=tpat
     e:lpat=tpat
     E:lpat=tpat
          As l, L, b and B, with the difference that the  command
          line  and trial completion patterns are anchored on the
          right side.  Here an empty ranchor  and  the  e  and  E
          forms  force  the match to the end of the trial comple-
          tion or command line string.

     Each lpat, tpat or anchor is either an empty string or  con-
     sists  of  a  sequence  of  literal characters (which may be
     quoted with a backslash), question marks, character classes,
     and  correspondence classes; ordinary shell patterns are not
     used.  Literal characters match  only  themselves,  question
     marks  match any character, and character classes are formed
     as for globbing and match any character in the given set.

     Correspondence classes are defined like  character  classes,
     but  with  two  differences: they are delimited by a pair of
     braces, and negated classes are not allowed, so the  charac-
     ters  !  and  ^  have  no special meaning directly after the
     opening brace.  They indicate that a range of characters  on
     the  line  match  a range of characters in the trial comple-
     tion, but (unlike ordinary character classes) paired accord-
     ing  to  the  corresponding  position  in the sequence.  For
     example, to make any ASCII lower case  letter  on  the  line
     match  the corresponding upper case letter in the trial com-
     pletion, you can use `m:{a-z}={A-Z}' (however, see below for
     the  recommended  form  for  this).   More  than one pair of
     classes can occur, in which case the first class before  the
     = 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  standard  `[:name:]' forms described for standard shell
     patterns, see the section FILENAME GENERATION in zshexpn(1),
     may appear in correspondence classes as well as normal char-
     acter classes.  The only special behaviour in correspondence
     classes is if the form on the left and the form on the right
     are each one of [:upper:], [:lower:].  In  these  cases  the
     character  in the word and the character on the line must be
     the same up to a difference in  case.   Hence  to  make  any
     lower  case  character  on  the line match the corresponding
     upper case character in the trial  completion  you  can  use



zsh 5.0.5          Last change: January 5, 2014                19






User Commands                                       ZSHCOMPWID(1)



     `m:{[:lower:]}={[:upper:]}'.   Although  the matching system
     does not yet handle multibyte characters, this is likely  to
     be  a future extension, at which point this syntax will han-
     dle arbitrary alphabets; hence this form,  rather  than  the
     use  of  explicit ranges, is the recommended form.  In other
     cases `[:name:]' forms are allowed.  If the two forms on the
     left  and  right  are  the  same,  the characters must match
     exactly.  In remaining cases, the  corresponding  tests  are
     applied  to both characters, but they are not otherwise con-
     strained; any matching character in one set  goes  with  any
     matching  character in the other set:  this is equivalent to
     the behaviour of ordinary 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 char-
     acters up to the next  appearance  of  the  anchor  will  be
     matched.  With  two  stars, substrings matched by the anchor
     can be matched, too.

     Examples:

     The keys of the options association defined by the parameter
     module  are the option names in all-lower-case form, without
     underscores, and without the optional no  at  the  beginning
     even  though  the  builtins  setopt  and unsetopt understand
     option names with upper case letters, underscores,  and  the
     optional  no.   The  following  alters the matching rules so
     that the prefix no and any underscore are ignored when  try-
     ing  to match the trial completions generated and upper case
     letters on the line match the corresponding lower case  let-
     ters in the words:

          compadd -M 'L:|[nN][oO]= M:_= M:{[:upper:]}={[:lower:]}' - \
            ${(k)options}

     The  first  part  says  that  the  pattern `[nN][oO]' at the
     beginning (the empty anchor before the pipe symbol)  of  the
     string  on  the line matches the empty string in the list of
     words generated by completion, so  it  will  be  ignored  if
     present.  The  second  part  does the same for an underscore
     anywhere in the command line string, and the third part uses
     correspondence  classes so that any upper case letter on the
     line matches the corresponding  lower  case  letter  in  the
     word.  The  use of the upper case forms of the specification
     characters (L and M) guarantees that what has  already  been
     typed on the command line (in particular the prefix no) will
     not be deleted.




zsh 5.0.5          Last change: January 5, 2014                20






User Commands                                       ZSHCOMPWID(1)



     Note that the use of L in  the  first  part  means  that  it
     matches  only when at the beginning of both the command line
     string and the trial completion. I.e.,  the  string  `_NO_f'
     would  not  be completed to `_NO_foo', nor would `NONO_f' be
     completed to `NONO_foo' because of the leading underscore or
     the  second  `NO'  on  the line which makes the pattern fail
     even though they are otherwise ignored.  To  fix  this,  one
     would  use  `B:[nN][oO]='  instead  of  the  first  part. As
     described above, this matches at the beginning of the  trial
     completion, independent of other characters or substrings at
     the beginning of the command line word which are ignored  by
     the same or other match-specs.

     The  second example makes completion case insensitive.  This
     is just the same as in the option example,  except  here  we
     wish to retain the characters in the list of completions:

          compadd -M 'm:{[:lower:]}={[:upper:]}' ...

     This  makes  lower case letters match their upper case coun-
     terparts.  To make upper case letters match the  lower  case
     forms as well:

          compadd -M 'm:{[:lower:][:upper:]}={[:upper:][:lower:]}' ...

     A  nice  example  for  the use of * patterns is partial word
     completion. Sometimes you would like to  make  strings  like
     `c.s.u'  complete  to  strings like `comp.source.unix', i.e.
     the word on the command line  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 completion is just as normal.

     With the pattern shown above, the string `c.u' could not  be
     completed  to  `comp.sources.unix'  because  the single star
     means that no dot (matched by the anchor) can be skipped. By



zsh 5.0.5          Last change: January 5, 2014                21






User Commands                                       ZSHCOMPWID(1)



     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  than  at  the  end.  However in our example we would
     like the code to recognise matches which contain extra char-
     acters  after the string on the line (the `nix' in the exam-
     ple).  Hence we say that the empty string at the end of  the
     string  on the line matches any characters at the end of the
     trial completion.

     More generally, the specification

          compadd -M 'r:|[.,_-]=* r:|=*' ...

     allows one to complete words with abbreviations  before  any
     of  the  characters in the square brackets.  For example, to
     complete veryverylongfile.c rather than veryverylongheader.h
     with  the  above  in effect, you can just type very.c before
     attempting completion.

     The specifications with both a left and a right  anchor  are
     useful  to  complete partial words whose parts are not 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  upper
     case  letter)  or  maybe  one  has  to complete strings with
     trailing numbers. Here one could use the  simple  form  with
     only one anchor as in:

          compadd -M 'r:|[[:upper:]0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234

     But  with  this,  the  string  `H' would neither complete to
     `FooHoo' nor to `LikeTHIS' because in each case there is  an
     upper  case letter before the `H' and that is matched by the
     anchor. Likewise, a `2' would  not  be  completed.  In  both
     cases this could be changed by using `r:|[[:upper:]0-9]=**',
     but then `H' completes to both `LikeTHIS' and `FooHoo' and a
     `2'  matches  the  other  strings  because characters can be
     inserted before every upper case letter and digit. To  avoid
     this one would use:

          compadd -M 'r:[^[:upper:]0-9]||[[:upper:]0-9]=** r:|=*' \
              LikeTHIS FooHoo foo123 bar234



zsh 5.0.5          Last change: January 5, 2014                22






User Commands                                       ZSHCOMPWID(1)



     By  using  these  two anchors, a `H' matches only upper case
     `H's that are immediately preceded by something matching the
     left  anchor  `[^[:upper:]0-9]'.  The  effect is, of course,
     that `H' matches only the string  `FooHoo',  a  `2'  matches
     only `bar234' and so on.

     When  using the completion system (see zshcompsys(1)), users
     can define match specifications that are to be used for spe-
     cific contexts by using the matcher and matcher-list styles.
     The values for the latter will be used everywhere.

COMPLETION WIDGET EXAMPLE
     The first step is to define the widget:

          zle -C complete complete-word complete-files

     Then the widget can be bound to  a  key  using  the  bindkey
     builtin 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 - * }

     This  function  will complete files in the current directory
     matching the current word.



ATTRIBUTES
     See  attributes(5)  for  descriptions   of   the   following
     attributes:

     +---------------+------------------+
     |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
     +---------------+------------------+
     |Availability   | shell/zsh        |
     +---------------+------------------+
     |Stability      | Volatile         |
     +---------------+------------------+
NOTES
     This   software   was   built   from   source  available  at
     https://java.net/projects/solaris-userland.   The   original
     community   source   was   downloaded   from    http://down-
     loads.source-
     forge.net/project/zsh/zsh/5.0.5/zsh-5.0.5.tar.bz2

     Further  information about this software can be found on the
     open source community website at http://www.zsh.org/.



zsh 5.0.5          Last change: January 5, 2014                23






User Commands                                       ZSHCOMPSYS(1)



NAME
     zshcompsys - zsh completion system

DESCRIPTION
     This describes the shell code for the `new' completion  sys-
     tem,  referred  to as compsys.  It is written in shell func-
     tions based on the features described in zshcompwid(1).

     The features are contextual, sensitive to the point at which
     completion  is  started.   Many completions are already pro-
     vided.  For this reason, a user can  perform  a  great  many
     tasks  without  knowing any details beyond how to initialize
     the system, which is described below in INITIALIZATION.

     The context that decides what completion is to be  performed
     may be
     o    an  argument  or  option  position:  these describe the
          position on the command line  at  which  completion  is
          requested.   For  example `first argument to rmdir, the
          word being completed names a directory';


     o    a special context, denoting an element in  the  shell's
          syntax.   For  example  `a word in command position' or
          `an array subscript'.


     A full context specification contains other elements, as  we
     shall describe.

     Besides  commands names and contexts, the system employs two
     more concepts, styles and tags.  These provide ways for  the
     user to configure the system's behaviour.

     Tags  play a dual role.  They serve as a classification sys-
     tem for the matches, typically indicating a class of  object
     that  the  user  may need to distinguish.  For example, when
     completing arguments of the ls command the user  may  prefer
     to  try files before directories, so both of these are tags.
     They also appear as the rightmost element in a context spec-
     ification.

     Styles  modify  various operations of the completion system,
     such as output formatting, but also what kinds of completers
     are  used  (and  in what order), or which tags are examined.
     Styles may accept arguments and are  manipulated  using  the
     zstyle command described in see zshmodules(1).

     In  summary,  tags describe what the completion objects are,
     and style how they are to be completed.  At  various  points
     of  execution,  the  completion  system  checks  what styles
     and/or tags are defined for the current  context,  and  uses



zsh 5.0.5          Last change: January 5, 2014                 1






User Commands                                       ZSHCOMPSYS(1)



     that  to  modify its behavior.  The full description of con-
     text handling, which determines how tags and other  elements
     of  the  context  influence  the  behaviour  of  styles,  is
     described below in COMPLETION SYSTEM CONFIGURATION.

     When a completion is requested,  a  dispatcher  function  is
     called; see the description of _main_complete in the list of
     control functions below. This dispatcher decides which func-
     tion  should be called to produce the completions, and calls
     it. The result is passed to one or  more  completers,  func-
     tions  that implement individual completion strategies: sim-
     ple completion, error correction, completion with error cor-
     rection, menu selection, etc.

     More generally, the shell functions contained in the comple-
     tion system are of two types:
     o    those beginning `comp' are to be called directly; there
          are only a few of these;


     o    those  beginning `_' are called by the completion code.
          The shell functions of this set, which  implement  com-
          pletion  behaviour  and may be bound to keystrokes, are
          referred to as `widgets'.   These  proliferate  as  new
          completions are required.


INITIALIZATION
     If  the system was installed completely, it should be enough
     to call the shell function compinit from your initialization
     file;  see  the next section.  However, the function compin-
     stall can be run by a user to configure various  aspects  of
     the completion system.

     Usually,  compinstall will insert code into .zshrc, although
     if that is not writable it will save it in another file  and
     tell you that file's location.  Note that it is up to you to
     make sure that the lines added to .zshrc are  actually  run;
     you  may, for example, need to move them to an earlier place
     in the file if .zshrc usually returns early.  So long as you
     keep  them  all together (including the comment lines at the
     start and finish), you can rerun  compinstall  and  it  will
     correctly  locate  and  modify  these lines.  Note, however,
     that any code you add to this 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  compinstall   has
     removed  definitions,  you will need to restart the shell to
     see the changes.



zsh 5.0.5          Last change: January 5, 2014                 2






User Commands                                       ZSHCOMPSYS(1)



     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 directo-
     ries from fpath.  Then it must be autoloaded  (`autoload  -U
     compinstall'  is  recommended).  You can abort the installa-
     tion any time you are being prompted  for  information,  and
     your  .zshrc  will  not be altered at all; changes only take
     place right at the end, where you are specifically asked for
     confirmation.

  Use of compinit
     This  section  describes  the  use of compinit to initialize
     completion for the current session when called directly;  if
     you  have  run  compinstall  it will be called automatically
     from your .zshrc.

     To initialize the system, the function compinit should be in
     a  directory mentioned in the fpath parameter, and should be
     autoloaded (`autoload -U compinit' is recommended), and then
     run  simply  as  `compinit'.  This will define a few utility
     functions, arrange for all the necessary shell functions  to
     be  autoloaded,  and will then re-define all widgets that do
     completion  to  use  the  new  system.   If  you   use   the
     menu-select  widget,  which is part of the zsh/complist mod-
     ule, you should make sure that that module is loaded  before
     the call to compinit so that that widget is also re-defined.
     If completion styles (see  below)  are  set  up  to  perform
     expansion  as well as completion by default, and the TAB key
     is bound to expand-or-complete, compinit will rebind  it  to
     complete-word;  this is necessary to use the correct form of
     expansion.

     Should you need to use the original completion commands, you
     can  still  bind keys to the old widgets by putting a `.' in
     front of the widget name, e.g. `.expand-or-complete'.

     To speed up the running of compinit, it can be made to  pro-
     duce  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



zsh 5.0.5          Last change: January 5, 2014                 3






User Commands                                       ZSHCOMPSYS(1)



     re-create  it  the next time it is run.  The check performed
     to see if there are new functions can be omitted  by  giving
     the option -C.  In this case the dump file will only be cre-
     ated if there isn't one already.

     The dumping is actually done by another function,  compdump,
     but  you  will  only need to run this yourself if you change
     the configuration (e.g. using compdef) and then want to dump
     the new one.  The name of the old dumped file will be remem-
     bered for this purpose.

     If the parameter _compdir is set,  compinit  uses  it  as  a
     directory  where  completion functions can be found; this is
     only necessary if they  are  not  already  in  the  function
     search path.

     For  security reasons compinit also checks if the completion
     system would use files not owned by root or by  the  current
     user,   or   files   in   directories  that  are  world-  or
     group-writable or that are not owned by root or by the  cur-
     rent user.  If such files or directories are found, compinit
     will ask if the completion system should really be used.  To
     avoid  these  tests and make all files found be used without
     asking, use the option -u, and  to  make  compinit  silently
     ignore all insecure files and directories use the option -i.
     This security check is skipped entirely when the  -C  option
     is given.

     The security check can be retried at any time by running the
     function  compaudit.   This  is  the  same  check  used   by
     compinit,  but  when  it is executed directly any changes to
     fpath are made local to the function so they do not persist.
     The directories to be checked may be passed as arguments; if
     none are given, compaudit uses fpath and  _compdir  to  find
     completion  system directories, adding missing ones to fpath
     as necessary.  To force a check of exactly  the  directories
     currently  named  in  fpath, set _compdir to an empty string
     before calling compaudit or compinit.

     The function bashcompinit provides compatibility with bash's
     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.

  Autoloaded files
     The  convention  for autoloaded functions used in completion
     is that they start with an underscore; as already mentioned,
     the  fpath/FPATH  parameter  must  contain  the directory in
     which they are stored.  If zsh  was  properly  installed  on
     your  system,  then  fpath/FPATH  automatically contains the



zsh 5.0.5          Last change: January 5, 2014                 4






User Commands                                       ZSHCOMPSYS(1)



     required directories for the standard functions.

     For incomplete installations,  if  compinit  does  not  find
     enough  files  beginning  with  an  underscore  (fewer  than
     twenty) in the search path, it will  try  to  find  more  by
     adding  the  directory _compdir to the search path.  If that
     directory has a subdirectory named Base, all  subdirectories
     will be added to the path.  Furthermore, if the subdirectory
     Base has a subdirectory named Core, compinit  will  add  all
     subdirectories  of  the  subdirectories is to the path: this
     allows the functions to be in the same format as in the  zsh
     source distribution.

     When  compinit is run, it searches all such files accessible
     via fpath/FPATH and reads the first line of  each  of  them.
     This  line  should  contain one of the tags described below.
     Files whose first line does not start with one of these tags
     are  not  considered to be part of the completion system and
     will not be treated specially.

     The tags are:

     #compdef names... [ -[pP] patterns... [ -N names... ] ]
          The file will be made  autoloadable  and  the  function
          defined  in  it  will  be called when completing names,
          each of which is either the name  of  a  command  whose
          arguments  are  to  be  completed or one of a number of
          special contexts in the form -context- described below.

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

          If the #compdef line contains one of the options -p  or
          -P,  the words following are taken to be patterns.  The
          function will be called when  completion  is  attempted
          for  a  command or context that matches one of the pat-
          terns.  The options -p and -P are used to specify  pat-
          terns  to  be  tried  before or after other completions
          respectively.  Hence -P may be used to specify  default
          actions.

          The  option -N is used after a list following -p or -P;
          it specifies that remaining words no longer define pat-
          terns.   It  is  possible  to  toggle between the three
          options as many times as necessary.



zsh 5.0.5          Last change: January 5, 2014                 5






User Commands                                       ZSHCOMPSYS(1)



     #compdef -k style key-sequences...
          This option creates a widget behaving like the  builtin
          widget  style  and binds it to the given key-sequences,
          if any.  The style must be one of the  builtin  widgets
          that    perform   completion,   namely   complete-word,
          delete-char-or-list, expand-or-complete, expand-or-com-
          plete-prefix,        list-choices,       menu-complete,
          menu-expand-or-complete, or reverse-menu-complete.   If
          the  zsh/complist  module is loaded (see zshmodules(1))
          the widget menu-select is also available.

          When one of the key-sequences is typed, the function in
          the file will be invoked to generate the matches.  Note
          that a key will not be re-bound if it already was (that
          is,  was  bound to 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 argu-
          ments.  Note in particular that the widget-name must be
          distinct  in  each  set.  If it does not begin with `_'
          this will be added.  The widget-name should  not  clash
          with  the  name  of any existing widget: names based on
          the name of the function are most useful.  For example,

               #compdef -K _foo_complete complete-word "^X^C" \
                 _foo_list list-choices "^X^D"

          (all  on  one  line) defines a widget _foo_complete for
          completion, bound to `^X^C', and a widget _foo_list for
          listing, bound to `^X^D'.

     #autoload [ options ]
          Functions   with  the  #autoload  tag  are  marked  for
          autoloading but are not  otherwise  treated  specially.
          Typically  they are to be called from within one of the
          completion functions.  Any  options  supplied  will  be
          passed  to the autoload builtin; a typical use is +X to
          force the function to be loaded immediately.  Note that
          the -U and -z flags are always added implicitly.

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

     The special contexts for which completion functions  can  be
     defined are:



zsh 5.0.5          Last change: January 5, 2014                 6






User Commands                                       ZSHCOMPSYS(1)



     -array-value-
          The    right   hand   side   of   an   array-assignment
          (`foo=(...)')

     -brace-parameter-
          The  name  of  a  parameter  expansion  within   braces
          (`${...}')

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

     -command-
          A word in command position

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

     -default-
          Any word for which no other completion is defined

     -equal-
          A word beginning with an equals sign

     -first-
          This is tried before  any  other  completion  function.
          The  function called may set the _compskip parameter to
          one of various values: all: no  further  completion  is
          attempted;  a string containing the substring patterns:
          no pattern  completion  functions  will  be  called;  a
          string   containing   default:  the  function  for  the
          `-default-' context will not be called,  but  functions
          defined for commands will

     -math-
          Inside mathematical contexts, such as `((...))'

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

     -redirect-
          The word after a redirection operator.

     -subscript-
          The contents of a parameter subscript.

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

     -value-
          On the right hand side of an assignment.



zsh 5.0.5          Last change: January 5, 2014                 7






User Commands                                       ZSHCOMPSYS(1)



     Default implementations are supplied for each of these  con-
     texts.   In  most cases the context -context- is implemented
     by a corresponding function _context, for example  the  con-
     text `-tilde-' and the function `_tilde').

     The contexts -redirect- and -value- allow extra context-spe-
     cific information.  (Internally,  this  is  handled  by  the
     functions  for each context calling the function _dispatch.)
     The extra information is added separated by commas.

     For the -redirect- context, the extra information is in  the
     form  `-redirect-,op,command',  where  op is the redirection
     operator and command is the name of the command on the line.
     If  there  is  no command on the line yet, the command field
     will be empty.

     For the -value- context, the form is `-value-,name,command',
     where  name  is  the  name of the parameter.  In the 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  com-
     mand  part  gives the name of the command, here make; other-
     wise 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.

     Also:

          compdef _foo -value-,-default-,-default-

     specifies that _foo provides completions for the  values  of
     parameters  for  which no special function has been defined.
     This is usually 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'




zsh 5.0.5          Last change: January 5, 2014                 8






User Commands                                       ZSHCOMPSYS(1)



     is  another way to make completion after `2> <TAB>' complete
     files matching `*.log'.

  Functions
     The following function is defined by  compinit  and  may  be
     called directly.

names... ] ]
     compdef  [  -ane  ]  function  names...  [ -[pP] patterns...
          [ -N
     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 comple-
          tion in the given contexts as described for  the  #com-
          pdef tag above.

          Alternatively,  all  the  arguments  may  have the form
          `cmd=service'.  Here service should already  have  been
          defined  by  `cmd1=service' lines in #compdef files, as
          described above.  The argument for  cmd  will  be  com-
          pleted in the same way as service.

          The  function  argument  may  alternatively be a string
          containing almost any shell code.  If the  string  con-
          tains  an  equal  sign, the above will take precedence.
          The option -e may be used to specify the first argument
          is to be evaluated as shell code even if it contains an
          equal sign.  The string will be executed using the eval
          builtin command to generate completions.  This provides
          a way of avoiding having to  define  a  new  completion
          function.   For  example,  to  complete files ending in
          `.h' as arguments to the command foo:

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

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

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

          The names may also contain -p, -P  and  -N  options  as
          described  for  the  #compdef  tag.   The effect on the
          argument list is identical, switching  between  defini-
          tions  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  pat-
          tern-functions  will be called; if it is set to a value



zsh 5.0.5          Last change: January 5, 2014                 9






User Commands                                       ZSHCOMPSYS(1)



          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-com-
          plete-prefix,        list-choices,       menu-complete,
          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 unde-
          fined-key.

          The form with -K is similar and defines  multiple  wid-
          gets 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  beginning  with
          an underscore.

          Wherever  applicable,  the -a option makes the function
          autoloadable, equivalent to autoload -U function.

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

          compdef _pids foo

     uses the function _pids to complete process IDs for the com-
     mand foo.

     Note also the _gnu_generic function described  below,  which
     can be used to complete options for commands that understand
     the `--help' option.

COMPLETION SYSTEM CONFIGURATION
     This section gives a short overview of  how  the  completion
     system  works, and then more detail on how users can config-
     ure how and when matches are generated.

  Overview
     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 cur-
     rent word may be an argument (such as the `-o' option to zsh
     which takes a shell option as an argument).



zsh 5.0.5          Last change: January 5, 2014                10






User Commands                                       ZSHCOMPSYS(1)



     This context information is condensed into a string consist-
     ing of multiple fields separated by colons, referred to sim-
     ply  as `the context' in the remainder of the documentation.
     This is used to look up  styles,  context-sensitive  options
     that  can  be  used to configure the completion system.  The
     context used for lookup may vary during the same call to the
     completion system.

     The context string always consists of a fixed set of fields,
     separated by colons and with  a  leading  colon  before  the
     first,   in   the  form  :completion:function:completer:com-
     mand:argument:tag.  These have the following meaning:

     o    The literal string completion, saying that  this  style
          is  used  by the completion system.  This distinguishes
          the context from those used by, for example,  zle  wid-
          gets and ZFTP functions.


     o    The function, if completion is called from a named wid-
          get rather than through the normal  completion  system.
          Typically  this is blank, but it is set by special wid-
          gets such as predict-on and the  various  functions  in
          the Widget directory of the distribution to the name of
          that function, often in an abbreviated form.


     o    The completer currently active, the name of  the  func-
          tion  without  the  leading  underscore  and with other
          underscores converted to hyphens.  A `completer' is  in
          overall  control  of how completion is to be performed;
          `complete' is the simplest, but other completers  exist
          to perform related tasks such as correction, or to mod-
          ify the behaviour of a later completer.  See  the  sec-
          tion `Control Functions' below for more information.


     o    The  command or a special -context-, just at it appears
          following the #compdef tag  or  the  compdef  function.
          Completion  functions  for  commands that have sub-com-
          mands usually modify this field to contain the name  of
          the  command  followed by a minus sign and the sub-com-
          mand.  For example, the completion function for the cvs
          command  sets  this  field  to  cvs-add when completing
          arguments to the add subcommand.


     o    The argument; this  indicates  which  command  line  or
          option  argument  we are completing.  For command argu-
          ments this generally takes the form argument-n, where n
          is  the  number  of  the argument, and for arguments to
          options the form option-opt-n where n is the number  of



zsh 5.0.5          Last change: January 5, 2014                11






User Commands                                       ZSHCOMPSYS(1)



          the  argument to option opt.  However, this is only the
          case if  the  command  line  is  parsed  with  standard
          UNIX-style  options  and arguments, so many completions
          do not set this.


     o    The tag.  As described previously,  tags  are  used  to
          discriminate  between the types of matches a completion
          function can generate in a certain context.   Any  com-
          pletion  function  may use any tag name it likes, but a
          list of the more common ones is given below.


     The context is gradually put together as the  functions  are
     executed,  starting  with  the  main entry point, which adds
     :completion: and the function  element  if  necessary.   The
     completer  then  adds the completer element.  The contextual
     completion adds the command and argument options.   Finally,
     the  tag  is  added  when the types of completion are known.
     For example, the context name

          :completion::complete:dvips:option-o-1:files

     says that normal completion was attempted as the first argu-
     ment to the option -o of the command dvips:

          dvips -o ...

     and the completion function will generate filenames.

     Usually completion will be tried for all possible tags in an
     order given by the completion function.  However,  this  can
     be altered by using the tag-order style.  Completion is then
     restricted to the list of given tags in the given order.

     The _complete_help bindable command shows all  the  contexts
     and  tags  available  for  completion at a particular point.
     This  provides  an  easy  way  of  finding  information  for
     tag-order  and other styles.  It is described in the section
     `Bindable Commands' below.

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

     When looking up styles the completion system uses full  con-
     text  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.



zsh 5.0.5          Last change: January 5, 2014                12






User Commands                                       ZSHCOMPSYS(1)



     For example, many completion functions can generate  matches
     in  a simple and a verbose form and use the verbose style to
     decide which form should be used.  To make  all  such  func-
     tions use the verbose form, put

          zstyle ':completion:*' verbose yes

     in a startup file (probably .zshrc).  This gives the verbose
     style the value yes in every context inside  the  completion
     system,  unless that context has a more specific definition.
     It is best to avoid giving the context as `*'  in  case  the
     style has some meaning outside the completion system.

     Many such general purpose styles can be configured simply by
     using the compinstall function.

     A more specific example of the use of the verbose  style  is
     by  the  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 functions  (see
     see zshcompwid(1))).  For example,

          zstyle -e ':completion:*' hosts 'reply=($myhosts)'

     This forces the value of the hosts style to be read from the
     variable myhosts each time a host name is  needed;  this  is
     useful  if the value of myhosts can change dynamically.  For
     another useful example, see the example in  the  description
     of  the  file-list  style  below.  This form can be slow and
     should be avoided for commonly examined styles such as  menu
     and list-rows-first.

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



zsh 5.0.5          Last change: January 5, 2014                13






User Commands                                       ZSHCOMPSYS(1)



     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 particu-
     lar styles and do not refer to a type of match.

     accounts
          used to look up the users-hosts style

     all-expansions
          used by the _expand completer when  adding  the  single
          string containing all possible expansions

     all-files
          for the names of all files (as distinct from a particu-
          lar subset, see the globbed-files tag).

     arguments
          for arguments to a command

     arrays
          for names of array parameters

     association-keys
          for keys of associative arrays;  used  when  completing
          inside a subscript to a parameter of this type

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

     builtins
          for names of builtin commands

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

     colormapids
          for X colormap ids

     colors
          for color names

     commands
          for names of external commands.  Also used  by  complex
          commands such as cvs when completing names subcommands.

     contexts



zsh 5.0.5          Last change: January 5, 2014                14






User Commands                                       ZSHCOMPSYS(1)



          for contexts in arguments to the zstyle builtin command

     corrections
          used  by  the  _approximate and _correct completers for
          possible corrections

     cursors
          for cursor names used by X programs

     default
          used in some contexts to provide a way of  supplying  a
          default  when  more specific tags are also valid.  Note
          that this tag is used when only the function  field  of
          the context name is set

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

     devices
          for names of device special files

     directories
          for names of directories -- local-directories  is  used
          instead  when  completing  arguments  of cd and related
          builtin commands when the cdpath array is set

     directory-stack
          for entries in the directory stack

     displays
          for X display names

     domains
          for network domains

     expansions
          used by the _expand completer for individual words  (as
          opposed  to  the  complete set of expansions) resulting
          from the expansion of a word on the command line

     extensions
          for X server extensions

     file-descriptors
          for numbers of open file descriptors

     files
          the generic file-matching tag used  by  functions  com-
          pleting filenames

     fonts



zsh 5.0.5          Last change: January 5, 2014                15






User Commands                                       ZSHCOMPSYS(1)



          for X font names

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

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

     globbed-files
          for  filenames when the name has been generated by pat-
          tern matching

     groups
          for names of user groups

     history-words
          for words from the history

     hosts
          for hostnames

     indexes
          for array indexes

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

     interfaces
          for network interfaces

     keymaps
          for names of zsh keymaps

     keysyms
          for names of X keysyms

     libraries
          for names of system libraries

     limits
          for system limits

     local-directories
          for names of directories that are subdirectories of the
          current  working directory when completing arguments of
          cd and related builtin commands (compare  path-directo-
          ries) -- when the cdpath array is unset, directories is
          used instead

     manuals
          for names of manual pages



zsh 5.0.5          Last change: January 5, 2014                16






User Commands                                       ZSHCOMPSYS(1)



     mailboxes
          for e-mail folders

     maps for map names (e.g. NIS maps)

     messages
          used to look up the format style for messages

     modifiers
          for names of X modifiers

     modules
          for modules (e.g. zsh modules)

     my-accounts
          used to look up the users-hosts style

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

     names
          for all kinds of names

     newsgroups
          for USENET groups

     nicknames
          for nicknames of NIS maps

     options
          for command options

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

     other-accounts
          used to look up the users-hosts style

     other-files
          for the names of any non-directory files.  This is used
          instead  of all-files when the list-dirs-first style is
          in effect.

     packages
          for packages (e.g. rpm or installed Debian packages)

     parameters
          for names of parameters

     path-directories



zsh 5.0.5          Last change: January 5, 2014                17






User Commands                                       ZSHCOMPSYS(1)



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

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

     pods for perl pods (documentation files)

     ports
          for communication ports

     prefixes
          for prefixes (like those of a URL)

     printers
          for print queue names

     processes
          for process identifiers

     processes-names
          used  to  look up the command style when generating the
          names of processes for killall

     sequences
          for sequences (e.g. mh sequences)

     sessions
          for sessions in the zftp function suite

     signals
          for signal names

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

     styles
          for styles used by the zstyle builtin command

     suffixes
          for filename extensions

     tags for tags (e.g. rpm tags)

     targets
          for makefile targets

     time-zones
          for time zones (e.g. when setting the TZ parameter)



zsh 5.0.5          Last change: January 5, 2014                18






User Commands                                       ZSHCOMPSYS(1)



     types
          for types of whatever (e.g. address types for the xhost
          command)

     urls used to look up the urls and local styles when complet-
          ing URLs

     users
          for usernames

     values
          for one of a set of values in certain lists

     variant
          used  by  _pick_variant  to  look up the command to run
          when determining what program is installed for  a  par-
          ticular command name.

     visuals
          for X visuals

     warnings
          used to look up the format style for warnings

     widgets
          for zsh widget names

     windows
          for IDs of X windows

     zsh-options
          for shell options

  Standard Styles
     Note  that  the  values of several of these styles represent
     boolean values.  Any of the strings `true', `on', `yes', and
     `1'  can be used for the value `true' and any of the strings
     `false', `off', `no', and `0' for the  value  `false'.   The
     behavior  for  any  other  value  is  undefined except where
     explicitly mentioned.  The default value may be either  true
     or false if the style is not set.

     Some of these styles are tested first for every possible tag
     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 nor-
     mally be defined along the lines of:





zsh 5.0.5          Last change: January 5, 2014                19






User Commands                                       ZSHCOMPSYS(1)



          zstyle ':completion:*:default' menu ...

     accept-exact
          This is tested for the default tag in addition  to  the
          tags  valid  for  the current context.  If it is set to
          `true' and any of the trial matches is the same as  the
          string on the command line, this match will immediately
          be accepted (even if it would otherwise  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 immedi-
          ately  even if the command line contains some more par-
          tially typed pathname components  and  these  match  no
          file under the directory accepted.

          This  style  is  also  used by the _expand completer to
          decide if words beginning with  a  tilde  or  parameter
          expansion  should  be  expanded.  For example, if there
          are parameters foo and foobar, the string  `$foo'  will
          only be expanded if accept-exact is set to `true'; oth-
          erwise the completion system will be  allowed  to  com-
          plete  $foo  to  $foobar.  If the style is set to `con-
          tinue', _expand will add the expansion as a  match  and
          the completion system will also be allowed to continue.

     accept-exact-dirs
          This  is   used   by   filename   completion.    Unlike
          accept-exact  it  is  a  boolean.  By default, filename
          completion examines all components of a path to see  if
          there  are  completions  of that component, even if the
          component matches an existing directory.  For  example,
          when  completion after /usr/bin/, the function examines
          possible completions to /usr.

          When this style is true, any  prefix  of  a  path  that
          matches  an  existing directory is accepted without any
          attempt to complete it further.  Hence,  in  the  given
          example, the path /usr/bin/ is accepted immediately and
          completion tried in that directory.

          If you wish to inhibit this behaviour entirely, set the
          path-completion style (see below) to false.

     add-space
          This  style is used by the _expand completer.  If it is
          true (the default), a space will be inserted after  all
          words  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



zsh 5.0.5          Last change: January 5, 2014                20






User Commands                                       ZSHCOMPSYS(1)



          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 expan-
          sion   of  a  substitution  of  the  form  `$(...)'  or
          `${...}'.

          The _prefix completer  uses  this  style  as  a  simple
          boolean  value  to decide if a space should be inserted
          before the suffix.

     ambiguous
          This applies when completing  non-final  components  of
          filename  paths,  in  other words those with a trailing
          slash.  If it is set, the  cursor  is  left  after  the
          first  ambiguous  component, even if menu completion is
          in use.  The style is always tested with the paths tag.

     assign-list
          When  completing  after  an  equals  sign that is being
          treated as an assignment, the  completion  system  nor-
          mally  completes  only one filename.  In some cases the
          value  may be a list of filenames separated by  colons,
          as with PATH and similar parameters.  This style can be
          set to a list of patterns matching the  names  of  such
          parameters.

          The  default  is to complete lists when the word on the
          line already contains a colon.

     auto-description
          If set, this style's value will be used as the descrip-
          tion  for options that are not described by the comple-
          tion 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.

     avoid-completer
          This is used by the _all_matches completer to decide if
          the string consisting of all matches should be added to
          the  list  currently  being  generated.  Its value is a
          list of names of 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.




zsh 5.0.5          Last change: January 5, 2014                21






User Commands                                       ZSHCOMPSYS(1)



     cache-path
          This  style defines the path where any cache files con-
          taining 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.

     cache-policy
          This  style  defines  the function that will be used to
          determine whether a cache needs  rebuilding.   See  the
          section on the _cache_invalid function below.

     call-command
          This style is used in the function for commands such as
          make and ant where calling the command directly to gen-
          erate  matches  suffers problems such as being slow or,
          as in the case of make can potentially cause actions in
          the makefile to be executed. If it is set to `true' the
          command is called  to  generate  matches.  The  default
          value of this style is `false'.

     command
          In  many  places,  completion  functions  need  to call
          external commands to generate the list of  completions.
          This  style can be used to override the command that is
          called in some such cases.  The elements of  the  value
          are  joined  with spaces to form a command line to exe-
          cute.  The value can also start with a hyphen, in which
          case  the  usual command will be added to the end; this
          is most useful for putting `builtin'  or  `command'  in
          front to make sure the appropriate version of a command
          is called, for example to avoid calling a  shell  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 generate  the
          IDs  to  complete  and the list of processes to display
          (if the verbose style is `true').  The list produced by
          the  command should look like the output of the ps com-
          mand.  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  com-
          plete.

          Note that the completion function generally has to call
          the specified command for each attempt to generate  the
          completion list.  Hence care should be taken to specify
          only commands that take a short time  to  run,  and  in
          particular to avoid any that may never terminate.




zsh 5.0.5          Last change: January 5, 2014                22






User Commands                                       ZSHCOMPSYS(1)



     command-path
          This is a list of directories to search for commands to
          complete.  The default for this style is the  value  of
          the special parameter path.

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

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

     complete-options
          This is used by the completer for cd, chdir and  pushd.
          For these commands a - is used to introduce a directory
          stack entry and completion of these is far more  common
          than  completing  options.   Hence  unless the value of
          this style is true options will not be completed,  even
          after  an  initial  -.   If it is true, options will be
          completed after an initial - unless there is a  preced-
          ing -- on the command line.

     completer
          The  strings  given  as the value of this style provide
          the names of the completer functions to use. The avail-
          able  completer  functions are described in the section
          `Control Functions' below.

          Each string may be either the name of a completer func-
          tion  or  a string of the form `function:name'.  In the
          first case the completer field of the context will con-
          tain  the  name  of  the  completer without the leading
          underscore and with all other underscores  replaced  by
          hyphens.   In  the second case the function is the name
          of the completer to call, but the context will  contain
          the  user-defined  name  in  the completer field of the
          context.  If the name starts with a hyphen, the  string
          for the context will be build from the name of the com-
          pleter function as in the  first  case  with  the  name
          appended to it.  For example:

               zstyle ':completion:*' completer _complete _complete:-foo





zsh 5.0.5          Last change: January 5, 2014                23






User Commands                                       ZSHCOMPSYS(1)



          Here,  completion  will  call  the  _complete completer
          twice, once  using  `complete'  and  once  using  `com-
          plete-foo' in the completer field of the context.  Nor-
          mally, using the same completer  more  than  once  only
          makes  sense  when used with the `functions:name' form,
          because otherwise the context name will be the same  in
          all calls to the completer; possible exceptions to this
          rule are the _ignored and _prefix completers.

          The  default  value  for  this  style   is   `_complete
          _ignored':  only  completion  will be done, first using
          the ignored-patterns style and the $fignore  array  and
          then without ignoring matches.

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

     delimiters
          This style is used when adding a delimiter for use with
          history modifiers or glob qualifiers that  have  delim-
          ited arguments.  It is an array of preferred delimiters
          to add.  Non-special characters are  preferred  as  the
          completion  system  may otherwise become confused.  The
          default list is :, +, /, -, %.  The list may  be  empty
          to force a delimiter to be typed.

     disabled
          If  this  is set to `true', the _expand_alias completer
          and  bindable  command  will  try  to  expand  disabled
          aliases, too.  The default is `false'.

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

     environ
          The  environ  style is used when completing for `sudo'.
          It is set to an array of `VAR=value' assignments to  be
          exported  into the local environment before the comple-
          tion for the target command is invoked.
          zstyle ':completion:*:sudo::' environ \
            PATH="/sbin:/usr/sbin:$PATH" HOME="/root"

     expand
          This style is used when completing  strings  consisting
          of multiple parts, such as path names.

          If  one  of its values is the string `prefix', the par-
          tially typed word from the line will be expanded as far



zsh 5.0.5          Last change: January 5, 2014                24






User Commands                                       ZSHCOMPSYS(1)



          as possible even if trailing parts cannot be completed.

          If one of its values is the string  `suffix',  matching
          names for components after the first ambiguous one will
          also be added.  This means that the resulting string is
          the longest unambiguous string possible.  However, menu
          completion can be used to cycle through all matches.

     fake This style may be set for any completion  context.   It
          specifies  additional  strings that will always be com-
          pleted 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 provided is shown
          alongside the value in completion listings.

          It is important to use a sufficiently restrictive  con-
          text  when  specifying  fake  strings.   Note  that the
          styles fake-files  and  fake-parameters  provide  addi-
          tional features when completing files or parameters.

     fake-always
          This  works  identically  to the fake style except that
          the ignored-patterns style is not applied to it.   This
          makes  it  possible  to  override a set of matches com-
          pletely by setting the ignored patterns to `*'.

          The following shows a way of supplementing any tag with
          arbitrary  data,  but having it behave for display pur-
          poses like a separate tag.  In this example we use  the
          features   of   the   tag-order  style  to  divide  the
          named-directories tag into two when performing  comple-
          tion with the standard completer complete for arguments
          of cd.  The  tag  named-directories-normal  behaves  as
          normal,  but  the tag named-directories-mine contains a
          fixed set of  directories.   This  has  the  effect  of
          adding  the  match  group  `extra directories' with the
          given completions.

               zstyle ':completion::complete:cd:*' tag-order \
                 'named-directories:-mine:extra\ directories
                 named-directories:-normal:named\ directories *'
               zstyle ':completion::complete:cd:*:named-directories-mine' \
                 fake-always mydir1 mydir2
               zstyle ':completion::complete:cd:*:named-directories-mine' \
                 ignored-patterns '*'

     fake-files
          This style is used when completing files and looked  up
          without   a   tag.    Its   values   are  of  the  form
          `dir:names...'.  This will add the names (strings sepa-
          rated by spaces) as possible matches when completing in



zsh 5.0.5          Last change: January 5, 2014                25






User Commands                                       ZSHCOMPSYS(1)



          the directory dir, even if no such files really  exist.
          The  dir may be a pattern; pattern characters or colons
          in dir should be quoted with a backslash to be  treated
          literally.

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

          The  pattern  form can be used to add a certain `magic'
          entry to all directories on a particular file system.

     fake-parameters
          This is used by the completion function  for  parameter
          names.   Its  values are names of parameters that might
          not yet be set but  should  be  completed  nonetheless.
          Each  name may also be followed by a colon and a string
          specifying the type of the  parameter  (like  `scalar',
          `array'  or `integer').  If the type is given, the name
          will only be completed if parameters of that  type  are
          required in the particular context.  Names for which no
          type is specified will always be completed.

     file-list
          This style controls whether files completed  using  the
          standard builtin mechanism are to be listed with a long
          list similar to ls -l.  Note that this feature uses the
          shell  module zsh/stat for file information; this loads
          the builtin stat which will replace any  external  stat
          executable.   To  avoid  this the following code can be
          included in an initialization file:

               zmodload -i zsh/stat
               disable stat

          The style may either be set to a true value (or `all'),
          or  one  of  the  values `insert' or `list', indicating
          that files are to be listed in long format in all  cir-
          cumstances,  or  when attempting to insert a file name,
          or when listing file names without attempting to insert
          one.

          More generally, the value may be an array of any of the
          above values, optionally followed by =num.  If  num  is
          present  it  gives  the  maximum  number of matches for
          which long listing style will be used.  For example,

               zstyle ':completion:*' file-list list=20 insert=10





zsh 5.0.5          Last change: January 5, 2014                26






User Commands                                       ZSHCOMPSYS(1)



          specifies that long format will be used when listing up
          to  20  files or inserting a file with up to 10 matches
          (assuming a listing is to be shown at all, for  example
          on  an ambiguous completion), else short format will be
          used.

               zstyle -e ':completion:*' file-list '(( ${+NUMERIC} )) && reply=(true)'

          specifies that long format will  be  used  any  time  a
          numeric argument is supplied, else short format.

     file-patterns
          This  is  used  by the standard function for completing
          filenames, _files.  If the style is unset up  to  three
          tags  are  offered,  `globbed-files',`directories'  and
          `all-files', depending on the types of files   expected
          by    the    caller   of   _files.    The   first   two
          (`globbed-files'  and   `directories')   are   normally
          offered together to make it easier to complete files in
          sub-directories.

          The file-patterns style provides  alternatives  to  the
          default  tags,  which are not used.  Its value consists
          of elements of the form `pattern:tag'; each string  may
          contain  any number of such specifications separated by
          spaces.

          The pattern is a pattern that is to be used to generate
          filenames.   Any  occurrence  of  the  sequence `%p' is
          replaced by any pattern(s) passed by the function call-
          ing  _files.  Colons in the pattern must be preceded by
          a backslash to make them distinguishable 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.

          The  tag  may  also  be  followed by an optional second
          colon and a description, which will  be  used  for  the
          `%d'  in the value of the format style (if that is set)
          instead of the default description supplied by the com-
          pletion  function.   If the description given here con-
          tains itself a `%d', that is replaced with the descrip-
          tion supplied by the completion function.

          For example, to make the rm command first complete only
          names of object files and then the names of  all  files



zsh 5.0.5          Last change: January 5, 2014                27






User Commands                                       ZSHCOMPSYS(1)



          if there is no matching object file:

               zstyle ':completion:*:*:rm:*' file-patterns \
                   '*.o:object-files' '%p:all-files'

          To  alter  the  default behaviour of file completion --
          offer files matching a pattern and directories  on  the
          first attempt, then all files -- to offer only matching
          files on  the  first  attempt,  then  directories,  and
          finally all files:

               zstyle ':completion:*' file-patterns \
                   '%p:globbed-files' '*(-/):directories' '*:all-files'

          This  works  even  where  there  is no special pattern:
          _files matches all files using the pattern `*'  at  the
          first  step  and stops when it sees this pattern.  Note
          also it will never try a pattern more than once  for  a
          single completion attempt.

          During  the  execution  of  completion  functions,  the
          EXTENDED_GLOB option is in effect,  so  the  characters
          `#', `~' and `^' have special meanings in the patterns.

     file-sort
          The standard filename  completion  function  uses  this
          style  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 values
          are: `size' to sort by the size of the file; `links' to
          sort by the number of links to the file; `modification'
          (or `time' or `date') to sort by the last  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  contains  the  string `reverse', sorting is
          done in the opposite order.  If the value contains  the
          string  `follow',  timestamps  are  associated with the
          targets of symbolic links; the default is  to  use  the
          timestamps of the links themselves.

     filter
          This is used by the LDAP plugin for e-mail address com-
          pletion to specify the attributes to match against when
          filtering entries.  So for example, if the style is set
          to `sn', matching is done against  surnames.   Standard
          LDAP filtering is used so normal completion matching is
          bypassed.  If this style is not set, the LDAP plugin is
          skipped.  You may also need to set the command style to
          specify how to connect to your LDAP server.




zsh 5.0.5          Last change: January 5, 2014                28






User Commands                                       ZSHCOMPSYS(1)



     force-list
          This forces a list of completions to be  shown  at  any
          point  where  listing  is done, even in cases where the
          list would usually be suppressed.   For  example,  nor-
          mally  the list is only shown if there are at least two
          different matches.  By setting this style to  `always',
          the  list will always be shown, even if there is only a
          single match that will immediately  be  accepted.   The
          style  may  also  be set to a number.  In this case the
          list will be shown if there  are  at  least  that  many
          matches, even if they would all insert the same string.

          This style is tested for the default tag as well as for
          each  tag  valid for the current completion.  Hence the
          listing can be forced only for certain types of  match.

     format
          If  this  is set for the descriptions tag, its value is
          used as a string to display above matches in completion
          lists.   The  sequence  `%d'  in  this  string  will be
          replaced with a short description of what these matches
          are.   This  string  may  also  contain  the  following
          sequences to specify output attributes, as described in
          the  section  EXPANSION  OF  PROMPT  SEQUENCES  in zsh-
          misc(1): `%B', `%S', `%U', `%F', `%K' and  their  lower
          case  counterparts,  as  well as `%{...%}'.  `%F', `%K'
          and `%{...%}' take arguments in the same form as prompt
          expansion.  Note that the %G sequence is not available;
          an argument to `%{' should be used instead.

          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 addi-
          tional `%'-sequences.  These are described for the com-
          pleter functions that make use of them.

          Some  completion functions display messages that may be
          customised by setting this style for the messages  tag.
          Here,  the `%d' is replaced with a message given by the
          completion function.

          Finally, the format string is looked up with the  warn-
          ings tag, for use when no matches could be generated at
          all.  In this  case  the  `%d'  is  replaced  with  the
          descriptions  for  the matches that were expected sepa-
          rated by spaces.  The sequence `%D'  is  replaced  with
          the same descriptions separated by newlines.





zsh 5.0.5          Last change: January 5, 2014                29






User Commands                                       ZSHCOMPSYS(1)



          It  is  possible to use printf-style field width speci-
          fiers 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.

     group-name
          The completion system  can  group  different  types  of
          matches,  which  appear  in separate lists.  This style
          can be used to give the names of groups for  particular
          tags.   For example, in command position the completion
          system generates names of  builtin  and  external  com-
          mands, names of aliases, shell functions and parameters
          and reserved words as possible  completions.   To  have
          the  external commands and shell functions listed sepa-
          rately:

               zstyle ':completion:*:*:-command-:*:commands' group-name commands
               zstyle ':completion:*:*:-command-:*:functions' group-name functions

          As a consequence, any match with the same tag  will  be
          displayed in the same group.

          If  the  name given is the empty string the name of the
          tag for the matches will be used as  the  name  of  the
          group.  So, to have all different types of matches dis-
          played separately, one can just set:

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

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

     group-order
          This  style  is  additional  to the group-name style to
          specify the order for display of the groups defined  by
          that  style  (compare tag-order, which determines which
          completions appear at all).  The groups named are shown
          in  the  given order; any other groups are shown in the
          order defined by the completion function.





zsh 5.0.5          Last change: January 5, 2014                30






User Commands                                       ZSHCOMPSYS(1)



          For example, to have names of builtin  commands,  shell
          functions  and  external  commands appear in that order
          when completing in command position:

               zstyle ':completion:*:*:-command-:*' group-order \
                      builtins functions commands

     groups
          A list of names of UNIX groups.  If this  is  not  set,
          group  names are taken from the YP database or the file
          `/etc/group'.

     hidden
          If this is set to true, matches for the  given  context
          will  not  be  listed, although any description for the
          matches set with the format style will be shown.  If it
          is  set to `all', not even the description will be dis-
          played.

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

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

     hosts-ports
          This  style  is  used  by  commands that need or accept
          hostnames and network ports.  The strings in the  value
          should  be  of  the  form `host:port'.  Valid ports are
          determined by the presence of hostnames; multiple ports
          for the same host may appear.

     ignore-line
          This  is tested for each tag valid for the current com-
          pletion.  If it is set to `true',  none  of  the  words
          that are already on the line will be considered as pos-
          sible completions.  If it is set to `current', the word
          the  cursor  is on will not be considered as a possible
          completion.  The value `current-shown' is  similar  but
          only  applies  if  the list of completions is currently
          shown on the screen.  Finally, if the style is  set  to
          `other',  all  words on the line except for the current
          one will be excluded from the possible completions.

          The values `current' and `current-shown' are a bit like
          the  opposite  of the accept-exact style:  only strings
          with missing characters will be completed.




zsh 5.0.5          Last change: January 5, 2014                31






User Commands                                       ZSHCOMPSYS(1)



          Note that you almost certainly don't want to  set  this
          to  `true'  or  `other'  for  a general context such as
          `:completion:*'.  This is  because  it  would  disallow
          completion of, for example, options multiple times even
          if the command in question accepts the option more than
          once.

     ignore-parents
          The  style is tested without a tag by the function com-
          pleting pathnames in  order  to  determine  whether  to
          ignore  the  names  of directories already mentioned in
          the current word, or the name of  the  current  working
          directory.   The  value must include one or both of the
          following strings:

          parent
               The name of any directory whose  path  is  already
               contained in the word on the line is ignored.  For
               example, when completing after foo/../, the direc-
               tory  foo  will  not be considered a valid comple-
               tion.

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

          In addition, the value may include one or both of:

          ..   Ignore  the  specified  directories  only when the
               word on the line contains the substring `../'.

          directory
               Ignore the specified directories only  when  names
               of  directories are completed, not when completing
               names of files.

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

     extra-verbose
          If set, the completion listing is more verbose  at  the
          cost  of a probable decrease in completion speed.  Com-
          pletion performance will suffer if this style is set to
          `true'.

     ignored-patterns
          A  list  of patterns; any trial completion matching one
          of the patterns will be  excluded  from  consideration.
          The  _ignored  completer can appear in the list of com-
          pleters to restore the ignored matches.  This is a more



zsh 5.0.5          Last change: January 5, 2014                32






User Commands                                       ZSHCOMPSYS(1)



          configurable version of the shell parameter $fignore.

          Note  that  the  EXTENDED_GLOB option is set during the
          execution of completion functions,  so  the  characters
          `#', `~' and `^' have special meanings in the patterns.

     insert
          This style is used by  the  _all_matches  completer  to
          decide whether to insert the list of all matches uncon-
          ditionally instead of adding the list as another match.

     insert-ids
          When  completing  process IDs, for example as arguments
          to the kill and wait builtins the name of a command may
          be  converted to the appropriate process ID.  A problem
          arises when the process name typed is not  unique.   By
          default  (or if this style is set explicitly to `menu')
          the name will be converted immediately to a set of pos-
          sible IDs, and menu completion will be started to cycle
          through them.

          If the value of the style is `single', the  shell  will
          wait  until  the user has typed enough to make the com-
          mand 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  comple-
          tion  will be started when the string typed by the user
          is longer than the common prefix to  the  corresponding
          IDs.

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

          The value may also contain the substrings `pending'  or
          `pending=val'.   In this case, the typed character will
          be inserted instead of starting completion  when  there
          is  unprocessed input pending.  If a val is given, com-
          pletion 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 parame-
          ter from the zsh/zle module being set properly which is
          not guaranteed on all platforms.

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



zsh 5.0.5          Last change: January 5, 2014                33






User Commands                                       ZSHCOMPSYS(1)



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

          In the case of the _match completer, the style may also
          be  set  to  the string `pattern'.  Then the pattern on
          the line is left unchanged if it does not  match  unam-
          biguously.

     keep-prefix
          This  style is used by the _expand completer.  If it is
          `true', the completer will try to keep  a  prefix  con-
          taining  a  tilde  or  parameter expansion.  Hence, for
          example, the string `~/f*' would be expanded to `~/foo'
          instead  of  `/home/user/foo'.   If the style is set to
          `changed' (the default), the prefix will only  be  left
          unchanged  if  there  were  other  changes  between the
          expanded words and the original word from  the  command
          line.  Any other value forces the prefix to be expanded
          unconditionally.

          The behaviour of expand when this style is true  is  to
          cause  _expand  to give up when a single expansion with
          the restored prefix is the same as the original;  hence
          any remaining completers may be called.

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

     known-hosts-files
          This style should contain a list of files to search for
          host  names  and  (if  the  use-ip  style  is  set)  IP
          addresses  in  a format compatible with ssh known_hosts
          files.    If    it    is    not    set,    the    files



zsh 5.0.5          Last change: January 5, 2014                34






User Commands                                       ZSHCOMPSYS(1)



          /etc/ssh/ssh_known_hosts   and  ~/.ssh/known_hosts  are
          used.

     list This style is used by the _history_complete_word  bind-
          able 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 particular AUTO_LIST.   The  con-
          text always starts with `:completion:history-words'.

     list-colors
          If the zsh/complist module is loaded, this style can be
          used  to  set  color  specifications.   This  mechanism
          replaces  the  use  of  the  ZLS_COLORS and ZLS_COLOURS
          parameters described in the 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)'  syn-
          tax  allowed  by the ZLS_COLORS and ZLS_COLOURS parame-
          ters and simply using the default tag.

          It is possible to use any color specifications  already
          set up for the GNU version of the ls command:

               zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS}

          The  default colors are the same as for the GNU ls com-
          mand and can be obtained by setting  the  style  to  an
          empty string (i.e. '').

     list-dirs-first
          This  is  used by file completion.  If set, directories
          to be completed are listed separately from  and  before
          completion for other files, regardless of tag ordering.
          In addition, the tag other-files is used  in  place  of
          all-files  for the remaining files, to indicate that no
          directories are presented with that tag.

     list-grouped
          If this style is `true' (the default),  the  completion
          system  will  try  to  make certain completion listings
          more compact by grouping matches.  For example, options
          for commands that have the same description (shown when



zsh 5.0.5          Last change: January 5, 2014                35






User Commands                                       ZSHCOMPSYS(1)



          the verbose style is set to `true') will  appear  as  a
          single  entry.   However, menu selection can be used to
          cycle through all the matches.

     list-packed
          This is tested for each tag valid in the  current  con-
          text  as  well  as  the  default  tag.  If it is set to
          `true', the corresponding matches appear in listings as
          if  the  LIST_PACKED  option were set.  If it is set to
          `false', they are listed normally.

     list-prompt
          If this style is set for the  default  tag,  completion
          lists that don't fit on the screen can be scrolled (see
          the description of the zsh/complist module  in  zshmod-
          ules(1)).   The value, if not the empty string, will be
          displayed after every  screenful  and  the  shell  will
          prompt  for  a  key  press;  if the style is set to the
          empty string, a default prompt will be used.

          The value may contain the  escape  sequences:  `%l'  or
          `%L',  which will be replaced by the number of the last
          line displayed and the total number of lines;  `%m'  or
          `%M', the number of the  last match shown and the total
          number of matches; and `%p' and `%P', `Top' when at the
          beginning of the list, `Bottom' when at the end and the
          position shown as a percentage of the total length oth-
          erwise.   In each case the form with the uppercase let-
          ter will be replaced by a string of fixed width, padded
          to  the   right  with  spaces, while the lowercase form
          will be replaced by a variable  width  string.   As  in
          other  prompt strings, the escape sequences `%S', `%s',
          `%B', `%b', `%U', `%u' for  entering  and  leaving  the
          display  modes  standout, bold and underline, and `%F',
          `%f', `%K', `%k' for changing the foreground background
          colour,  are  also  available, as is the form `%{...%}'
          for enclosing escape sequences which display with  zero
          (or, with a numeric argument, some other) width.

          After  deleting  this  prompt  the  variable LISTPROMPT
          should be unset for the removal to take effect.

     list-rows-first
          This style is tested in the same way as the list-packed
          style  and  determines whether matches are to be listed
          in a  rows-first  fashion  as  if  the  LIST_ROWS_FIRST
          option were set.

     list-suffixes
          This style is used by the function that completes file-
          names.  If it is true, and completion is attempted on a
          string  containing  multiple  partially  typed pathname



zsh 5.0.5          Last change: January 5, 2014                36






User Commands                                       ZSHCOMPSYS(1)



          components, all ambiguous  components  will  be  shown.
          Otherwise, completion stops at the first ambiguous com-
          ponent.

     list-separator
          The value of this style is used in  completion  listing
          to  separate  the string to complete from a description
          when  possible  (e.g.  when  completing  options).   It
          defaults to `--' (two hyphens).

     local
          This  is  for use with functions that complete URLs for
          which the corresponding files  are  available  directly
          from  the  file  system.   Its  value should consist of
          three strings: a hostname, the path to the default  web
          pages  for the server, and the directory name used by a
          user placing web pages within their home area.

          For example:

               zstyle ':completion:*' local toast \
                   /var/http/public/toast public_html

          Completion after `http://toast/stuff/'  will  look  for
          files  in  the  directory /var/http/public/toast/stuff,
          while  completion  after  `http://toast/~yousir/'  will
          look for files in the directory ~yousir/public_html.

     mail-directory
          If set, zsh will assume that mailbox files can be found
          in the directory specified.  It defaults to `~/Mail'.

     match-original
          This is used by the _match completer.  If it is set  to
          only,  _match  will  try  to  generate  matches without
          inserting a `*' at the cursor position.  If set to  any
          other  non-empty  value,  it will first try to generate
          matches without inserting the `*' and if that yields no
          matches,  it  will try again with the `*' inserted.  If
          it is unset or set to the empty string,  matching  will
          only be performed with the `*' inserted.

     matcher
          This  style  is tested separately for each tag valid in
          the 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 `Comple-
          tion Matching Control' in zshcompwid(1).

     matcher-list
          This style can be set to a list of match specifications
          that are to be applied everywhere. Match specifications



zsh 5.0.5          Last change: January 5, 2014                37






User Commands                                       ZSHCOMPSYS(1)



          are  described in the section `Completion Matching Con-
          trol' in zshcompwid(1).  The completion system will try
          them  one  after  another  for each completer selected.
          For example, to try first  simple  completion  and,  if
          that generates no matches, case-insensitive completion:

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

          By default each  specification  replaces  the  previous
          one; however, if a specification is prefixed with +, it
          is added to the existing list.  Hence it is possible to
          create increasingly general specifications without rep-
          etition:

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

          It is possible to create match specifications valid for
          particular  completers  by using the third field of the
          context.  For example, to use the completers  _complete
          and  _prefix but only allow case-insensitive completion
          with _complete:

               zstyle ':completion:*' completer _complete _prefix
               zstyle ':completion:*:complete:*' matcher-list \
                      '' 'm:{a-zA-Z}={A-Za-z}'

          User-defined names,  as  explained  for  the  completer
          style,  are  available.   This makes it possible to try
          the same completer more than once with different  match
          specifications  each  time.  For example, to try normal
          completion without a match specification,  then  normal
          completion with case-insensitive matching, then correc-
          tion, and finally partial-word completion:

               zstyle ':completion:*' completer _complete _correct _complete:foo
               zstyle ':completion:*:complete:*' matcher-list \
                   '' 'm:{a-zA-Z}={A-Za-z}'
               zstyle ':completion:*:foo:*' matcher-list \
                   'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*'

          If the style is unset in any context no match  specifi-
          cation is applied.  Note also that some completers such
          as _correct and _approximate do not use the match spec-
          ifications  at  all,  though these completers will only
          ever be called once even if the  matcher-list  contains
          more than one element.

          Where multiple specifications are useful, note that the
          entire  completion  is  done  for   each   element   of
          matcher-list, which can quickly reduce the shell's per-
          formance.  As a rough  rule  of  thumb,  one  to  three
          strings will give acceptable performance.  On the other



zsh 5.0.5          Last change: January 5, 2014                38






User Commands                                       ZSHCOMPSYS(1)



          hand, putting multiple space-separated values into  the
          same string does not have an appreciable impact on per-
          formance.

          If there is no current matcher or it is empty, and  the
          option  NO_CASE_GLOB  is  in  effect,  the matching for
          files is  performed  case-insensitively  in  any  case.
          However,    any   matcher   must   explicitly   specify
          case-insensitive matching if that is required.

     max-errors
          This is used by the _approximate and _correct completer
          functions  to determine the maximum number of errors to
          allow.  The completer will try to generate  completions
          by  first  allowing  one error, then two errors, and so
          on, until either a match or matches were found  or  the
          maximum  number  of errors given by this style has been
          reached.

          If  the  value  for  this  style  contains  the  string
          `numeric', the completer function will take any numeric
          argument as the maximum number of errors  allowed.  For
          example, with

               zstyle ':completion:*:approximate:::' max-errors 2 numeric

          two errors are allowed if no numeric argument is given,
          but with a numeric argument of six (as in `ESC-6 TAB'),
          up  to  six errors are accepted.  Hence with a value of
          `0 numeric', no correcting completion will be attempted
          unless a numeric argument is given.

          If  the  value  contains  the string `not-numeric', the
          completer will not try to  generate  corrected  comple-
          tions  when  given  a numeric argument, so in this case
          the number given should  be  greater  than  zero.   For
          example, `2 not-numeric' specifies that correcting com-
          pletion with two errors will usually be performed,  but
          if  a  numeric argument is given, correcting completion
          will not be performed.

          The default value for this style is `2 numeric'.

     max-matches-width
          This style is used to determine the trade  off  between
          the width of the display used for matches and the width
          used for their descriptions when the verbose  style  is
          in  effect.  The value gives the number of display col-
          umns to reserve for the matches.  The default  is  half
          the width of the screen.





zsh 5.0.5          Last change: January 5, 2014                39






User Commands                                       ZSHCOMPSYS(1)



          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 prece-
          dence over that for the `default' tag.

          If none of the values found in this way is true but  at
          least one is set to `auto', the shell behaves as if the
          AUTO_MENU option is set.

          If one of the values is explicitly set to  false,  menu
          completion  will  be  explicitly turned off, overriding
          the MENU_COMPLETE option and other settings.

          In the form `yes=num', where `yes' may be  any  of  the
          true values (`yes', `true', `on' and `1'), menu comple-
          tion will be turned  on  if  there  are  at  least  num
          matches.   In the form `yes=long', menu completion will
          be turned on if the list does not fit  on  the  screen.
          This  does  not  activate menu completion if the widget
          normally only lists completions,  but  menu  completion
          can   be   activated   in  that  case  with  the  value
          `yes=long-list'       (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  selection,
          as implemented by the zsh/complist module.  The follow-
          ing values may appear either alongside  or  instead  of
          the values above.

          If  the value contains the string `select', menu selec-
          tion will be started unconditionally.

          In the form `select=num', menu selection will  only  be
          started if there are at least num matches.  If the val-
          ues for more than one tag provide a number, the  small-
          est number is taken.

          Menu selection can be turned off explicitly by defining
          a value containing the string`no-select'.





zsh 5.0.5          Last change: January 5, 2014                40






User Commands                                       ZSHCOMPSYS(1)



          It is also possible to start menu selection only if the
          list of matches does not fit on the screen by using the
          value `select=long'.  To start menu selection  even  if
          the current widget only performs listing, use the value
          `select=long-list'.

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

          Finally, it is possible to activate two  special  modes
          of menu selection.  The word `interactive' in the value
          causes interactive mode to be entered immediately  when
          menu  selection  is started; see the description of the
          zsh/complist module in zshmodules(1) for a  description
          of  interactive  mode.   Including  the string `search'
          does the same for incremental search mode.   To  select
          backward   incremental   search,   include  the  string
          `search-backward'.

     muttrc
          If set, gives the location of  the  mutt  configuration
          file.  It defaults to `~/.muttrc'.

     numbers
          This  is  used with the jobs tag.  If it is `true', the
          shell will complete job numbers instead of the shortest
          unambiguous  prefix  of  the  job command text.  If the
          value is a number, job numbers will  only  be  used  if
          that  many words from the job descriptions are required
          to resolve ambiguities.  For example, if the  value  is
          `1',  strings  will  only be used if all jobs differ in
          the first word on their command lines.

     old-list
          This is used by the _oldlist completer.  If it  is  set
          to  `always', then standard widgets which perform list-
          ing will retain the current list  of  matches,  however
          they  were generated; this can be turned off explicitly
          with the value `never', giving  the  behaviour  without
          the  _oldlist completer.  If the style is unset, or any
          other value, then the existing list of  completions  is
          displayed if it is not already; otherwise, the standard
          completion list is generated; this is the  default  be-
          haviour  of _oldlist.  However, if there is an old list
          and this style contains the name of the completer func-
          tion that generated the list, then the old list will be
          used even if it was generated by a  widget  which  does
          not do listing.




zsh 5.0.5          Last change: January 5, 2014                41






User Commands                                       ZSHCOMPSYS(1)



          For  example,  suppose  you  type  ^Xc to use the _cor-
          rect_word widget, which generates a list of corrections
          for  the  word  under  the  cursor.  Usually, typing ^D
          would generate a standard list of completions  for  the
          word   on  the  command  line,  and  show  that.   With
          _oldlist, it will instead show the list of  corrections
          already generated.

          As  another example consider the _match completer: with
          the insert-unambiguous style set to `true'  it  inserts
          only a common prefix string, if there is any.  However,
          this may remove parts of the original pattern, so  that
          further  completion  could produce more matches than on
          the first attempt.  By using the _oldlist completer and
          setting  this style to _match, the list of matches gen-
          erated on the first attempt will be used again.

     old-matches
          This is used by the _all_matches completer to decide if
          an  old  list  of matches should be used if one exists.
          This is selected by one of the `true' values or by  the
          string  `only'.   If  the value is `only', _all_matches
          will only use an old list and won't have any effect  on
          the list of matches currently being generated.

          If this style is set it is generally unwise to call the
          _all_matches completer unconditionally.   One  possible
          use  is for either this style or the completer style to
          be defined with the -e option to  zstyle  to  make  the
          style conditional.

     old-menu
          This  is  used  by the _oldlist completer.  It controls
          how menu  completion  behaves  when  a  completion  has
          already  been  inserted  and  the user types a standard
          completion key such as TAB.  The default  behaviour  of
          _oldlist  is that menu completion always continues with
          the existing list of completions.  If this style is set
          to `false', however, a new completion is started if the
          old list was generated by a different  completion  com-
          mand;  this  is the behaviour without the _oldlist com-
          pleter.

          For example, suppose you type ^Xc to generate a list of
          corrections,  and  menu completion is started in one of
          the usual ways.  Usually, or with  this  style  set  to
          false,  typing  TAB at this point would start trying to
          complete the line as it now appears.  With _oldlist, it
          instead  continues to cycle through the list of correc-
          tions.

     original



zsh 5.0.5          Last change: January 5, 2014                42






User Commands                                       ZSHCOMPSYS(1)



          This is used by  the  _approximate  and  _correct  com-
          pleters  to  decide  if  the  original string should be
          added as a possible completion.  Normally, this is done
          only  if  there  are at least two possible corrections,
          but if this style is set to `true', it is always added.
          Note that the style will be examined with the completer
          field in the context name set to correct-num or approx-
          imate-num,  where num is the number of errors that were
          accepted.

     packageset
          This style is used when  completing  arguments  of  the
          Debian `dpkg' program.  It contains an override for the
          default package set for a given context.  For example,

               zstyle ':completion:*:complete:dpkg:option--status-1:*' \
                              packageset avail

          causes available packages, rather than  only  installed
          packages, to be completed for `dpkg --status'.

     path The function that completes color names uses this style
          with the colors tag.  The value should be the  pathname
          of  a  file  containing color names in the format of an
          X11 rgb.txt file.  If the style is  not  set  but  this
          file  is  found in one of various standard locations it
          will be used as the default.

     path-completion
          This is used by filename completion.  By default, file-
          name  completion  examines  all components of a path to
          see if there are completions of  that  component.   For
          example,  /u/b/z  can  be  completed  to  /usr/bin/zsh.
          Explicitly setting this style to  false  inhibits  this
          behaviour  for  path  components up to the / before the
          cursor;    this    overrides     the     setting     of
          accept-exact-dirs.

          Even  with the style set to false, it is still possible
          to complete multiple paths by setting the  option  COM-
          PLETE_IN_WORD  and  moving the cursor back to the first
          component in the path to be  completed.   For  example,
          /u/b/z  can  be completed to /usr/bin/zsh if the cursor
          is after the /u.

     pine-directory
          If set, specifies the directory containing PINE mailbox
          files.   There is no default, since recursively search-
          ing this  directory  is  inconvenient  for  anyone  who
          doesn't use PINE.

     ports



zsh 5.0.5          Last change: January 5, 2014                43






User Commands                                       ZSHCOMPSYS(1)



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

     prefix-hidden
          This is used for certain completions which share a com-
          mon prefix, for example command options beginning  with
          dashes.   If it is `true', the prefix will not be shown
          in the list of matches.

          The default value for this style is `false'.

     prefix-needed
          This style is also relevant for matches with  a  common
          prefix.  If it is set to `true' this common prefix must
          be typed by the user to generate the matches.

          The style is applicable to the options, signals,  jobs,
          functions, and parameters completion tags.

          For  command  options, this means that the initial `-',
          `+', or `--' must be  typed  explicitly  before  option
          names will be completed.

          For  signals,  an initial `-' is required before signal
          names will be completed.

          For jobs, an initial `%' is required before  job  names
          will be completed.

          For function and parameter names, an initial `_' or `.'
          is required before function or parameter names starting
          with those characters will be completed.

          The  default  value for this style is `false' for func-
          tion and parameter completions, and  `true'  otherwise.

     preserve-prefix
          This  style  is  used  when completing path names.  Its
          value should be a pattern matching an initial prefix of
          the  word  to  complete  that  should be left unchanged
          under all circumstances.  For example, on  some  Unices
          an  initial  `//' (double slash) has a special meaning;
          setting this style to the string `//' will preserve it.
          As  another  example, setting this style to `?:/' under
          Cygwin would allow completion after `a:/...' and so on.

     range
          This  is  used  by the _history completer and the _his-
          tory_complete_word bindable  command  to  decide  which
          words should be completed.




zsh 5.0.5          Last change: January 5, 2014                44






User Commands                                       ZSHCOMPSYS(1)



          If it is a singe number, only the last N words from the
          history will be completed.

          If it is a range of  the  form  `max:slice',  the  last
          slice  words  will be completed; then if that yields no
          matches, the slice words before those will be tried and
          so  on.   This  process  stops either when at least one
          match was been found, or max words have been tried.

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

     recursive-files
          If this style is set, its value is an array of patterns
          to be tested against `$PWD/': note the trailing  slash,
          which allows directories in the pattern to be delimited
          unambiguously by including slashes on both  sides.   If
          an  ordinary  file completion fails and the word on the
          command line does not yet have a directory part to  its
          name,  the style is retrieved using the same tag as for
          the completion just attempted, then the elements tested
          against  $PWD/ in turn.  If one matches, then the shell
          reattempts completion by prepending  the  word  on  the
          command  line  with  each directory in the expansion of
          **/*(/) in turn.  Typically the elements of  the  style
          will  be  set  to  restrict  the  number of directories
          beneath the current one to  a  manageable  number,  for
          example `*/.git/*'.

          For example,

               zstyle ':completion:*' recursive-files '*/zsh/*'

          If  the  current  directory  is /home/pws/zsh/Src, then
          zle_trTAB can be completed to Zle/zle_tricky.c.

     regular
          This style is used by the _expand_alias  completer  and
          bindable command.  If set to `true' (the default), reg-
          ular aliases will be expanded but only in command posi-
          tion.   If  it  is set to `false', regular aliases will
          never be expanded.   If it is set to `always',  regular
          aliases  will  be expanded even if not in command posi-
          tion.

     rehash
          If this is set when completing external  commands,  the
          internal  list  (hash)  of commands will be updated for
          each search by issuing the rehash command.  There is  a
          speed  penalty  for  this  which  is  only likely to be
          noticeable when directories in the path have slow  file
          access.



zsh 5.0.5          Last change: January 5, 2014                45






User Commands                                       ZSHCOMPSYS(1)



     remote-access
          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 connections are in
          fact  to a remote site, so some may be prevented unnec-
          essarily.

     remove-all-dups
          The _history_complete_word  bindable  command  and  the
          _history  completer use this to decide if all duplicate
          matches should be removed, rather than just consecutive
          duplicates.

     select-prompt
          If  this  is set for the default tag, its value will be
          displayed during menu selection  (see  the  menu  style
          above)  when  the  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 num-
          bers refer to the match or line  the  mark  is  on.   A
          default  prompt  is  used  when  the value is the empty
          string.

     select-scroll
          This style is tested for the default tag and determines
          how  a completion list is scrolled during a menu selec-
          tion (see the menu style  above)  when  the  completion
          list  does  not  fit  on the screen as a whole.  If the
          value  is  `0'  (zero),  the  list   is   scrolled   by
          half-screenfuls;  if it is a positive integer, the list
          is scrolled by the given number of lines; if  it  is  a
          negative  number,  the  list is scrolled by a screenful
          minus the absolute value of the given number of  lines.
          The default is to scroll by single lines.

     separate-sections
          This style is used with the manuals tag when completing
          names of manual pages.  If it is  `true',  entries  for
          different sections are added separately using tag names
          of the form `manual.X', where X is the section  number.
          When the group-name style is also in effect, pages from
          different sections will appear separately.  This  style
          is  also  used similarly with the words style when com-
          pleting words for the dict  command.  It  allows  words
          from  different  dictionary databases to be added sepa-
          rately.  The default for this style is `false'.

     show-completer
          Tested whenever a new completer is  tried.   If  it  is



zsh 5.0.5          Last change: January 5, 2014                46






User Commands                                       ZSHCOMPSYS(1)



          true,  the completion system outputs a progress message
          in the listing area showing  what  completer  is  being
          tried.   The  message will be overwritten by any output
          when completions are found and is removed after comple-
          tion is finished.

     single-ignored
          This  is  used  by the _ignored completer when there is
          only one match.  If its value  is  `show',  the  single
          match will be displayed but not inserted.  If the value
          is `menu', then  the  single  match  and  the  original
          string are both added as matches and menu completion is
          started, making it easy to select either of them.

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

          The style is tested  first  against  the  full  context
          including the tag, and if that fails to produce a value
          against the context without the tag.

          If the  calling  widget  explicitly  requests  unsorted
          matches,   this  is  usually  honoured.   However,  the
          default (unsorted) behaviour of completion for the com-
          mand  history may be overridden by setting the style to
          true.

          In the _expand completer, if it is set to  `true',  the
          expansions  generated  will always be sorted.  If it is
          set to `menu', then the expansions are only sorted when
          they  are  offered  as  single  strings  but not in the
          string containing all possible expansions.

     special-dirs
          Normally, the completion  code  will  not  produce  the
          directory  names  `.' and `..' as possible completions.
          If this style is set to `true', it will  add  both  `.'
          and `..' as possible 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 con-
          sists only of a path beginning with  `../'.   Otherwise
          the value is `false'.

               zstyle -e ':completion:*' special-dirs \
                  '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'



zsh 5.0.5          Last change: January 5, 2014                47






User Commands                                       ZSHCOMPSYS(1)



     squeeze-slashes
          If  set  to  `true',  sequences  of slashes in filename
          paths (for example in `foo//bar') will be treated as  a
          single  slash.   This  is  the  usual behaviour of UNIX
          paths.  However, by default the file  completion  func-
          tion  behaves  as  if  there  were  a  `*'  between the
          slashes.

     stop If set to `true', the  _history_complete_word  bindable
          command  will  stop once when reaching the beginning or
          end of the  history.   Invoking  _history_complete_word
          will  then  wrap around to the opposite end of the his-
          tory.  If this style is set to `false'  (the  default),
          _history_complete_word  will  loop  immediately as in a
          menu completion.

     strip-comments
          If set to `true', this style causes non-essential  com-
          ment  text to be removed from completion matches.  Cur-
          rently it is only used when completing e-mail addresses
          where  it  removes any display name from the addresses,
          cutting them down to plain user@host form.

     subst-globs-only
          This is used by the _expand completer.  If it is set to
          `true',  the expansion will only be used if it resulted
          from globbing; hence, if expansions resulted  from  the
          use  of the substitute style described below, but these
          were not further changed by  globbing,  the  expansions
          will be rejected.

          The default for this style is `false'.

     substitute
          This  boolean  style  controls whether the _expand com-
          pleter will first try to expand  all  substitutions  in
          the string (such as `$(...)' and `${...}').

          The default is `true'.

     suffix
          This  is  used  by  the  _expand  completer if the word
          starts with a tilde or contains a parameter  expansion.
          If  it is set to `true', the word will only be expanded
          if it doesn't have a suffix, i.e. if  it  is  something
          like   `~foo'   or   `$foo'   rather  than  `~foo/'  or
          `$foo/bar', unless that suffix itself contains  charac-
          ters  eligible  for  expansion.   The  default for this
          style is `true'.

     tag-order
          This provides a mechanism  for  sorting  how  the  tags



zsh 5.0.5          Last change: January 5, 2014                48






User Commands                                       ZSHCOMPSYS(1)



          available in a particular context will be used.

          The  values  for  the style are sets of space-separated
          lists of tags.  The tags in each value will be tried at
          the  same time; if no match is found, the next value is
          used.  (See the file-patterns style for an exception to
          this behavior.)

          For example:

               zstyle ':completion:*:complete:-command-:*' tag-order \
                   'commands functions'

          specifies  that  completion  in  comm