This is zsh.info, produced by makeinfo version 4.0 from ./zsh.texi.

INFO-DIR-SECTION Utilities
START-INFO-DIR-ENTRY
* ZSH: (zsh).                     The Z Shell Manual.
END-INFO-DIR-ENTRY


File: zsh.info,  Node: The zsh/computil Module,  Next: The zsh/deltochar Module,  Prev: The zsh/complist Module,  Up: Zsh Modules

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 *Note Completion System:: ).  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 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.

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

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

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

comptags
comptry
     These implement the internals of the tags mechanism.

compvalues
     Like comparguments, but for the _values function.


File: zsh.info,  Node: The zsh/deltochar Module,  Next: The zsh/example Module,  Prev: The zsh/computil Module,  Up: Zsh Modules

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 occurrence
     of the character itself is not deleted.


File: zsh.info,  Node: The zsh/example Module,  Next: The zsh/files Module,  Prev: The zsh/deltochar Module,  Up: Zsh Modules

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.


File: zsh.info,  Node: The zsh/files Module,  Next: The zsh/mapfile Module,  Prev: The zsh/example Module,  Up: Zsh Modules

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 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 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
     accidentally chown /etc/passwd if /tmp/foo happens to be a link to
     /etc.  It will also check where it is after leaving directories,
     so that a recursive chown of a deep directory tree can't end up
     recursively chowning /usr as a result of directories being moved
     up the tree.

ln [ -dfis ] FILENAME DEST
ln [ -dfis ] FILENAME ... DIR
     Creates hard (or, with -s, symbolic) links.  In the first form, the
     specified DESTination is created, as a link to the specified
     FILENAME.  In the second form, each of the FILENAMEs is taken in
     turn, and linked to a pathname in the specified DIRectory that has
     the same last pathname component.

     Normally, ln will not attempt to create hard links to directories.
     This check can be overridden using the -d option.  Typically only
     the super-user can actually succeed in creating hard links to
     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 man page umask(2)) is used.

mv [ -fi ] FILENAME DEST
mv [ -fi ] FILENAME ... DIR
     Moves files.  In the first form, the specified FILENAME is moved
     to the specified DESTination.  In the second form, each of the
     FILENAMEs is taken in turn, and moved to a pathname in the
     specified DIRectory that has the same last pathname component.

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

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

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

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

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

     The -r option causes rm to recursively descend into directories,
     deleting all files in the directory before removing the directory
     with the rmdir system call (see man page 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 man page sync(2)),
     which flushes dirty buffers to disk.  It might return before the
     I/O has actually been completed.


File: zsh.info,  Node: The zsh/mapfile Module,  Next: The zsh/mathfunc Module,  Prev: The zsh/files Module,  Up: Zsh Modules

The zsh/mapfile Module
======================

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

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

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

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

Limitations
-----------

Although reading and writing of the file in question is efficiently
handled, zsh's internal memory management may be arbitrarily baroque.
Thus it should not automatically be assumed that use of mapfile
represents a gain in 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.


File: zsh.info,  Node: The zsh/mathfunc Module,  Next: The zsh/parameter Module,  Prev: The zsh/mapfile Module,  Up: Zsh Modules

The zsh/mathfunc Module
=======================

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

     (( f = sin(0.3) ))

assigns the sine of 0.3 to the parameter f.

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

The following functions take a single floating point 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 man page 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
expressions.

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

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

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

The function abs does not convert the type of its single argument; it
returns the absolute value of either a floating point number or an
integer.  The functions float and int convert their arguments into a
floating point or integer value (by truncation) respectively.

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


File: zsh.info,  Node: The zsh/parameter Module,  Next: The zsh/sched Module,  Prev: The zsh/mathfunc Module,  Up: Zsh Modules

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

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 parameters
     currently defined. The values are strings describing the type of
     the parameter, in the same format used by the t parameter flag, see
     *Note Parameter Expansion:: .  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 directory
     of the job).

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

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

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

userdirs
     This associative array maps user names to the 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.


