zshmodules(1) - phpMan

Command: man perldoc info search(apropos)  

ZSHMODULES(1)                                                    ZSHMODULES(1)

       zshmodules - zsh loadable modules

       Some  optional  parts  of  zsh are in modules, separate from the core of the shell.
       Each of these modules may be linked in to the shell at build time, or can be dynam-
       ically linked while the shell is running if the installation supports this feature.
       Modules are linked at runtime with the zmodload command, see zshbuiltins(1).

       The modules that are bundled with the zsh distribution are:

              Builtins for manipulating extended attributes (xattr).

              Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege) sets.

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

              The compctl builtin for controlling completion.

              The basic completion code.

              Completion listing extensions.

              A module with utility builtins needed for the shell function  based  comple-
              tion system.

              curses windowing commands

              Some date/time commands and parameters.

              A ZLE function duplicating EMACS' zap-to-char.

              An example of how to write a module.

              Some basic file manipulation commands as builtins.

              Access to external files via a special associative array.

              Standard scientific functions for use in mathematical evaluations.

              Arrange for files for new users to be installed.

              Access to internal hash tables via special associative arrays.

              Interface to the PCRE library.

              Interface to the POSIX regex library.

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

              Manipulation of Unix domain sockets

              A builtin command interface to the stat system call.

              A builtin interface to various low-level system features.

              Manipulation of TCP sockets

              Interface to the termcap database.

              Interface to the terminfo database.

              A builtin FTP client.

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

              Access to internals of the Zsh Line Editor via parameters.

              A module allowing profiling for shell functions.

              A builtin for starting a command in a pseudo-terminal.

              Block and return when file descriptors are ready.

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

       The zsh/attr module is used for manipulating extended attributes.   The  -h  option
       causes  all  commands  to  operate on symbolic links instead of their targets.  The
       builtins in this module are:

       zgetattr [ -h ] filename attribute [ parameter ]
              Get the extended attribute attribute from the  specified  filename.  If  the
              optional argument parameter is given, the attribute is set on that parameter
              instead of being printed to stdout.

       zsetattr [ -h ] filename attribute value
              Set the extended attribute attribute on the specified filename to value.

       zdelattr [ -h ] filename attribute
              Remove the extended attribute attribute from the specified filename.

       zlistattr [ -h ] filename [ parameter ]
              List the extended attributes currently set on the specified filename. If the
              optional  argument parameter is given, the list of attributes is set on that
              parameter instead of being printed to stdout.

       zgetattr and zlistattr allocate memory dynamically.  If the attribute  or  list  of
       attributes  grows  between  the allocation and the call to get them, they return 2.
       On all other errors, 1 is returned.  This allows the calling function to check  for
       this case and retry.

       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  dis-
              plays the capability sets on each specified filename.

       setcap capabilities filename ...
              This  is  a  built-in implementation of the POSIX standard utility.  It sets
              the capability sets on each specified filename to  the  specified  capabili-

       The zsh/clone module makes available one builtin command:

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

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

              The  target of clone should be an unused terminal, such as an unused virtual
              console or a virtual terminal created by

              xterm -e sh -c 'trap : INT QUIT TSTP; tty;  while  :;  do  sleep  100000000;

              Some  words of explanation are warranted about this long xterm command line:
              when doing clone on a pseudo-terminal, some other session  ("session"  meant
              as  a  unix session group, or SID) is already owning the terminal. Hence the
              cloned zsh cannot acquire the pseudo-terminal as  a  controlling  tty.  That
              means two things:

              the job control signals will go to the sh-started-by-xterm process
                    group (that's why we disable INT QUIT and TSTP with trap; otherwise
                    the while loop could get suspended or killed)

              the cloned shell will have job control disabled, and the job
                    control keys (control-C, control-\ and control-Z) will not work.

              This does not apply when cloning to an unused vc.

              Cloning  to  a  used  (and unprepared) terminal will result in two processes
              reading simultaneously from the same terminal, with input bytes  going  ran-
              domly to either process.

              clone is mostly useful as a shell built-in replacement for openvt.

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

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

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

   Colored completion listings
       Whenever  one  of  the parameters ZLS_COLORS or ZLS_COLOURS is set and the zsh/com-
       plist 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 specifica-
       tions of the form 'name=value'.  The name may be one of the following strings, most
       of  which  specify  file  types  for which the value will be used.  The strings and
       their default values are:

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

       fi 0   for regular files

       di 32  for directories

       ln 36  for symbolic links.  If this has the special value  target,  symbolic  links
              are dereferenced and the target file used to determine the display format.

       pi 31  for named pipes (FIFOs)

       so 33  for sockets

       bd 44;37
              for block devices

       cd 44;37
              for character devices

       or none
              for a symlink to nonexistent file (default is the value defined for ln)

       mi none
              for  a non-existent file (default is the value defined for fi); this code is
              currently not used

       su 37;41
              for files with setuid bit set

       sg 30;43
              for files with setgid bit set

       tw 30;42
              for world writable directories with sticky bit set

       ow 34;43
              for world writable directories without sticky bit set

       sa none
              for files with an associated suffix alias; this is only  tested  after  spe-
              cific suffixes, as described below

       st 37;44
              for directories with sticky bit set but not world writable

       ex 35  for executable files

       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 ('=') followed by a pat-
       tern;  the  EXTENDED_GLOB  option  will be turned on for evaluation of the 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 the form with the
       leading equal sign take precedence over the values defined for file types, which in
       turn take precedence over the form with the leading asterisk (file extensions).

       The  leading-equals form also allows different parts of the displayed strings to be
       colored differently.  For this, the pattern has to use the '(#b)' globbing flag and
       pairs  of  parentheses  surrounding the parts of the strings that are to be colored
       differently.  In this case the value may consist of more than one color code  sepa-
       rated  by  equal  signs.   The  first  code will be used for all parts for which no
       explicit code is specified and the following codes  will  be  used  for  the  parts
       matched  by  the  sub-patterns  in  parentheses.   For  example,  the specification
       '=(#b)(?)*(?)=0=3=7' will be used for all matches which are at least two characters
       long  and will use the code '3' for the first character, '7' for the last character
       and '0' for the rest.

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

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

       When printing a match, the code prints the value of lc, the value for the file-type
       or  the last matching specification with a '*', the value of rc, the string to dis-
       play for the match itself, and then the value of ec if that is defined or the  val-
       ues of lc, no, and rc if ec is not defined.

       The  default values are ISO 6429 (ANSI) compliant and can be used on vt100 compati-
       ble terminals such as xterms.  On monochrome terminals the default values will have
       no  visible  effect.   The colors function from the contribution can be used to get
       associative arrays containing the codes for ANSI terminals (see the section  'Other
       Functions'  in  zshcontrib(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 zshcomp-

   Scrolling in completion listings
       To enable scrolling through a completion list, the  LISTPROMPT  parameter  must  be
       set.   Its  value  will be used as the prompt; if it is the empty string, a default
       prompt will be used.  The value may contain escapes of the form '%x'.  It  supports
       the  escapes  '%B',  '%b',  '%S',  '%s',  '%U',  '%u',  '%F',  '%f', '%K', '%k' 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 lowercase form will not be padded.

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

              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

              stop listing but take no other action

       Every  other  character  stops  listing and immediately processes the key as usual.
       Any key that is not bound in the listscroll  keymap  or  that  is  bound  to  unde-
       fined-key is looked up in the keymap currently selected.

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

   Menu selection
       The  zsh/complist module also offers an alternative style of selecting matches from
       a list, called menu selection, which can be used if the shell is set up  to  return
       to  the  last  prompt  after  showing a completion list (see the ALWAYS_LAST_PROMPT
       option in zshoptions(1)).

       Menu selection can be invoked directly by the widget menu-select  defined  by  this
       module.   This is a standard ZLE widget that can be bound to a key in the usual way
       as described in zshzle(1).

       Alternatively, the parameter MENUSELECT can be set to an integer, which  gives  the
       minimum  number  of matches that must be present before menu selection is automati-
       cally 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 number of lines of the screen minus the (absolute) value.

       As for the ZLS_COLORS, ZLS_COLOURS and LISTPROMPT  parameters,  neither  MENUPROMPT
       nor  MENUSCROLL  should be set directly when using the shell function based comple-
       tion 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  suffixes
       that  are not displayed).  In the list used for menu selection, however, even these
       matches are shown so that it is possible to select them.  To highlight such matches
       the  hi  and  du capabilities in the ZLS_COLORS and ZLS_COLOURS parameters are sup-
       ported for hidden matches of the first and second kind, respectively.

       Selecting matches is done by moving the mark around using the  zle  movement  func-
       tions.   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.  Note that the following
       always perform the same task within the menu selection map and cannot  be  replaced
       by user defined widgets, nor can the set of functions be extended:

       accept-line, accept-search
              accept the current match and leave menu selection (but do not cause the com-
              mand line to be accepted)

              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

              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 imme-
              diately 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  func-
              tions which are otherwise special during menu selection)

       undo   removes matches inserted during the menu selection by one of the three func-
              tions before

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

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

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

       backward-char, vi-backward-char
              moves the mark one column left

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

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

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

              moves the mark to the last line of the previous group of matches

              moves the mark to the first line

              moves the mark to the last line

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

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

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

              moves the mark to the previous match

              this toggles between normal and interactive mode; in  interactive  mode  the
              keys  bound  to  self-insert  and self-insert-unmeta insert into the command
              line as in normal editing mode but without  leaving  menu  selection;  after
              each  character  completion  is  tried again and the list changes to contain
              only the new matches; the completion widgets make  the  longest  unambiguous
              string  be inserted in the command line and undo and backward-delete-char go
              back to the previous set of matches

              this starts incremental searches in the list of  completions  displayed;  in
              this  mode,  accept-line  only  leaves incremental search, going back to the
              normal menu selection mode

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

       During this selection the widget uses the keymap menuselect.  Any key that  is  not
       defined in this keymap or that is bound to undefined-key is looked up in the keymap
       currently selected.  This is used to ensure that the most important keys used  dur-
       ing  selection  (namely  the  cursor keys, return, and TAB) have sensible defaults.
       However, keys in the menuselect keymap can be modified directly using  the  bindkey
       builtin command (see zshmodules(1)). For example, to make the return key leave menu
       selection without accepting the match currently selected one could call

              bindkey -M menuselect '^M' send-break

       after loading the zsh/complist module.

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

              This is used by the _arguments function to do the argument and command  line
              parsing.   Like  compdescribe it has an option -i to do the parsing and ini-
              tialize some internal state and various options to access the state informa-
              tion to decide what should be completed.

              This is used by the _describe function to build the displays for the matches
              and to get the strings to add as matches with their options.  On  the  first
              call  one  of the options -i or -I should be supplied as the first argument.
              In the first case, display strings without the descriptions will  be  gener-
              ated, 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 different  sets  of  matches  and
              store  the  options in the first array, the strings with descriptions in the
              second, the matches for these in the third, the strings without descriptions
              in  the fourth, and the matches for them in the fifth array.  These are then
              directly given to compadd to register the matches with the completion  code.

              Used by the _path_files function to optimize complex recursive filename gen-
              eration (globbing).  It does three things.  With the -p and  -P  options  it
              builds  the  glob  patterns  to use, including the paths already handled and
              trying to optimize the patterns with respect to the prefix and  suffix  from
              the line and the match specification currently used.  The -i option does the
              directory tests for the ignore-parents style and the -r option  tests  if  a
              component  for  some  of the matches are equal to the string on the line and
              removes all other matches if that is true.

              Used by the _tags function to implement the  internals  of  the  group-order
              style.  This only takes its arguments as names of completion groups and cre-
              ates 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 lead-
              ing equal sign will not be quoted.

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

              These implement the internals of the tags mechanism.

              Like comparguments, but for the _values function.

       The zsh/curses module makes available one builtin command and various parameters.

       zcurses init
       zcurses end
       zcurses addwin targetwin nlines ncols begin_y begin_x [ parentwin ]
       zcurses delwin targetwin
       zcurses refresh [ targetwin ... ]
       zcurses touch targetwin ...
       zcurses move targetwin new_y new_x
       zcurses clear targetwin [ redraw | eol | bot ]
       zcurses position targetwin array
       zcurses char targetwin character
       zcurses string targetwin string
       zcurses border targetwin border
       zcurses attr targetwin [ {+/-}attribute | fg_col/bg_col ] [...]
       zcurses bg targetwin [ {+/-}attribute | fg_col/bg_col | @char ] [...]
       zcurses scroll targetwin [ on | off | {+/-}lines ]
       zcurses input targetwin [ param [ kparam [ mparam ] ] ]
       zcurses mouse [ delay num | {+/-}motion ]
       zcurses timeout targetwin intval
       zcurses querychar targetwin [ param ]
              Manipulate curses windows.  All uses of this command should be bracketed  by
              'zcurses  init'  to  initialise  use of curses, and 'zcurses end' to end it;
              omitting 'zcurses end' can cause the terminal to be in an unwanted state.

              The subcommand addwin creates a window with nlines lines and ncols  columns.
              Its  upper  left  corner will be placed at row begin_y and column begin_x of
              the screen.  targetwin is a string and refers to the name of a  window  that
              is  not  currently  assigned.  Note in particular the curses convention that
              vertical values appear before horizontal values.

              If addwin is given an existing window as the final argument, the new  window
              is  created  as a subwindow of parentwin.  This differs from an ordinary new
              window in that the memory of the window contents is shared with the parent's
              memory.   Subwindows  must  be  deleted  before their parent.  Note that the
              coordinates of subwindows are relative to the screen,  not  the  parent,  as
              with other windows.

              Use the subcommand delwin to delete a window created with addwin.  Note that
              end does not implicitly delete windows, and that delwin does not  erase  the
              screen image of the window.

              The  window  corresponding  to  the full visible screen is called stdscr; it
              always exists after 'zcurses init' and cannot be delete with delwin.

              The subcommand refresh will refresh window targetwin; this is  necessary  to
              make  any  pending  changes (such as characters you have prepared for output
              with char) visible on the screen.  refresh without an  argument  causes  the
              screen to be cleared and redrawn.  If multiple windows are given, the screen
              is updated once at the end.

              The subcommand touch marks the targetwins listed as changed.  This is neces-
              sary before refreshing windows if a window that was in front of another win-
              dow (which may be stdscr) is deleted.

              The subcommand move moves the cursor position in targetwin  to  new  coordi-
              nates new_y and new_x.  Note that the subcommand string (but not the subcom-
              mand char) advances the cursor position over the characters added.

              The subcommand clear erases the contents of targetwin.   One  (and  no  more
              than  one)  of  three  options may be specified.  With the option redraw, in
              addition the next refresh of targetwin will cause the screen to  be  cleared
              and repainted.  With the option eol, targetwin is only cleared to the end of
              the current cursor line.  With the option bot, targetwin is cleared  to  the
              end  of  the  window,  i.e  everything  to the right and below the cursor is

              The subcommand position writes various positions associated  with  targetwin
              into the array named array.  These are, in order:

              The y and x coordinates of the cursor relative to the top left
                     of targetwin

              The y and x coordinates of the top left of targetwin on the

              The size of targetwin in y and x dimensions.

              Outputting  characters  and  strings are achieved by char and string respec-

              To draw a border around window targetwin, use border.  Note that the  border
              is not subsequently handled specially:  in other words, the border is simply
              a set of characters output at the edge of the window.  Hence it can be over-
              written, can scroll off the window, etc.

              The subcommand attr will set targetwin's attributes or foreground/background
              color pair for any successive character output.  Each attribute given on the
              line  may  be  prepended  by a + to set or a - to unset that attribute; + is
              assumed if absent.  The attributes supported are blink, bold, dim,  reverse,
              standout, and underline.

              Each  fg_col/bg_col  attribute  (to  be read as 'fg_col on bg_col') sets the
              foreground and background color for character output.  The color default  is
              sometimes  available  (in  particular if the library is ncurses), specifying
              the foreground or background color with which  the  terminal  started.   The
              color pair default/default is always available.

              bg overrides the color and other attributes of all characters in the window.
              Its usual use is to set the background initially, but it will overwrite  the
              attributes  of any characters at the time when it is called.  In addition to
              the arguments allowed with attr, an argument @char specifies a character  to
              be  shown  in  otherwise blank areas of the window.  Owing to limitations of
              curses this cannot be a multibyte character (use of ASCII characters only is
              recommended).   As  the  specified  set  of attributes override the existing
              background, turning attributes off in the arguments is  not  useful,  though
              this does not cause an error.

              The  subcommand  scroll  can  be  used  with on or off to enabled or disable
              scrolling of a window when the cursor would otherwise move below the  window
              due  to  typing  or output.  It can also be used with a positive or negative
              integer to scroll the window up or down the given number  of  lines  without
              changing the current cursor position (which therefore appears to move in the
              opposite direction  relative  to  the  window).   In  the  second  case,  if
              scrolling  is  off  it  is  temporarily  turned on to allow the window to be

              The subcommand input reads a single character from the window without  echo-
              ing  it back.  If param is supplied the character is assigned to the parame-
              ter param, else it is assigned to the parameter REPLY.

              If both param and kparam are supplied, the key is read in 'keypad' mode.  In
              this  mode special keys such as function keys and arrow keys return the name
              of the key in the parameter kparam.  The key names are the macros defined in
              the  curses.h  or  ncurses.h  with  the  prefix 'KEY_' removed; see also the
              description of the parameter zcurses_keycodes below.   Other  keys  cause  a
              value  to  be  set  in  param as before.  On a successful return only one of
              param or kparam contains a non-empty string; the other is set  to  an  empty

              If  mparam  is also supplied, input attempts to handle mouse input.  This is
              only available with the ncurses library; mouse handling can be  detected  by
              checking  for  the  exit  status of 'zcurses mouse' with no arguments.  If a
              mouse button is  clicked  (or  double-  or  triple-clicked,  or  pressed  or
              released with a configurable delay from being clicked) then kparam is set to
              the string MOUSE, and mparam is set to an array consisting of the  following
              -      An  identifier  to discriminate different input devices; this is only
                     rarely useful.
              -      The x, y and z coordinates of the mouse click relative  to  the  full
                     screen,  as  three  elements in that order (i.e. the y coordinate is,
                     unusually, after the x coordinate).  The z coordinate is only  avail-
                     able for a few unusual input devices and is otherwise set to zero.
              -      Any  events  that  occurred  as separate items; usually there will be
                     just one.  An event consists  of  PRESSED,  RELEASED,  CLICKED,  DOU-
                     BLE_CLICKED  or TRIPLE_CLICKED followed immediately (in the same ele-
                     ment) by the number of the button.
              -      If the shift key was pressed, the string SHIFT.
              -      If the control key was pressed, the string CTRL.
              -      If the alt key was pressed, the string ALT.

              Not all mouse events may be passed through to the terminal window; most ter-
              minal  emulators handle some mouse events themselves.  Note that the ncurses
              manual implies that using input both with and  without  mouse  handling  may
              cause the mouse cursor to appear and disappear.

              The  subcommand  mouse can be used to configure the use of the mouse.  There
              is no window argument; mouse options are global.  'zcurses  mouse'  with  no
              arguments  returns  status  0  if mouse handling is possible, else status 1.
              Otherwise, the possible arguments (which may be combined on the same command
              line)  are  as  follows.   delay  num sets the maximum delay in milliseconds
              between press and release events to be considered as a click;  the  value  0
              disables click resolution, and the default is one sixth of a second.  motion
              proceeded by an optional '+' (the default) or - turns on or off reporting of
              mouse  motion  in addition to clicks, presses and releases, which are always
              reported.  However, it appears reports for mouse motion  are  not  currently

              The  subcommand  timeout specifies a timeout value for input from targetwin.
              If intval is negative, 'zcurses input' waits indefinitely for a character to
              be  typed;  this is the default.  If intval is zero, 'zcurses input' returns
              immediately; if there is typeahead it is returned, else no input is done and
              status  1  is returned.  If intval is positive, 'zcurses input' waits intval
              milliseconds for input and if there is  none  at  the  end  of  that  period
              returns status 1.

              The  subcommand  querychar queries the character at the current cursor posi-
              tion.  The return values are stored in the array named  param  if  supplied,
              else  in  the array reply.  The first value is the character (which may be a
              multibyte character if the system supports them); the second  is  the  color
              pair  in  the  usual fg_col/bg_col notation, or 0 if color is not supported.
              Any attributes other than color that apply to the character, as set with the
              subcommand attr, appear as additional elements.

              Readonly integer.  The maximum number of colors the terminal supports.  This
              value is initialised by the curses library and is not  available  until  the
              first time zcurses init is run.

              Readonly  integer.  The maximum number of color pairs fg_col/bg_col that may
              be defined in 'zcurses attr' commands; note this limit applies to all  color
              pairs  that  have  been used whether or not they are currently active.  This
              value is initialised by the curses library and is not  available  until  the
              first time zcurses init is run.

              Readonly  array.   The attributes supported by zsh/curses; available as soon
              as the module is loaded.

              Readonly array.  The colors supported by zsh/curses; available  as  soon  as
              the module is loaded.

              Readonly  array.   The  values  that may be returned in the second parameter
              supplied to 'zcurses input' in the order in which they  are  defined  inter-
              nally by curses.  Not all function keys are listed, only F0; curses reserves
              space for F0 up to F63.

              Readonly array.  The current list of windows, i.e.  all  windows  that  have
              been created with 'zcurses addwin' and not removed with 'zcurses delwin'.

       The zsh/datetime module makes available one builtin command:

       strftime [ -s scalar ] format epochtime
       strftime -r [ -q ] [ -s scalar ] format timestring
              Output the date denoted by epochtime in the format specified.

              With  the  option  -r  (reverse),  use  the format format to parse the input
              string timestring and output the number of seconds since the epoch at  which
              the  time occurred.  If no timezone is parsed, the current timezone is used;
              other parameters are set to zero if not present.   If  timestring  does  not
              match  format  the  command  returns status 1; it will additionally print an
              error message unless the option -q (quiet) is given.  If timestring  matches
              format  but  not all characters in timestring were used, the conversion suc-
              ceeds; however, a warning is issued unless the  option  -q  is  given.   The
              matching  is  implemented  by the system function strptime; see strptime(3).
              This means that zsh format extensions are not available, however for reverse
              lookup  they are not required.  If the function is not implemented, the com-
              mand returns status 2 and (unless -q is given) prints a message.

              If -s scalar is given, assign the date string (or epoch time in  seconds  if
              -r is given) to scalar instead of printing it.

       The zsh/datetime module makes available several parameters; all are readonly:

              A  floating  point value representing the number of seconds since the epoch.
              The notional accuracy is to nanoseconds if the clock_gettime call is  avail-
              able and to microseconds otherwise, but in practice the range of double pre-
              cision floating point and shell  scheduling  latencies  may  be  significant

              An integer value representing the number of seconds since the epoch.

              An array value containing the number of seconds since the epoch in the first
              element and the remainder of the time since the epoch in nanoseconds in  the
              second  element.  To ensure the two elements are consistent the array should
              be copied or otherwise referenced as a single substitution before the values
              are used.  The following idiom may be used:

                     for secs nsecs in $epochtime; do

       The zsh/deltochar module makes available two ZLE functions:

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

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

       The zsh/example module makes available one builtin command:

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

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

       The zsh/files module makes available some common commands for file manipulation  as
       builtins; these commands are probably not needed for many normal situations but can
       be useful in emergency recovery situations with constrained  resources.   The  com-
       mands  do not implement all features now required by relevant standards committees.

       For all commands, a variant beginning zf_ is also available  and  loaded  automati-
       cally.   Using  the  features  capability  of zmodload will let you load only those
       names you want.

       The commands loaded by default are:

       chgrp [ -hRs ] group filename ...
              Changes group of files specified.   This  is  equivalent  to  chown  with  a
              user-spec argument of ':group'.

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

              The user-spec can be in four forms:

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

              In  each case, the ':' may instead be a '.'.  The rule is that if there is a
              ':' then the separator is ':', otherwise if there is a '.' then the  separa-
              tor is '.', otherwise there is no separator.

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

              If the target is a symbolic link, the -h option causes chown to set the own-
              ership of the link instead of its target.

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

              The -s option is a zsh extension to chown functionality.  It  enables  para-
              noid  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 directo-
              ries, so that a recursive chown of a deep directory tree can't end up recur-
              sively chowning /usr as a result of directories being moved up the tree.

       ln [ -dfhins ] filename dest
       ln [ -dfhins ] filename ... dir
              Creates  hard  (or, with -s, symbolic) links.  In the first form, the speci-
              fied 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 path-
              name 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 directories.  This  does  not
              apply to symbolic links in any case.

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

              The -h and -n options are identical and both exist for compatibility; either
              one indicates that if the target is a symlink then it should not be derefer-
              enced.  Typically this is used in combination with -sf so that if an  exist-
              ing link points to a directory then it will be removed, instead of followed.
              If this option is used with multiple filenames and the target is a  symbolic
              link pointing to a directory then the result is an error.

       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 direc-
              tory  already exists.  The -m option can be used to specify (in octal) a set
              of file permissions for the created directories, otherwise mode 777 modified
              by the current umask (see umask(2)) is used.

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

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

              Note that this mv will not move files across devices.   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.  Typically only the super-user can actually
              succeed in unlinking directories in this way.  -d takes precedence over  -r.

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

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

              The  -s  option is a zsh extension to rm functionality.  It enables paranoid
              behaviour, intended to avoid common security problems involving  a  root-run
              rm  being tricked into removing files other than the ones intended.  It will
              refuse  to   follow   symbolic   links,   so   that   (for   example)   ''rm
              /tmp/foo/passwd''  can't accidentally remove /etc/passwd if /tmp/foo happens
              to be a link to /etc.  It will also check where it is after leaving directo-
              ries,  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

       rmdir dir ...
              Removes empty directories specified.

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

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

              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

              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.

              A file may conveniently be read into an array as one line per  element  with
              the  form 'array=("${(f)mapfile[filename]}")'.  The double quotes are neces-
              sary to prevent empty lines from being removed.

       Although reading and writing of the file in question is efficiently handled,  zsh's
       internal  memory management may be arbitrarily baroque; however, mapfile is usually
       very much more efficient than anything involving a loop.  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  opera-
       tions).   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

       No errors are printed or flagged for non-existent, unreadable, or unwritable files,
       as the parameter mechanism is too low in the shell execution hierarchy to make this

       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 provides standard mathematical functions for use when eval-
       uating mathematical formulae.  The syntax agrees with normal C and FORTRAN  conven-
       tions, 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  auto-
       matically  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  cor-
       responding  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 argument: acos,  acosh,  asin,
       asinh,  atan,  atanh,  cbrt,  ceil,  cos, cosh, erf, erfc, exp, expm1, fabs, floor,
       gamma, j0, j1, lgamma, log, log10, log1p, logb, sin, sinh, sqrt, tan, tanh, y0, y1.
       The  atan  function can optionally take a second argument, in which case it behaves
       like the C function atan2.  The ilogb function takes a single floating point  argu-
       ment, 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(RPAR' and 'signgam' are distinct expressions.

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

       The  following take an integer first argument and a floating 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 floating point number  or  an  integer.   The  functions
       float  and  int  convert their arguments into a floating point or integer value (by
       truncation) respectively.

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

       The  function  rand48  is  available  if your system's mathematical library has the
       function erand48(3).  It returns a pseudo-random floating point  number  between  0
       and 1.  It takes a single string optional argument.

       If  the  argument  is  not  present, the random number seed is initialised by three
       calls to the rand(3) function --- this produces the same random numbers as the next
       three values of $RANDOM.

       If  the argument is present, it gives the name of a scalar parameter where the cur-
       rent random number seed will be stored.  On the first call, the value must  contain
       at least twelve hexadecimal digits (the remainder of the string is ignored), or the
       seed will be initialised in the same manner as for a call to rand48 with  no  argu-
       ment.  Subsequent calls to rand48(param) will then maintain the seed in the parame-
       ter param as a string of twelve hexadecimal digits, with no  base  signifier.   The
       random  number  sequences  for different parameters are completely independent, and
       are also independent from that used by calls to rand48 with no argument.

       For example, consider

              print $(( rand48(seed) ))
              print $(( rand48() ))
              print $(( rand48(seed) ))

       Assuming $seed does not exist, it will be initialised by the first  call.   In  the
       second  call,  the  default seed is initialised; note, however, that because of the
       properties of rand() there is a correlation between the seeds used for the two ini-
       tialisations,  so  for more secure uses, you should generate your own 12-byte seed.
       The third call returns to the same sequence of random numbers  used  in  the  first
       call, unaffected by the intervening rand48().

       The zsh/newuser module is loaded at boot if it is available, the RCS option is set,
       and the PRIVILEGED option is not set (all three are true by default).   This  takes
       place immediately after commands in the global zshenv file (typically /etc/zshenv),
       if any, have been executed.  If the module is not available it is silently  ignored
       by the shell; the module may safely be removed from $MODULE_PATH by the administra-
       tor if it is not required.

       On loading, the module tests if any  of  the  start-up  files  .zshenv,  .zprofile,
       .zshrc or .zlogin exist in the directory given by the environment variable ZDOTDIR,
       or the user's home directory if that is not set.  The test is not performed and the
       module  halts  processing  if  the  shell  was  in an emulation mode (i.e. had been
       invoked as some other shell than zsh).

       If none of the start-up files were found,  the  module  then  looks  for  the  file
       newuser  first  in  a  sitewide  directory,  usually  the  parent  directory of the
       site-functions directory, and if that is not found the module searches  in  a  ver-
       sion-specific  directory,  usually the parent of the functions directory containing
       version-specific functions.  (These directories can be configured when zsh is built
       using  the  --enable-site-scriptdir=dir and --enable-scriptdir=dir flags to config-
       ure, respectively; the defaults are prefix/share/zsh and prefix/share/zsh/$ZSH_VER-
       SION where the default prefix is /usr/local.)

       If  the  file newuser is found, it is then sourced in the same manner as a start-up
       file.  The file is expected to contain code to install start-up files for the user,
       however any valid shell code will be executed.

       The zsh/newuser module is then unconditionally unloaded.

       Note that it is possible to achieve exactly the same effect as the zsh/newuser mod-
       ule by adding code to /etc/zshenv.  The module exists simply to allow the shell  to
       make  arrangements for new users without the need for intervention by package main-
       tainers and system administrators.

       The script supplied with the module invokes the shell function zsh-newuser-install.
       This  may  be  invoked  directly by the user even if the zsh/newuser module is dis-
       abled.  Note, however, that if the module is not installed the function will not be
       installed  either.   The  function  is documented in the section User Configuration
       Functions in zshcontrib(1).

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

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

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

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

              Like functions but for disabled functions.

              This associative array gives information about  the  builtin  commands  cur-
              rently  enabled. The keys are the names of the builtin commands and the val-
              ues are either 'undefined' for builtin commands that will  automatically  be
              loaded  from  a module if invoked or 'defined' for builtin commands that are
              already loaded.

              Like builtins but for disabled builtin commands.

              This array contains the enabled reserved words.

              Like reswords but for disabled reserved words.

              This maps the names of the regular aliases currently enabled to their expan-

              Like aliases but for disabled regular aliases.

              Like aliases, but for global aliases.

              Like galiases but for disabled global aliases.

              Like raliases, but for suffix aliases.

              Like saliases but for disabled suffix aliases.

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

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

              Setting or unsetting keys in this array is not possible.

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

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

              A special array containing the words stored in the history.

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

              The keys of the associative arrays are usually valid job numbers, and  these
              are  the  values  output  with, for example, ${(k)jobdirs}.  Non-numeric job
              references may be used when looking up a value; for example,  ${jobdirs[%+]}
              refers to the current job.

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

              Handling of the keys of the associative array is as  described  for  jobdirs

              This  associative  array gives information about the states of the jobs cur-
              rently 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 pro-

              Handling of the keys of the associative array is as  described  for  jobdirs

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

              This associative array maps user names to the pathnames of their home direc-

              This associative array maps names of system groups of which the current user
              is a member to the corresponding group identifiers.  The  contents  are  the
              same as the groups output by the id command.

              This  array  contains the absolute line numbers and corresponding file names
              for the point where the current function, sourced file, or  (if  EVAL_LINENO
              is  set)  eval command was called.  The array is of the same length as func-
              sourcetrace and functrace, but differs from funcsourcetrace in that the line
              and  file  are  the  point of call, not the point of definition, and differs
              from functrace in that all values are absolute line numbers in files, rather
              than relative to the start of a function, if any.

              This  array contains the file names and line numbers of the points where the
              functions, sourced files, and (if EVAL_LINENO is  set)  eval  commands  cur-
              rently  being  executed were defined.  The line number is the line where the
              'function name' or 'name ()' started.  In the case of an autoloaded function
              the  line  number  is reported as zero.  The format of each element is file-
              name:lineno.  For functions autoloaded from a file  in  native  zsh  format,
              where  only  the  body of the function occurs in the file, or for files that
              have been executed by the source or '.' builtins, the trace  information  is
              shown as filename:0, since the entire file is the definition.

              Most  users will be interested in the information in the funcfiletrace array

              This array contains the names of  the  functions,  sourced  files,  and  (if
              EVAL_LINENO  is set) eval commands. currently being executed. The first ele-
              ment is the name of the function using the parameter.

              This array contains the names and line numbers of the callers  corresponding
              to  the  functions  currently being executed.  The format of each element is
              name:lineno.  Callers are also shown for sourced files; the  caller  is  the
              point where the source or '.' command was executed.

       The zsh/pcre module makes some commands available as builtins:

       pcre_compile [ -aimxs ] PCRE
              Compiles a perl-compatible regular expression.

              Option  -a  will force the pattern to be anchored.  Option -i will compile a
              case-insensitive pattern.  Option -m will compile a multi-line pattern; that
              is,  ^ and $ will match newlines within the pattern.  Option -x will compile
              an extended pattern, wherein whitespace and # comments are ignored.   Option
              -s  makes  the  dot metacharacter match all characters, including those that
              indicate newline.

              Studies the previously-compiled PCRE which may result in faster matching.

       pcre_match [ -v var ] [ -a arr ] [ -n offset ] [ -b ] string
              Returns successfully if string matches the previously-compiled PCRE.

              Upon successful match, if the expression captures substrings  within  paren-
              theses, pcre_match will set the array $match to those substrings, unless the
              -a option is given, in which case it will set the array arr.  Similarly, the
              variable  MATCH  will  be  set  to the entire matched portion of the string,
              unless the -v option is given, in which case the variable var will  be  set.
              No  variables  are  altered  if  there  is no successful match.  A -n option
              starts searching for a match from the byte offset position  in  string.   If
              the  -b option is given, the variable ZPCRE_OP will be set to an offset pair
              string, representing the byte offset positions of the entire matched portion
              within  the  string.   For example, a ZPCRE_OP set to "32 45" indicates that
              the matched portion began on byte offset 32 and ended  on  byte  offset  44.
              Here,  byte  offset  position  45 is the position directly after the matched
              portion.  Keep in mind that the byte position isn't necessarily the same  as
              the  character  position  when UTF-8 characters are involved.  Consequently,
              the byte offset positions are only to be relied on in the context  of  using
              them for subsequent searches on string, using an offset position as an argu-
              ment to the -n option.  This is mostly  used  to  implement  the  "find  all
              non-overlapping matches" functionality.

              A simple example of "find all non-overlapping matches":

                     string="The following zip codes: 78884 90210 99513"
                     pcre_compile -m "\d{5}"
                     pcre_match -b -- $string
                     while [[ $? -eq 0 ]] do
                         pcre_match -b -n $b[2] -- $string
                     print -l $accum

       The zsh/pcre module makes available the following test condition:
       expr -pcre-match pcre
              Matches a string against a perl-compatible regular expression.

              For example,

              [[ "$text" -pcre-match ^d+$ ]] && print text variable contains only "d's".

       The zsh/regex module makes available the following test condition:
       expr -regex-match regex
              Matches a string against a POSIX extended regular expression.  On successful
              match, matched portion of the string will normally be placed  in  the  MATCH
              variable.  If there are any capturing parentheses within the regex, then the
              match array variable will contain those.  If the match  is  not  successful,
              then the variables will not be altered.

              For example,

                     [[ alphabetical -regex-match ^a([^a]+)a([^a]+)a ]] &&
                     print -l $MATCH X $match

              If  the  option REMATCH_PCRE is not set, then the =~ operator will automati-
              cally load this module as needed and will invoke the -regex-match  operator.

              If  BASH_REMATCH  is set, then the array BASH_REMATCH will be set instead of
              MATCH and match.

       The zsh/sched module makes available one builtin command and one parameter.

       sched [-o] [+]hh:mm[:ss] command ...
       sched [-o] [+]seconds command ...
       sched [ -item ]
              Make an entry in the scheduled list of commands to execute.  The time may be
              specified  in either absolute or relative time, and either as hours, minutes
              and (optionally) seconds separated by a colon, or seconds alone.   An  abso-
              lute  number  of  seconds  indicates  the  time  since the epoch (1970/01/01
              00:00); this is useful in combination with the features in the  zsh/datetime
              module, see the zsh/datetime module entry in zshmodules(1).

              With  no arguments, prints the list of scheduled commands.  If the scheduled
              command has the -o flag set, this is shown at the start of the command.

              With the argument '-item', removes the given item from the list.   The  num-
              bering  of the list is continuous and entries are in time order, so the num-
              bering can change when entries are added or deleted.

              Commands are executed either immediately  before  a  prompt,  or  while  the
              shell's  line  editor is waiting for input.  In the latter case it is useful
              to be able to produce output that does not interfere  with  the  line  being
              edited.   Providing the option -o causes the shell to clear the command line
              before the event and redraw it afterwards.  This should  be  used  with  any
              scheduled  event  that  produces  visible  output to the terminal; it is not
              needed, for example, with output that updates a  terminal  emulator's  title

              The  sched builtin is not made available by default when the shell starts in
              a mode emulating another shell.  It can be made available with  the  command
              'zmodload -F zsh/sched b:sched'.

              A readonly array corresponding to the events scheduled by the sched builtin.
              The indices of the array correspond to the numbers shown when sched  is  run
              with  no  arguments  (provided  that the KSH_ARRAYS option is not set).  The
              value of the array consists of the scheduled time in seconds since the epoch
              (see  the  section  'The  zsh/datetime Module' for facilities for using this
              number), followed by a colon, followed by any options (which  may  be  empty
              but  will  be preceded by a '-' otherwise), followed by a colon, followed by
              the command to be executed.

              The sched builtin should be used for manipulating  the  events.   Note  that
              this  will  have  an  immediate effect on the contents of the array, so that
              indices may become invalid.

       The zsh/net/socket module makes available one builtin command:

       zsocket [ -altv ] [ -d fd ] [ args ]
              zsocket is implemented as a builtin to allow full use of shell command  line
              editing, file I/O, and job control mechanisms.

   Outbound Connections
       zsocket [ -v ] [ -d fd ] filename
              Open  a  new  Unix domain connection to filename.  The shell parameter REPLY
              will be set to the file descriptor associated with  that  connection.   Cur-
              rently, only stream connections are supported.

              If -d is specified, its argument will be taken as the target file descriptor
              for the connection.

              In order to elicit more verbose output, use -v.

   Inbound Connections
       zsocket -l [ -v ] [ -d fd ] filename
              zsocket -l will open a socket listening on filename.   The  shell  parameter
              REPLY will be set to the file descriptor associated with that listener.

              If -d is specified, its argument will be taken as the target file descriptor
              for the connection.

              In order to elicit more verbose output, use -v.

       zsocket -a [ -tv ] [ -d targetfd ] listenfd
              zsocket -a will accept an incoming connection to the socket associated  with
              listenfd.   The  shell  parameter  REPLY  will be set to the file descriptor
              associated with the inbound connection.

              If -d is specified, its argument will be taken as the target file descriptor
              for the connection.

              If  -t  is specified, zsocket will return if no incoming connection is pend-
              ing.  Otherwise it will wait for one.

              In order to elicit more verbose output, use -v.

       The zsh/stat module makes available one builtin command under two possible names:

       zstat [ -gnNolLtTrs ] [ -f fd ] [ -H hash ] [ -A array ] [ -F fmt ] [ +element ]  [
       file ... ]
       stat ...
              The command acts as a front end to the stat system call (see stat(2)).   The
              same  command  is provided with two names; as the name stat is often used by
              an external command it is recommended that only the zstat form of  the  com-
              mand  is  used.  This can be arranged by loading the module with the command
              'zmodload -F zsh/stat b:zstat'.

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

              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  permis-
                     sions.   With the -s option, this will be returned as a string corre-
                     sponding 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.

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

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

              block  The number of disk blocks used by the file.

              link   If  the  file is a link and the -L option is in effect, this contains
                     the name of the file linked to, otherwise it is empty.  Note that  if
                     this  element  is  selected  (''zstat  +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.  Otherwise, all elements  will
              be shown for all files.


              -A array
                     Instead  of displaying the results on standard output, assign them to
                     an array, one struct stat element per array element for each file  in
                     order.   In this case 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

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

              -L     Perform  an  lstat (see lstat(2)) rather than a stat system call.  In
                     this case, if the file is a link, information about the  link  itself
                     rather  than the target file is returned.  This option is required to
                     make the link element useful.  It's important to note  that  this  is
                     the exact opposite from ls(1), etc.

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

              -N     Never show the names of files.

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

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

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

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

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

       The zsh/system module makes available various builtin commands and parameters.

       syserror [ -e errvar ] [ -p prefix ] [ errno | errname ]
              This  command  prints  out the error message associated with errno, a system
              error number, followed by a newline to standard error.

              Instead of the error number, a name errname,  for  example  ENOENT,  may  be
              used.  The set of names is the same as the contents of the array errnos, see

              If the string prefix is given, it is printed in front of the error  message,
              with no intervening space.

              If errvar is supplied, the entire message, without a newline, is assigned to
              the parameter names errvar and nothing is output.

              A return  status  of  0  indicates  the  message  was  successfully  printed
              (although  it  may not be useful if the error number was out of the system's
              range), a return status of 1 indicates an error in  the  parameters,  and  a
              return  status  of 2 indicates the error name was not recognised (no message
              is printed for this).

       sysread [ -c countvar ] [ -i infd ] [ -o outfd ]
         [ -s bufsize ] [ -t timeout ] [ param ]
              Perform a single system read from file descriptor infd, or zero if  that  is
              not  given.   The  result of the read is stored in param or REPLY if that is
              not given.  If countvar is given, the number of bytes read  is  assigned  to
              the parameter named by countvar.

              The  maximum  number  of bytes read is bufsize or 8192 if that is not given,
              however the command returns as soon as any number of bytes was  successfully

              If timeout is given, it specifies a timeout in seconds, which may be zero to
              poll the file descriptor.  This is handled by the poll system call if avail-
              able, otherwise the select system call if available.

              If  outfd  is  given, an attempt is made to write all the bytes just read to
              the file descriptor outfd.  If this fails, because of a system  error  other
              than  EINTR  or  because  of  an internal zsh error during an interrupt, the
              bytes read but not written are stored in the parameter  named  by  param  if
              supplied (no default is used in this case), and the number of bytes read but
              not written is stored in the parameter named by countvar  if  that  is  sup-
              plied.   If  it  was  successful, countvar contains the full number of bytes
              transferred, as usual, and param is not set.

              The error EINTR (interrupted system call)  is  handled  internally  so  that
              shell  interrupts  are  transparent to the caller.  Any other error causes a

              The possible return statuses are
              0      At least one byte of data was successfully read and, if  appropriate,

              1      There  was  an  error  in the parameters to the command.  This is the
                     only error for which a message is printed to standard error.

              2      There was an error on the read, or on polling the input file descrip-
                     tor for a timeout.  The parameter ERRNO gives the error.

              3      Data  were  successfully read, but there was an error writing them to
                     outfd.  The parameter ERRNO gives the error.

              4      The attempt to read timed out.  Note this does not set ERRNO as  this
                     is not a system error.

              5      No  system  error  occurred,  but zero bytes were read.  This usually
                     indicates end of file.  The parameters are set according to the usual
                     rules; no write to outfd is attempted.

       syswrite [ -c countvar ] [ -o outfd ] data
              The  data  (a  single  string  of  bytes) are written to the file descriptor
              outfd, or 1 if that is not given, using the  write  system  call.   Multiple
              write operations may be used if the first does not write all the data.

              If  countvar is given, the number of byte written is stored in the parameter
              named by countvar; this may not be the full  length  of  data  if  an  error

              The error EINTR (interrupted system call) is handled internally by retrying;
              otherwise an error causes the command to return.  For example, if  the  file
              descriptor  is set to non-blocking output, an error EAGAIN (on some systems,
              EWOULDBLOCK) may result in the command returning early.

              The return status may be 0 for success, 1 for an error in the parameters  to
              the  command, or 2 for an error on the write; no error message is printed in
              the last case, but the parameter ERRNO will reflect the error that occurred.

       zsystem flock [ -t timeout ] [ -f var ] [-er] file
       zsystem flock -u fd_expr
              The  builtin  zsystem's subcommand flock performs advisory file locking (via
              the fcntl(2) system call) over the entire contents of the given file.   This
              form  of locking requires the processes accessing the file to cooperate; its
              most obvious use is between two instances of the shell itself.

              In the first form the named file, which must already  exist,  is  locked  by
              opening  a  file  descriptor  to  the  file  and applying a lock to the file
              descriptor.  The lock terminates when the shell  process  that  created  the
              lock  exits;  it  is  therefore often convenient to create file locks within
              subshells, since the lock is automatically released when the subshell exits.
              Status 0 is returned if the lock succeeds, else status 1.

              In  the  second  form the file descriptor given by the arithmetic expression
              fd_expr is closed, releasing a lock.  The file descriptor can be queried  by
              using  the  '-f  var'  form during the lock; on a successful lock, the shell
              variable var is set to the file descriptor used for locking.  The lock  will
              be released if the file descriptor is closed by any other means, for example
              using 'exec {var}>&-'; however, the form described here  performs  a  safety
              check that the file descriptor is in use for file locking.

              By default the shell waits indefinitely for the lock to succeed.  The option
              -t timeout specifies a timeout for the lock in seconds; currently this  must
              be an integer.  The shell will attempt to lock the file once a second during
              this period.  If the attempt times out, status 2 is returned.

              If the option -e is given, the file descriptor for  the  lock  is  preserved
              when  the  shell uses exec to start a new process; otherwise it is closed at
              that point and the lock released.

              If the option -r is given, the lock is only for reading, otherwise it is for
              reading and writing.  The file descriptor is opened accordingly.

       zsystem supports subcommand
              The  builtin  zsystem's subcommand supports tests whether a given subcommand
              is supported.  It returns status 0  if  so,  else  status  1.   It  operates
              silently  unless  there  was  a syntax error (i.e. the wrong number of argu-
              ments), in which case status 255 is returned.  Status 1 can indicate one  of
              two  things:  subcommand is known but not supported by the current operating
              system, or subcommand is not known (possibly because this is an  older  ver-
              sion of the shell before it was implemented).

       errnos A  readonly  array  of the names of errors defined on the system.  These are
              typically macros defined in C by including the system header  file  errno.h.
              The index of each name (assuming the option KSH_ARRAYS is unset) corresponds
              to the error number.  Error numbers num before the last  known  error  which
              have no name are given the name Enum in the array.

              Note  that  aliases  for  errors are not handled; only the canonical name is

              A readonly associative array.  The keys are:
       pid    Returns the process ID of the current process, even in  subshells.   Compare
              $$, which returns the process ID of the main shell process.

       ppid   Returns  the  process  ID of the parent of the current process, even in sub-
              shells.  Compare $PPID, which returns the process ID of the  parent  of  the
              main shell process.

       The zsh/net/tcp module makes available one builtin command:

       ztcp [ -acflLtv ] [ -d fd ] [ args ]
              ztcp  is  implemented  as  a builtin to allow full use of shell command line
              editing, file I/O, and job control mechanisms.

              If ztcp is run with no options, it will output the contents of  its  session

              If  it  is  run  with only the option -L, it will output the contents of the
              session table in a format suitable for automatic  parsing.   The  option  is
              ignored if given with a command to open or close a session.  The output con-
              sists of a set of lines, one per session, each containing the following ele-
              ments separated by spaces:

              File descriptor
                     The  file  descriptor  in use for the connection.  For normal inbound
                     (I) and outbound (O) connections this may be read and written by  the
                     usual  shell mechanisms.  However, it should only be close with 'ztcp

              Connection type
                     A letter indicating how the session was created:

                      Z      A session created with the zftp command.

                      L      A connection opened for listening with 'ztcp -l'.

                      I      An inbound connection accepted with 'ztcp -a'.

                      O      An outbound connection created with 'ztcp host ...'.

              The local host
                     This is usually set to an all-zero IP address as the address  of  the
                     localhost is irrelevant.

              The local port
                     This is likely to be zero unless the connection is for listening.

              The remote host
                     This  is  the  fully qualified domain name of the peer, if available,
                     else an IP address.  It is an  all-zero  IP  address  for  a  session
                     opened for listening.

              The remote port
                     This is zero for a connection opened for listening.

   Outbound Connections
       ztcp [ -v ] [ -d fd ] host [ port ]
              Open  a new TCP connection to host.  If the port is omitted, it will default
              to port 23.  The connection will be added to the session table and the shell
              parameter REPLY will be set to the file descriptor associated with that con-

              If -d is specified, its argument will be taken as the target file descriptor
              for the connection.

              In order to elicit more verbose output, use -v.

   Inbound Connections
       ztcp -l [ -v ] [ -d fd ] port
              ztcp  -l will open a socket listening on TCP port.  The socket will be added
              to the session table and the shell parameter REPLY will be set to  the  file
              descriptor associated with that listener.

              If -d is specified, its argument will be taken as the target file descriptor
              for the connection.

              In order to elicit more verbose output, use -v.

       ztcp -a [ -tv ] [ -d targetfd ] listenfd
              ztcp -a will accept an incoming connection to the port associated with  lis-
              tenfd.   The  connection  will  be  added to the session table and the shell
              parameter REPLY will be set to  the  file  descriptor  associated  with  the
              inbound connection.

              If -d is specified, its argument will be taken as the target file descriptor
              for the connection.

              If -t is specified, ztcp will return if no incoming connection  is  pending.
              Otherwise it will wait for one.

              In order to elicit more verbose output, use -v.

   Closing Connections
       ztcp -cf [ -v ] [ fd ]
       ztcp -c [ -v ] [ fd ]
              ztcp  -c  will  close  the  socket  associated  with fd.  The socket will be
              removed from the session table.  If fd is not  specified,  ztcp  will  close
              everything in the session table.

              Normally,  sockets  registered by zftp (see zshmodules(1) ) cannot be closed
              this way.  In order to force such a socket closed, use -f.

              In order to elicit more verbose output, use -v.

       Here is how to create a TCP connection between two instances of zsh.   We  need  to
       pick an unassigned port; here we use the randomly chosen 5123.

       On host1,
              zmodload zsh/net/tcp
              ztcp -l 5123
              ztcp -a $listenfd
       The second from last command blocks until there is an incoming connection.

       Now create a connection from host2 (which may, of course, be the same machine):
              zmodload zsh/net/tcp
              ztcp host1 5123

       Now  on  each  host,  $fd contains a file descriptor for talking to the other.  For
       example, on host1:
              print This is a message >&$fd
       and on host2:
              read -r line <&$fd; print -r - $line
       prints 'This is a message'.

       To tidy up, on host1:
              ztcp -c $listenfd
              ztcp -c $fd
       and on host2
              ztcp -c $fd

       The zsh/termcap module makes available one builtin command:

       echotc cap [ arg ... ]
              Output the termcap value corresponding to the capability cap, with  optional

       The zsh/termcap module makes available one parameter:

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

       The zsh/terminfo module makes available one builtin command:

       echoti cap [ arg ]
              Output  the terminfo value corresponding to the capability cap, instantiated
              with arg if applicable.

       The zsh/terminfo module makes available one parameter:

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

       The zsh/zftp module makes available one builtin command:

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

              All commands consist of the command name zftp followed by the name of a sub-
              command.  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.

       open host[:port] [ user [ password [ account ] ] ]
              Open  a new FTP session to host, which may be the name of a TCP/IP connected
              host or an IP number in the standard dot notation.  If the  argument  is  in
              the  form host:port, open a connection to TCP port port instead of the stan-
              dard FTP port 21.  This may be the name of a TCP service or a  number:   see
              the description of ZFTP_PORT below for more information.

              If IPv6 addresses in colon format are used, the host should be surrounded by
              quoted square  brackets  to  distinguish  it  from  the  port,  for  example
              '[fe80::203:baff:fe02:8b56]'.   For  consistency  this  is  allowed with all
              forms of host.

              Remaining arguments are passed to the login subcommand.   Note  that  if  no
              arguments  beyond host are supplied, open will not automatically call login.
              If no arguments at all are supplied, open will use the parameters set by the
              params subcommand.

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

       login [ name [ password [ account ] ] ]
       user [ name [ password [ account ] ] ]
              Login the user name with parameters password and account.  Any of the param-
              eters  can  be omitted, and will be read from standard input if needed (name
              is always needed).  If standard input is a terminal, a prompt for  each  one
              will  be  printed on standard error and password will not be echoed.  If any
              of the parameters are not used, a warning message is printed.

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

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

       params [ host [ user [ password [ account ] ] ] ]
       params -
              Store the given parameters for a later open command with no arguments.  Only
              those  given  on  the  command line will be remembered.  If no arguments are
              given, the parameters currently set are printed, although the password  will
              appear  as  a  line of stars; the return status 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 han-
              dling  of password.  If the '?' is followed by a string, that is used as the
              prompt for reading the parameter instead of the default message (any  neces-
              sary  punctuation  and  whitespace  should  be  included  at  the end of the
              prompt).  The first letter of the parameter (only) may be quoted with a '\';
              hence an argument "\\$word" guarantees that the string from the shell param-
              eter $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 corresponding password with the given prompt.

       test   Test the connection; if the server has reported that it has closed the  con-
              nection (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

              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

       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  com-
              mand  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 similar to dir.

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

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

              The  transfer  type is only passed to the remote host when a data connection
              is established; this command involves no network overhead.

       ascii  The same as type A.

       binary The same as type I.

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

       remote files...
       local [ files... ]
              Print  the size and last modification time of the remote or local files.  If
              there is more than one item on the list, the name of  the  file  is  printed
              first.   The first number is the file size, the second is the last modifica-
              tion 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, com-
              pared 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
       appendat file point
              Versions  of  get, put and append which will start the transfer at the given
              point in the remote file.  This is useful for  appending  to  an  incomplete
              local file.  However, note that this ability is not universally supported by
              servers (and is not quite the behaviour specified by the standard).

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

       mkdir directory
              Create a new directory directory on the server.

       rmdir directory
              Delete the directory directory  on the server.

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

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

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

       quit   Close  the  current  data  connection.   This  unsets  the  shell parameters
              ZFTP_PWD, ZFTP_TYPE and ZFTP_MODE.

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

              Each  session  remembers  the  status  of the connection, the set of connec-
              tion-specific shell parameters (the same set as are unset when a  connection
              closes, as given in the description of close), and any user parameters spec-
              ified with the params subcommand.  Changing to a previous  session  restores
              those  values; changing to a new session initialises them in the same way as
              if zftp had just been loaded.  The name of the current session is  given  by
              the parameter ZFTP_SESSION.

       rmsession [ sessname ]
              Delete  a  session;  if a name is not given, the current session is deleted.
              If the current session is deleted, the earliest 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  recom-
              mended that sessions not be deleted while background commands which use zftp
              are still active.

       The following shell parameters are used by zftp.  Currently none of them  are  spe-

              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.

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

              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.

              Readonly.  The number of the remote TCP port to which the connection is open
              (even  if  the  port  was originally specified as a named service).  Usually
              this is the standard FTP port, 21.

              In the unlikely event that your system does not have the appropriate conver-
              sion  functions, this appears in network byte order.  If your system is lit-
              tle-endian, the port then consists of two swapped  bytes  and  the  standard
              port  will  be reported as 5376.  In that case, numeric ports passed to zftp
              open will also need to be in this format.

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

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

              Readonly.  The username currently logged in, if any.

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

              Readonly.  The current directory on the server.

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

              Readonly.  The last line of the last reply sent by  the  server.   This  can
              still  be  read  after the connection is closed, and is not changed when the
              current session changes.

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

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

              P      Passive:  attempt to make the remote server initiate data  transfers.
                     This  is slightly more efficient than sendport mode.  If the letter S
                     occurs later in the string, zftp 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

              D      Dumb:   use only the bare minimum of FTP commands.  This prevents the
                     variables ZFTP_SYSTEM and ZFTP_PWD from being set, and will mean  all
                     connections  default  to  ASCII  type.  It may prevent ZFTP_SIZE from
                     being set during a transfer if the server does  not  send  it  anyway
                     (many servers do).

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

              A  string  of  digits  between 0 and 5 inclusive, specifying which responses
              from the server should be printed.  All responses go to standard error.   If
              any  of  the  numbers  1  to  5 appear in the string, raw responses from the
              server with reply codes beginning with that digit will be printed  to  stan-
              dard  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  avail-
              able',  which forces termination of a connection, is classified as 421, i.e.
              'transient negative', an interesting interpretation of the word 'transient'.

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

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

              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 connec-
              tion is closed.  In the last case, $ZFTP_PWD will  be  unset;  otherwise  it
              will reflect the new directory.

              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 terminal, not  to
              standard output.

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

                     The name of the remote file being transferred from or to.

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

                     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

                     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 otherwise never called twice with the same value
              of ZFTP_COUNT.

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

       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 subshells 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 unex-
       pected 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 back-
       ground are not possible, as they should be.  This is presumably a bug in the  oper-
       ating system.

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

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

              This array contains the names of the keymaps currently defined.

              This associative array contains one entry per widget 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
              function implementing the widget, or it is a string  of  the  form  'comple-
              tion:type:name',  for  completion widgets. In the last case type is the name
              of the builtin widgets the completion widget imitates in  its  behavior  and
              name is the name of the shell function implementing the completion widget.

       When  loaded,  the  zsh/zprof causes shell functions to be profiled.  The profiling
       results can be obtained with the zprof builtin command made available by this  mod-
       ule.  There is no way to turn profiling off other than unloading the module.

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

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

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

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

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

              As long as the zsh/zprof module is loaded, profiling will be done and multi-
              ple invocations of the zprof builtin command will show the times and numbers
              of calls since the module was loaded.  With the -c option, the zprof builtin
              command will reset its internal counters and will not show the listing.

       The zsh/zpty module offers one builtin:

       zpty [ -e ] [ -b ] name [ arg ... ]
              The arguments following name are concatenated with spaces between, then exe-
              cuted 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 command in later calls to

              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

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

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

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

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

       zpty -r [ -mt ] name [ param [ pattern ] ]
              The -r option can be used to read the output of the command name.  With only
              a name argument, the output read is copied to the standard  output.   Unless
              the  pseudo-terminal  is  non-blocking,  copying continues until the command
              under the pseudo-terminal exits; when non-blocking, only as much  output  as
              is immediately available is copied.  The return status 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-ter-
              minal is non-blocking.  The return status 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  status  is
              zero  if  the  string read matches the pattern, or if the command has exited
              but at least one character could  still  be  read.   If  the  option  -m  is
              present,  the return status is zero only if the pattern matches.  As of this
              writing, a maximum of one megabyte of output can be consumed this way; if  a
              full  megabyte  is  read  without matching the pattern, the return status is

              In all cases, the return status is non-zero if nothing could be read, and is
              2 if this is because the command has finished.

              If  the  -r option is combined with the -t option, zpty tests whether output
              is available before trying to read.  If no output is available, zpty immedi-
              ately  returns  the  status 1.  When used with a pattern, the behaviour on a
              failed poll is similar to when the command has exited:  the return value  is
              zero  if  at  least  one  character  could still be read even if the pattern
              failed to match.

       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 status 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/zselect module makes available one builtin command:

       zselect [ -rwe -t timeout -a array ] [ fd ... ]
              The zselect builtin is a front-end to the 'select' system call, which blocks
              until  a  file  descriptor  is ready for reading or writing, or has an error
              condition, with an optional timeout.  If this is not available on your  sys-
              tem, the command prints an error message and returns status 2 (normal errors
              return status 1).  For more information, see your systems documentation  for
              select(3).   Note  there is no connection with the shell builtin of the same

              Arguments and options may be intermingled in any  order.   Non-option  argu-
              ments  are  file  descriptors,  which must be decimal integers.  By default,
              file descriptors are to be tested for reading, i.e. zselect will return when
              data  is  available  to be read from the file descriptor, or more precisely,
              when a read operation from the file descriptor will not block.  After a  -r,
              -w and -e, the given file descriptors are to be tested for reading, writing,
              or error conditions.  These options and an arbitrary list of  file  descrip-
              tors may be given in any order.

              (The  presence of an 'error condition' is not well defined in the documenta-
              tion for many implementations of  the  select  system  call.   According  to
              recent versions of the POSIX specification, it is really an exception condi-
              tion, of which the only standard example is out-of-band data received  on  a
              socket.  So zsh users are unlikely to find the -e option useful.)

              The option '-t timeout' specifies a timeout in hundredths of a second.  This
              may be zero, in which case the file descriptors will simply  be  polled  and
              zselect  will  return  immediately.   It is possible to call zselect with no
              file descriptors and a non-zero timeout for use as a finer-grained  replace-
              ment  for  'sleep'; note, however, the return status is always 1 for a time-

              The option '-a array' indicates that array should be  set  to  indicate  the
              file  descriptor(s)  which are ready.  If the option is not given, the array
              reply will be used for this purpose.  The array will contain a string  simi-
              lar to the arguments for zselect.  For example,

                     zselect -t 0 -r 0 -w 1

              might  return immediately with status 0 and $reply containing '-r 0 -w 1' to
              show that both file descriptors are ready for the requested operations.

              The option '-A assoc' indicates that the associative array assoc  should  be
              set  to  indicate the file descriptor(s( which are ready.  This option over-
              rides the option -a, nor will reply be modified.  The keys of assoc are  the
              file  descriptors,  and  the  corresponding values are any of the characters
              'rwe' to indicate the condition.

              The command returns status 0 if some file descriptors are ready for reading.
              If the operation timed out, or a timeout of 0 was given and no file descrip-
              tors were ready, or there was an error, it returns status 1  and  the  array
              will  not  be  set  (nor modified in any way).  If there was an error in the
              select operation the appropriate error message is printed.

       The zsh/zutil module only adds some builtins:

       zstyle [ -L [ pattern [ style ] ] ]
       zstyle [ -e | - | -- ] pattern style strings ...
       zstyle -d [ pattern [ styles ... ] ]
       zstyle -g name [ pattern [ style ] ]
       zstyle -abs context style name [ sep ]
       zstyle -Tt context style [ strings ...]
       zstyle -m context style pattern
              This builtin command is used to define and lookup styles.  Styles are  pairs
              of  names  and  values,  where  the values consist of any number of strings.
              They are stored together with patterns  and  lookup  is  done  by  giving  a
              string,  called the 'context', which is compared to the patterns.  The defi-
              nition 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 components (substrings separated by colons) or
              if the patterns for the components are more specific, where  simple  strings
              are  considered  to  be more specific than patterns and complex patterns are
              considered to be more specific than the pattern '*'.

              The first form (without arguments) lists the definitions.  Styles are  shown
              in  alphabetic  order  and  patterns are shown in the order zstyle will test

              If the -L option is given, listing is done in the form of calls  to  zstyle.
              The  optional  first argument is a pattern which will be matched against the
              string supplied as the pattern for the context; note that  this  means,  for
              example,  'zstyle -L ":completion:*"' will match any supplied pattern begin-
              ning ':completion:', not  just  ":completion:*":   use  ":completion:\*"  to
              match  that.   The  optional second argument limits the output to a specific
              style (not a pattern).  -L is not compatible with any other options.

              The other forms are the following:

              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 evaluation, 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 used as the name of an array
                     in  which  the results are stored. Without any further arguments, all
                     patterns defined are returned. With a pattern the styles defined  for
                     that  pattern  are  returned and with both a pattern and a style, the
                     value strings of that combination is returned.

              The other forms can be used to look up or test patterns.

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

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

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

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

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

              zstyle -m context style pattern
                     Match a value. Returns status zero if the pattern  matches  at  least
                     one of the strings in the value.

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

              The  %-escapes  also  understand  ternary  expressions  in  the form used by
              prompts.  The % is followed by a '(' and then an ordinary  format  specifier
              character as described above.  There may be a set of digits either before or
              after the '('; these specify a test number, which defaults to  zero.   Nega-
              tive numbers are also allowed.  An arbitrary delimiter character follows the
              format specifier, which is followed by a piece of 'true' text, the delimiter
              character  again,  a  piece of 'false' text, and a closing parenthesis.  The
              complete expression (without the digits) thus looks like '%(X.text1.text2)',
              except  that the '.' character is arbitrary.  The value given for the format
              specifier in the char:string expressions  is  evaluated  as  a  mathematical
              expression,  and compared with the test number.  If they are the same, text1
              is output, else text2 is output.  A parenthesis may be escaped in  text2  as
              %).  Either of text1 or text2 may contain nested %-escapes.

              For example:

                     zformat -f REPLY "The answer is '%3(c.yes.no)'." c:3

              outputs "The answer is 'yes'." to REPLY since the value for the format spec-
              ifier c is 3, agreeing with the digit argument to the ternary expression.

              The second form, using the -a option, can  be  used  for  aligning  strings.
              Here,  the  specs  are of the form 'left:right' where 'left' and 'right' are
              arbitrary strings.  These strings are modified by replacing  the  colons  by
              the sep string and padding the left strings with spaces to the right so that
              the sep strings in the result (and hence the right strings after  them)  are
              all  aligned if the strings are printed below each other.  All strings with-
              out 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.

              This implements some internals of the _regex_arguments function.

       zparseopts [ -D ] [ -K ] [ -M ] [ -E ] [ -a array ] [ -A assoc ] specs
              This  builtin  simplifies  the  parsing of options in positional parameters,
              i.e. the set of arguments given by $*.  Each spec describes one  option  and
              must  be  of the form 'opt[=array]'.  If an option described by opt is found
              in the positional parameters it is copied into the array specified with  the
              -a option; if the optional '=array' is given, it is instead copied into that

              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 char-
              acters can appear in the option name provided it is preceded by a backslash.

              name+  The name is the name of the option without the leading '-'.  To spec-
                     ify 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 pars-
                     ing  stops  if the next positional parameter does not also begin with
                     '-' (unless the -E option is used).

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

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

                     A  '+'  as  described above may appear between the name and the first

       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 associa-
              tive array with the option names as keys and the arguments (if any)  as  the

       -D     If  this  option is given, all options found are removed from the positional
              parameters of the calling shell or shell function, up to but  not  including
              any not described by the specs.  This is similar to using the shift builtin.

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

       -M     This changes the assignment rules to implement a map among equivalent option
              names.  If any spec uses the '=array' form, the string array is  interpreted
              as the name of another spec, which is used to choose where to store the val-
              ues.  If no other spec is found, the  values  are  stored  as  usual.   This
              changes  only  the  way  the values are stored, not the way $* is parsed, so
              results may be unpredicable if the 'name+' specifier is used inconsistently.

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

       For example,

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

       will have the effect of

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

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

       As an example for the -E option, consider:

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

       will have the effect of

              bar=(-b y)
              set -- -a x -c z arg1 arg2

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

       The -M option can be used like this:

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

       to have the effect of

              bar=(-a '' -b xyz)

zsh 4.3.14                     December 6, 2011                  ZSHMODULES(1)

Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2017-12-12 19:54 @ CrawledBy CCBot/2.0 (http://commoncrawl.org/faq/)
Valid XHTML 1.0!Valid CSS!