zshmodules man page on Ultrix

Man page or keyword search:  
man Server   3690 pages
apropos Keyword Search (all sections)
Output format
Ultrix logo
[printable version]

ZSHMODULES(1)							 ZSHMODULES(1)

NAME
       zshmodules - zsh loadable modules

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

       zsh/cap
	      Builtins	for manipulating POSIX.1e (POSIX.6) capability (privi‐
	      lege) sets.

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

       zsh/compctl
	      The compctl builtin for controlling completion.

       zsh/complete
	      The basic completion code.

       zsh/complist
	      Completion listing extensions.

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

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

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

       zsh/files
	      Some basic file manipulation commands as builtins.

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

       zsh/mathfunc
	      Standard	scientific  functions  for use in mathematical evalua‐
	      tions.

       zsh/parameter
	      Access to internal hash tables via special associative arrays.

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

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

       zsh/termcap
	      Interface to the termcap database.

       zsh/terminfo
	      Interface to the terminfo database.

       zsh/zftp
	      A builtin FTP client.

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

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

       zsh/zprof
	      A module allowing profiling for shell functions.

       zsh/zpty
	      A builtin for starting a command in a pseudo-terminal.

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

THE ZSH/CAP MODULE
       The zsh/cap module is used for manipulating POSIX.1e (POSIX.6) capabil‐
       ity 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  capabili‐
	      ties.

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

THE ZSH/CLONE MODULE
       The zsh/clone module makes available one builtin command:

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

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

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

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

THE ZSH/COMPLIST MODULE
       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  module  is	 loaded	 or  linked into the shell, completion
       lists will be colored.  Note, however, that complist will not automati‐
       cally  be loaded if it is not linked in:	 on systems with dynamic load‐
       ing, `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	 file‐
	      names 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 (`*') fol‐
       lowed 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 pat‐
       tern  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 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 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 character and `0' for the rest.

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

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

       When  printing  a match, the code prints the value of lc, the value for
       the file-type or the last matching 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 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 zshcon‐
       trib(1)).  For example, after loading  colors,  one  could  use	`$col‐
       ors[red]'  to  get  the	code  for  foreground  color  red  and	`$col‐
       ors[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 `Comple‐
       tion 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 `num‐
       ber/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 low‐
       ercase 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:

       send-break
	      stops listing discarding the key pressed

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

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

       Every  other  character stops listing and immediately 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 zshoptions(1)).  It can be
       invoked directly by the	widget	menu-select  defined  by  the  module.
       Alternatively, the parameter MENUSELECT can be set to an integer, which
       gives the minimum number of 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 MENUSE‐
       LECT 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 sup‐
       ports 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	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 com‐
       pletion 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, respectively.

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

       accept-line
	      accepts the current match and leaves menu selection

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

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

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

       accept-and-infer-next-history
	      accepts the current match and then tries	completion  with  menu
	      selection again;	in the case of files this allows one to select
	      a directory and 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 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

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

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

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

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

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

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

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

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

       During this selection the widget uses the keymap 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 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
       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 summary, these  builtin
       commands are:

       comparguments
	      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 initialize some internal state and various
	      options to access the state information to decide what should be
	      completed.

       compdescribe
	      This is used by the _describe function to build the displays for
	      the matches and to get the strings to add as matches with	 their
	      options.	 On  the first call one of the options -i or -I should
	      be supplied as the first argument.  In the first	case,  display
	      strings  without the descriptions will be generated, in the sec‐
	      ond 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.

       compfiles
	      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 specification currently used.   The	 -i  option  does  the
	      directory	 tests	for the ignore-parents style and the -r option
	      tests if a component for some of the matches are	equal  to  the
	      string  on  the  line  and  removes all other matches if that is
	      true.

       compgroups
	      Used by the _tags function to implement  the  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	dupli‐
	      cates).

       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 quot‐
	      ing  themselves.	Instead of interpreting the first character of
	      the all_quotes key of  the  compstate  special  association  and
	      using  the  q  flag  for	parameter expansions, one can use this
	      builtin command.	The arguments are the names of scalar or array
	      parameters  and  the  values  of	these parameters are quoted as
	      needed for the innermost quoting level.  If  the	-p  option  is
	      given,  quoting  is  done	 as if there is some prefix before the
	      values of the parameters, so that a leading equal sign will  not
	      be quoted.

	      The return value is non-zero in case of an error and zero other‐
	      wise.

       comptags
       comptry
	      These implement the internals of the tags mechanism.

       compvalues
	      Like comparguments, but for the _values function.

