Home Man
Today's Posts

Linux & Unix Commands - Search Man Pages

RedHat 9 (Linux i386) - man page for zshmodules (redhat section 1)

ZSHMODULES(1)			     General Commands Manual			    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  dynamically  linked
       while  the  shell  is running if the installation supports this feature.  The modules that
       are bundled with the zsh distribution are:

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

	      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.

	      Access to internal hash tables via special associative arrays.

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

	      A builtin command interface to the stat system call.

	      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.

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

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

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

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

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

       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

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

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

       The zsh/complete module makes available several builtin commands  which	can  be  used  in
       user-defined completion 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/complist mod-
       ule is loaded or linked into the shell, completion lists will be colored.  Note,  however,
       that  complist  will  not automatically be loaded if it is not linked in:  on systems with
       dynamic loading, `zmodload zsh/complist' is required.

       The parameters ZLS_COLORS and ZLS_COLOURS describe how matches are highlighted.	 To  turn
       on  highlighting an empty value suffices, in which case all the default values given below
       will be used.  The format of the value of these parameters is the same as used by the  GNU
       version	of  the  ls  command:  a  colon-separated  list  of  specifications  of  the form
       `name=value'.  The name may be one of the 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

       pi 31  for named pipes (FIFOs)

       so 33  for sockets

       bd 44;37
	      for block devices

       cd 44;37
	      for character devices

       ex 35  for executable files

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

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

       rc m   for the right code

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

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

       ec none
	      for the end code

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

       The last form also allows different parts of the displayed strings to be  colored  differ-
       ently.  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 separated by equal signs.  The first code
       will be used for all parts for which no explicit code is specified and the following codes
       will  be  used for the parts matched by the sub-patterns in 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 char-
       acter and `0' for the rest.

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

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

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

       The default values are ISO 6429 (ANSI) compliant and can be used on vt100 compatible  ter-
       minals  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 zshcon-
       trib(1)).  For example, after loading colors, one could use `$colors[red]' to get the code
       for foreground color red and `$colors[bg-green]' for the code for background color green.

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

   Scrolling in completion listings
       To  enable scrolling through a completion list, the 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' 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

       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 undefined-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 zshop-
       tions(1)).  It can be invoked directly by the widget menu-select defined  by  the  module.
       Alternatively,  the parameter MENUSELECT can be set to an integer, which gives the minimum
       number of matches that must be present before menu selection is automatically  turned  on.
       This second method requires that menu completion be started, either directly from a widget
       such as menu-complete, or due to one of the options MENU_COMPLETE or AUTO_MENU being  set.
       If  MENUSELECT  is set, but is 0, 1 or empty, menu selection will always be started during
       an ambiguous menu completion.

       When using the completion system based on shell functions, the MENUSELECT parameter should
       not  be	used  (like the ZLS_COLORS and ZLS_COLOURS parameters described above).  Instead,
       the menu style should be used with the select=... 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 termi-
       nal 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 LIST-
       PROMPT, 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 parame-
       ter 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  completion  system.
       Instead, the select-prompt and select-scroll styles should be used.

       The  completion	code sometimes decides not to show all of the matches in the list.  These
       hidden matches are either matches for which  the  completion  function  which  added  them
       explicitly  requested that they not appear in the list (using the -n option of the compadd
       builtin command) or they are matches which duplicate a string already in the list (because
       they differ only in things like prefixes or suffixes that are not displayed).  In the list
       used for menu selection, however, even these matches are shown so that it is  possible  to
       select  them.   To highlight such matches the hi and du capabilities in the ZLS_COLORS and
       ZLS_COLOURS parameters are supported for hidden matches of  the	first  and  second  kind,

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

	      accepts the current match and leaves menu selection

	      leaves menu selection and restores the previous contents of the command line

       redisplay, clear-screen
	      execute their normal function without leaving menu 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 immediately attempt  to
	      complete	files in it;  if there are no matches, a message is shown and one can use
	      undo to go back to completion on the previous level, every other	key  leaves  menu
	      selection  (including  the  other  zle functions which are otherwise special during
	      menu selection)

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

       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

       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 during 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 zshmod-
       ules(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 comple-
       tion 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 inter-
       esting when writing your own completion functions.  In  summary,  these	builtin  commands

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

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

	      Once compdescribe has been called with either the -i or the -I option,  it  can  be
	      repeatedly called with the -g option and the names of five arrays as its arguments.
	      This will step through the 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  generation
	      (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 specifi-
	      cation currently used.  The -i option does the directory tests for the  ignore-par-
	      ents 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 creates the groups
	      for it (all six types: sorted and unsorted, both without removing duplicates,  with
	      removing all duplicates and with removing consecutive 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  inter-
	      preting the first character of the all_quotes key of the compstate special associa-
	      tion and using the q flag for parameter expansions, one can use this  builtin  com-
	      mand.   The arguments are the names of scalar or array parameters and the values of
	      these parameters are quoted as needed for the innermost quoting level.  If  the  -p
	      option  is  given,  quoting is done as if there is some prefix before the values of
	      the parameters, so that a leading equal sign will not be quoted.

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

	      These implement the internals of the tags mechanism.

	      Like comparguments, but for the _values function.

       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 some standard commands available as builtins:

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

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

	      The user-spec can be in four forms:

	      user   change owner to user; do not change group
	      user:: change owner to user; do not change group
	      user:  change owner to user; change group to user's primary group
		     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 separator is `.',
	      otherwise there is no separator.

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

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

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

       ln [ -dfis ] filename dest
       ln [ -dfis ] filename ... dir
	      Creates  hard (or, with -s, symbolic) links.  In the first form, the specified des-
	      tination is created, as a link to the specified filename.  In the second form, each
	      of the filenames is taken in turn, and linked to a pathname in the specified direc-
	      tory 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 suc-
	      ceed 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 precedence.

       mkdir [ -p ] [ -m mode ] dir ...
	      Creates directories.  With the -p option, non-existing parent directories are first
	      created if necessary, and there will be  no  complaint  if  the  directory  already
	      exists.	The -m option can be used to specify (in octal) a set of file 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

       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

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

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

       rmdir dir ...
	      Removes empty directories specified.

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

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

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

	      When  the array is accessed as a whole, the keys are the names of files in the cur-
	      rent 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.

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

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

       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 evaluating
       mathematical formulae.  The syntax agrees with normal C and FORTRAN conventions, for exam-

	      (( f = sin(0.3) ))

       assigns the sine of 0.3 to the parameter f.

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

       The following functions take a single floating point 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 argument, but returns an integer.

       The function signgam takes no arguments, and returns an integer, which is the  C  variable
       of the same name, as described in gamma(3).  Note that it is therefore only useful immedi-
       ately after a call to gamma or lgamma.  Note also that `signgam()' and `signgam' are  dis-
       tinct 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,

       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  con-
       vert their arguments into a floating point or integer value (by truncation) respectively.

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

       The zsh/parameter module 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

	      This array gives access to the command hash table. The keys are the names of exter-
	      nal 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.  Set-
	      ting 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 currently
	      enabled. The keys are the names of the builtin commands and the values  are  either
	      `undefined' for builtin commands that will automatically be loaded from a module if
	      invoked or `defined' for builtin commands that are already loaded.

	      Like builtins but for disabled builtin commands.

	      This array contains the enabled reserved words.

	      Like reswords but for disabled reserved words.

	      This maps the names of the regular aliases currently enabled to their expansions.

	      Like raliases but for disabled regular aliases.

	      Like raliases, but for global aliases.

	      Like galiases but for disabled global aliases.

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

	      An  associative  array  giving information about 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 direc-

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

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

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

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

	      This associative array maps user names to the pathnames of their home directories.

	      This  array contains the names of the functions currently being executed. The first
	      element is the name of the function using the parameter.

       The zsh/sched module makes available one builtin command:

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

       The zsh/stat module makes available one builtin command:

       stat [ -gnNolLtTrs ] [ -f fd ] [ -H hash ] [ -A array ] [ -F fmt ] [ +element ] [ file ...
	      The command acts as a front end to the stat system call (see stat(2)).  If the stat
	      call  fails, the appropriate system error message printed and status 1 is returned.
	      The fields of struct stat give information about the files provided as arguments to
	      the  command.   In addition to those available from the stat call, an extra element
	      `link' is provided.  These elements are:

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

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

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

	      nlink  The number of hard links to the file.

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

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

	      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,  respec-
		     tively,  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

	      block  The number of disk blocks used by the file.

	      link   If the file is a link and the -L option is in effect, this contains the name
		     of the file linked to, otherwise it is empty.  Note that if this element  is
		     selected (``stat +link'') then the -L option is automatically 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  shortened  to  any
	      unique  set  of  leading characters.  Otherwise, all elements will be shown for all


	      -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  ele-
		     ment; if -n is given, the file name appears as a separate array element pre-
		     ceding all the others.  Other formatting options are respected.

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

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

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

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

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

	      -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  ele-
		     ment useful.

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

	      -N     Never show the names of files.

	      -o     If a raw file mode is printed, show it in octal, which is	more  useful  for
		     human  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  for-
		     matted 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 num-
		     bers.  In each case the format is like that of ls -l.

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

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

       The zsh/termcap module makes available one builtin command:

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

       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
	      Output the terminfo value corresponding to the capability cap.

       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 imple-
	      mented as a builtin to allow full use of shell command line editing, file I/O,  and
	      job  control mechanisms.	Often, users will access it via shell functions providing
	      a more powerful interface; a set is provided  with  the  zsh  distribution  and  is
	      described  in  zshzftpsys(1).   However, the zftp command is entirely usable in its
	      own right.

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

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

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

       login [ name [ password [ account ] ] ]
       user [ name [ password [ account ] ] ]
	      Login  the  user	name with parameters password and account.  Any of the parameters
	      can be omitted, and will be read from standard input  if	needed	(name  is  always
	      needed).	If standard input is a terminal, a 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 value is one if no parameters were set, zero otherwise.

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

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

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

	      For example,

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

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

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

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

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

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

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

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

       ls [ args ]
	      Give  a (short) listing of the remote directory.	With no args, produces a raw list
	      of the files in the directory, one per line.  Otherwise,	up  to	vagaries  of  the
	      server implementation, behaves 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 overridden.

	      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 modification time of the file
	      in the format CCYYMMDDhhmmSS consisting of year, month,  date,  hour,  minutes  and
	      seconds  in  GMT.   Note	that this format, including the length, is guaranteed, so
	      that time strings can be directly compared via the [[ builtin's < and >  operators,
	      even if they are too long to be represented as integers.

	      Not  all	servers  support  the  commands for retrieving this information.  In that
	      case, the remote command will print nothing and return status 2, compared with sta-
	      tus 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

       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.  How-
	      ever, 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 con-
	      trol connection are sent to standard error.

       quit   Close the current data connection.  This unsets  the  shell  parameters  ZFTP_HOST,

       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 cre-
	      ate a new session of that name.

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

       rmsession [ sessname ]
	      Delete a session; if a name is not given, the 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 recommended 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 special.

	      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

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

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

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

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

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

	      D      Dumb:   use  only the bare minimum of FTP commands.  This prevents the vari-
		     ables 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 mode.

	      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  num-
	      bers  1  to  5 appear in the string, raw responses from the server with reply codes
	      beginning with that digit will be printed to standard error.  The  first	digit  of
	      the three digit reply code is defined by RFC959 to correspond to:

	      1.     A positive preliminary reply.

	      2.     A positive completion reply.

	      3.     A positive intermediate reply.

	      4.     A transient negative completion reply.

	      5.     A permanent negative completion reply.

	      It  should  be  noted that, for unknown reasons, the reply `Service not available',
	      which forces 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 processed  for-
	      mat.   By  convention,  servers  use this mechanism for sending information for the
	      user to read.  The appropriate reply code, if it matches the same  response,  takes

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

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

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

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

	      The   function  is  initially  called  with  ZFTP_TRANSFER  set  appropriately  and
	      ZFTP_COUNT set to zero.  After the transfer  is  finished,  the  function  will  be
	      called  one more time with ZFTP_TRANSFER set to GF or PF, in case it wishes to tidy
	      up.  It is 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 necessary.

       A  connection  may  not be opened in the left hand side of a pipe as this occurs in a sub-
       shell 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 unexpected
       effects, even if it does not use the session being deleted.  This  is  because  all  shell
       subprocesses  share  information  on  the state of all connections, and deleting a session
       changes the ordering of that information.

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

       The zsh/zle module 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 wid-
	      get 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 `completion:type:name', for completion wid-
	      gets. In the last case type is the name of the builtin widgets the completion  wid-
	      get  imitates in its behavior and name is the name of the shell function implement-
	      ing the completion widget.

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

       zprof [ -c ]
	      Without the -c option, zprof lists profiling results to standard output.	The  for-
	      mat 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]'.RE, then the number of  calls  made  to
	      the  function.   The  next three columns list the time in milliseconds spent in the
	      function and its descendents, the average time in milliseconds spent in  the  func-
	      tion  and  its  descendents  per call and the percentage of time spent in all shell
	      functions used in this function and its descendents.  The following  three  columns
	      give the same information, but counting only the time spent in the function itself.
	      The final 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 descendents.	Each of these entries consists of descriptions for the	functions
	      that  called  the  function  described, the function itself, and the functions that
	      were called from it.  The description for the function itself has the  same  format
	      as in the summary (and shows the same information).  The other lines don't show the
	      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 sec-
	      tion from the surrounding lines.

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

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

	      As  long	as  the  zsh/zprof  module is loaded, profiling will be done and multiple
	      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 executed as
	      a  command,  as  if  passed  to  the  eval builtin.  The command runs under a newly
	      assigned pseudo-terminal; this is useful	for  running  commands	non-interactively
	      which  expect an interactive environment.  The name is not part of the command, but
	      is used to refer to this command in later calls to zpty.

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

	      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

       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

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

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

       zpty -r [ -t ] name [ param [ pattern ] ]
	      The -r option can be used to read the output of the command name.  With only a name
	      argument, the output read is copied to the standard output.  Unless the pseudo-ter-
	      minal is non-blocking, copying continues until the command under the  pseudo-termi-
	      nal  exits;  when  non-blocking, only as much output as is immediately available is
	      copied.  The return value is zero if any output is copied.

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

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

	      In all cases, the return value 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  immediately
	      returns the value 1.

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

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

       The zsh/zutil module only adds some builtins:

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

	      For ordering of comparisons, patterns are searched from most specific to least spe-
	      cific, 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  compo-
	      nents  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 pat-
	      tern `*'.

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

	      zstyle [ - | -- | -e ] pattern style strings ...
		     Defines  the  given style for the pattern with the strings as the value.  If
		     the -e option is given, the strings will be concatenated (separated by  spa-
		     ces)  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 com-
		     bination 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  associa-
		     tive  array,   the  first,  third, etc. strings are used as the keys and the
		     other strings are used as the values.

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

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

	      zstyle -m context style pattern
		     Match  a  value.  Returns status zero if the 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 resulting string is stored in the  parame-
	      ter param.

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

	      This implements some internals of the _regex_arguments function.

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

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

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

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

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

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

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

	      name:: 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 itself.

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

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

       The options of zparseopts itself are:

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

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

       -D     If this option is given, all options found are removed from the positional  parame-
	      ters  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 zparseopts.

       -E     This changes the parsing rules to not stop at the first string that isn't described
	      by  one  of  the	specs.	 It can be used to test for or (if used together with -D)
	      extract options and their 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.

zsh 4.0.6				 August 14, 2002			    ZSHMODULES(1)

All times are GMT -4. The time now is 12:42 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
Show Password