zshmodules - zsh loadable modules


DESCRIPTION

       Some  optional  parts of zsh are in modules, separate from
       the core of the shell.   Each  of  these  modules  may  be
       linked  in  to  the shell at build time, or can be dynami­
       cally linked while the shell is running if  the  installa­
       tion  supports this feature.  The modules that are bundled
       with the zsh distribution are:

       zsh/cap
              Builtins for manipulating POSIX.1e (POSIX.6)  capa­
              bility (privilege) sets.

       zsh/clone
              A  builtin  that  can  clone  a  running shell onto
              another terminal.

       zsh/compctl
              The compctl builtin for controlling completion.

       zsh/complete
              The basic completion code.

       zsh/complist
              Completion listing extensions.

       zsh/computil
              A module with utility builtins needed for the shell
              function based completion system.

       zsh/deltochar
              A ZLE function duplicating EMACS' zap-to-char.

       zsh/example
              An example of how to write a module.

       zsh/files
              Some  basic file manipulation commands as builtins.

       zsh/mapfile
              Access to external files via a special  associative
              array.

       zsh/mathfunc
              Standard scientific functions for use in mathemati­
              cal evaluations.

       zsh/parameter
              Access to internal hash tables via special associa­
              tive arrays.

              A  builtin that provides a timed execution facility
              within the shell.

       zsh/stat
              A builtin command  interface  to  the  stat  system
              call.

       zsh/termcap
              Interface to the termcap database.

       zsh/terminfo
              Interface to the terminfo database.

       zsh/zftp
              A builtin FTP client.

       zsh/zle
              The  Zsh  Line  Editor,  including  the bindkey and
              vared builtins.

       zsh/zleparameter
              Access to internals of  the  Zsh  Line  Editor  via
              parameters.

       zsh/zprof
              A module allowing profiling for shell functions.

       zsh/zpty
              A builtin for starting a command in a pseudo-termi­
              nal.

       zsh/zutil
              Some utility builtins, e.g. the one for  supporting
              configuration via styles.


THE ZSH/CAP MODULE

       The  zsh/cap  module  is  used  for  manipulating POSIX.1e
       (POSIX.6) capability sets.  If the operating  system  does
       not  support  this interface, the builtins defined by this
       module will do nothing.  The builtins in this module are:

       cap [ capabilities ]
              Change the shell's process capability sets  to  the
              specified   capabilities,   otherwise  display  the
              shell's current capabilities.

       getcap filename ...
              This is a  built-in  implementation  of  the  POSIX
              standard  utility.  It displays the capability sets
              on each specified filename.

       setcap capabilities filename ...
              This is a  built-in  implementation  of  the  POSIX

              each specified filename to the specified  capabili­
              ties.


THE ZSH/CLONE MODULE

       The zsh/clone module makes available one builtin command:

       clone tty
              Creates  a  forked  instance  of the current shell,
              attached to the specified tty.  In the  new  shell,
              the  PID,  PPID  and  TTY  special  parameters  are
              changed appropriately.  $! is set to  zero  in  the
              new shell, and to the new shell's PID in the origi­
              nal shell.

              The return value of the builtin  is  zero  in  both
              shells if successful, and non-zero on error.


THE ZSH/COMPCTL MODULE

       The  zsh/compctl  module  makes available two builtin com­
       mands. compctl, is the old, deprecated way to control com­
       pletions  for  ZLE.  See zshcompctl(1).  The other builtin
       command, compcall can be used in  user-defined  completion
       widgets, see zshcompwid(1).


THE ZSH/COMPLETE MODULE

       The  zsh/complete  module  makes available several builtin
       commands which can be used in user-defined completion wid­
       gets, see zshcompwid(1).