THE ZSH/DELTOCHAR MODULE
       The zsh/deltochar module makes available two ZLE functions:

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

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

THE ZSH/EXAMPLE MODULE
       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
       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
	      user:group
		     change owner to user; change group to group
	      :group do not change owner; change group to group

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

	      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  directo‐
	      ries, 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  paranoid behaviour, intended to avoid security problems
	      involving a chown being tricked into affecting files other  than
	      the  ones intended.  It will refuse to follow symbolic links, so
	      that (for example) ``chown luser /tmp/foo/passwd''  can't	 acci‐
	      dentally	chown  /etc/passwd if /tmp/foo happens to be a link to
	      /etc.  It will also check where it is after leaving directories,
	      so  that a recursive chown of a deep directory tree can't end up
	      recursively chowning /usr as a result of directories being moved
	      up the tree.

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

	      Normally,	 ln  will not attempt to create hard links to directo‐
	      ries.  This check can be overridden using the -d option.	 Typi‐
	      cally  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 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 spec‐
	      ified 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.  Histori‐
	      cal 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 direc‐
	      tory with the rmdir system 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
	      directories,  so	that  a	 recursive removal of a deep directory
	      tree can't end up recursively  removing  /usr  as	 a  result  of
	      directories being moved up the tree.

       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
       The zsh/mapfile module provides one special associative array parameter
       of the same name.

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

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

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

   Limitations
       Although reading and writing of the file	 in  question  is  efficiently
       handled,	 zsh's	internal memory management may be arbitrarily baroque.
       Thus it should not automatically be assumed that use of mapfile	repre‐
       sents  a gain in efficiency over use of other mechanisms.  Note in par‐
       ticular that the whole contents of the file will always	reside	physi‐
       cally 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
       The zsh/mathfunc module provides standard  mathematical	functions  for
       use when evaluating mathematical formulae.  The syntax agrees with nor‐
       mal C and FORTRAN conventions, for example,

	      (( f = sin(0.3) ))

       assigns the sine of 0.3 to the parameter f.

       Most functions take floating point  arguments  and  return  a  floating
       point  value.   However,	 any  necessary conversions from or to integer
       type will be performed automatically by the  shell.   Apart  from  atan
       with  a second argument and the abs, int and float functions, all func‐
       tions behave as noted in the manual page for the corresponding C	 func‐
       tion,  except that any arguments out of range for the function in ques‐
       tion 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 immediately after a call to  gamma  or
       lgamma.	 Note also that `signgam()' and `signgam' are distinct expres‐
       sions.

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

       The  following take an integer first argument and a floating point sec‐
       ond argument: jn, yn.

       The following take a floating point first argument and an integer  sec‐
       ond 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 ZSH/PARAMETER MODULE
       The  zsh/parameter  module  gives  access  to some of the internal hash
       tables used by the shell by defining some special parameters.

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

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

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

       dis_functions
	      Like functions but for disabled functions.

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

       dis_builtins
	      Like builtins but for disabled builtin commands.

       reswords
	      This array contains the enabled reserved words.

       dis_reswords
	      Like reswords but for disabled reserved words.

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

       dis_aliases
	      Like raliases but for disabled regular aliases.

       galiases
	      Like raliases, but for global aliases.

       dis_galiases
	      Like galiases but for disabled global aliases.

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

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

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

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

       historywords
	      A special array containing the words stored in the history.

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

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

       jobstates
	      This associative array gives information about the states of the
	      jobs  currently known. The keys are the job numbers and the val‐
	      ues 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  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.

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

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

       funcstack
	      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
       The zsh/sched module makes available one builtin command:

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

