This is Info file zsh.info, produced by Makeinfo-1.55 from the input
file ./zsh.texi.

This is a texinfo version of the man page for the Z Shell, originally by
Paul Falstad.  It was converted from the `zsh.1' file distributed with
zsh v2.5.0 by Jonathan Hardwick, `jch@cs.cmu.edu' and updated/modified
by Clive Messer, `clive@epos.demon.co.uk' to its present state.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: zsh.info,  Node: Shell Builtin Commands,  Next: Programmable Completion,  Prev: Options,  Up: Top

Shell Builtin Commands
**********************

`- simple command'
     *Note Precommand Modifiers::.

`. FILE [ ARG ... ]'
     Read and execute commands from FILE and execute them in the
     current shell environment.  If FILE does not contain a slash, or if
     `PATH_DIRS' is set, the shell looks in the components of `path' to
     find the directory containing FILE.  Files in the current
     directory are not read unless `.' appears somewhere in `path'.  If
     any arguments ARG are given, they become the positional
     parameters; the old positional parameters are restored when the
     FILE is done executing.  The exit status is the exit status of the
     last command executed.

`: [ ARG ... ]'
     This command only expands parameters.  A zero exit code is
     returned.

`alias [ -grmL ] [ NAME[=VALUE] ] ...'
     For each NAME with a corresponding VALUE, define an alias with that
     value.  A trailing space in VALUE causes the next word to be
     checked for alias substitution.  If the `-g' flag is present,
     define a global alias; global aliases are expanded even if they do
     not occur in command position.  For each NAME with no VALUE, print
     the value of NAME, if any.  With no arguments, print all currently
     defined aliases.  If the `-m' flag is given the arguments are
     taken as patterns (they should be quoted to preserve them from
     being interpreted as glob patterns) and the aliases matching these
     patterns are printed.  When printing aliases and the `-g' or `-r'
     flags are present, then restrict the printing to global or regular
     aliases, respectively.  If the `-L' flag is present, then print
     each alias in a manner suitable for putting in a startup script.
     The exit status is nonzero if a NAME (with no VALUE) is given for
     which no alias has been defined.

`autoload [ NAME ... ]'
     For each of the NAMEs (which are names of functions), create a
     function marked undefined.  The `fpath' variable will be searched
     to find the actual function definition when the function is first
     referenced.  The definition is contained in a file of the same
     name as the function.  If the file found contains a standard
     definition for the function, that is stored as the function;
     otherwise, the contents of the entire file are stored as the
     function.  The latter format allows functions to be used directly
     as scripts.

`bg [ JOB ... ]'
`JOB ... &'
     Put each specified JOB in the background, or the current job if
     none is specified. *Note Jobs & Signals::.

`bindkey -mevd'
`bindkey -r IN-STRING ...'
`bindkey -uU COMMAND'
`bindkey [ -a ] IN-STRING [ COMMAND ] ...'
`bindkey -s [ -a ] IN-STRING OUT-STRING ...'
     The `-e' and `-v' options put the keymaps in emacs mode and vi
     mode respectively; they cannot be used simultaneously.  The `-d'
     option resets all bindings to the compiled-in settings.  If not
     used with options `-e' or `-v', the maps will be left in emacs
     mode, or in vi mode if the `VISUAL' or `EDITOR' variables contain
     the string `vi'.  Metafied characters are bound to self-insert by
     default.  The `-m' option loads the compiled-in bindings of these
     characters for the mode determined by the preceding options, or
     the current mode if used alone.  Any previous binding done by the
     user will be preserved.  If the `-r' option is given, remove any
     binding for each IN-STRING.  If the `-u' option is given, undefine
     every key bound to COMMAND in the current keymap; with `-U', do so
     in every keymap.  If the `-s' option is not specified, bind each
     IN-STRING to a specified COMMAND.  If no COMMAND is specified,
     print the binding of IN-STRING if it is bound, or return a nonzero
     exit code if it is not bound.  If the `-s' option is specified,
     bind each IN-STRING to each specified OUT-STRING.  When IN-STRING
     is typed, OUT-STRING will be pushed back and treated as input to
     the line editor.  The process is recursive, but to avoid infinite
     loops the shell will report an error if more than 20 consecutive
     replacements happen.  If the `-a' option is specified, bind the
     IN-STRINGs in the alternative keymap instead of the standard one.
     The alternative keymap is used in vi command mode.

     It's possible for an IN-STRING to be bound to something and also
     be the beginning of a longer bound string.  In this case the shell
     will wait a certain time to see if more characters are typed, and
     if not it will execute the binding.  This timeout is defined by the
     `KEYTIMEOUT' parameter; the default is 0.4 seconds.  No timeout is
     done if the prefix string is not bound.

     For either IN-STRING or OUT-STRING, control characters may be
     specified in the form `^X', and the backslash may be used to
     introduce one of the following escape sequences:

    `\a'
          Bell character

    `\n'
          Linefeed (newline)

    `\b'
          Backspace

    `\t'
          Horizontal tab

    `\v'
          Vertical tab

    `\f'
          Form feed

    `\r'
          Carriage return

    `\e'
    `\E'
          Escape

    `\NNN'
          Character code in octal

    `\xNN'
          Character code in hexadecimal

    `\M-XXX'
          Character or escape sequence with meta bit set.  The `-'
          after the `M' is optional.

    `\C-X'
          Control character.  The `-' after the `M' is optional.

     In all other cases, `\' escapes the following character.  Delete is
     written as `^?'.  Note that `\M^?' and `^\M?' are not the same.

     Multi-character IN-STRINGS cannot contain the null character (`^@'
     or `^ ').  If they appear in a bindkey command, they will be
     silently translated to `\M-^@'.  This restriction does not apply
     to OUT-STRINGS, single-character IN-STRINGS and the first
     character of a multi-char IN-STRING.

