Parameters Set By The Shell
===========================

The following parameters are automatically set by the shell:

! <S>
     The process ID of the last background command invoked.

# <S>
     The number of positional parameters in decimal.  Note that some
     confusion may occur with the syntax $#PARAM which substitutes the
     length of PARAM.  Use ${#} to resolve ambiguities.  In particular,
     the sequence `$#-...' in an arithmetic expression is interpreted as
     the length of the parameter -, q.v.

ARGC <S> <Z>
     Same as #.

$ <S>
     The process ID of this shell.

- <S>
     Flags supplied to the shell on invocation or by the set or setopt
     commands.

* <S>
     An array containing the positional parameters.

argv <S> <Z>
     Same as *.  Assigning to argv changes the local positional
     parameters, but argv is _not_ itself a local parameter.  Deleting
     argv with unset in any function deletes it everywhere, although
     only the innermost positional parameter array is deleted (so * and
     @ in other scopes are not affected).

@ <S>
     Same as argv[@], even when argv is not set.

? <S>
     The exit value returned by the last command.

0 <S>
     The name used to invoke the current shell.  If the
     FUNCTION_ARGZERO option is set, this is set temporarily within a
     shell function to the name of the function, and within a sourced
     script to the name of the script.

status <S> <Z>
     Same as ?.

pipestatus <S> <Z>
     An array containing the exit values returned by all commands in the
     last pipeline.

_ <S>
     The last argument of the previous command.  Also, this parameter
     is set in the environment of every command executed to the full
     pathname of the command.

CPUTYPE
     The machine type (microprocessor class or machine model), as
     determined at run time.

EGID <S>
     The effective group ID of the shell process.  If you have
     sufficient privileges, you may change the effective group ID of
     the shell process by assigning to this parameter.  Also (assuming
     sufficient privileges), you may start a single command with a
     different effective group ID by `(EGID=GID; command)'

EUID <S>
     The effective user ID of the shell process.  If you have sufficient
     privileges, you may change the effective user ID of the shell
     process by assigning to this parameter.  Also (assuming sufficient
     privileges), you may start a single command with a different
     effective user ID by `(EUID=UID; command)'

ERRNO <S>
     The value of errno (see man page errno(3)) as set by the most
     recently failed system call.  This value is system dependent and
     is intended for debugging purposes.

GID <S>
     The real group ID of the shell process.  If you have sufficient
     privileges, you may change the group ID of the shell process by
     assigning to this parameter.  Also (assuming sufficient
     privileges), you may start a single command under a different
     group ID by `(GID=GID; command)'

HOST
     The current hostname.

LINENO <S>
     The line number of the current line within the current script,
     sourced file, or shell function being executed, whichever was
     started most recently.  Note that in the case of shell functions
     the line number refers to the function as it appeared in the
     original definition, not necessarily as displayed by the functions
     builtin.

LOGNAME
     If the corresponding variable is not set in the environment of the
     shell, it is initialized to the login name corresponding to the
     current login session. This parameter is exported by default but
     this can be disabled using the typeset builtin.

MACHTYPE
     The machine type (microprocessor class or machine model), as
     determined at compile time.

OLDPWD
     The previous working directory.  This is set when the shell
     initializes and whenever the directory changes.

OPTARG <S>
     The value of the last option argument processed by the getopts
     command.

OPTIND <S>
     The index of the last option argument processed by the getopts
     command.

OSTYPE
     The operating system, as determined at compile time.

PPID <S>
     The process ID of the parent of the shell.

PWD
     The present working directory.  This is set when the shell
     initializes and whenever the directory changes.

RANDOM <S>
     A random integer from 0 to 32767, newly generated each time this
     parameter is referenced.  The random number generator can be
     seeded by assigning a numeric value to RANDOM.

SECONDS <S>
     The number of seconds since shell invocation.  If this parameter
     is assigned a value, then the value returned upon reference will
     be the value that was assigned plus the number of seconds since
     the assignment.

SHLVL <S>
     Incremented by one each time a new shell is started.

signals
     An array containing the names of the signals.

TTY
     The name of the tty associated with the shell, if any.

TTYIDLE <S>
     The idle time of the tty associated with the shell in seconds or
     -1 if there is no such tty.

UID <S>
     The real user ID of the shell process.  If you have sufficient
     privileges, you may change the user ID of the shell by assigning
     to this parameter.  Also (assuming sufficient privileges), you may
     start a single command under a different user ID by `(UID=UID;
     command)'

USERNAME <S>
     The username corresponding to the real user ID of the shell
     process.  If you have sufficient privileges, you may change the
     username (and also the user ID and group ID) of the shell by
     assigning to this parameter.  Also (assuming sufficient
     privileges), you may start a single command under a different
     username (and user ID and group ID) by `(USERNAME=USERNAME;
     command)'

VENDOR
     The vendor, as determined at compile time.

ZSH_NAME
     Expands to the basename of the command used to invoke this instance
     of zsh.

ZSH_VERSION
     The version number of this zsh.

Parameters Used By The Shell
============================

The following parameters are used by the shell.

In cases where there are two parameters with an upper- and lowercase
form of the same name, such as path and PATH, the lowercase form is an
array and the uppercase form is a scalar with the elements of the array
joined together by colons.  These are similar to tied parameters
created via `typeset -T'.  The normal use for the colon-separated form
is for exporting to the environment, while the array form is easier to
manipulate within the shell.  Note that unsetting either of the pair
will unset the other; they retain their special properties when
recreated, and recreating one of the pair will recreate the other.

ARGV0
     If exported, its value is used as the argv[0] of external commands.
     Usually used in constructs like `ARGV0=emacs nethack'.

BAUD
     The baud rate of the current connection.  Used by the line editor
     update mechanism to compensate for a slow terminal by delaying
     updates until necessary.  This may be profitably set to a lower
     value in some circumstances, e.g.  for slow modems dialing into a
     communications server which is connected to a host via a fast
     link; in this case, this variable would be set by default to the
     speed of the fast link, and not the modem.  This parameter should
     be set to the baud rate of the slowest part of the link for best
     performance. The compensation mechanism can be turned off by
     setting the variable to zero.

cdpath <S> <Z> (CDPATH <S>)
     An array (colon-separated list) of directories specifying the
     search path for the cd command.

COLUMNS <S>
     The number of columns for this terminal session.  Used for
     printing select lists and for the line editor.

DIRSTACKSIZE
     The maximum size of the directory stack.  If the stack gets larger
     than this, it will be truncated automatically.  This is useful
     with the AUTO_PUSHD option.

FCEDIT
     The default editor for the fc builtin.

fignore <S> <Z> (FIGNORE <S>)
     An array (colon separated list) containing the suffixes of files
     to be ignored during filename completion.  However, if the
     completion generates only files which would match if this variable
     would be ignored, than these files are completed anyway.

fpath <S> <Z> (FPATH <S>)
     An array (colon separated list) of directories specifying the
     search path for function definitions.  This path is searched when
     a function with the -u attribute is referenced.  If an executable
     file is found, then it is read and executed in the current
     environment.

histchars <S>
     Three characters used by the shell's history and lexical analysis
     mechanism.  The first character signals the start of a history
     expansion (default `!').  The second character signals the start
     of a quick history substitution (default `^').  The third
     character is the comment character (default `#').

HISTCHARS <S> <Z>
     Same as histchars.  (Deprecated.)

HISTFILE
     The file to save the history in when an interactive shell exits.
     If unset, the history is not saved.

HISTSIZE <S>
     The maximum number of events stored in the internal history list.
     If you use the HIST_EXPIRE_DUPS_FIRST option, setting this value
     larger than the SAVEHIST size will give you the difference as a
     cushion for saving duplicated history events.

HOME <S>
     The default argument for the cd command.

IFS <S>
     Internal field separators (by default space, tab, newline and
     NUL), that are used to separate words which result from command or
     parameter expansion and words read by the read builtin.  Any
     characters from the set space, tab and newline that appear in the
     IFS are called _IFS white space_.  One or more IFS white space
     characters or one non-IFS white space character together with any
     adjacent IFS white space character delimit a field.  If an IFS
     white space character appears twice consecutively in the IFS, this
     character is treated as if it were not an IFS white space
     character.

KEYTIMEOUT
     The time the shell waits, in hundredths of seconds, for another
     key to be pressed when reading bound multi-character sequences.

LANG <S>
     This variable determines the locale category for any category not
     specifically selected via a variable starting with `LC_'.

LC_ALL <S>
     This variable overrides the value of the `LANG' variable and the
     value of any of the other variables starting with `LC_'.

LC_COLLATE <S>
     This variable determines the locale category for character
     collation information within ranges in glob brackets and for
     sorting.

LC_CTYPE <S>
     This variable determines the locale category for character handling
     functions.

LC_MESSAGES <S>
     This variable determines the language in which messages should be
     written.  Note that zsh does not use message catalogs.

LC_NUMERIC <S>
     This variable affects the decimal point character and thousands
     separator character for the formatted input/output functions and
     string conversion functions.  Note that zsh ignores this setting
     when parsing floating point mathematical expressions.

LC_TIME <S>
     This variable determines the locale category for date and time
     formatting in prompt escape sequences.

LINES <S>
     The number of lines for this terminal session.  Used for printing
     select lists and for the line editor.

LISTMAX
     In the line editor, the number of matches to list without asking
     first. If the value is negative, the list will be shown if it
     spans at most as many lines as given by the absolute value.  If
     set to zero, the shell asks only if the top of the listing would
     scroll off the screen.

LOGCHECK
     The interval in seconds between checks for login/logout activity
     using the watch parameter.

MAIL
     If this parameter is set and mailpath is not set, the shell looks
     for mail in the specified file.

MAILCHECK
     The interval in seconds between checks for new mail.

mailpath <S> <Z> (MAILPATH <S>)
     An array (colon-separated list) of filenames to check for new
     mail.  Each filename can be followed by a `?' and a message that
     will be printed.  The message will undergo parameter expansion,
     command substitution and arithmetic expansion with the variable $_
     defined as the name of the file that has changed.  The default
     message is `You have new mail'.  If an element is a directory
     instead of a file the shell will recursively check every file in
     every subdirectory of the element.

manpath <S> <Z> (MANPATH <S> <Z>)
     An array (colon-separated list) whose value is not used by the
     shell.  The manpath array can be useful, however, since setting it
     also sets MANPATH, and vice versa.

module_path <S> <Z> (MODULE_PATH <S>)
     An array (colon-separated list) of directories that zmodload
     searches for dynamically loadable modules.  This is initialized to
     a standard pathname, usually `/usr/local/lib/zsh/$ZSH_VERSION'.
     (The `/usr/local/lib' part varies from installation to
     installation.)  For security reasons, any value set in the
     environment when the shell is started will be ignored.

     These parameters only exist if the installation supports dynamic
     module loading.

NULLCMD <S>
     The command name to assume if a redirection is specified with no
     command.  Defaults to cat.  For `sh'/`ksh' behavior, change this
     to :.  For `csh'-like behavior, unset this parameter; the shell
     will print an error message if null commands are entered.

path <S> <Z> (PATH <S>)
     An array (colon-separated list) of directories to search for
     commands.  When this parameter is set, each directory is scanned
     and all files found are put in a hash table.

POSTEDIT <S>
     This string is output whenever the line editor exits.  It usually
     contains termcap strings to reset the terminal.

PROMPT <S> <Z>
PROMPT2 <S> <Z>
PROMPT3 <S> <Z>
PROMPT4 <S> <Z>
     Same as PS1, PS2, PS3 and PS4, respectively.

prompt <S> <Z>
     Same as PS1.

PS1 <S>
     The primary prompt string, printed before a command is read.  the
     default is `%m%# '.  It undergoes a special form of expansion
     before being displayed; see Prompt Expansion.

PS2 <S>
     The secondary prompt, printed when the shell needs more information
     to complete a command.  It is expanded in the same way as PS1.
     The default is `%_> ', which displays any shell constructs or
     quotation marks which are currently being processed.

PS3 <S>
     Selection prompt used within a select loop.  It is expanded in the
     same way as PS1.  The default is `?# '.

PS4 <S>
     The execution trace prompt.  Default is `+%N:%i> ', which displays
     the name of the current shell structure and the line number within
     it.  In sh or ksh emulation, the default is `+ '.

psvar <S> <Z> (PSVAR <S>)
     An array (colon-separated list) whose first nine values can be
     used in PROMPT strings.  Setting psvar also sets PSVAR, and vice
     versa.

READNULLCMD <S>
     The command name to assume if a single input redirection is
     specified with no command.  Defaults to more.

REPORTTIME
     If nonnegative, commands whose combined user and system execution
     times (measured in seconds) are greater than this value have timing
     statistics printed for them.

REPLY
     This parameter is reserved by convention to pass string values
     between shell scripts and shell builtins in situations where a
     function call or redirection are impossible or undesirable.  The
     read builtin and the select complex command may set REPLY, and
     filename generation both sets and examines its value when
     evaluating certain expressions.  Some modules also employ REPLY
     for similar purposes.

reply
     As REPLY, but for array values rather than strings.

RPROMPT <S>
RPS1 <S>
     This prompt is displayed on the right-hand side of the screen when
     the primary prompt is being displayed on the left.  This does not
     work if the SINGLELINEZLE option is set.  It is expanded in the
     same way as PS1.

SAVEHIST
     The maximum number of history events to save in the history file.

SPROMPT <S>
     The prompt used for spelling correction.  The sequence `%R'
     expands to the string which presumably needs spelling correction,
     and `%r' expands to the proposed correction.  All other prompt
     escapes are also allowed.

STTY
     If this parameter is set in a command's environment, the shell
     runs the stty command with the value of this parameter as
     arguments in order to set up the terminal before executing the
     command. The modes apply only to the command, and are reset when
     it finishes or is suspended. If the command is suspended and
     continued later with the fg or wait builtins it will see the modes
     specified by STTY, as if it were not suspended.  This
     (intentionally) does not apply if the command is continued via
     `kill -CONT'.  STTY is ignored if the command is run in the
     background, or if it is in the environment of the shell but not
     explicitly assigned to in the input line. This avoids running stty
     at every external command by accidentally exporting it. Also note
     that STTY should not be used for window size specifications; these
     will not be local to the command.

TERM <S>
     The type of terminal in use.  This is used when looking up termcap
     sequences.  An assignment to TERM causes zsh to re-initialize the
     terminal, even if the value does not change (e.g., `TERM=$TERM').
     It is necessary to make such an assignment upon any change to the
     terminal definition database or terminal type in order for the new
     settings to take effect.

TIMEFMT
     The format of process time reports with the time keyword.  The
     default is `%E real  %U user  %S system  %P %J'.  Recognizes the
     following escape sequences:

    %%
          A `%'.

    %U
          CPU seconds spent in user mode.

    %S
          CPU seconds spent in kernel mode.

    %E
          Elapsed time in seconds.

    %P
          The CPU percentage, computed as (%U+%S)/%E.

    %J
          The name of this job.

     A star may be inserted between the percent sign and flags printing
     time.  This cause the time to be printed in `HH:MM:SS.TTT' format
     (hours and minutes are only printed if they are not zero).

TMOUT
     If this parameter is nonzero, the shell will receive an ALRM
     signal if a command is not entered within the specified number of
     seconds after issuing a prompt. If there is a trap on SIGALRM, it
     will be executed and a new alarm is scheduled using the value of
     the TMOUT parameter after executing the trap.  If no trap is set,
     and the idle time of the terminal is not less than the value of the
     TMOUT parameter, zsh terminates.  Otherwise a new alarm is
     scheduled to TMOUT seconds after the last keypress.

TMPPREFIX
     A pathname prefix which the shell will use for all temporary files.
     Note that this should include an initial part for the file name as
     well as any directory names.  The default is `/tmp/zsh'.

watch <S> <Z> (WATCH <S>)
     An array (colon-separated list) of login/logout events to report.
     If it contains the single word `all', then all login/logout events
     are reported.  If it contains the single word `notme', then all
     events are reported as with `all' except $USERNAME.  An entry in
     this list may consist of a username, an `@' followed by a remote
     hostname, and a `%' followed by a line (tty).  Any or all of these
     components may be present in an entry; if a login/logout event
     matches all of them, it is reported.

WATCHFMT
     The format of login/logout reports if the watch parameter is set.
     Default is `%n has %a %l from %m'.  Recognizes the following
     escape sequences:

    %n
          The name of the user that logged in/out.

    %a
          The observed action, i.e. "logged on" or "logged off".

    %l
          The line (tty) the user is logged in on.

    %M
          The full hostname of the remote host.

    %m
          The hostname up to the first `.'.  If only the IP address is
          available or the utmp field contains the name of an X-windows
          display, the whole name is printed.

          _NOTE:_ The `%m' and `%M' escapes will work only if there is
          a host name field in the utmp on your machine.  Otherwise
          they are treated as ordinary strings.

    %S (%s)
          Start (stop) standout mode.

    %U (%u)
          Start (stop) underline mode.

    %B (%b)
          Start (stop) boldface mode.

    %t
    %@
          The time, in 12-hour, am/pm format.

    %T
          The time, in 24-hour format.

    %w
          The date in `DAY-DD' format.

    %W
          The date in `MM/DD/YY' format.

    %D
          The date in `YY-MM-DD' format.

    %(X:TRUE-TEXT:FALSE-TEXT)
          Specifies a ternary expression.  The character following the
          X is arbitrary; the same character is used to separate the
          text for the "true" result from that for the "false" result.
          Both the separator and the right parenthesis may be escaped
          with a backslash.  Ternary expressions may be nested.

          The test character X may be any one of `l', `n', `m' or `M',
          which indicate a `true' result if the corresponding escape
          sequence would return a non-empty value; or it may be `a',
          which indicates a `true' result if the watched user has
          logged in, or `false' if he has logged out.  Other characters
          evaluate to neither true nor false; the entire expression is
          omitted in this case.

          If the result is `true', then the TRUE-TEXT is formatted
          according to the rules above and printed, and the FALSE-TEXT
          is skipped.  If `false', the TRUE-TEXT is skipped and the
          FALSE-TEXT is formatted and printed.  Either or both of the
          branches may be empty, but both separators must be present in
          any case.

WORDCHARS <S>
     A list of non-alphanumeric characters considered part of a word by
     the line editor.

ZBEEP
     If set, this gives a string of characters, which can use all the
     same codes as the bindkey command as described in The zsh/zle Module,
     that will be output to the terminal instead of
     beeping.  This may have a visible instead of an audible effect;
     for example, the string `\e[?5h\e[?5l' on a vt100 or xterm will
     have the effect of flashing reverse video on and off (if you
     usually use reverse video, you should use the string
     `\e[?5l\e[?5h' instead).  This takes precedence over the NOBEEP
     option.

ZDOTDIR
     The directory to search for shell startup files (.zshrc, etc), if
     not $HOME.

Options
*******

Specifying Options
==================

Options are primarily referred to by name.  These names are case
insensitive and underscores are ignored.  For example, `allexport' is
equivalent to `A__lleXP_ort'.

The sense of an option name may be inverted by preceding it with `no',
so `setopt No_Beep' is equivalent to `unsetopt beep'.  This inversion
can only be done once, so `nonobeep' is _not_ a synonym for `beep'.
Similarly, `tify' is not a synonym for `nonotify' (the inversion of
`notify').

Some options also have one or more single letter names.  There are two
sets of single letter options: one used by default, and another used to
emulate `sh'/`ksh' (used when the SH_OPTION_LETTERS option is set).
The single letter options can be used on the shell command line, or
with the set, setopt and unsetopt builtins, as normal Unix options
preceded by `-'.

The sense of the single letter options may be inverted by using `+'
instead of `-'.  Some of the single letter option names refer to an
option being off, in which case the inversion of that name refers to
the option being on.  For example, `+n' is the short name of `exec', and
`-n' is the short name of its inversion, `noexec'.

In strings of single letter options supplied to the shell at startup,
trailing whitespace will be ignored; for example the string `-f    '
will be treated just as `-f', but the string `-f i' is an error.  This
is because many systems which implement the `#!' mechanism for calling
scripts do not strip trailing whitespace.