zshmisc - everything and then some


SIMPLE COMMANDS & PIPELINES

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

              echo foo

       is a simple command with arguments.

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

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

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

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

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


       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 value.  If it  does  not,  the
       value  of the sublist is that return value, else it is the
       value returned by the print (almost certainly zero).

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

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


PRECOMMAND MODIFIERS

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

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

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

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

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

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

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


COMPLEX COMMANDS

       A complex command in zsh is one of the following:

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

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

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

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

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

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

       case word in [ [(] pattern [ | pattern ] ... ) list
              (;;|;&) ] ... esac
              Execute the list associated with the first  pattern
              that  matches  word,  if any.  The form of the pat­
              terns is the same as that used for filename genera­
              tion.   See  the section `Filename Generation'.  If
              the list that is executed  is  terminated  with  ;&
              rather  than  ;;,  the  following list is also exe­
              cuted.  This  continues  until  either  a  list  is


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

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

       { list }
              Execute list.

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

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

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

       [[ exp ]]
              Evaluates the conditional expression exp and return
              a zero exit status if it is true.  See the  section



ALTERNATE FORMS FOR COMPLEX COMMANDS

       Many of  zsh's  complex  commands  have  alternate  forms.
       These  particular  versions  of complex commands should be
       considered deprecated and may be removed  in  the  future.
       The  versions  in the previous section should be preferred
       instead.  The short versions below only work if sublist is
       of  the  form  `{  list }' or if the SHORT_LOOPS option is
       set.  In this case, 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.

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

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

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

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

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

       while list { list }
              An alternative form of while.

       until list { list }
              An alternative form of until.

       repeat word sublist
              This is a short form of repeat.

              (;;|;&) ] ... }
              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  the
       IGNORE_BRACES option is not set.


COMMENTS

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