THE ZSH/STAT MODULE
       The zsh/stat module makes available one builtin command:

       stat  [	-gnNolLtTrs  ] [ -f fd ] [ -H hash ] [ -A array ] [ -F fmt ] [
       +element ] [ file ... ]
	      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 dis‐
		     play of the ls -l command.

	      nlink  The number of hard links to the file.

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

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

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

	      size   The size of the file in bytes.

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

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

	      block  The number of disk blocks used by the file.

	      link   If the file is a link and the -L  option  is  in  effect,
		     this  contains  the name of the 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  pre‐
	      ceded  by a `+' in the option list; only one element is allowed.
	      The element may be shortened to any unique set of leading	 char‐
	      acters.  Otherwise, all elements will be shown for all files.

	      Options:

	      -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 nei‐
		     ther 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 for‐
		     matting of the time elements.  The -s option is implied.

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

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

	      -L     Perform an lstat (see lstat(2)) rather than a stat system
		     call.   In	 this case, if the file is a link, information
		     about the link itself rather  than	 the  target  file  is
		     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 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	individual  element  has  been
		     selected.

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

THE ZSH/TERMCAP MODULE
       The zsh/termcap module makes available one builtin command:

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

       The zsh/termcap module makes available one parameter:

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

THE ZSH/TERMINFO MODULE
       The zsh/terminfo module makes available one builtin command:

       echoti cap
	      Output the terminfo value corresponding to the capability cap.

       The zsh/terminfo module makes available one parameter:

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

THE ZSH/ZFTP MODULE
       The zsh/zftp module makes available one builtin command:

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

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

   Subcommands
       open host [ user [ password [ account ] ] ]
	      Open a new FTP session to host, which  may  be  the  name	 of  a
	      TCP/IP  connected host or an IP number in the standard dot nota‐
	      tion.  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  sup‐
	      plied,  open  will  use the parameters set by the params subcom‐
	      mand.

	      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 remem‐
	      bered.  If no arguments are given, the parameters currently  set
	      are  printed,  although  the  password  will appear as a line of
	      stars; the return value is one if no parameters were  set,  zero
	      otherwise.

	      Any  of the parameters may be specified as a `?', which may need
	      to be quoted to protect it from shell expansion.	In this	 case,
	      the  appropriate	parameter  will be read from stdin as with the
	      login subcommand, including special handling  of	password.   If
	      the  `?' is followed by a string, that is used as the prompt for
	      reading the parameter instead of the default message (any 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 parameter $word will be treated liter‐
	      ally, 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 subcommand for the current session when	 a  connection
	      is open.

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

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

       dir [ args... ]
	      Give a (verbose) listing of the remote directory.	 The args  are
	      passed directly to the server. The command's behaviour is imple‐
	      mentation 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  out‐
	      put.

       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 for‐
	      mat CCYYMMDDhhmmSS consisting of year, month, date,  hour,  min‐
	      utes  and	 seconds in GMT.  Note that this format, including the
	      length, is guaranteed, so that time strings can be directly com‐
	      pared  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	infor‐
	      mation.  In that case, the remote command will print nothing and
	      return status 2, compared with status 1 for a file not found.

	      The local command (but not remote) may be	 used  with  no	 argu‐
	      ments,  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 send‐
	      ing 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 append‐
	      ing to an incomplete local file.	However, note that this	 abil‐
	      ity  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.

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

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

	      Each  session remembers the status of the 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  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 exist‐
	      ing session becomes the new current session, otherwise the  cur‐
	      rent  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.

   Parameters
       The following shell parameters are used by  zftp.   Currently  none  of
       them are special.

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

       ZFTP_IP
	      Readonly.	 The IP address of the current connection in dot nota‐
	      tion.

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

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

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

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

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

       ZFTP_PWD
	      Readonly.	 The current directory on the server.

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

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

       ZFTP_SESSION
	      Readonly.	 The name of the current FTP session; see the descrip‐
	      tion of the session subcommand.

       ZFTP_PREFS
	      A string of preferences for altering aspects  of	zftp's	behav‐
	      iour.  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  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 mode.

       ZFTP_VERBOSE
	      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 standard  error.   The	 first
	      digit of the three digit reply code is defined by RFC959 to cor‐
	      respond 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 format.	By convention, servers
	      use this mechanism for sending information for the user to read.
	      The  appropriate	reply  code,  if it matches the same response,
	      takes priority.

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

   Functions
       zftp_chpwd
	      If this function is set by the user, it is called every time the
	      directory changes on the server, including when a user is logged
	      in, or when a connection is closed.  In the last case, $ZFTP_PWD
	      will be unset; otherwise it will reflect the new directory.

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

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

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

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

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

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

	      The function is initially called with ZFTP_TRANSFER  set	appro‐
	      priately and ZFTP_COUNT set to zero.  After the transfer is fin‐
	      ished,  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.

   Problems
       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 connec‐
       tion 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 other‐
       wise 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 order‐
       ing of that information.

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

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

THE ZSH/ZLEPARAMETER MODULE
       The zsh/zleparameter module defines two special parameters that can  be
       used  to	 access	 internal information of the Zsh Line Editor (see zsh‐
       zle(1)).

       keymaps
	      This array contains the names of the keymaps currently defined.

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

THE ZSH/ZPROF MODULE
       When  loaded, the zsh/zprof causes shell functions to be profiled.  The
       profiling results can be obtained with the zprof builtin	 command  made
       available  by this module.  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]'.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 informa‐
	      tion,  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 section from the surrounding lines.

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

	      Also in this case, the column showing the number of calls	 to  a
	      function also shows a slash and then the total number of invoca‐
	      tions 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
       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-termi‐
	      nal; 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 echoed.

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

       zpty -d [ names ... ]
	      The second form, with the -d option, is used to delete  commands
	      previously  started,  by supplying a list of their names.	 If no
	      names are given, all commands are deleted.  Deleting  a  command
	      causes the HUP signal to be sent to the corresponding 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-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-terminal is non-block‐
	      ing, copying continues until the command under the pseudo-termi‐
	      nal  exits; when non-blocking, only as much output as is immedi‐
	      ately available is copied.  The return value is zero if any out‐
	      put is copied.

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

	      If a pattern is given as well, output is read  until  the	 whole
	      string  read matches the pattern, even in the non-blocking case.
	      The return value is zero if the string read matches the pattern,
	      or  if  the  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 com‐
	      mands currently defined.	If the -L option  is  given,  this  is
	      done in the form of calls to the zpty builtin.

THE ZSH/ZUTIL MODULE
       The zsh/zutil module only adds some builtins:

       zstyle [ -L ]
       zstyle [ -e | - | -- ] pattern style strings ...
       zstyle -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 pat‐
	      terns and lookup is done by giving a string,  called  the	 `con‐
	      text', which is compared to the patterns.	 The definition stored
	      for the first matching pattern will be returned.

	      For ordering of comparisons, patterns  are  searched  from  most
	      specific	to  least specific, and patterns that are equally spe‐
	      cific 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  pat‐
	      terns are considered to be more specific than the pattern `*'.

	      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  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 evalua‐
		     tion.  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  defini‐
		     tions  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 not
		     defined, the status is 2.

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

	      zstyle -m context style pattern
		     Match a value. Returns status zero if the 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 for‐
	      mat 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
	      parameter param.

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

       zregexparse
	      This implements some internals of the _regex_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
	      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 exam‐
		     ple,  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 argu‐
		     ment, so parsing stops if the next	 positional  parameter
		     does  not	also  begin  with `-' (unless the -E option is
		     used).

	      name:
	      name:-
	      name:: If one or two colons are given, the option takes an argu‐
		     ment;  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 options.

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

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

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

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

       As an example for the -E option, consider:

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

       will have the effect of

	      bar=(-b y)
	      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.1			 June 1, 2001			 ZSHMODULES(1)
[top]

List of man pages available for Ultrix

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net