`break [ N ]'
     Exit from an enclosing `for', `while', `until', `select', or
     `repeat' loop.  If N is specified, then break N levels instead of
     just one.

`builtin NAME [ ARGS ] ...'
     Executes the builtin NAME, with the given ARGS.

`bye'
     Same as `exit'.

`cd [ ARG ]'
`cd OLD NEW'
`cd [+-]n'
     Change the current directory.  In the first form, change the
     current directory to ARG, or to the value of `HOME' if ARG is not
     specified.  If ARG is `-', change to the value of `OLDPWD', the
     previous directory.  If a directory named ARG is not found in the
     current directory and ARG does not begin with a slash, search each
     component of the shell parameter `cdpath'.  If the option
     `CDABLEVARS' is set, and a parameter named ARG exists whose value
     begins with a slash, treat its value as the directory.

     The second form of `cd' substitutes the string NEW for the string
     OLD in the name of the current directory, and tries to change to
     this new directory.

     The third form of `cd' extracts an entry from the directory stack,
     and changes to that directory.  An argument of the form `+N'
     identifies a stack entry by counting from the left of the list
     shown by the `dirs' command, starting with zero.  An argument of
     the form `-N' counts from the right.  If the `PUSHD_MINUS' option
     is set, the meanings of `+' and `-' in this context are swapped.

`chdir'
     Same as `cd'.

`command simple command'
     *Note Precommand Modifiers::.

`compctl'
     *Note Programmable Completion::.

`continue [ NUM ]'
     Resume the next iteration of the enclosing `for', `while',
     `until', `select', or `repeat' loop.  If N is specified, break out
     of N-1 loops and resume at the N'th enclosing loop.

`declare [ ARG ... ]'
     Same as `typeset'.

`dirs [ -v ] [ ARG ... ]'
     With no arguments, print the contents of the directory stack.  If
     the `-v' option is given, number the directories in the stack when
     printing.  Directories are added to this stack with the `pushd'
     command, and removed with the `cd' or `popd' commands.  If
     arguments are specified, load them onto the directory stack,
     replacing anything that was there, and push the current directory
     onto the stack.

`disable [ -afmr ] ARG ...'
     Disable the hash table element named ARG temporarily.  The default
     is to disable builtin commands.  This allows you to use an
     external command with the same name as a builtin command.  The
     `-a' option causes `disable' to act on aliases.  The `-f' option
     causes `disable' to act on shell functions.  The `-r' option
     causes `disable' to act on reserved words.  Without arguments all
     disabled hash table elements from the corresponding hash table are
     printed.  With the `-m' flag the arguments are taken as patterns
     (which should be quoted to preserve them from being taken as glob
     patterns) and all hash table elements from the corresponding hash
     table matching these patterns are disabled.  Disabled objects can
     be enabled with the `enable' command.

`disown [ JOB ... ]'
`job ... &|'
`job ... &!'
     Remove the specified jobs from the job table; the shell will no
     longer report their status, and will not complain if you try to
     exit an interactive shell with them running or stopped.  If no
     `job' is specified use the current `job'.

`echo [ -neE ] [ ARG ... ]'
     Write each ARG on the standard output, with a space separating
     each one.  If the `-n' flag is not present, print a newline at the
     end.  `echo' recognizes the following escape sequences:

    `\a'
          Bell

    `\b'
          Backspace

    `\c'
          Don't print an ending newline

    `\e'
          Escape

    `\f'
          Form feed

    `\n'
          Newline

    `\r'
          Carriage return

    `\t'
          Horizontal tab

    `\v'
          Vertical tab

    `\\'
          Backslash

    `\0NNN'
          Character code in octal, with a maximum of three digits after
          the zero.  A non-octal digit terminates the number.

    `\xNN'
          Character code in hexadecimal, with a maximum of two digits
          after the `x'.  A non-hexadecimal digit terminates the number.

     The `-E' flag or the `BSD_ECHO' option can be used to disable
     these escape sequences.  In the later case `-e' flag can be used
     to enable them.

`echotc CAP [ ARG ... ]'
     Output the termcap string corresponding to the capability CAP,
     with optional arguments.

`emulate [ -R ] [ zsh | sh | ksh | csh ]'
     Set up zsh options to emulate the specified shell as much as
     possible.  `csh' will never be fully emulated.  If the argument is
     not one of the shells listed above, `zsh' will be used as a
     default.  If the `-R' option is given, all options are reset to
     their default value corresponding to the specified emulation mode.

`enable [ -afmr ] ARG ...'
     Enable the hash table element named ARG, presumably disabled
     earlier with `disable'.  The default is to enable builtin
     commands.  The `-a' option causes `enable' to act on aliases.  The
     `-f' option causes `enable' to act on shell functions.  The `-r'
     option causes `enable' to act on reserved words.  Without
     arguments all enable hash table elements from the corresponding
     hash table are printed.  With the `-m' flag the arguments are
     taken as patterns (should be quoted) and all hash table elements
     from the corresponding hash table matching these patterns are
     enabled.  Enabled objects can be disabled with the `disable'
     builtin command.

`eval [ ARG ... ]'
     Read the arguments as input to the shell and execute the resulting
     command(s) in the current shell process.