THE ZSH/COMPLIST MODULE

       The zsh/complist module offers three extensions to comple­
       tion listings: the ability to highlight matches in such  a
       list,  the ability to scroll through long lists and a dif­
       ferent style of menu completion.

   Colored completion listings
       Whenever one of the parameters ZLS_COLORS  or  ZLS_COLOURS
       is  set  and  the  zsh/complist module is loaded or linked
       into the shell, completion lists will be  colored.   Note,
       however, that complist will not automatically be loaded if
       it is not linked in:  on  systems  with  dynamic  loading,
       `zmodload zsh/complist' is required.

       The  parameters  ZLS_COLORS  and  ZLS_COLOURS describe how
       matches are highlighted.  To turn on highlighting an empty
       value suffices, in which case all the default values given
       below will be used.  The format  of  the  value  of  these
       parameters  is  the same as used by the GNU version of the
       ls command: a colon-separated list  of  specifications  of
       the form `name=value'.  The name may be one of the follow­
       ing strings, most of which specify file  types  for  which
       the  value  will  be  used.  The strings and their default


       no 0   for normal text  (i.e.  when  displaying  something
              other than a matched file)

       fi 0   for regular files

       di 32  for directories

       ln 36  for symbolic links

       pi 31  for named pipes (FIFOs)

       so 33  for sockets

       bd 44;37
              for block devices

       cd 44;37
              for character devices

       ex 35  for executable files

       mi none
              for  a  non-existent  file  (default  is  the value
              defined for fi)

       lc \e[ for the left code (see below)

       rc m   for the right code

       tc 0   for the character indicating the file type  printed
              after filenames if the LIST_TYPES option is set

       sp 0   for  the  spaces printed after matches to align the
              next column

       ec none
              for the end code

       Apart from these strings, the name may also be an asterisk
       (`*')  followed  by any string. The value given for such a
       string will be used for all files whose name ends with the
       string.   The  name  may also be an equals sign (`=') fol­
       lowed by a pattern.  The value given for this pattern will
       be used for all matches (not just filenames) whose display
       string are matched by the pattern.  Definitions  for  both
       of  these take precedence over the values defined for file
       types and the form with the leading asterisk takes  prece­
       dence over the form with the leading equal sign.

       The last form also allows different parts of the displayed
       strings to be colored differently.  For this, the  pattern
       has   to  use  the  `(#b)'  globbing  flag  and  pairs  of

       to  be  colored  differently.   In this case the value may
       consist of more than one color  code  separated  by  equal
       signs.   The  first  code  will  be used for all parts for
       which no explicit code  is  specified  and  the  following
       codes  will  be used for the parts matched by the sub-pat­
       terns in  parentheses.   For  example,  the  specification
       `=(#b)(?)*(?)=0=3=7'  will  be  used for all matches which
       are at least two characters long and will use the code `3'
       for  the  first  character, `7' for the last character and
       `0' for the rest.

       All three forms of name may be preceded by  a  pattern  in
       parentheses.   If  this  is  given, the value will be used
       only for matches in groups whose names are matched by  the
       pattern   given   in   the   parentheses.    For  example,
       `(g*)m*=43' highlights all matches beginning with  `m'  in
       groups  whose  names   begin with `g' using the color code
       `43'.  In case of the `lc',  `rc',  and  `ec'  codes,  the
       group pattern is ignored.

       Note  also  that  all  patterns  are tried in the order in
       which they appear in the parameter value until  the  first
       one matches which is then used.

       When  printing  a  match, the code prints the value of lc,
       the value for the file-type or the last matching  specifi­
       cation  with a `*', the value of rc, the string to display
       for the match itself, and then the value of ec if that  is
       defined  or  the  values  of  lc,  no, and rc if ec is not
       defined.

       The default values are ISO 6429 (ANSI) compliant  and  can
       be  used on vt100 compatible terminals such as xterms.  On
       monochrome terminals the default values will have no visi­
       ble effect.  The colors function from the contribution can
       be used to get associative arrays containing the codes for
       ANSI  terminals (see the section `Other Functions' in zsh­
       contrib(1)).  For example, after loading colors, one could
       use  `$colors[red]'  to  get the code for foreground color
       red and `$colors[bg-green]' for the  code  for  background
       color green.

       If  the  completion  system  invoked  by compinit is used,
       these parameters should not be set  directly  because  the
       system  controls  them  itself.   Instead, the list-colors
       style should be used (see the section  `Completion  System
       Configuration' in zshcompsys(1)).

   Scrolling in completion listings
       To  enable  scrolling through a completion list, the LIST­
       PROMPT parameter must be set.  Its value will be  used  as
       the  prompt;  if  it is the empty string, a default prompt

       `%x'.   It  supports  the  escapes `%B', `%b', `%S', `%s',
       `%U', `%u' and `%{...%}' used also  in  shell  prompts  as
       well  as  three  pairs  of additional sequences: a `%l' or
       `%L' is replaced by the number of the last line shown  and
       the  total  number  of lines in the form `number/total'; a
       `%m' or `%M' is replaced with the number of the last match
       shown and the total number of matches; and `%p' or `%P' is
       replaced with `Top', `Bottom' or the position of the first
       line  shown  in  percent  of  the  total  number of lines,
       respectively.  In each of these cases the  form  with  the
       uppercase  letter  will be replaced with a string of fixed
       width, padded to the right with spaces, while  the  lower­
       case form will not be padded.

       If  the  parameter  LISTPROMPT is set, the completion code
       will not ask if the list  should  be  shown.   Instead  it
       immediately starts displaying the list, stopping after the
       first screenful, showing the prompt at the bottom, waiting
       for   a   keypress  after  temporarily  switching  to  the
       listscroll keymap.  Some of the zle functions have a  spe­
       cial meaning while scrolling lists:

       send-break
              stops listing discarding the key pressed

       accept-line, down-history, down-line-or-history
       down-line-or-search, vi-down-line-or-history
              scrolls forward one line

       complete-word, menu-complete, expand-or-complete
       expand-or-complete-prefix, menu-complete-or-expand
              scrolls forward one screenful

       Every  other  character stops listing and immediately pro­
       cesses the key as usual.  Any key that is not bound in the
       listscroll  keymap  or  that  is bound to undefined-key is
       looked up in the keymap currently selected.

       As for the ZLS_COLORS and  ZLS_COLOURS  parameters,  LIST­
       PROMPT  should  not  be  set directly when using the shell
       function   based   completion   system.    Instead,    the
       list-prompt style should be used.

   Menu selection
       The  zsh/complist  module also offers an alternative style
       of selecting matches from a list, called  menu  selection,
       which  can be used if the shell is set up to return to the
       last prompt after  showing  a  completion  list  (see  the
       ALWAYS_LAST_PROMPT  option  in  zshoptions(1)).  It can be
       invoked directly by the widget menu-select defined by  the
       module.   Alternatively,  the  parameter MENUSELECT can be
       set to an integer,  which  gives  the  minimum  number  of

       automatically turned on.  This second method requires that
       menu  completion be started, either directly from a widget
       such as menu-complete,  or  due  to  one  of  the  options
       MENU_COMPLETE  or  AUTO_MENU  being set.  If MENUSELECT is
       set, but is 0, 1 or empty, menu selection will  always  be
       started during an ambiguous menu completion.

       When using the completion system based on shell functions,
       the MENUSELECT parameter should  not  be  used  (like  the
       ZLS_COLORS  and  ZLS_COLOURS  parameters described above).
       Instead, the menu style should be used with the select=...
       keyword.

       After  menu  selection  is  started,  the  matches will be
       listed. If there are more matches than fit on the  screen,
       only  the first screenful is shown.  The matches to insert
       into the command line can be selected from this list.   In
       the  list  one match is highlighted using the value for ma
       from the ZLS_COLORS or ZLS_COLOURS parameter.  The default
       value  for  this is `7' which forces the selected match to
       be highlighted using standout mode on  a  vt100-compatible
       terminal.   If  neither ZLS_COLORS nor ZLS_COLOURS is set,
       the same terminal control sequence as for the `%S'  escape
       in prompts is used.

       If  there  are more matches than fit on the screen and the
       parameter MENUPROMPT is set, its value will be shown below
       the  matches.   It  supports  the same escape sequences as
       LISTPROMPT, but the number of the match or line shown will
       be that of the one where the mark is placed.  If its value
       is the empty string, a default prompt will be used.

       The MENUSCROLL parameter can be used to  specify  how  the
       list is scrolled.  If the parameter is unset, this is done
       line by line, if it is set to `0' (zero),  the  list  will
       scroll  half  the  number  of lines of the screen.  If the
       value is positive, it gives the number of lines to  scroll
       and  if it is negative, the list will be scrolled the num­
       ber of lines of the screen minus the (absolute) value.

       As for the ZLS_COLORS, ZLS_COLOURS and LISTPROMPT  parame­
       ters,  neither  MENUPROMPT  nor  MENUSCROLL  should be set
       directly when using the shell  function  based  completion
       system.   Instead,  the  select-prompt  and  select-scroll
       styles should be used.

       The completion code sometimes decides not to show  all  of
       the  matches in the list.  These hidden matches are either
       matches for which the completion function which added them
       explicitly  requested  that  they  not  appear in the list
       (using the -n option of the compadd  builtin  command)  or
       they  are  matches which duplicate a string already in the
       list (because they differ only in things like prefixes  or

       menu selection, however, even these matches are  shown  so
       that  it  is  possible  to select them.  To highlight such
       matches the hi and du capabilities in the  ZLS_COLORS  and
       ZLS_COLOURS parameters are supported for hidden matches of
       the first and second kind, respectively.

       Selecting matches is done by moving the mark around  using
       the  zle  movement functions.  When not all matches can be
       shown on the screen at the same time, the list will scroll
       up  and  down  when  crossing the top or bottom line.  The
       following zle functions have special meaning  during  menu
       selection:

       accept-line
              accepts the current match and leaves menu selection

       send-break
              leaves menu selection  and  restores  the  previous
              contents of the command line

       redisplay, clear-screen
              execute  their normal function without leaving menu
              selection

       accept-and-hold, accept-and-menu-complete
              accept the currently inserted  match  and  continue
              selection  allowing  to  select  the  next match to
              insert into the line

       accept-and-infer-next-history
              accepts the current match and then tries completion
              with  menu  selection  again;  in the case of files
              this allows one to select a directory  and  immedi­
              ately  attempt  to  complete files in it;  if there
              are no matches, a message is shown and one can  use
              undo  to  go  back  to  completion  on the previous
              level,  every  other  key  leaves  menu   selection
              (including the other zle functions which are other­
              wise special during menu selection)

       undo   removes matches inserted during the menu  selection
              by one of the three functions before

       down-history, down-line-or-history
       vi-down-line-or-history,  down-line-or-search
              moves the mark one line down

       up-history, up-line-or-history
       vi-up-line-or-history, up-line-or-search
              moves the mark one line up

       forward-char, vi-forward-char
              moves the mark one column right

              moves the mark one column left

       forward-word, vi-forward-word
       vi-forward-word-end, emacs-forward-word
              moves the mark one screenful down

       backward-word, vi-backward-word, emacs-backward-word
              moves the mark one screenful up

       vi-forward-blank-word, vi-forward-blank-word-end
              moves  the mark to the first line of the next group
              of matches

       vi-backward-blank-word
              moves the mark to the last  line  of  the  previous
              group of matches

       beginning-of-history
              moves the mark to the first line

       end-of-history
              moves the mark to the last line

       beginning-of-buffer-or-history, beginning-of-line
       beginning-of-line-hist, vi-beginning-of-line
              moves the mark to the leftmost column

       end-of-buffer-or-history, end-of-line
       end-of-line-hist, vi-end-of-line
              moves the mark to the rightmost column

       complete-word, menu-complete, expand-or-complete
       expand-or-complete-prefix, menu-expand-or-complete
              moves the mark to the next match

       reverse-menu-complete
              moves the mark to the previous match

       All movement functions wrap around at the edges; any other
       zle function not listed leaves menu selection and executes
       that  function.   It  is  possible  to make widgets in the
       above list do the same by using the  form  of  the  widget
       with   a   `.'   in   front.    For  example,  the  widget
       `.accept-line' has the effect of  leaving  menu  selection
       and accepting the entire command line.

       During  this  selection the widget uses the keymap menuse­
       lect.  Any key that is not defined in this keymap or  that
       is  bound to undefined-key is looked up in the keymap cur­
       rently selected.  This is used to  ensure  that  the  most
       important  keys  used  during selection (namely the cursor
       keys, return, and TAB) have sensible  defaults.   However,
       keys  in  the  menuselect  keymap can be modified directly

       example, to make the return key leave menu selection with­
       out accepting the match currently selected one could call

              bindkey -M menuselect '^M' send-break

       after loading the zsh/complist module.


THE ZSH/COMPUTIL MODULE

       The zsh/computil module adds several builtin commands that
       are  used  by some of the completion functions in the com­
       pletion system based on shell functions (see zshcompsys(1)
       ).   Except  for compquote these builtin commands are very
       specialised and thus not  very  interesting  when  writing
       your  own completion functions.  In summary, these builtin
       commands are:

       comparguments
              This is used by the _arguments function to  do  the
              argument  and  command  line parsing.  Like compde­
              scribe it has an option -i to do  the  parsing  and
              initialize  some internal state and various options
              to access the  state  information  to  decide  what
              should be completed.

       compdescribe
              This is used by the _describe function to build the
              displays for the matches and to get the strings  to
              add  as  matches  with their options.  On the first
              call one of the options -i or -I should be supplied
              as  the first argument.  In the first case, display
              strings without the descriptions will be generated,
              in the second case, the string used to separate the
              matches from their descriptions must  be  given  as
              the  second  argument and the descriptions (if any)
              will be shown.  All other arguments  are  like  the
              definition arguments to _describe itself.

              Once  compdescribe  has been called with either the
              -i or the -I option, it can  be  repeatedly  called
              with  the -g option and the names of five arrays as
              its arguments.  This will step through the  differ­
              ent  sets  of  matches and store the options in the
              first array, the strings with descriptions  in  the
              second,  the  matches  for  these in the third, the
              strings without descriptions in the fourth, and the
              matches  for  them  in  the fifth array.  These are
              then directly given  to  compadd  to  register  the
              matches with the completion code.

       compfiles
              Used  by  the _path_files function to optimize com­
              plex recursive filename generation (globbing).   It
              does  three  things.  With the -p and -P options it

              paths  already  handled  and trying to optimize the
              patterns with respect to the prefix and suffix from
              the  line  and  the  match  specification currently
              used.  The -i option does the directory  tests  for
              the ignore-parents style and the -r option tests if
              a component for some of the matches  are  equal  to
              the  string  on  the  line  and  removes  all other
              matches if that is true.

       compgroups
              Used by the _tags function to implement the  inter­
              nals of the group-order style.  This only takes its
              arguments as names of completion groups and creates
              the  groups  for  it  (all  six  types:  sorted and
              unsorted, both without  removing  duplicates,  with
              removing  all duplicates and with removing consecu­
              tive duplicates).

       compquote [ -p ] names ...
              There may be reasons to write completion  functions
              that have to add the matches using the -Q option to
              compadd and perform quoting themselves.  Instead of
              interpreting  the first character of the all_quotes
              key of the compstate special association and  using
              the  q  flag  for parameter expansions, one can use
              this builtin command.  The arguments are the  names
              of  scalar  or  array  parameters and the values of
              these parameters  are  quoted  as  needed  for  the
              innermost  quoting  level.   If  the  -p  option is
              given, quoting is done as if there is  some  prefix
              before  the  values  of  the  parameters, so that a
              leading equal sign will not be quoted.

              The return value is non-zero in case  of  an  error
              and zero otherwise.

       comptags
       comptry
              These  implement  the  internals of the tags mecha­
              nism.

       compvalues
              Like comparguments, but for the _values function.


THE ZSH/DELTOCHAR MODULE

       The zsh/deltochar module makes  available  two  ZLE  func­
       tions:

       delete-to-char
              Read a character from the keyboard, and delete from
              the cursor position up to and  including  the  next
              (or, with repeat count n, the nth) instance of that
              character.   Negative  repeat  counts  mean  delete


       zap-to-char
              This  behaves  like delete-to-char, except that the
              final occurrence of the  character  itself  is  not
              deleted.


THE ZSH/EXAMPLE MODULE

       The  zsh/example  module  makes available one builtin com­
       mand:

       example [ -flags ] [ args ... ]
              Displays the flags  and  arguments  it  is  invoked
              with.

       The purpose of the module is to serve as an example of how
       to write a module.


THE ZSH/FILES MODULE

       The zsh/files module makes some standard  commands  avail­
       able as builtins:

       chgrp [ -Rs ] group filename ...
              Changes  group of files specified.  This is equiva­
              lent  to  chown  with  a  user-spec   argument   of
              `:group'.

       chown [ -Rs ] user-spec filename ...
              Changes ownership and group of files specified.

              The user-spec can be in four forms:

              user   change owner to user; do not change group
              user:: change owner to user; do not change group
              user:  change owner to user; change group to user's
                     primary group
              user:group
                     change owner to user; change group to group
              :group do not change owner; change group to group

              In each case, the `:' may instead be  a  `.'.   The
              rule  is  that if there is a `:' then the separator
              is `:', otherwise if there is a `.' then the  sepa­
              rator is `.', otherwise there is no separator.

              Each of user and group may be either a username (or
              group name, as appropriate) or a  decimal  user  ID
              (group  ID).  Interpretation as a name takes prece­
              dence, if there  is  an  all-numeric  username  (or
              group name).

              The  -R  option causes chown to recursively descend
              into directories, changing  the  ownership  of  all
              files in the directory after changing the ownership


              The -s option is a zsh extension to chown function­
              ality.   It enables paranoid behaviour, intended to
              avoid security problems  involving  a  chown  being
              tricked  into  affecting  files other than the ones
              intended.  It will refuse to follow symbolic links,
              so     that    (for    example)    ``chown    luser
              /tmp/foo/passwd''    can't    accidentally    chown
              /etc/passwd  if  /tmp/foo  happens  to be a link to
              /etc.  It will also check where it is after leaving
              directories,  so  that  a recursive chown of a deep
              directory tree can't end  up  recursively  chowning
              /usr  as a result of directories being moved up the
              tree.

       ln [ -dfis ] filename dest
       ln [ -dfis ] filename ... dir
              Creates hard (or, with -s, symbolic) links.  In the
              first  form,  the specified destination is created,
              as a link to the specified filename.  In the second
              form,  each  of the filenames is taken in turn, and
              linked to a pathname  in  the  specified  directory
              that has the same last pathname component.

              Normally,  ln will not attempt to create hard links
              to directories.  This check can be overridden using
              the  -d  option.  Typically only the super-user can
              actually succeed in creating hard links to directo­
              ries.  This does not apply to symbolic links in any
              case.

              By default, existing files cannot  be  replaced  by
              links.  The -i option causes the user to be queried
              about replacing  existing  files.   The  -f  option
              causes existing files to be silently deleted, with­
              out querying.  -f takes precedence.

       mkdir [ -p ] [ -m mode ] dir ...
              Creates   directories.    With   the   -p   option,
              non-existing  parent  directories are first created
              if necessary, and there will be no complaint if the
              directory  already  exists.   The  -m option can be
              used to specify (in octal) a set  of  file  permis­
              sions  for  the created directories, otherwise mode
              777 modified by the current umask (see umask(2)) is
              used.

       mv [ -fi ] filename dest
       mv [ -fi ] filename ... dir
              Moves  files.   In  the  first  form, the specified
              filename is moved to the specified destination.  In
              the  second form, each of the filenames is taken in
              turn, and moved to  a  pathname  in  the  specified

              nent.

              By default, the user will be queried before replac­
              ing  any  file  that  the user cannot write to, but
              writable files will be silently  removed.   The  -i
              option  causes the user to be queried about replac­
              ing any existing files.  The -f option  causes  any
              existing  files  to  be  silently  deleted, without
              querying.  -f takes precedence.

              Note that  this  mv  will  not  move  files  across
              devices.   Historical  versions  of mv, when actual
              renaming is impossible, fall back  on  copying  and
              removing  files;  if this behaviour is desired, use
              cp and rm manually.  This may change  in  a  future
              version.

       rm [ -dfirs ] filename ...
              Removes files and directories specified.

              Normally,  rm  will  not remove directories (except
              with the -r option).  The -d option  causes  rm  to
              try   removing   directories   with   unlink   (see
              unlink(2)), the same method used for files.   Typi­
              cally  only  the super-user can actually succeed in
              unlinking directories in this way.  -d takes prece­
              dence over -r.

              By  default, the user will be queried before remov­
              ing any file that the user  cannot  write  to,  but
              writable  files  will  be silently removed.  The -i
              option causes the user to be queried about removing
              any  files.   The  -f  option  causes  files  to be
              silently deleted, without querying, and  suppresses
              all error indications.  -f takes precedence.

              The -r option causes rm to recursively descend into
              directories, deleting all files  in  the  directory
              before removing the directory with the rmdir system
              call (see rmdir(2)).

              The -s option is a zsh extension to rm  functional­
              ity.   It  enables  paranoid behaviour, intended to
              avoid common security problems involving a root-run
              rm being tricked into removing files other than the
              ones intended.  It will refuse to  follow  symbolic
              links, so that (for example) ``rm /tmp/foo/passwd''
              can't accidentally remove /etc/passwd  if  /tmp/foo
              happens  to  be a link to /etc.  It will also check
              where it is after leaving directories,  so  that  a
              recursive  removal  of  a deep directory tree can't
              end up recursively removing /usr  as  a  result  of
              directories being moved up the tree.

              Removes empty directories specified.

       sync   Calls  the  system  call  of  the  same  name  (see
              sync(2)), which flushes dirty buffers to disk.   It
              might  return before the I/O has actually been com­
              pleted.


THE ZSH/MAPFILE MODULE

       The zsh/mapfile module provides  one  special  associative
       array parameter of the same name.

       mapfile
              This  associative  array takes as keys the names of
              files; the resulting value is the  content  of  the
              file.   The  value  is  treated  identically to any
              other text coming from a parameter.  The value  may
              also  be  assigned  to,  in  which case the file in
              question is written (whether or not  it  originally
              existed);  or  an  element may be unset, which will
              delete the file in question.  For  example,  `vared
              mapfile[myfile]'  works  as  expected,  editing the
              file `myfile'.

              When the array is accessed as a whole, the keys are
              the  names  of  files in the current directory, and
              the values are empty (to save a  huge  overhead  in
              memory).  Thus ${(k)mapfile} has the same affect as
              the glob operator *(D), since files beginning  with
              a  dot  are  not  special.  Care must be taken with
              expressions such as rm  ${(k)mapfile},  which  will
              delete  every file in the current directory without
              the usual `rm *' test.

              The parameter mapfile may  be  made  read-only;  in
              that  case,  files referenced may not be written or
              deleted.

   Limitations
       Although reading and writing of the file  in  question  is
       efficiently  handled, zsh's internal memory management may
       be arbitrarily baroque.  Thus it should not  automatically
       be  assumed that use of mapfile represents a gain in effi­
       ciency over use of other mechanisms.  Note  in  particular
       that  the  whole  contents  of the file will always reside
       physically in  memory  when  accessed  (possibly  multiple
       times, due to standard parameter substitution operations).
       In particular, this means handling  of  sufficiently  long
       files  (greater than the machine's swap space, or than the
       range of the pointer type) will be incorrect.

       No errors are printed or flagged for non-existent, unread­
       able,  or  unwritable files, as the parameter mechanism is

       venient.

       It  is  unfortunate that the mechanism for loading modules
       does not yet allow the user to specify  the  name  of  the
       shell parameter to be given the special behaviour.


THE ZSH/MATHFUNC MODULE

       The  zsh/mathfunc  module  provides  standard mathematical
       functions for use when evaluating  mathematical  formulae.
       The  syntax  agrees with normal C and FORTRAN conventions,
       for example,

              (( f = sin(0.3) ))

       assigns the sine of 0.3 to the parameter f.

       Most functions take floating point arguments and return  a
       floating  point value.  However, any necessary conversions
       from or to integer type will be performed automatically by
       the shell.  Apart from atan with a second argument and the
       abs, int and float  functions,  all  functions  behave  as
       noted in the manual page for the corresponding C function,
       except that any arguments out of range for the function in
       question  will  be  detected  by  the  shell  and an error
       reported.

       The following functions take a single floating point argu­
       ment:  acos,  acosh, asin, asinh, atan, atanh, cbrt, ceil,
       cos, cosh, erf, erfc, exp, expm1, fabs, floor, gamma,  j0,
       j1, lgamma, log, log10, log1p, logb, sin, sinh, sqrt, tan,
       tanh, y0, y1.  The atan function  can  optionally  take  a
       second argument, in which case it behaves like the C func­
       tion atan2.  The ilogb function takes  a  single  floating
       point argument, but returns an integer.

       The  function  signgam  takes no arguments, and returns an
       integer, which is the C variable  of  the  same  name,  as
       described  in  gamma(3).   Note  that it is therefore only
       useful immediately after a call to gamma or lgamma.   Note
       also  that  `signgam()' and `signgam' are distinct expres­
       sions.

       The following functions take two floating point arguments:
       copysign, fmod, hypot, nextafter.

       The  following take an integer first argument and a float­
       ing point second argument: jn, yn.

       The following take a floating point first argument and  an
       integer second argument: ldexp, scalb.

       The  function  abs does not convert the type of its single
       argument; it  returns  the  absolute  value  of  either  a

       and int convert their arguments into a floating  point  or
       integer value (by truncation) respectively.

       Note that the C pow function is available in ordinary math
       evaluation as the `**' operator and is not provided  here.


THE ZSH/PARAMETER MODULE

       The  zsh/parameter  module  gives  access  to  some of the
       internal hash tables used by the shell  by  defining  some
       special parameters.

       options
              The  keys  for this associative array are the names
              of the options that can be set and unset using  the
              setopt and unsetopt builtins. The value of each key
              is either the string on if the option is  currently
              set,  or  the  string  off  if the option is unset.
              Setting a key to one of these strings is like  set­
              ting  or unsetting the option, respectively. Unset­
              ting a key in this array is like setting it to  the
              value off.

       commands
              This  array gives access to the command hash table.
              The keys are the names of  external  commands,  the
              values are the pathnames of the files that would be
              executed when the command would be invoked. Setting
              a  key  in  this  array defines a new entry in this
              table in the same way as  with  the  hash  builtin.
              Unsetting  a  key  as  in  `unset  "commands[foo]"'
              removes the entry for the given key from  the  com­
              mand hash table.

       functions
              This  associative array maps names of enabled func­
              tions to their definitions. Setting a key in it  is
              like defining a function with the name given by the
              key and the body given by the  value.  Unsetting  a
              key  removes  the definition for the function named
              by the key.

       dis_functions
              Like functions but for disabled functions.

       builtins
              This associative array gives information about  the
              builtin  commands  currently  enabled. The keys are
              the names of the builtin commands  and  the  values
              are  either  `undefined'  for builtin commands that
              will automatically  be  loaded  from  a  module  if
              invoked  or `defined' for builtin commands that are
              already loaded.

              Like builtins but for disabled builtin commands.

       reswords
              This array contains the enabled reserved words.

       dis_reswords
              Like reswords but for disabled reserved words.

       aliases
              This maps the names of  the  regular  aliases  cur­
              rently enabled to their expansions.

       dis_aliases
              Like raliases but for disabled regular aliases.

       galiases
              Like raliases, but for global aliases.

       dis_galiases
              Like galiases but for disabled global aliases.

       parameters
              The keys in this associative array are the names of
              the parameters currently defined.  The  values  are
              strings  describing  the  type of the parameter, in
              the same format used by the t parameter  flag,  see
              zshexpn(1)  .   Setting  or  unsetting keys in this
              array is not possible.

       modules
              An associative array giving information about  mod­
              ules. The keys are the names of the modules loaded,
              registered to be autoloaded, or aliased. The  value
              says  which state the named module is in and is one
              of   the   strings   `loaded',   `autoloaded',   or
              `alias:name',  where name is the name the module is
              aliased to.

              Setting or unsetting keys in this array is not pos­
              sible.

       dirstack
              A  normal  array holding the elements of the direc­
              tory stack.  Note  that  the  output  of  the  dirs
              builtin  command  includes  one more directory, the
              current working directory.

       history
              This associative array maps history  event  numbers
              to the full history lines.

       historywords
              A  special array containing the words stored in the


       jobdirs
              This associative array  maps  job  numbers  to  the
              directories  from  which the job was started (which
              may not be the current directory of the job).

       jobtexts
              This associative array  maps  job  numbers  to  the
              texts  of the command lines that were used to start
              the jobs.

       jobstates
              This associative array gives information about  the
              states  of  the  jobs currently known. The keys are
              the job numbers and the values are strings  of  the
              form  `job-state:mark:pid=state...'.  The job-state
              gives the state the whole job is currently in,  one
              of  `running',  `suspended', or `done'. The mark is
              `+' for the current job, `-' for the  previous  job
              and  empty  otherwise.  This  is  followed  by  one
              `pid=state' for every process in the job. The  pids
              are,  of  course,  the  process  IDs  and the state
              describes the state of that process.

       nameddirs
              This associative array  maps  the  names  of  named
              directories to the pathnames they stand for.

       userdirs
              This associative array maps user names to the path­
              names of their home directories.

       funcstack
              This array contains the names of the functions cur­
              rently  being  executed.  The  first element is the
              name of the function using the parameter.


THE ZSH/SCHED MODULE

       The zsh/sched module makes available one builtin command:

       sched [+]hh:mm command ...
       sched [ -item ]
              Make an entry in the scheduled list of commands  to
              execute.  The time may be specified in either abso­
              lute or relative time.  With no  arguments,  prints
              the  list of scheduled commands.  With the argument
              `-item', removes the given item from the list.


THE ZSH/STAT MODULE

       The zsh/stat module makes available one builtin command:

       stat [ -gnNolLtTrs ] [ -f fd ] [ -H hash ] [ -A array ] [
              -F  fmt ] [ +element ] [ file ... ]

              call  (see  stat(2)).   If the stat call fails, the
              appropriate system error message printed and status
              1  is  returned.   The  fields  of struct stat give
              information about the files provided  as  arguments
              to  the  command.   In  addition to those available
              from the stat call, an extra element `link' is pro­
              vided.  These elements are:

              device The  number  of the device on which the file
                     resides.

              inode  The unique number of the file on this device
                     (`inode' number).

              mode   The  mode  of  the file; that is, the file's
                     type and access permissions.   With  the  -s
                     option,  this  will  be returned as a string
                     corresponding to the  first  column  in  the
                     display of the ls -l command.

              nlink  The number of hard links to the file.

              uid    The  user ID of the owner of the file.  With
                     the -s option, this is displayed as  a  user
                     name.

              gid    The  group  ID  of  the  file.   With the -s
                     option, this is displayed as a group name.

              rdev   The raw device number.  This is only  useful
                     for special devices.

              size   The size of the file in bytes.

              atime
              mtime
              ctime  The  last  access,  modification  and  inode
                     change times of the file,  respectively,  as
                     the  number of seconds since midnight GMT on
                     1st January,  1970.   With  the  -s  option,
                     these  are  printed as strings for the local
                     time zone; the format can  be  altered  with
                     the  -F  option,  and with the -g option the
                     times are in GMT.

              blksize
                     The number of bytes in one allocation  block
                     on the device on which the file resides.

              block  The  number of disk blocks used by the file.

              link   If the file is a link and the -L  option  is
                     in  effect,  this  contains  the name of the

                     that  if  this  element  is selected (``stat
                     +link'') then the -L option is automatically
                     used.

              A  particular  element may be selected by including
              its name preceded by a `+' in the option list; only
              one  element is allowed.  The element may be short­
              ened to any unique set of leading characters.  Oth­
              erwise, all elements will be shown for all files.

              Options:

              -A array
                     Instead  of  displaying the results on stan­
                     dard output, assign them to  an  array,  one
                     struct  stat  element  per array element for
                     each file in order.  In  this  case  neither
                     the  name of the element nor the name of the
                     files appears in array unless the -t  or  -n
                     options  were given, respectively.  If -t is
                     given, the element name appears as a  prefix
                     to  the  appropriate array element; if -n is
                     given, the file name appears as  a  separate
                     array  element  preceding  all  the  others.
                     Other formatting options are respected.

              -H hash
                     Similar to -A, but instead assign the values
                     to  hash.   The keys are the elements listed
                     above.  If the -n option  is  provided  then
                     the name of the file is included in the hash
                     with key name.

              -f fd  Use the file on file descriptor  fd  instead
                     of  named  files;  no  list of file names is
                     allowed in this case.

              -F fmt Supplies a strftime (see strftime(3)) string
                     for  the  formatting  of  the time elements.
                     The -s option is implied.

              -g     Show the time elements in the GMT time zone.
                     The -s option is implied.

              -l     List  the  names  of  the  type elements (to
                     standard output or an array as  appropriate)
                     and  return  immediately; options other than
                     -A and arguments are ignored.

              -L     Perform an lstat (see lstat(2)) rather  than
                     a  stat  system  call.  In this case, if the
                     file is a link, information about  the  link
                     itself   rather  than  the  target  file  is

                     the link element useful.

              -n     Always  show  the  names  of files.  Usually
                     these are only shown when output is to stan­
                     dard  output and there is more than one file
                     in the list.

              -N     Never show the names of files.

              -o     If a raw file mode is printed,  show  it  in
                     octal,  which  is more useful for human con­
                     sumption than the  default  of  decimal.   A
                     leading  zero  will be printed in this case.
                     Note that this does not affect whether a raw
                     or  formatted  file  mode is shown, which is
                     controlled by the -r  and  -s  options,  nor
                     whether a mode is shown at all.

              -r     Print  raw  data (the default format) along­
                     side string data (the -s format); the string
                     data  appears  in  parentheses after the raw
                     data.

              -s     Print mode, uid, gid and the three time ele­
                     ments  as  strings  instead  of numbers.  In
                     each case the format is like that of ls  -l.

              -t     Always  show the type names for the elements
                     of struct  stat.   Usually  these  are  only
                     shown  when output is to standard output and
                     no individual element has been selected.

              -T     Never show the type names of the struct stat
                     elements.


THE ZSH/TERMCAP MODULE

       The  zsh/termcap  module  makes available one builtin com­
       mand:

       echotc cap [ arg ... ]
              Output the termcap value corresponding to the capa­
              bility cap, with optional arguments.

       The zsh/termcap module makes available one parameter:

       termcap
              An  associative  array that maps termcap capability
              codes to their values.


THE ZSH/TERMINFO MODULE

       The zsh/terminfo module makes available one  builtin  com­
       mand:

              Output  the  terminfo  value  corresponding  to the
              capability cap.

       The zsh/terminfo module makes available one parameter:

       terminfo
              An associative array that maps terminfo  capability
              names to their values.


THE ZSH/ZFTP MODULE

       The zsh/zftp module makes available one builtin command:

       zftp subcommand [ args ]
              The  zsh/zftp  module  is  a  client  for FTP (file
              transfer protocol).  It is implemented as a builtin
              to  allow  full  use of shell command line editing,
              file I/O, and job control mechanisms.  Often, users
              will access it via shell functions providing a more
              powerful interface; a set is provided with the  zsh
              distribution  and  is  described  in zshzftpsys(1).
              However, the zftp command is entirely usable in its
              own right.

              All  commands consist of the command name zftp fol­
              lowed by the  name  of  a  subcommand.   These  are
              listed below.  The return status of each subcommand
              is supposed to reflect the success  or  failure  of
              the  remote  operation.   See  a description of the
              variable ZFTP_VERBOSE for more information  on  how
              responses from the server may be printed.

   Subcommands
       open host [ user [ password [ account ] ] ]
              Open  a  new  FTP session to host, which may be the
              name of a TCP/IP connected host or an IP number  in
              the standard dot notation.  Remaining arguments are
              passed to the login subcommand.  Note  that  if  no
              arguments  beyond  host are supplied, open will not
              automatically call login.  If no arguments  at  all
              are  supplied,  open will use the parameters set by
              the params subcommand.

              After  a  successful  open,  the  shell   variables
              ZFTP_HOST,  ZFTP_IP  and ZFTP_SYSTEM are available;
              see `Variables' below.

       login [ name [ password [ account ] ] ]
       user [ name [ password [ account ] ] ]
              Login the user name with  parameters  password  and
              account.  Any of the parameters can be omitted, and
              will be read from standard input if needed (name is
              always needed).  If standard input is a terminal, a

              error  and  password will not be echoed.  If any of
              the parameters are not used, a warning  message  is
              printed.

              After  a  successful  login,  the  shell  variables
              ZFTP_USER, ZFTP_ACCOUNT and ZFTP_PWD are available;
              see `Variables' below.

              This  command  may  be  re-issued  when  a  user is
              already logged in, and the  server  will  first  be
              reinitialized for a new user.

       params [ host [ user [ password [ account ] ] ] ]
       params -
              Store the given parameters for a later open command
              with no arguments.  Only those given on the command
              line  will  be  remembered.   If  no  arguments are
              given, the parameters currently  set  are  printed,
              although  the  password  will  appear  as a line of
              stars; the return value is  one  if  no  parameters
              were set, zero otherwise.

              Any  of  the  parameters may be specified as a `?',
              which may need to be  quoted  to  protect  it  from
              shell  expansion.   In  this  case, the appropriate
              parameter will be read from stdin as with the login
              subcommand, including special handling of password.
              If the `?' is followed by a string, that is used as
              the prompt for reading the parameter instead of the
              default  message  (any  necessary  punctuation  and
              whitespace  should  be  included  at the end of the
              prompt).  The first letter of the parameter  (only)
              may  be  quoted  with  a  `\';  hence  an  argument
              "\\$word" guarantees that the string from the shell
              parameter  $word will be treated literally, whether
              or not it begins with a `?'.

              If instead a single  `-'  is  given,  the  existing
              parameters,  if  any,  are  deleted.  In that case,
              calling open with no arguments will cause an error.

              The  list  of  parameters  is  not  deleted after a
              close, however it will be deleted if  the  zsh/zftp
              module is unloaded.

              For example,

                     zftp params ftp.elsewhere.xx juser '?Password for juser: '

              will  store  the host ftp.elsewhere.xx and the user
              juser and then prompt the user for the  correspond­
              ing password with the given prompt.

              that it has closed the connection (maybe due  to  a
              timeout),  return  status  2;  if no connection was
              open anyway, return status 1; else return status 0.
              The  test subcommand is silent, apart from messages
              printed by the $ZFTP_VERBOSE  mechanism,  or  error
              messages  if  the  connection  closes.  There is no
              network overhead for this test.

              The test is only supported on systems  with  either
              the  select(2)  or  poll(2) system calls; otherwise
              the message  `not  supported  on  this  system'  is
              printed instead.

              The test subcommand will automatically be called at
              the start of any other subcommand for  the  current
              session when a connection is open.

       cd directory
              Change  the  remote  directory  to directory.  Also
              alters the shell variable ZFTP_PWD.

       cdup   Change the remote directory to the  one  higher  in
              the directory tree.  Note that cd .. will also work
              correctly on non-UNIX systems.

       dir [ args... ]
              Give a (verbose) listing of the  remote  directory.
              The  args  are  passed  directly to the server. The
              command's behaviour  is  implementation  dependent,
              but  a UNIX server will typically interpret args as
              arguments to the ls command and with  no  arguments
              return  the  result  of  `ls  -l'. The directory is
              listed to standard output.

       ls [ args ]
              Give a (short) listing  of  the  remote  directory.
              With  no  args, produces a raw list of the files in
              the directory, one  per  line.   Otherwise,  up  to
              vagaries of the server implementation, behaves sim­
              ilar to dir.

       type [ type ]
              Change the type for the transfer to type, or  print
              the  current  type  if type is absent.  The allowed
              values are `A' (ASCII), `I' (Image,  i.e.  binary),
              or `B' (a synonym for `I').

              The  FTP default for a transfer is ASCII.  However,
              if zftp finds  that  the  remote  host  is  a  UNIX
              machine  with  8-bit  byes,  it  will automatically
              switch to using  binary  for  file  transfers  upon
              open.  This can subsequently be overridden.

              when a data connection is established; this command
              involves no network overhead.

       ascii  The same as type A.

       binary The same as type I.

       mode [ S | B ]
              Set  the  mode  type  to  stream  (S) or block (B).
              Stream mode is  the  default;  block  mode  is  not
              widely supported.

       remote files...
       local [ files... ]
              Print  the  size  and last modification time of the
              remote or local files.  If there is more  than  one
              item  on  the list, the name of the file is printed
              first.  The first number is the file size, the sec­
              ond  is  the  last modification time of the file in
              the  format  CCYYMMDDhhmmSS  consisting  of   year,
              month,  date,  hour,  minutes  and  seconds in GMT.
              Note that this format,  including  the  length,  is
              guaranteed,  so  that  time strings can be directly
              compared via the [[ builtin's <  and  >  operators,
              even  if  they  are  too  long to be represented as
              integers.

              Not all servers support the commands for retrieving
              this information.  In that case, the remote command
              will print nothing and return  status  2,  compared
              with status 1 for a file not found.

              The local command (but not remote) may be used with
              no arguments, in which case the  information  comes
              from  examining  file descriptor zero.  This is the
              same file as seen by a put command with no  further
              redirection.

       get file [...]
              Retrieve  all  files from the server, concatenating
              them and sending them to standard output.

       put file [...]
              For each file, read a file from standard input  and
              send that to the remote host with the given name.

       append file [...]
              As put, but if the remote file already exists, data
              is appended to it instead of overwriting it.

       getat file point
       putat file point

              Versions of get, put and append  which  will  start
              the transfer at the given point in the remote file.
              This is useful for appending to an incomplete local
              file.   However, note that this ability is not uni­
              versally supported by servers (and is not quite the
              behaviour specified by the standard).

       delete file [...]
              Delete the list of files on the server.

       mkdir directory
              Create a new directory directory on the server.

       rmdir directory
              Delete the directory directory  on the server.

       rename old-name new-name
              Rename file old-name to new-name on the server.

       site args...
              Send  a  host-specific  command to the server.  You
              will probably only need this if instructed  by  the
              server to use it.

       quote args...
              Send  the  raw  FTP command sequence to the server.
              You should be familiar with the FTP command set  as
              defined  in  RFC959 before doing this.  Useful com­
              mands may include STAT and  HELP.   Note  also  the
              mechanism  for  returning messages as described for
              the variable ZFTP_VERBOSE below, in particular that
              all  messages  from the control connection are sent
              to standard error.

       close
       quit   Close the current data connection.  This unsets the
              shell  parameters  ZFTP_HOST, ZFTP_IP, ZFTP_SYSTEM,
              ZFTP_USER, ZFTP_ACCOUNT,  ZFTP_PWD,  ZFTP_TYPE  and
              ZFTP_MODE.

       session [ sessname ]
              Allows  multiple  FTP  sessions to be used at once.
              The name of the session is an arbitrary  string  of
              characters;   the   default   session   is   called
              `default'.  If this command is  called  without  an
              argument,  it  will  list all the current sessions;
              with an argument, it  will  either  switch  to  the
              existing  session  called sessname, or create a new
              session of that name.

              Each session remembers the status  of  the  connec­
              tion,  the set of connection-specific shell parame­
              ters (the same set as are unset when  a  connection

              any user parameters specified with the params  sub­
              command.   Changing  to a previous session restores
              those values; changing to a new session initialises
              them  in  the  same  way  as  if zftp had just been
              loaded.  The name of the current session  is  given
              by the parameter ZFTP_SESSION.

       rmsession [ sessname ]
              Delete  a session; if a name is not given, the cur­
              rent session is deleted.  If the current session is
              deleted,  the earliest existing session becomes the
              new current session, otherwise the current  session
              is  not  changed.   If the session being deleted is
              the only one, a new  session  called  `default'  is
              created  and becomes the current session; note that
              this is a new session even  if  the  session  being
              deleted is also called `default'. It is recommended
              that sessions not be deleted while background  com­
              mands which use zftp are still active.

   Parameters
       The  following  shell  parameters  are used by zftp.  Cur­
       rently none of them are special.

       ZFTP_TMOUT
              Integer.  The time in seconds to wait for a network
              operation  to  complete  before returning an error.
              If this is not set when the module  is  loaded,  it
              will  be  given  the  default value 60.  A value of
              zero turns off timeouts.  If a  timeout  occurs  on
              the  control  connection  it will be closed.  Use a
              larger value if this occurs too frequently.

       ZFTP_IP
              Readonly.  The IP address of the current connection
              in dot notation.

       ZFTP_HOST
              Readonly.   The  hostname  of  the  current  remote
              server.  If the host was opened as  an  IP  number,
              ZFTP_HOST  contains  that  instead;  this saves the
              overhead for a name lookup, as IP numbers are  most
              commonly used when a nameserver is unavailable.

       ZFTP_SYSTEM
              Readonly.   The  system type string returned by the
              server in response to an  FTP  SYST  request.   The
              most  interesting  case is a string beginning "UNIX
              Type: L8", which ensures maximum compatibility with
              a local UNIX host.

              Readonly.  The type to be used for data transfers ,
              either `A' or `I'.   Use  the  type  subcommand  to
              change this.

       ZFTP_USER
              Readonly.   The  username  currently  logged in, if
              any.

       ZFTP_ACCOUNT
              Readonly.  The account name of the current user, if
              any.   Most servers do not require an account name.

       ZFTP_PWD
              Readonly.  The current directory on the server.

       ZFTP_CODE
              Readonly.  The three digit code  of  the  last  FTP
              reply  from the server as a string.  This can still
              be read after the connection is closed, and is  not
              changed when the current session changes.

       ZFTP_REPLY
              Readonly.   The last line of the last reply sent by
              the server.  This can still be read after the  con­
              nection is closed, and is not changed when the cur­
              rent session changes.

       ZFTP_SESSION
              Readonly.  The name of the current FTP session; see
              the description of the session subcommand.

       ZFTP_PREFS
              A  string  of  preferences  for altering aspects of
              zftp's behaviour.   Each  preference  is  a  single
              character.  The following are defined:

              P      Passive:   attempt to make the remote server
                     initiate data transfers.  This  is  slightly
                     more  efficient  than sendport mode.  If the
                     letter S occurs later in  the  string,  zftp
                     will  use  sendport  mode if passive mode is
                     not available.

              S      Sendport:  initiate  transfers  by  the  FTP
                     PORT  command.   If this occurs before any P
                     in the string, passive mode  will  never  be
                     attempted.

              D      Dumb:  use only the bare minimum of FTP com­
                     mands.    This   prevents   the    variables
                     ZFTP_SYSTEM and ZFTP_PWD from being set, and
                     will mean all connections default  to  ASCII
                     type.   It  may prevent ZFTP_SIZE from being

                     send it anyway (many servers do).

              If  ZFTP_PREFS  is  not set when zftp is loaded, it
              will be set to a default of `PS', i.e. use  passive
              mode  if available, otherwise fall back to sendport
              mode.

       ZFTP_VERBOSE
              A string of digits between 0 and 5 inclusive, spec­
              ifying  which  responses  from the server should be
              printed.  All responses go to standard  error.   If
              any of the numbers 1 to 5 appear in the string, raw
              responses from the server with reply  codes  begin­
              ning  with  that  digit will be printed to standard
              error.  The first digit of the  three  digit  reply
              code is defined by RFC959 to correspond to:

              1.     A positive preliminary reply.

              2.     A positive completion reply.

              3.     A positive intermediate reply.

              4.     A transient negative completion reply.

              5.     A permanent negative completion reply.

              It  should  be noted that, for unknown reasons, the
              reply `Service not available', which forces  termi­
              nation  of a connection, is classified as 421, i.e.
              `transient negative', an interesting interpretation
              of the word `transient'.

              The  code  0 is special:  it indicates that all but
              the last line of multiline replies  read  from  the
              server  will be printed to standard error in a pro­
              cessed format.  By  convention,  servers  use  this
              mechanism  for  sending information for the user to
              read.  The appropriate reply code,  if  it  matches
              the same response, takes priority.

              If  ZFTP_VERBOSE is not set when zftp is loaded, it
              will be set to the default value  450,  i.e.,  mes­
              sages  destined for the user and all errors will be
              printed.  A null string is valid and specifies that
              no messages should be printed.

   Functions
       zftp_chpwd
              If  this  function is set by the user, it is called
              every time the directory  changes  on  the  server,
              including  when  a  user  is  logged  in, or when a

              will  be  unset;  otherwise it will reflect the new
              directory.

       zftp_progress
              If this function is set by the  user,  it  will  be
              called  during  a get, put or append operation each
              time sufficient data has  been  received  from  the
              host.   During  a get, the data is sent to standard
              output, so it is vital that  this  function  should
              write  to  standard error or directly to the termi­
              nal, not to standard output.

              When it is called with a transfer in progress,  the
              following additional shell parameters are set:

              ZFTP_FILE
                     The  name  of  the  remote file being trans­
                     ferred from or to.

              ZFTP_TRANSFER
                     A G for a get operation and a P  for  a  put
                     operation.

              ZFTP_SIZE
                     The  total  size  of the complete file being
                     transferred: the same  as  the  first  value
                     provided by the remote and local subcommands
                     for a particular file.  If the server cannot
                     supply  this  value  for a remote file being
                     retrieved, it will not be set.  If input  is
                     from  a  pipe the value may be incorrect and
                     correspond simply to a full pipe buffer.

              ZFTP_COUNT
                     The amount of data  so  far  transferred;  a
                     number  between zero and $ZFTP_SIZE, if that
                     is set.  This number is always available.

              The function is initially called with ZFTP_TRANSFER
              set  appropriately  and  ZFTP_COUNT  set  to  zero.
              After the transfer is finished, the  function  will
              be  called  one more time with ZFTP_TRANSFER set to
              GF or PF, in case it wishes to tidy up.  It is oth­
              erwise  never  called  twice with the same value of
              ZFTP_COUNT.

              Sometimes the progress meter may cause  disruption.
              It is up to the user to decide whether the function
              should be defined and to use unfunction when neces­
              sary.

       A  connection may not be opened in the left hand side of a
       pipe as this occurs in a subshell and the file information
       is  not updated in the main shell.  In the case of type or
       mode changes or closing the connection in a subshell,  the
       information  is  returned  but  variables  are not updated
       until the next call to zftp.  Other status changes in sub­
       shells  will  not be reflected by changes to the variables
       (but should be otherwise harmless).

       Deleting sessions while a zftp command is  active  in  the
       background  can  have  unexpected effects, even if it does
       not use the session being deleted.  This  is  because  all
       shell  subprocesses  share information on the state of all
       connections, and deleting a session changes  the  ordering
       of that information.

       On  some  operating systems, the control connection is not
       valid after a fork(), so that operations in subshells,  on
       the left hand side of a pipeline, or in the background are
       not possible, as they should be.  This is presumably a bug
       in the operating system.


THE ZSH/ZLE MODULE

       The zsh/zle module contains the Zsh Line Editor.  See zsh­
       zle(1).


THE ZSH/ZLEPARAMETER MODULE

       The zsh/zleparameter module defines two special parameters
       that can be used to access internal information of the Zsh
       Line Editor (see zshzle(1)).

       keymaps
              This array contains the names of the  keymaps  cur­
              rently defined.

       widgets
              This  associative array contains one entry per wid­
              get defined. The name of the widget is the key  and
              the value gives information about the widget. It is
              either the string `builtin' for builtin widgets,  a
              string  of  the  form  `user:name' for user-defined
              widgets, where name is the name of the shell  func­
              tion  implementing the widget, or it is a string of
              the  form  `completion:type:name',  for  completion
              widgets.  In  the last case type is the name of the
              builtin widgets the completion widget  imitates  in
              its  behavior  and  name  is  the name of the shell
              function implementing the completion widget.


THE ZSH/ZPROF MODULE

       When loaded, the zsh/zprof causes shell  functions  to  be
       profiled.   The profiling results can be obtained with the
       zprof builtin  command  made  available  by  this  module.

       the module.

       zprof [ -c ]
              Without  the  -c  option,  zprof  lists   profiling
              results to standard output.  The format is compara­
              ble to that of commands like gprof.

              At the top there is a summary listing all functions
              that  were  called  at least once.  This summary is
              sorted in decreasing order of the  amount  of  time
              spent in each.  The lines contain the number of the
              function in order, which is used in other parts  of
              the  list  in suffixes of the form `[num]'.RE, then
              the number of calls made to the function.  The next
              three  columns  list the time in milliseconds spent
              in the function and its  descendents,  the  average
              time  in milliseconds spent in the function and its
              descendents per call and  the  percentage  of  time
              spent  in all shell functions used in this function
              and its descendents.  The following  three  columns
              give  the  same  information, but counting only the
              time spent in the function itself.  The final  col­
              umn shows the name of the function.

              After the summary, detailed information about every
              function that was  invoked  is  listed,  sorted  in
              decreasing  order  of  the  amount of time spent in
              each function and its descendents.  Each  of  these
              entries  consists of descriptions for the functions
              that called the function  described,  the  function
              itself, and the functions that were called from it.
              The description for the  function  itself  has  the
              same  format  as in the summary (and shows the same
              information).  The other lines don't show the  num­
              ber of the function at the beginning and have their
              function named indented to make it easier  to  dis­
              tinguish the line showing the function described in
              the section from the surrounding lines.

              The information shown in this case  is  almost  the
              same as in the summary, but only refers to the call
              hierarchy being  displayed.   For  example,  for  a
              calling  function the column showing the total run­
              ning time lists the time  spent  in  the  described
              function  and  its  descendents  only for the times
              when it was called  from  that  particular  calling
              function.   Likewise,  for  a called function, this
              columns lists the total time spent  in  the  called
              function  and  its  descendents  only for the times
              when it was called from the function described.

              Also in this case, the column showing the number of
              calls to a function also shows a slash and then the

              function.

              As  long as the zsh/zprof module is loaded, profil­
              ing will be done and multiple  invocations  of  the
              zprof  builtin command will show the times and num­
              bers of calls since the module  was  loaded.   With
              the -c option, the zprof builtin command will reset
              its internal counters and will not show  the  list­
              ing.  )


THE ZSH/ZPTY MODULE

       The zsh/zpty module offers one builtin:

       zpty [ -e ] [ -b ] name [ arg ... ]
              The  arguments following name are concatenated with
              spaces between, then executed as a command,  as  if
              passed to the eval builtin.  The command runs under
              a newly assigned pseudo-terminal;  this  is  useful
              for running commands non-interactively which expect
              an interactive environment.  The name is  not  part
              of  the  command, but is used to refer to this com­
              mand in later calls to zpty.

              With the -e option, the pseudo-terminal is  set  up
              so that input characters are echoed.

              With  the  -b  option, input to and output from the
              pseudo-terminal are made non-blocking.

       zpty -d [ names ... ]
              The second form, with the -d  option,  is  used  to
              delete  commands previously started, by supplying a
              list of their names.  If no names  are  given,  all
              commands  are  deleted.   Deleting a command causes
              the HUP signal to be sent to the corresponding pro­
              cess.

       zpty -w [ -n ] name [ strings ... ]
              The  -w  option  can be used to send the to command
              name the  given  strings  as  input  (separated  by
              spaces).   If the -n option is not given, a newline
              is added at the end.

              If no strings are provided, the standard  input  is
              copied to the pseudo-terminal; this may stop before
              copying the full input if  the  pseudo-terminal  is
              non-blocking.

              Note  that  the  command  under the pseudo-terminal
              sees this input as if it were typed, so beware when
              sending  special  tty  driver  characters  such  as
              word-erase, line-kill, and end-of-file.

              The -r option can be used to read the output of the
              command  name.  With only a name argument, the out­
              put read is copied to the standard output.   Unless
              the  pseudo-terminal  is non-blocking, copying con­
              tinues until the command under the  pseudo-terminal
              exits; when non-blocking, only as much output as is
              immediately available is copied.  The return  value
              is zero if any output is copied.

              When  also given a param argument, at most one line
              is read and stored in the  parameter  named  param.
              Less   than   a  full  line  may  be  read  if  the
              pseudo-terminal is non-blocking.  The return  value
              is  zero  if  at  least  one character is stored in
              param.

              If a pattern is given as well, output is read until
              the  whole string read matches the pattern, even in
              the non-blocking case.  The return value is zero if
              the string read matches the pattern, or if the com­
              mand has exited but at least  one  character  could
              still  be  read.   As of this writing, a maximum of
              one megabyte of output can be consumed this way; if
              a  full  megabyte is read without matching the pat­
              tern, the return value is non-zero.

              In all cases, the return value is non-zero if noth­
              ing  could be read, and is 2 if this is because the
              command has finished.

              If the -r option is combined with  the  -t  option,
              zpty  tests whether output is available before try­
              ing to read.  If no output is available, zpty imme­
              diately returns the value 1.

       zpty -t name
              The  -t option without the -r option can be used to
              test whether the command name is still running.  It
              returns  a zero value if the command is running and
              a non-zero value otherwise.

       zpty [ -L ]
              The last form, without any arguments,  is  used  to
              list  the  commands  currently  defined.  If the -L
              option is given, this is done in the form of  calls
              to the zpty builtin.


THE ZSH/ZUTIL MODULE

       The zsh/zutil module only adds some builtins:

       zstyle [ -L ]
       zstyle [ -e | - | -- ] pattern style strings ...

       zstyle -g name [ pattern [ style ] ]
       zstyle -abs context style name [ sep ]
       zstyle -Tt context style [ strings ...]
       zstyle -m context style pattern
              This  builtin  command is used to define and lookup
              styles.  Styles are  pairs  of  names  and  values,
              where  the values consist of any number of strings.
              They are stored together with patterns  and  lookup
              is  done  by giving a string, called the `context',
              which is compared to the patterns.  The  definition
              stored  for  the  first  matching  pattern  will be
              returned.

              For ordering of comparisons, patterns are  searched
              from  most specific to least specific, and patterns
              that are equally specific keep the order  in  which
              they  were  defined.  A pattern is considered to be
              more specific than another if it contains more com­
              ponents  (substrings separated by colons) or if the
              patterns for  the  components  are  more  specific,
              where simple strings are considered to be more spe­
              cific than patterns and complex patterns  are  con­
              sidered to be more specific than the pattern `*'.

              The  first form (without arguments) lists the defi­
              nitions in the order zstyle will test them. If  the
              -L  option is given, listing is done in the form of
              calls to zstyle.  Forms with arguments:

              zstyle [ - | -- | -e ] pattern style strings ...
                     Defines the given style for the pattern with
                     the  strings as the value.  If the -e option
                     is given, the strings will  be  concatenated
                     (separated  by  spaces)  and  the  resulting
                     string will be evaluated (in the same way as
                     it is done by the eval builtin command) when
                     the style is looked up.  In  this  case  the
                     parameter  `reply'  must  be assigned to set
                     the strings returned after  the  evaluation.
                     Before evaluating the value, reply is unset,
                     and if it is still unset after  the  evalua­
                     tion, the style is treated as if it were not
                     set.

              zstyle -d [ pattern [ styles ... ] ]
                     Delete style definitions. Without  arguments
                     all  definitions are deleted, with a pattern
                     all definitions for that pattern are deleted
                     and if any styles are given, then only those
                     styles are deleted for the pattern.

              zstyle -g name [ pattern [ style ] ]
                     Retrieve a style  definition.  The  name  is

                     results  are  stored.  Without  any  further
                     arguments,    all   patterns   defined   are
                     returned. With a pattern the styles  defined
                     for  that pattern are returned and with both
                     a pattern and a style, the value strings  of
                     that combination is returned.

              The other forms can be used to look up or test pat­
              terns.

              zstyle -s context style name [ sep ]
                     The parameter name is set to  the  value  of
                     the  style  interpreted as a string.  If the
                     value contains several strings they are con­
                     catenated  with  spaces  (or  with  the  sep
                     string if that is given) between them.

              zstyle -b context style name
                     The value is stored in name  as  a  boolean,
                     i.e.  as  the  string `yes' if the value has
                     only one string and that string is equal  to
                     one  of  `yes', `true', `on', or `1'. If the
                     value is any other string or has  more  than
                     one string, the parameter is set to `no'.

              zstyle -a context style name
                     The  value is stored in name as an array. If
                     name is declared as  an  associative  array,
                     the  first,  third, etc. strings are used as
                     the keys and the other strings are  used  as
                     the values.

              zstyle -t context style [ strings ...]
              zstyle -T context style [ strings ...]
                     Test  the  value  of  a  style,  i.e. the -t
                     option only  returns  a  status  (sets  $?).
                     Without  any  strings  the  return status is
                     zero if the style is defined  for  at  least
                     one matching pattern, has only one string in
                     its value, and  that  is  equal  to  one  of
                     `true',  `yes',  `on' or `1'. If any strings
                     are given the status is zero if and only  if
                     at  least  one of the strings is equal to at
                     least one of the strings in  the  value.  If
                     the style is not defined, the status is 2.

                     The  -T option tests the values of the style
                     like -t, but it returns zero (rather than 2)
                     if the style is not defined for any matching
                     pattern.

              zstyle -m context style pattern
                     Match a value. Returns status  zero  if  the

                     in the value.

       zformat -f param format specs ...
       zformat -a array sep specs ...
              This builtin provides two different forms  of  for­
              matting.  The  first  form  is selected with the -f
              option. In this case the format string will be mod­
              ified  by  replacing sequences starting with a per­
              cent sign in it with strings from the specs.   Each
              spec should be of the form `char:string' which will
              cause every appearance of the sequence  `%char'  in
              format  to  be  replaced  by  the  string.  The `%'
              sequence may also contain optional minimum and max­
              imum field width specifications between the `%' and
              the `char' in the form `%min.maxc', i.e. the  mini­
              mum  field  width is given first and if the maximum
              field width is used, it has to  be  preceded  by  a
              dot.   Specifying  a  minimum field width makes the
              result be padded with spaces to the  right  if  the
              string   is   shorter  than  the  requested  width.
              Padding to the left can be  achieved  by  giving  a
              negative  minimum  field width.  If a maximum field
              width is specified, the string  will  be  truncated
              after   that   many   characters.   After  all  `%'
              sequences for the given specs have been  processed,
              the  resulting  string  is  stored in the parameter
              param.

              The second form, using the -a option, can  be  used
              for  aligning  strings.  Here, the specs are of the
              form `left:right'  where  `left'  and  `right'  are
              arbitrary  strings.   These strings are modified by
              replacing the colons by the sep string and  padding
              the  left  strings with spaces to the right so that
              the sep strings in the result (and hence the  right
              strings  after them) are all aligned if the strings
              are printed below each other.  All strings  without
              a  colon are left unchanged and all strings with an
              empty right string have the trailing colon removed.
              In  both  cases  the lengths of the strings are not
              used to determine how the other strings are  to  be
              aligned.   The  resulting strings are stored in the
              array.

       zregexparse
              This implements some internals of the  _regex_argu­
              ments function.

       zparseopts [ -D ] [ -K ] [ -E ] [ -a array ] [ -A assoc ]
              specs
              This builtin simplifies the parsing of  options  in
              positional  parameters,  i.e.  the set of arguments
              given by $*.  Each spec describes  one  option  and

              described by opt is found in the positional parame­
              ters it is copied into the array specified with the
              -a option; if the optional `=array' is given, it is
              instead copied into that array.

              Note  that  it is an error to give any spec without
              an `=array' unless one of the -a or -A  options  is
              used.

              Unless the -E option is given, parsing stops at the
              first string that isn't described  by  one  of  the
              specs.   Even  with  -E,  parsing always stops at a
              positional parameter equal to `-' or `--'.

              The opt description must be one of  the  following.
              Any  of  the  special  characters can appear in the
              option name provided it is preceded by a backslash.

              name
              name+  The  name  is the name of the option without
                     the leading `-'.   To  specify  a  GNU-style
                     long  option,  one  of the usual two leading
                     `-' must be included in name; for example, a
                     `--file'  option is represented by a name of
                     `-file'.

                     If a `+' appears after name, the  option  is
                     appended  to  array each time it is found in
                     the positional parameters; without  the  `+'
                     only  the  last  occurrence of the option is
                     preserved.

                     If one of these forms is  used,  the  option
                     takes  no  argument, so parsing stops if the
                     next  positional  parameter  does  not  also
                     begin  with  `-'  (unless  the  -E option is
                     used).

              name:
              name:-
              name:: If one or two colons are given,  the  option
                     takes an argument; with one colon, the argu­
                     ment is mandatory and with two colons it  is
                     optional.   The  argument is appended to the
                     array after the option itself.

                     An optional argument is put  into  the  same
                     array  element as the option name (note that
                     this makes empty strings as arguments indis­
                     tinguishable).    A  mandatory  argument  is
                     added as a separate element unless the  `:-'
                     form  is used, in which case the argument is
                     put into the same element.

                     the name and the first colon.

       The options of zparseopts itself are:

       -a array
              As described above, this names the default array in
              which to store the recognised options.

       -A assoc
              If this is given, the options and their values  are
              also  put into an associative array with the option
              names as keys and the arguments  (if  any)  as  the
              values.

       -D     If  this  option  is  given,  all options found are
              removed from the positional parameters of the call­
              ing  shell or shell function, up to but not includ­
              ing any not described by the specs.  This is  simi­
              lar to using the shift builtin.

       -K     With  this option, the arrays specified with the -a
              and -A options and with the `=array' forms are kept
              unchanged  when none of the specs for them is used.
              This allows assignment of default  values  to  them
              before calling zparseopts.

       -E     This  changes  the parsing rules to not stop at the
              first string that isn't described  by  one  of  the
              specs.   It  can  be  used  to test for or (if used
              together with -D) extract options and  their  argu­
              ments,  ignoring  all  other  options and arguments
              that may be in the positional parameters.

       For example,

              set -- -a -bx -c y -cz baz -cend
              zparseopts a=foo b:=bar c+:=bar

       will have the effect of

              foo=(-a)
              bar=(-b x -c y -c z)

       The arguments from `baz' on will not be used.

       As an example for the -E option, consider:

              set -- -a x -b y -c z arg1 arg2
              zparseopts -E -D b:=bar

       will have the effect of

              bar=(-b y)


       I.e., the option -b and its arguments are taken  from  the
       positional parameters and put into the array bar.


Man(1) output converted with man2html