File: zsh.info,  Node: The zsh/sched Module,  Next: The zsh/stat Module,  Prev: The zsh/parameter Module,  Up: Zsh Modules

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.


File: zsh.info,  Node: The zsh/stat Module,  Next: The zsh/termcap Module,  Prev: The zsh/sched Module,  Up: Zsh Modules

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 man
     page 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 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
     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 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 neither the name of the
          element nor the name of the files appears in ARRAY unless the
          -t or -n options were given, respectively.  If -t is given,
          the element name appears as a prefix to the appropriate array
          element; if -n is given, the file name appears as a separate
          array element preceding all the others.  Other formatting
          options are respected.

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

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

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

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

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

    -L
          Perform an lstat (see man page lstat(2)) rather than a stat
          system call.  In this case, if the file is a link, information
          about the link itself rather than the target file is returned.
          This option is required to make the link element useful.

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


File: zsh.info,  Node: The zsh/termcap Module,  Next: The zsh/terminfo Module,  Prev: The zsh/stat Module,  Up: Zsh Modules

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.


File: zsh.info,  Node: The zsh/terminfo Module,  Next: The zsh/zftp Module,  Prev: The zsh/termcap Module,  Up: Zsh Modules

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.


File: zsh.info,  Node: The zsh/zftp Module,  Next: The zsh/zle Module,  Prev: The zsh/terminfo Module,  Up: Zsh Modules

The zsh/zftp Module
===================

The zsh/zftp module makes available one builtin command:

zftp SUBCOMMAND [ ARGS ]
     The zsh/zftp module is a client for FTP (file transfer protocol).
     It is implemented as a builtin to allow full use of shell command
     line editing, file I/O, and job control mechanisms.  Often, users
     will access it via shell functions providing a more powerful
     interface; a set is provided with the zsh distribution and is
     described in *Note Zftp Function System::.  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 printed.

Subcommands
-----------

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

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

login [ NAME [ PASSWORD [ ACCOUNT ] ] ]
user [ NAME [ PASSWORD [ ACCOUNT ] ] ]
     Login the user NAME with parameters PASSWORD and ACCOUNT.  Any of
     the parameters can be omitted, and will be read from standard
     input if needed (NAME is always needed).  If standard input is a
     terminal, a 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 PASSWORD.  If the `?' is
     followed by a string, that is used as the prompt for reading the
     parameter instead of the default message (any necessary
     punctuation and whitespace should be included at the end of the
     prompt).  The first letter of the parameter (only) may be quoted
     with a `\'; hence an argument "\\$word" guarantees that the string
     from the shell parameter $word will be treated literally, whether
     or not it begins with a `?'.

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

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

     For example,

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

     will store the host ftp.elsewhere.xx and the user juser and then
     prompt the user for the 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
     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 status 1 for a file not found.

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

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

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

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

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

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

mkdir DIRECTORY
     Create a new directory DIRECTORY on the server.

rmdir DIRECTORY
     Delete the directory DIRECTORY  on the server.

rename OLD-NAME NEW-NAME
     Rename file OLD-NAME to NEW-NAME on the server.

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

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

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

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

     Each session remembers the status of the 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 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.

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

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

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

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
     description of the session subcommand.

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

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

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

    D
          Dumb:  use only the bare minimum of FTP 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 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 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
     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:

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

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


File: zsh.info,  Node: The zsh/zle Module,  Next: The zsh/zleparameter Module,  Prev: The zsh/zftp Module,  Up: Zsh Modules

The zsh/zle Module
==================

The zsh/zle module contains the Zsh Line Editor.  See *Note Zsh Line
Editor::.


File: zsh.info,  Node: The zsh/zleparameter Module,  Next: The zsh/zprof Module,  Prev: The zsh/zle Module,  Up: Zsh Modules

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 *Note
Zsh Line Editor::).

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 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 widgets. In the last case TYPE is the name of the
     builtin widgets the completion widget imitates in its behavior and
     NAME is the name of the shell function implementing the completion
     widget.