`exec simple command'
     *Note Precommand Modifiers::.

`exit [ N ]'
     Exit the shell with the exit code specified by N; if none is
     specified, use the exit code from the last command executed.  An
     `EOF' condition will also cause the shell to exit, unless the
     `IGNORE_EOF' option is set.

`export [ NAME[=VALUE] ... ]'
     The specified NAMEs are marked for automatic export to the
     environment of subsequently executed commands.  `export' is
     equivalent to `typeset -x'.

`false'
     Do nothing and return an exit code of 1.

`fc [ -e ENAME ] [ -nlrdDfEim ] [ OLD=NEW ... ] [ FIRST [ LAST ]]'
`fc -ARWI [ FILENAME ]'
     Select a range of commands from FIRST to LAST from the history
     list.  The arguments FIRST and LAST may be specified as a number
     or as a string.  A negative number is used as an offset to the
     current history event number.  A string specifies the most recent
     event beginning with the given string.  All substitutions OLD=NEW,
     if any, are then performed on the commands.  If the `-l' flag is
     given, the resulting commands are listed on standard output.  If
     the `-m' flag is also given the first argument is taken as a
     pattern (which should be quoted), and only the history events
     matching this pattern will be shown.  Otherwise the editor program
     ENAME is invoked on a file containing these history events.  If
     ENAME is not given, the value of the parameter `FCEDIT' is used.
     If ENAME is `-', no editor is invoked.  When editing is complete,
     the edited command(s) is executed.  If FIRST is not specified, it
     will be set to -1 (the most recent event), or to -16 if the `-l'
     flag is given.  If LAST is not specified, it will be set to FIRST,
     or to -1 if the `-l' flag is given.  The flag `-r' reverses the
     order of the commands and the flag `-n' suppresses command numbers
     when listing.  Also when listing, `-d' prints timestamps for each
     command, `-f' prints full time and date stamps. Adding the `-E'
     flag causes the dates to be printed as (`dd.mm.yyyy'), instead of
     the default, `mm/dd/yyyy'.  Adding the `-i' flag causes the dates
     to be printed as `yyyy-mm-dd', in a fixed format.  With the `-D'
     flag, `fc' prints elapsed times.

     `fc -R' reads the history from the given file, `fc -W' writes the
     history out to the given file, and `fc -A' appends the history out
     to the given file. `fc -AI' (`WI') appends (writes) only those
     events that are new since the last incremental append (write) to
     the history file.  In any case the file will have no more than
     `SAVEHIST' entries.

`fg [ JOB ... ]'
`JOB ...'
     Bring the specified JOBs to the foreground.  If no JOB is
     specified, use the current job.

`functions [ +-tum ] [ NAME ... ]'
     Equivalent to `typeset -f'.

`getln NAME ...'
     Read the top value from the buffer stack and put it in the shell
     parameter NAME.  Equivalent to `read -zr'.  The flags `-c', `-l',
     `-A', `-e', `-E', and `-n' are also supported.

`getopts OPTSTRING NAME [ ARG ... ]'
     Checks ARG for legal options.  If ARG is omitted, use the
     positional parameters.  A valid option argument begins with a `+'
     or a `-'.  An argument not beginning with a `+' or a `-', or the
     argument `--', ends the options.  OPTSTRING contains the letters
     that `getopts' recognizes.  If a letter is followed by a `:', that
     option is expected to have an argument.  The options can be
     separated from the argument by blanks.

     Each time it is invoked, `getopts' places the option letter it
     finds in the shell parameter NAME, prepended with a `+' when ARG
     begins with a `+'.  The index of the next ARG is stored in
     `OPTIND'.  The option argument, if any, is stored in `OPTARG'.

     A leading `:' in OPTSTRING causes `getopts' to store the letter of
     the invalid option in `OPTARG', and to set NAME to `?' for an
     unknown option and to `:' when a required option is missing.
     Otherwise, `getopts' prints an error message.  The exit status is
     nonzero when there are no more options.

`hash [ -dfmr ] [ NAME[=VALUE ] ] ...'
     With no arguments or options, `hash' will list the entire command
     hash table.

     The `-m' option causes the arguments to be taken as patterns (they
     should be quoted) and the elements of the command hash table
     matching these patterns are printed.

     The `-r' option causes the command hash table to be thrown out and
     restarted.  The `-f' option causes the entire path to be searched,
     and all the commands found are added to the hash table.  These
     options cannot be used with any arguments.

     For each NAME with a corresponding VALUE, put NAME in the command
     hash table, associating it with the pathname VALUE.  Whenever NAME
     is used as a command argument, the shell will try to execute the
     file given by VALUE.  For each NAME with no corresponding VALUE,
     search for NAME in the path, and add it to the command hash table,
     and associating it with the discovered path, if it is found.

     Adding the `-d' option causes `hash' to act on the named directory
     table instead of the command hash table.  The remaining discussion
     of `hash' will assume that the `-d' is given.

     If invoked without any arguments, and without any other options,
     `hash -d' lists the entire named directory table.

     The `-m' option causes the arguments to be taken as patterns (they
     should be quoted) and the elements of the named directory table
     matching these patterns are printed.

     The `-r' option causes the named directory table to be thrown out
     and restarted so that it only contains  `~'.  The `-f' option
     causes all usernames to be added to the named directory table.
     These options cannot be used with any arguments.

     For each NAME with a corresponding VALUE, put NAME in the named
     directory table.  The directory name NAME is then associated with
     the specified path VALUE, so that VALUE may be referred to as
     `~NAME'.  For each NAME with no corresponding VALUE, search for as
     a username and as a parameter.  If it is found, it is added to the
     named directory hash table.

`history [ -nrdDfEim ] [ FIRST [ LAST ]]'
     Same as `fc -l'.

`integer [ +-lrtux ] [ NAME[=VALUE] ]'
     Same as `typeset -i', except that options irrelevant to integers
     are not permitted.

`jobs [ -lprs ] [ JOB ... ]'
     Lists information about each given job, or all jobs if JOB is
     omitted.  The `-l' flag lists process ids, and the `-p' flag lists
     process groups.  If the `-r' flag is given only running jobs will
     be listed; if the `-s' flag is given only stopped jobs are shown.