ALIASING

       Every  token in the shell input is checked to see if there
       is an alias defined for it.  If so, it is replaced by  the
       text  of  the  alias  if  it is in command position (if it
       could be the first word of a simple 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.   But
       there  is  nothing  to  prevent an alias being defined for
       \foo as well.


QUOTING

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

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


       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 execution of a command contains the  file  descriptors
       of the invoking shell as modified by input/output specifi­
       cations.

       The following may appear anywhere in a simple  command  or
       may precede or follow a complex command.  Expansion occurs
       before word or digit is used except as  noted  below.   If
       the  result of substitution on word produces more than one
       filename, redirection occurs for each separate filename in
       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  cre­
              ated.

       > 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 stan­
              dard output.  If the file does not exist,  and  the
              CLOBBER  option  is  unset,  this  causes an error;


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

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

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

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

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

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

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

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

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

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

              ... 1>fname 2>&1

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


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  speci­
       fied  outputs, similar to tee, provided the MULTIOS option
       is set, as it is by default.  Thus:

              date >foo >bar

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

              date >foo | cat

       writes  the  date  to the file `foo', and also pipes it to
       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

              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,  pro­
       vided the MULTIOS option is set.  Thus

              sort <foo <fubar

       or even

              sort <f{oo,ubar}

       is equivalent to `cat foo fubar | sort'.

       Note that a pipe is an implicit redirection; thus

              cat bar | sort <foo

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

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

              echo foo > bar > baz

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


REDIRECTIONS WITH NO COMMAND

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

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

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

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

              < file

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


COMMAND EXECUTION

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

       Otherwise,  the shell searches each element of $path for a
       directory containing an executable file by that name.   If
       the search is unsuccessful, the shell prints an error mes­
       sage and returns a nonzero exit status.

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


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  exe­
       cuted  like  commands  with  the arguments passed as posi­
       tional parameters.  (See the section `Command Execution'.)

       Functions  execute  in  the same process as the caller and
       share all files and present  working  directory  with  the
       caller.   A trap on EXIT set inside a function is executed
       after the function completes in  the  environment  of  the
       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.

       A function can be marked as undefined using  the  autoload
       builtin  (or  `functions  -u'  or  `typeset -fu').  Such a
       function has no body.  When the  function  is  first  exe­
       cuted,  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 sup­
       pressed if the autoload builtin or its equivalent is given
       the  option  -U.  This is recommended for the use of func­
       tions supplied with the zsh distribution.  Note  that  for
       functions  precompiled  with  the zcompile builtin command
       the flag -U must be provided when the .zwc  file  is  cre­
       ated,  as  the  corresponding information is compiled into
       the latter.

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

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

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

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

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

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

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

       Otherwise,  the  function body (with no surrounding `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 func­
       tion definition (which will  be  retained  for  subsequent
       calls  to the function), and a call to the shell function,
       including any arguments, at the end.

       For example, suppose the autoload file func contains

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

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

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

              myfunc() {
                autoload -X
              }


       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.   A true
       autoloaded function can be identified by the  presence  of
       the  comment  `#  undefined' in the body, because all com­
       ments are discarded from defined functions.  This is  done
       so that

              eval "$(functions)"

       produces a reasonable result.

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

              autoload +X myfunc


SPECIAL FUNCTIONS

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

       chpwd  Executed  whenever the current working directory is
              changed.

       periodic
              If the parameter PERIOD is set,  this  function  is
              executed  every  $PERIOD  seconds,  just  before  a
              prompt.

       precmd Executed before each prompt.

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

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

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

       TRAPDEBUG
              Executed after each command.

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

       TRAPZERR
              Executed whenever a command  has  a  non-zero  exit
              status.   However,  the function is not executed if
              the command occurred in a sublist followed by  `&&'
              or  `||';  only  the  final command in a sublist of
              this type causes the trap to be executed.

       The  functions  beginning  `TRAP'  may  alternatively   be
       defined with the trap builtin:  this may be preferable for
       some uses, as they are then run in the environment of  the
       calling  process,  rather than in their own function envi­
       ronment.  Apart from the difference in  calling  procedure
       and  the  fact  that the function form appears in lists of
       functions, the forms

              TRAPNAL() {
               # code
              }

       and

              trap '
               # code

       are equivalent.


JOBS

       If the MONITOR option is set, an interactive shell associ­
       ates  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 asyn­
       chronously with `&', the shell prints a line  which  looks
       like:

              [1] 1234

       was job number 1 and had one  (top-level)  process,  whose
       process ID was 1234.

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

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

       A job being run in the background will suspend if it tries
       to read from the terminal.  Background jobs  are  normally
       allowed  to  produce  output,  but this can be disabled by
       giving the command `stty tostop'.  If  you  set  this  tty
       option, then background jobs will suspend when they try to
       produce output like they do when they try to read input.

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

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

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

       The shell learns immediately whenever  a  process  changes
       state.   It  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.

       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
       (running) 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 sus­
       pended jobs will be terminated, and the running jobs  will
       be sent a SIGHUP signal, if the HUP option is set.

       To  avoid  having  the  shell  terminate the running jobs,
       either use the nohup command (see nohup(1)) or the  disown
       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.  Otherwise, signals have the values
       inherited by the shell from its parent (but see the  TRAP­
       NAL special functions in the section `Functions').


ARITHMETIC EVALUATION

       The  shell  can  perform integer and floating point arith­
       metic, either using the builtin let, or via a substitution
       of  the form $((...)).  For integers, the shell is usually
       compiled to use 8-byte precision where this is  available,
       otherwise  precision  is 4 bytes.  This can be tested, for
       example, by giving the command `print  -  $((  12345678901
       ))';  if the number appears unchanged, the precision is at
       least 8 bytes.  Floating point arithmetic is always double
       precision.

       The  let  builtin  command takes arithmetic expressions as
       arguments; each is evaluated separately.   Since  many  of
       the arithmetic operators, as well as spaces, require quot­
       ing, an alternative form  is  provided:  for  any  command
       which  begins  with  a  `((',  all  the characters until a
       matching `))' are  treated  as  a  quoted  expression  and
       arithmetic  expansion performed as for an argument of let.
       More precisely, `((...))' is equivalent  to  `let  "..."'.
       For example, the following statement

              (( val = 2 + 1 ))

       is equivalent to

              let "val = 2 + 1"

       both  assigning  the value 3 to the shell variable foo 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

       and thirty-six representing the arithmetic base and n is a
       number in that base (for example, `16#ff' is 255  in  hex­
       adecimal).   The  base# may also be omitted, in which case
       base 10 is used.  For  backwards  compatibility  the  form
       `[base]n' is also accepted.

       It  is also possible to specify a base to be used for out­
       put 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 integer variable is implicitly defined by an  arith­
       metic  expression,  any base specified in this way will be
       set as the variable's output arithmetic  base  as  if  the
       option  `-i  base'  to  the typeset builtin had been used.
       The expression has no precedence and  if  it  occurs  more
       than  once  in a mathematical expression, the last encoun­
       tered is used.  For clarity  it  is  recommended  that  it
       appear at the beginning of an expression.  As an example:

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

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

       When an output base is specified using the `[#base]'  syn­
       tax,  an  appropriate base prefix will be output if neces­
       sary, so that the value output is valid syntax for  input.
       If  the  #  is doubled, for example `[##16]', then no base
       prefix is output.

       Floating point constants are recognized by the presence of
       a  decimal point or an exponent.  The decimal point may be
       the first character of  the  constant,  but  the  exponent
       character e or E may not, as it will be taken for a param­
       eter name.

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

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

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

       The operators `&&', `||', `&&=', and `||=' are  short-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.

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

       An  expression  of the form `##x' where x is any character
       sequence such as `a', `^A', or `\M-\C-x' gives  the  ASCII
       value  of  this  character  and  an expression of the form
       `#foo' gives the ASCII value of the first character of the
       value  of  the parameter foo.  Note that this is different
       from the expression `$#foo', a standard parameter  substi­
       tution  which gives the length of the parameter foo.  `#\'
       is accepted instead of `##', but its use is deprecated.

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

              ((val2 = val1 * 2))

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

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

       Likewise, floating point numbers can be declared with  the

       their output format, as described for the typeset builtin.
       The output format can be bypassed by using arithmetic sub­
       stitution instead  of  the  parameter  substitution,  i.e.
       `${float}'  uses the defined format, but `$((float))' uses
       a generic floating point format.

       Promotion of integer to floating point values is performed
       where  necessary.   In  addition,  if  any  operator which
       requires an integer (`~', `&', `|', `^', `%',  `<<',  `>>'
       and their equivalents with assignment) is given a floating
       point argument, it will be silently rounded  down  to  the
       next integer.

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

       If a variable is first assigned in a numeric context with­
       out previously being declared, it will be implicitly typed
       as  integer or float and retain that type either until the
       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 conse­
       quently 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.

              true if file exists and is a directory.

       -e file
              true if file exists.

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

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

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

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

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

       -o option
              true if option named option is on.  option may be a
              single character, in which case it is a single let­
              ter option  name.   (See  the  section  `Specifying
              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 pro­
              cess.

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

       -t fd  true if file descriptor number fd is open and asso­
              ciated  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 pro­
              cess.

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

              true if length of string is zero.

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

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

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

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

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

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

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

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

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

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

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

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

       exp1 -eq exp2
              true if exp1 is numerically equal to exp2.

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

              true if exp1 is numerically less than exp2.

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

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

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

       ( exp )
              true if exp is true.

       ! exp  true if exp is false.

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

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

       Normal shell expansion is performed on  the  file,  string
       and pattern arguments, but the result of each expansion is
       constrained to be a single word, similar to the effect  of
       double quotes.  However, pattern metacharacters are active
       for the pattern arguments; the patterns are  the  same  as
       those  used  for  filename generation, see zshexpn(1), but
       there is no special behaviour of `/' nor initial dots, and
       no glob qualifiers are allowed.

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

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

       For example, the following:

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

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


PROMPT EXPANSION

       Prompt sequences undergo  a  special  form  of  expansion.

       option to the print builtin.

       If the PROMPT_SUBST option is set, the  prompt  string  is
       first  subjected to parameter expansion, command substitu­
       tion 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.  Some  escapes
       take  an  optional  integer  argument, which should appear
       between the `%' and the next character  of  the  sequence.
       The following escape sequences are recognized:

       %%     A `%'.

       %)     A `)'.

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

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

       %h
       %!     Current history event number.

       %L     The current value of $SHLVL.

       %M     The full machine hostname.

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

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

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

              Start (stop) boldface mode.

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

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

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

       %n     $USERNAME.

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

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

       %w     The date in day-dd format.

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

       %D     The date in yy-mm-dd format.

       %D{string}
              string  is  formatted  using the strftime function.
              See strftime(3) for more details.  Three additional
              codes  are  available:   %f  prints  the day of the
              month, like %e but without any preceding  space  if
              the  day is a single digit, and %K/%L correspond to
              %k/%l for the hour of the day (24/12 hour clock) in
              the same way.

       %l     The  line  (tty)  the  user is logged in on without
              /dev/ prefix.  If name starts with /dev/tty this is
              stripped.

       %y     The  line  (tty)  the  user is logged in on without
              /dev/ prefix.  It does  not  treat  /dev/tty*  spe­
              cially.

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

       %_     The status of the parser, i.e. the shell constructs
              (like `if' and `for') that have been started on the

              strings  will  be  printed;  zero or negative or no
              integer means print as many as there are.  This  is
              most  useful  in prompts PS2 for continuation lines
              and PS4 for debugging with the  XTRACE  option;  in
              the  latter  case  it  will  also work non-interac­
              tively.

       %E     Clears to end of line.

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

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

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

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

              The left parenthesis may be preceded or followed by
              a positive integer n, which defaults  to  zero.   A
              negative  integer  will  be  multiplied by -1.  The
              test character x may be any of the following:

              c
              .
              ~      True  if  the  current  path,  with   prefix
                     replacement, has at least n elements.
              /
              C      True  if  the  current  absolute path has at
                     least n elements.
              t      True if the time in minutes is equal to n.
              T      True if the time in hours is equal to n.
              d      True if the day of the month is equal to  n.

                     0).
              w      True if the day of the week is  equal  to  n
                     (Sunday = 0).
              ?      True  if the exit status of the last command
                     was n.
              #      True if the effective  uid  of  the  current
                     process is n.
              g      True  if  the  effective  gid of the current
                     process is n.
              l      True if at least n characters  have  already
                     been printed on the current line.
              L      True if the SHLVL parameter is at least n.
              S      True if the SECONDS parameter is at least n.
              v      True if the array psvar has at least n  ele­
                     ments.
              _      True  if  at  least  n shell constructs were
                     started.
              !      True if the shell  is  running  with  privi­
                     leges.

       %<string<
       %>string>
       %[xstring]
              Specifies truncation behaviour for the remainder of
              the prompt string.  The third, deprecated, form  is
              equivalent  to  `%xstringx',  i.e.  x may be `<' or
              `>'.  The numeric argument, which in the third form
              may appear immediately after the `[', specifies the
              maximum permitted length  of  the  various  strings
              that  can  be  displayed in the prompt.  The string
              will be 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 also subject  to  stan­
              dard  print  processing,  in  addition to any back­
              slashes removed by a  double  quoted  string:   the
              worst case is therefore `print -P "%<\\\\<<..."'.

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

              The  part of the prompt string to be truncated runs
              to the end of the string, or to the end of the next

              next truncation encountered at  the  same  grouping
              level  (i.e.  truncations  inside  a `%(' are sepa­
              rate), which ever comes first.   In  particular,  a
              truncation  with  argument  zero (e.g. `%<<') marks
              the end of the range of the string to be  truncated
              while  turning  off  truncation  from there on. For
              example, the prompt '%10<...<%~%<<%# ' will print a
              truncated  representation of the current directory,
              followed by a `%' or  `#',  followed  by  a  space.
              Without  the  `%<<',  those two characters would be
              included in the string to be truncated.

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


Man(1) output converted with man2html