`kill [ -s SIGNAL_NAME ] JOB ...'
`kill [ -SIG ] JOB ...'
`kill -l [ SIG ... ]'
     Sends either `SIGTERM' or the specified signal to the given jobs or
     processes.  Signals are given by number or by names, without the
     `SIG' prefix.  If the signal being sent is not `KILL' or `CONT',
     then the job will be sent a `CONT' signal if it is stopped.  The
     argument JOB can be the process id of a job not in the job list.
     In the third form, `kill -l', if SIG is not specified the signal
     names are listed.  Otherwise, for each SIG that is a name, the
     corresponding signal number is listed.  For each SIG that is a
     signal number or a number representing the exit status of a
     process which was terminated or stopped by a signal the name of
     the signal is printed.

`let ARG ...'
     Evaluate each ARG as an arithmetic expression.  *Note Arithmetic
     Evaluation::, for a description of arithmetic expressions.  The
     exit status is 0 if the value of the last expression is nonzero,
     and 1 otherwise.

`limit [ -hs ] [ RESOURCE [ LIMIT ] ] ...'
     Set or display resource limits.  Unless the `-s' flag is given the
     limit applies only the children of the shell.  If `-s' is given
     without other arguments, the resource limits of the current shell
     is set to the previously set resource limits of the children.  If
     LIMIT is not specified, print the current limit placed on
     RESOURCE; otherwise set the limit to the specified value.  If the
     `-h' flag is given, use hard limits instead of soft limits.  If no
     RESOURCE is given, print all limits.
     RESOURCE is one of:

    `cputime'
          Maximum CPU seconds per process.

    `filesize'
          Largest single file allowed.

    `datasize'
          Maximum data size (including stack) for each process.

    `stacksize'
          Maximum stack size for each process.

    `coredumpsize'
          Maximum size of a core dump.

    `resident'
    `memoryuse'
          Maximum resident set size.

    `memorylocked'
          Maximum amount of memory locked in RAM.

    `descriptors'
          Maximum value for a file descriptor.

    `openfiles'
          Maximum number of open files.

    `vmemorysize'
          Maximum amount of virtual memory.

     Which of these resource limits are available depends on the system.
     lIMIT is a number, with an optional scaling factor, as follows:

    `Nh'
          Hours.

    `Nk'
          Kilobytes.  This is the default for all but cputime.

    `Nm'
          Megabytes or minutes.

    `MM:SS'
          Minutes and seconds.

`local [ +-LRZilrtu [N]] [ NAME[=VALUE] ]'
     Same as `typeset', except that the options `-x' and `-f' are not
     permitted.

`log'
     List all users currently logged in who are affected by the current
     setting of the `watch' parameter.

`logout'
     Exit the shell, if this is a login shell.

`noglob simple command'
     *Note Precommand Modifiers::.

`popd [ +-N ]'
     Removes a entry from the directory stack and, performs a `cd' to
     the new top directory.  With no argument, the current top entry is
     removed.  An argument of the form `+N' identifies a stack entry by
     counting from the left of the list shown by the `dirs' command,
     starting with zero.  An argument of the form `-n' counts from the
     right.  If the `PUSHD_MINUS' option is set, the meanings of `+'
     and `-' in this context are swapped.

`print [ -nrslzpNDPoOicm ] [ -uN ] [ -R [ -en ]] [ ARG ... ]'
     With no flags or with flag `-', the arguments are printed on the
     standard output as described by `echo', with the following
     differences: the escape sequence `\M-x' metafies the character `x'
     (sets the highest bit), `\C-x' produces a control character
     (`\C-@' and `\C-?' give the characters NULL and delete) and `\E'
     is a synonym for `\e'.  Finally, if not in an escape sequence, `\'
     escapes the following character and is not printed.

    `-r'
          Ignore the escape conventions of `echo'.

    `-R'
          Emulate the BSD `echo' command which does not process escape
          sequences unless the `-e' flag is given.  The `-n' flag
          suppresses the trailing newline.  Only the `-e' and `-n'
          flags are recognized after `-R', all other arguments and
          options are printed.

    `-m'
          Take the fist argument as a pattern (should be  quoted) and
          remove it from the argument list together with subsequent
          arguments that do not match this pattern.

    `-s'
          Place the results in the history list instead of on the
          standard output.

    `-n'
          Do not add a newline to the output.

    `-l'
          Print the arguments separated by newlines instead of spaces.

    `-N'
          Print the arguments separated and terminated by nulls.

    `-o'
          Print the arguments sorted in ascending order.

    `-O'
          Print the arguments sorted in descending order.

    `-i'
          If given together with `-o' or `-O', makes the sort be
          case-insensitive.

    `-c'
          Print the arguments in columns.

    `-uN'
          Print the arguments to file descriptor N.

    `-p'
          Print the arguments to the input of the coprocess.

    `-z'
          Push the arguments onto the editing buffer stack, separated
          by spaces; no escape sequences are recognized.

    `-D'
          Treat the arguments as directory names, replacing prefixes
          with `~' expressions, as appropriate.

    `-P'
          Recognize the same escape sequences as in the `PROMPT'
          parameter.

`pushd [ ARG ]'
`pushd OLD NEW'
`pushd +-N'
     Change the current directory, and push the old current directory
     onto the directory stack.  In the first form, change the current
     directory to ARG.  If ARG is not specified, change to the second
     directory on the stack (that is, exchange the top two entries), or
     change to the value of `HOME' if the `PUSHD_TO_HOME' option is set
     or if there is only one entry on the stack.  If ARG is `-', change
     to the value of `OLDPWD', the previous directory.  If a directory
     named ARG is not found in the current directory and ARG does not
     contain a slash, search each component of the shell parameter
     `cdpath'.  If the option `CDABLEVARS' is set, and a parameter
     named ARG exists whose value begins with a slash, treat its value
     as the directory.  If the option `PUSHD_SILENT' is not set, the
     directory stack will be printed after a `pushd' is performed.

     The second form of `pushd' substitutes the string NEW for the
     string OLD in the name of the current directory, and tries to
     change to this new directory.

     The third form of `pushd' changes directory by rotating the
     directory list.  An argument of the form `+n' identifies a stack
     entry by counting from the left of the list shown by the `dirs'
     command, starting with zero.  An argument of the form `-n' counts
     from the right.  If the `PUSHD_MINUS' option is set, the meanings
     of `+' and `-' in this context are swapped.

`pushln'
     Equivalent to `print -nz'.

`pwd [ -rLP ]'
     Print the absolute pathname of the current working directory.  If
     the `-r' or the `-P' flag is specified, or the `CHASE_LINKS'
     option is set and the `-L' flag is not given, the printed path
     will not contain symbolic links.

`r'
     Equivalent to `fc -e -'.

`read [ -rzpqAclneE ] [ -k [NUM] ] [ -uN ] [ NAME?PROMPT ] [ NAME ... ]'
     Read one line and break it into fields using the characters in
     `IFS' as separators.

    `-r'
          Raw mode: a `\' at the end of a line does not signify line
          continuation.

    `-q'
          Read only one character from the terminal and set NAME to `y'
          if this character was `y' or `Y' and to `n' otherwise.  With
          this flag set the return value is zero only if the character
          was `y' or `Y'.

    `-k [ NUM ]'
          Read only one (or NUM) characters from the terminal.

    `-z'
          Read from the editor buffer stack.  The first field is
          assigned to the first NAME, the second field to the second
          NAME,  etc., with leftover fields assigned to the last NAME.

    `-e'
    `-E'
          The words read are printed after the whole line is read.  If
          the `-e' flag is set, the words are not assigned to the
          parameters.

    `-A'
          The first NAME is taken as the name of an array and all words
          are assigned to it.

    `-c'
    `-l'
          These flags are allowed only if called inside a function used
          for completion (specified with the `-K' flag to `compctl').
          If the `-c' flag is given, the words of  the  current command
          are  read. If the `-l' flag is given, the whole line is
          assigned as a scalar.  If `name' is omitted then `REPLY' is
          used for scalars and `reply' for arrays.

    `-n'
          Together with either of the previous flags, this option gives
          the number of the word the cursor is on or the index of the
          character the cursor is on respectively.

    `-uN'
          Input is read from file descriptor N.

    `-p'
          Input is read from the coprocess.

     If the first argument contains a `?', the remainder of this word is
     used as a `prompt' on standard error when the shell is
     interactive.  The exit status is `0' unless an end-of-file is
     encountered.

`readonly [ NAME[=VALUE]] ...'
     The given NAMES are marked readonly; these names cannot be changed
     by subsequent assignment.

`rehash [ -df ]'
     Throw out the command hash table and start over.  If the `-f'
     option is set, rescan the command path immediately, instead of
     rebuilding the hash table incrementally.

     The `-d' option causes `rehash' to act on the named directory table
     instead of the command hash table.  This reduces the named
     directory table to only the `~' entry.  If the `-f' option is also
     used, the named directory table is rebuilt immediately.

     `rehash' is equivalent to `hash -r'.

`return [ N ]'
     Causes a shell function or `.' script to return to the invoking
     script with the return status specified by N.  If N is omitted
     then the return status is that of the last command executed.

     If `return' was executed from a trap in a `TRAPxxx' function, the
     effect is different for zero and nonzero return status.  With zero
     status (or after an implicit return at the end of the trap), the
     shell will return to whatever it was previously processing;  with
     a non-zero status, the shell will behave as interrupted except
     that the return status of the trap is retained.  Note that the
     signal which caused the trap is passed as the first argument, so
     the statement `return $((128+$1))' will return the same status as
     if the signal had not been trapped.

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

`set [ +-OPTIONS ] [ +-o OPTION NAME ] ... [ +-A [ NAME ] ] [ ARG ... ]'
     Set the options for the shell and/or set the positional
     parameters, or declare an array.  If the `-s' option is given it
     causes the specified arguments to be sorted before assigning them
     to the positional parameters (or to the array NAME if `-A' is
     used).  With `+s' sort arguments in descending order.  *Note
     Options::, for the meaning of the other flags.  Flags may be
     specified by name using the `-o' option.  If the `-A' flag is
     specified, NAME is set to an array containing the given ARGs; if
     `+A' is used and NAME is an array, the gien arguments will replace
     the initial elements of that array; if no NAME is specified, all
     arrays are printed.  Otherwise the positional parameters are set.
     If no arguments are given, then the names and values of all
     parameters are printed on the standard output.  If the only
     argument is `+', the names of all parameters are printed.

`setopt [ -m ] [ +-OPTIONS ] [ NAME ... ]'
     Set the options for the shell.  All options specified either with
     flags or by name are set.  If no arguments are supplied, the names
     of all options currently set are printed.  In option names, case is
     insignificant, and all underscore characters are ignored.  If the
     `-m' flag is given the arguments are taken as patterns (which
     should be quoted to preserve them from being interpreted as glob
     patterns), and all options with names matching these patterns are
     set.

`shift [ N ] [ NAME ... ]'
     The positional parameters from `$N+1' ... are renamed `$1', where
     N is an arithmetic expression that defaults to 1.  If any NAMEs
     are given then the arrays with these names are shifted, instead of
     the positional parameters.

`source'
     Same as `.', except that the current directory is always searched
     and is always searched first, before directories in `path'.

`suspend [ -f ]'
     Suspend the execution of the shell (send it a `SIGTSTP') until it
     receives a `SIGCONT'.  If the `-f' option is not given, complain
     if this is a login shell.

`test ARG ...'
`[ ARG ... ]'
     Like the system version of `test'.  Added for compatibility; use
     conditional expressions instead.

`times'
     Print the accumulated user and system times for the shell and for
     processes run from the shell.

`trap [ ARG ] [ SIG ] ...'
     ARG is a command to be read and executed when the shell receives
     SIG.  Each SIG can be given as a number or as the name of a
     signal.  If ARG is `-', then all traps SIG are reset to their
     default values.  If ARG is the null string, then this signal is
     ignored by the shell and by the commands it invokes.  If SIG is
     `ZERR' then ARG will be executed after each command with a nonzero
     exit status.  If SIG is `DEBUG' then ARG will be executed after
     each command. If SIG is `0' or `EXIT' and the `trap' statement is
     executed inside the body of a function, then the command ARG is
     executed after the function completes.  If SIG is `0' or `EXIT'
     and the `trap' statement is not executed inside the body of a
     function, then the command ARG is executed when the shell
     terminates.  The `trap' command with no arguments prints a list of
     commands associated with each signal.

`true'
     Do nothing and return an exit code of 0.

`ttyctl [ -fu ]'
     The `-f' option freezes the tty, and `-u' un-freezes it.  When the
     tty is frozen, no changes made to the tty settings by external
     programs will be honoured by the shell, except for changes in the
     size of the screen; the shell will simply reset the settings to
     their previous values as soon as each command exits.  Thus, `stty'
     and similar programs have no effect when the tty is frozen.
     Without options it reports whether the terminal is frozen or not.

`type [ -fpam ] NAME ...'
     Same as `whence -v'.

`typeset [ +-LRUZfilrtuxm [N]] [ NAME[=VALUE]] ...'
     Set attributes and values for shell parameters.  When invoked
     inside a function, a new parameter is created which will be unset
     when the function completes.  The new parameter will not be
     exported unless `ALL_EXPORT' is set, in which case the parameter
     will be exported provided no parameter of that name already
     exists.  The following attributes are valid:

    `-L'
          Left justify and remove leading blanks from VALUE.  If N is
          nonzero, it defines the width of the field; otherwise it is
          determined by the width of the value of the first assignment.
          When the parameter is printed, it is filled on the right
          with blanks or truncated if necessary to fit the field.
          Leading zeros are removed if the `-Z' flag is also set.

    `-R'
          Right justify and fill with leading blanks.  If N is nonzero
          it defines the width of the field; otherwise it is determined
          by the width of the value of the first assignment.  When the
          parameter is printed, the field is left filled with blanks or
          truncated from the end.

    `-U'
          For arrays keep only the first element of each duplications.
          It can also be set for colon separated special parameters
          like `PATH' or `FIGNORE', etc.

    `-Z'
          Right justify and fill with leading zeros if the first
          non-blank character is a digit and the `-L' flag has not been
          set.  If N is nonzero it defines the width of the field;
          otherwise it is determined by the width of the value of the
          first assignment.

    `-f'
          The names refer to functions rather than parameters.  No
          assignments can be made, and the only other valid flags are
          `-t' and `-u'.  The flag `-t' turns on execution tracing for
          this function.  The flag `-u' causes this function to be
          marked for autoloading.  The `fpath' parameter will be
          searched to find the function definition when the function is
          first referenced.; see `autoload'.

    `-i'
          Use an internal integer representation.  If N is nonzero it
          defines the output arithmetic base, otherwise it is
          determined by the first assignment.

    `-l'
          Convert to lower case.

    `-r'
          The given NAMEs are marked read-only.

    `-t'
          Tags the named parameters.  Tags have no special meaning to
          the shell.

    `-u'
          Convert to upper case.

    `-x'
          Mark for automatic export to the environment of subsequently
          executed commands.

     Using `+' rather than `-' causes these flags to be turned off.  If
     no arguments are given but flags are specified, a list of named
     parameters which have these flags set is printed.  Using `+'
     instead of `-' keeps their values from being printed.  If no
     arguments or options are given, the names and attributes of all
     parameters are printed.  If only the `-m' flag is given the
     arguments are taken as patterns (which should be quoted), and all
     parameters or functions (with the `-f' flag) with matching names
     are printed.

`ulimit [ -SHacdflmnpstv ] [ LIMIT ] ...'
     Set or display resource limits of the shell and the processes
     started by the shell.  The value of LIMIT can be a number in the
     unit specified below or the value `unlimited'.  If the `-H' flag
     is given use hard limits instead of soft limits.  If the `-S' flag
     is given together with the `-H' flag set both hard and soft
     limits.  If no options are used, the file size limit (`-f') is
     assumed.  If LIMIT is omitted the current value of the specified
     resources are printed.  When more than one resource values are
     printed the limit name and unit is printed before each value.

    `-a'
          Lists all of the current resource limits.

    `-c'
          Maximum size of core dumps, in 512-byte blocks.

    `-d'
          Maximum size of the data segment, in Kbytes.

    `-f'
          Maximum size of individual files written, in 512-byte blocks.

    `-l'
          Maximum size of locked-in memory, in Kbytes.

    `-m'
          Maximum size of physical memory, in Kbytes.

    `-n'
          Maximum number of open file descriptors.

    `-s'
          Maximum size of stack, in Kbytes.

    `-t'
          Maximum number of CPU seconds.

    `-u'
          The number of processes available to the user.

    `-v'
          Maximum size of virtual memory, in Kbytes.

`umask [ -S] [ MASK ]'
     The umask is set to MASK.  MASK can be either an octal number or a
     symbolic value as described in `chmod(1)'.  If MASK is omitted,
     the current value is printed.  The `-S' option causes the mask to
     be printed as a symbolic value.  Otherwise, the mask is printed as
     an octal number.  Note that in the symbolic form the permissions
     you specify are those which are to be allowed (not denied) to the
     users specified).

`unalias [ -m ] NAME ...'
     The alias definition, if any, for each NAME is removed.  With the
     `-m' flag, the arguments are taken as patterns (which should be
     quoted), and all aliases with matching names are removed.
     `unalias' is equivalent to `unhash -a'.

`unfunction [ -m ] NAME ...'
     The function definition, if any, for each NAME is removed.  With
     the `-m' flag, the arguments are taken as patterns (which should be
     quoted), and all function with matching names are removed.
     `unfunction' is equivalent to `unhash -f'.

`unhash [ -adfm ] NAME ...'
     Remove the element named NAME from an internal hash table.  The
     default is remove elements from the command hash table.  The `-a'
     option causes `unhash' to remove aliases.  The `-f' option causes
     `unhash' to remove shell functions.  The `-d' options causes
     `unhash' to remove named directories.  If the `-m' flag is given
     the arguments are taken as patterns (should be quoted) and all
     elements of the corresponding hash table with matching names will
     be removed.

`unlimit [ -hs ] RESOURCE ...'
     The resource limit for each RESOURCE is set to the hard limit.  If
     the `-h' flag is given and the shell is running as root, the hard
     resource limit for each RESOURCE is removed.  The resources of the
     shell process are only changed if the `-s' flag is given.

`unset [ -fm ] NAME ...'
     Each named parameter is unset.  If the `-m' flag is set, the
     arguments are taken as patterns (which should be quoted), and all
     parameters with matching names are unset.  `Unset -f' is
     equivalent to `unfunction'.

`unsetopt [ -m ]  [ +-OPTIONS ] [ NAME ... ]'
     Unset the options for the shell.  All options specified either with
     flags or by name are unset.  If the `-m' flag is given, the
     arguments are taken as patterns (which should be quoted), and all
     options with names matching these patterns are unset.

`vared [ -c ] [ -h ] [ -p PROMPT] [ -r RPROMPT ] NAME'
     The value of the parameter NAME is loaded into the edit buffer,
     and the line editor is invoked.  When the editor exits, NAME is
     set to the string value returned by the editor.  If the `-c' flag
     is given, the parameter is created if it doesn't already exist.
     If the `-p' flag is given, PROMPT will be taken as the prompt to
     display at the left and if the `-r' flag is given, the following
     string gives the prompt to display at the right.  If the `-h' flag
     is specified, the history can be accessed from `zle'.

`wait [ JOB ... ]'
     Wait for the specified jobs or processes.  If JOB is not given
     then all currently active child processes are waited for.  Each
     JOB can be either a job specification or the process-id of a job
     in the job table.  The exit status from this command is that of
     the job waited for.

`whence [ -vcfpam ] NAME ...'
     For each name, indicate how it would be interpreted if used as a
     command name.  The `-v' flag produces a more verbose report.  The
     `-c' flag prints the results in a csh-like format and takes
     precedence over `-v'.  The `-f' flag causes the contents of a
     shell function to be displayed, which would otherwise not happen
     unless the `-c' flag were used.  The `-p' flag does a path search
     for NAME even if it is an alias, reserved word, shell function or
     builtin.  The `-a' flag does a search for all occurrences of NAME
     throughout the command path.  With the `-m' flag, the arguments
     are taken as patterns (which should be quoted), and the
     information is displayed for each command matching one of these
     patterns.

`where'
     Same as `whence -ca'.

`which [ -pam ] NAME ...'
     Same as `whence -c'.


File: zsh.info,  Node: Programmable Completion,  Next: Concept Index,  Prev: Shell Builtin Commands,  Up: Top

Programmable Completion
***********************

`compctl [ -CDT ] OPTIONS [ COMMAND ... ]'

`compctl [ -CDT ] OPTIONS'
`        [  -x  PATTERN  OPTIONS - ... -- ] [ + OPTIONS [ -x ... -- ]
... [+] ]'
`        [ COMMAND ... ]'

`compctl -L [ -CDT ] [ COMMAND ... ]'

`compctl + COMMAND ...'

Control the editor's completion behaviour according to the supplied set
of OPTIONS.  Various editing commands, notably
`expand-or-complete-word', usually bound to TAB, will attempt to
complete a word typed by the user, while others, notably
`delete-char-or-list', usually bound to `^D' in emacs editing mode,
list the possibilities; `compctl' controls what those possibilities
are.  They may for example be filenames (the most common case, and
hence the default), shell variables, or words from a user-specified
list.

* Menu:

* Command Flags::
* Options Flags::
* Alternative Completion::
* Extended Completion::
* Example::


File: zsh.info,  Node: Command Flags,  Next: Options Flags,  Up: Programmable Completion

Command Flags
=============

Completion of the arguments of a command may be different for each
command or may use the default.  The behaviour when completing the
command word itself may also be separately specified.  These correspond
to the following flags and arguments, all of which (except for `-L')
may be combined with any combination of the options described
subsequently in *Note Options Flags::.

`COMMAND ...'
     controls completion for the named commands, which must be listed
     last on the command line.  If completion is attempted for a
     command with a pathname containing slashes and no completion
     definition is found, the  search is retried with the last pathname
     component.  Note that aliases are expanded before the command name
     is determined unless the `COMPLETE_ALIASES' option is set.
     Commands should not be combined with the `-D', `-C' or `-T' flags.

`-D'
     controls default completion behavior for the arguments of commands
     not assigned any special behavior.  If no `compctl -D' command has
     been issued, filenames are completed.

`-C'
     controls completion when the command word itself is being
     completed.  If no `compctl -C' command has been issued,  the names
     of any executable command (whether in the path or specific to the
     shell, such as aliases or functions) are completed.

`-T'
     supplies completion flags to be used  before any other processing
     is done, even those given to specific commands with other `compctl'
     definitions.  This is only useful when combined with extended
     completion (the `-x' flag. *Note Extended Completion::).  Using
     this flag you can define default behaviour which will apply to all
     commands without exception, or you can alter the standard behaviour
     for all commands.  For example, if your access to the user
     database is too slow  and/or it contains too many users (so that
     completion after `~' is too slow to be usable), you can use

     `compctl -Tx  'C[0,*/*]' -f - 's[~]' -k FRIENDS -S/'

     to complete the strings in the array FRIENDS after a `~'.  The
     first argument is necessary so that this form of `~'-completion is
     not tried after the directory name is finished.

`-L'
     lists the existing completion behaviour in a manner suitable for
     putting into a start-up script; the existing behaviour is not
     changed.  Any combination of the above forms may be specified,
     otherwise all defined completions are listed.  Any other flags
     supplied are ignored.

`no argument'
     If no argument is given, `compctl' lists all defined completions
     in an abbreviated form; with a list of OPTIONS, all completions
     with those flags set (not counting extended completion) are listed.

     If the `+' flag is alone and followed immediately by the COMMAND
     list, the completion behaviour for all the commands in the list is
     reset to the default.  In other words, completion will
     subsequently use the options specified by the `-D' flag.


File: zsh.info,  Node: Options Flags,  Next: Alternative Completion,  Prev: Command Flags,  Up: Programmable Completion

Options Flags
=============

`[ -fcFBdeaRGovNAIOPZEnbjrzu ]'
`[ -k ARRAY ] [ -g GLOBSTRING ] [ -s SUBSTSTRING ]'
`[ -K FUNCTION ] [ -H NUM PATTERN ]'
`[ -Q ] [ -P PREFIX ] [ -S SUFFIX ]'
`[ -q ] [ -X EXPLANATION ]'
`[ -l CMD ] [ -U ]'

The remaining options specify the type of command arguments to look for
during completion.  Any combination of these flags may be specified;
the result is a sorted list of all the possibilities.  The options are
described in the following sections.

* Menu:

* Simple Flags::
* Flags with arguments::
* Control Flags::


File: zsh.info,  Node: Simple Flags,  Next: Flags with arguments,  Up: Options Flags

Simple Flags
------------

These produce completion lists made up by the shell itself:

`-f'
     Filenames and file-system paths.

`-c'
     Command names, including aliases, shell functions, builtins and
     reserved words.

`-F'
     Function names.

`-B'
     Names of builtin commands.

`-m'
     Names of external commands.

`-w'
     Reserved words.

`-a'
     Alias names.

`-R'
     Names of regular (non-global) aliases.

`-G'
     Names of global aliases.

`-d'
     This can be combined with `-F', `-B', `-w', `-a', `-R' and `-G' to
     get names of disabled functions, builtins, reserved words or
     aliases.

`-e'
     This option (to show enabled commands) is in effect by default, but
     may be combined with `-d'; `-de' in combination with `-F', `-B',
     `-w', `-a', `-R' and `-G' will complete names of functions,
     builtins, reserved words or aliases whether or not they are
     disabled.

`-o'
     Names of shell options. *Note Options::.

`-v'
     Names of any variable defined in the shell.

`-N'
     Names of scalar (non-array) parameters.

`-A'
     Array names.

`-I'
     Names of integer variables.

`-O'
     Names of read-only variables.

`-p'
     Names of parameters used by the shell (including special
     parameters).

`-Z'
     Names of shell special parameters.

`-E'
     Names of environment variables.

`-n'
     Named directories.

`-b'
     Key binding names.

`-j'
     Job names: the first word of the job leader's command line.  This
     is useful with the kill builtin.

`-r'
     Names of running jobs.

`-z'
     Names of suspended jobs.

`-u'
     User names.

