ZSHPARAM(1)
NAME
zshparam - zsh parameters
DESCRIPTIONS
A parameter has a name, a value, and a number of
attributes. A name may be any sequence of alphanumeric
characters and _'s, or the single characters *, @, #, ?,
-, $, or !. The value may be either a scalar (a string),
an integer, or an array. To assign a scalar or integer
value to a parameter, use the typeset builtin. To assign
an array value, use set -A name value .... The value of a
parameter may also be assigned by writing:
name=value ...
If the integer attribute, -i, is set for name, the value
is subject to arithmetic evaluation.
The value of an array parameter may be assigned by writ-
ing:
name=(value ...) ...
Individual elements of an array may be selected using a
subscript. A subscript of the form [exp] selects the sin-
gle element exp, where exp is an arithmetic expression
which will be subject to arithmetic expansion as if it
were surrounded by "$((...))". The elements are numbered
beginning with 1 unless the KSH_ARRAYS option is set when
they are numbered from zero.
A subscript of the form [*] or [@] evaluates to all ele-
ments of an array; there is no difference between the two
except when they appear within double quotes. "$foo[*]"
evaluates to "$foo[1] $foo[2] ...", while "$foo[@]" evalu-
ates to "$foo[1]" "$foo[2]", etc.
A subscript of the form [exp1,exp2] selects all elements
in the range exp1 to exp2, inclusive. If one of the sub-
scripts evaluates to a negative number, say -n, then the
nth element from the end of the array is used. Thus
"$foo[-3]" is the third element from the end of the array
foo, and "$foo[1,-1]" is the same as "$foo[*]".
Subscripting may also be performed on non-array values, in
which case the subscripts specify a substring to be
extracted. For example, if FOO is set to foobar, then
echo $FOO[2,5] prints ooba.
Subscripts may be used inside braces used to delimit a
parameter name, thus ${foo[2]} is equivalent to $foo[2].
If the KSH_ARRAYS option is set, the braced form is the
only one that will work, the subscript otherwise not being
treated specially.
If a subscript is used on the left side of an assignment
the selected range is replaced by the expression on the
right side.
If the opening bracket or the comma is directly followed
by an opening parentheses the string up to the matching
closing one is considered to be a list of flags. The flags
currently understood are:
e this option has no effect and retained for
backward compatibility only
w if the parameter subscripted is a scalar
than this flag makes subscription work on a
per-word basis instead of characters
s:string:
this gives the string that separates words
(for use with the w flag)
p Recognize the same escape sequences as the
print builtin in the string argument of a
subsequent s flag.
f if the parameter subscripted is a scalar
than this flag makes subscription work on a
per-line basis instead of characters. This
is a shorthand for pws:\n:.
r if this flag is given the exp is taken as a
pattern and the result is the first matching
array element, substring or word (if the
parameter is an array, if it is a scalar, or
if it is a scalar and the w flag is given,
respectively); note that this is like giving
a number: $foo[(r)??,3] and
$foo[(r)??,(r)f*] work
R like r, but gives the last match
i like r, but gives the index of the match
instead; this may not be combined with a
second argument
I like i, but gives the index of the last
match
n:expr:
if combined with r, R, , or I, makes them
give the n'th or n'th last match (if expr
evaluates to n)
Positional Parameters
Positional parameters are set by the shell on invocation,
by the set builtin, or by direct assignment. The parame-
ter n, where n is a number, is the nth positional parame-
ter. The parameters *, @, and argv are arrays containing
all the positional parameters; thus argv[n], etc. is
equivalent to simply n.
Special Parameters
The following parameters are automatically set by the
shell:
! The process id of the last background com-
mand invoked.
# The number of positional parameters in deci-
mal.
ARGC Same as #. It has no special meaning in
sh/ksh compatibility mode.
$ The process id of this shell.
- Flags supplied to the shell on invocation or
by the set or setopt commands.
* An array containing the positional parame-
ters.
argv Same as *. It has no special meaning in
sh/ksh compatibility mode.
@ Same as argv[@] but it can be used in sh/ksh
compatibility mode.
? The exit value returned by the last command.
status Same as ?. It has no special meaning in
sh/ksh compatibility mode.
_ The last argument of the previous command.
Also, this parameter is set in the environ-
ment of every command executed to the full
pathname of the command.
EGID 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=egid ; command)
EUID 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=euid ; command)
ERRNO The value of errno as set by the most
recently failed system call. This value is
system dependent and is intended for
debugging purposes.
GID The group id of the shell process. If you
have sufficient privileges, you may change
the group id of the shell process by assign-
ing to this parameter. Also (assuming suf-
ficient privileges), you may start a single
command under a different group id by:
(GID=gid ; command)
HOST The current hostname.
LINENO The line number of the current line within
the current script being executed.
LOGNAME
If the corresponding variable is not set in
the environment of the shell, it is initial-
ized 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.
OPTARG The value of the last option argument pro-
cessed by the getopts command.
OPTIND The index of the last option argument pro-
cessed by the getopts command.
OSTYPE The operating system, as determined at com-
pile time.
PPID The process id of the parent of the shell.
PWD The present working directory.
RANDOM A random integer from 0 to 32767, newly gen-
erated each time this parameter is refer-
enced. The random number generator can be
seeded by assigning a numeric value to RAN-
DOM.
SECONDS
The number of seconds since shell invoca-
tion. If this parameter is assigned a
value, then the value returned upon refer-
ence will be the value that was assigned
plus the number of seconds since the assign-
ment.
SHLVL Incremented by one each time a new shell is
started.
signals
An array containing the names of the sig-
nals.
TTY The name of the tty associated with the
shell, if any.
TTYIDLE
The idle time of the tty associated with the
shell in seconds or -1 if there is no such
tty.
UID The 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
The username corresponding to the 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.
ZSHNAME
Expands to the basename of the command used
to invoke this instance of zsh.
ZSH_NAME
Expands to the basename of the command used
to invoke this instance of zsh.
ZSH_VERSION
The version number of this zsh.
The following parameters are used by the shell:
ARGV0 If exported, it's value is used as argv[0]
of external commands. Usually used in con-
structs 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 prof-
itably set to a lower value in some circum-
stances, 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 (CDPATH)
An array (colon-separated list) of directo-
ries specifying the search path for the cd
command.
COLUMNS
The number of columns for this terminal ses-
sion. 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 (FIGNORE)
An array (colon separated list) containing
the suffixes of files to be ignored during
filename completion. However, if the com-
pletion generates only files which would
match if this variable would be ignored,
than these files are completed anyway.
fpath (FPATH)
An array (colon separated list) of directo-
ries specifying the search path for function
definitions. This path is searched when a
function with the -u attribute is refer-
enced. If an executable file is found, then
it is read and executed in the current envi-
ronment.
histchars
Three characters used by the shell's history
and lexical analysis mechanism. The first
character signals the start of a history
substitution (default `!'). The second
character signals the start of a quick his-
tory substitution (default `^'). The third
character is the comment character (default
`#').
HISTCHARS
Same as histchars.
HISTFILE
The file to save the history in when an
interactive shell exits. If unset, the his-
tory is not saved.
HISTSIZE
The maximum size of the history list.
HOME The default argument for the cd command.
IFS Internal field separators, normally space,
tab, and newline, that are used to separate
words which result from command or parameter
substitution 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 charac-
ter 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 This variable determines the locale category
for any category not specifically selected
via a variable starting with LC_.
LC_ALL This variable overrides the value of the
LANG variable and the value of any of the
other variables starting with LC_.
LC_COLLATE
This variable determines the locale category
for character collation information within
ranges in glob brackets and for sorting.
LC_CTYPE
This variable determines the locale category
for character handling functions.
LC_MESSAGES
This variable determines the language in
which messages should be written. Note that
zsh does not use message catalogs.
LC_TIME
This variable determines the locale category
for date and time formatting in promt escape
sequences.
LINES The number of lines for this terminal ses-
sion. Used for printing select lists and
for the line editor.
LISTMAX
In the line editor, the number of filenames
to list without asking first. 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 param-
eter.
MAIL If this parameter is set and mailpath is not
set, the shell looks for mail in the speci-
fied file.
MAILCHECK
The interval in seconds between checks for
new mail.
mailpath (MAILPATH)
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 arith-
metic substitution 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 (MANPATH)
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.
NULLCMD
The command name to assume if a redirection
is specified with no command. Defaults to
cat. For sh/ksh-like behavior, change this
to :. For csh-like behavior, unset this
parameter; the shell will print an error
message if null commands are entered.
path (PATH)
An array (colon-separated list) of directo-
ries to search for commands. When this
parameter is set, each directory is scanned
and all files found are put in a hash table.
POSTEDIT
This string is output whenever the line edi-
tor exits. It usually contains termcap
strings to reset the terminal.
PS1 The primary prompt string, printed before a
command is read; the default is "%m%# ". If
the escape sequence takes an optional inte-
ger, it should appear between the '%' and
the next character of the sequence. The
following escape sequences are recognized:
%% A `%'.
%) A `)'.
%d
%/ Present working directory ($PWD).
%~ $PWD. If it has a named directory
as its prefix, that part is replaced
by a ~ followed by the name of the
directory. If it starts with $HOME,
that part is replaced by a ~.
%c
%.
%C Trailing component of $PWD. An
integer may follow the '%' to get
more than one component. Unless %C
is used, tilde expansion is per-
formed first.
%h
%! Current history event number
%M The full machine hostname.
%m The hostname up to the first '.'.
An integer may follow the '%' to
specify how many components of the
hostname are desired.
%S (%s)
Start (stop) standout mode.
%U (%u)
Start (stop) underline mode.
%B (%b)
Start (stop) boldface mode.
%t
%@ Current time of day, in 12-hour,
am/pm format.
%T Current time of day, in 24-hour for-
mat.
%* Current time of day in 24-hour for-
mat, with seconds.
%n $USERNAME.
%w The date in day-dd format.
%W The date in mm/dd/yy format.
%D The date in yy-mm-dd format.
%D{string}
string is formatted using the strf-
time function. See strftime(3) for
more details, if your system has it.
%l The line (tty) the user is logged in
on.
%? The return code of the last command
executed just before the prompt.
%_ The status of the parser, i.e. the
shell constructs (like `if' and
`for') that have been started on the
command line. If given an integer
number that many strings will be
printed; zero or no integer means
print as many as there are.
%E Clears to end of line.
%# A '#' if the shell is running as
root, a '%' if not. Equivalent to
%(#.#.%%).
%v The value of the first element of
the $psvar array parameter. Follow-
ing the '%' with an integer gives
that element of the array.
%{...%}
Include a string as a literal escape
sequence. The string within the
braces should not change the cursor
position.
%(x.true-text.false-text)
Specifies a ternary expression. The
character following the x is arbi-
trary; the same character is used to
separate the text for the "true"
result from that for the "false"
result. This separator may not
appear in the true-text, except as
part of a % sequence. A `)' may
appear in the false-text as `%)'.
True-text and false-text may both
contain arbitrarily-nested escape
sequences, including further ternary
expressions. The left parenthesis
may be preceded or followed by a
positive integer n, which defaults
to zero. The test character x may
be any of the following:
c
.
~ True if the current path,
with prefix replacement, has
at least n elements.
/
C True if the current absolute
path has at least n elements.
t True if the time in minutes
is equal to n.
T True if the time in hours is
equal to n.
d True if the day of the month
is equal to n.
D True if the month is equal to
n (January = 0).
w True if the day of the week
is equal to n (Sunday = 0).
? True if the exit status of
the last command was n.
# True if the effective uid of
the current process is n.
g True if the effective gid of
the current process is n.
L True if the SHLVL parameter
is at least n.
S True if the SECONDS parameter
is at least n.
v True if the array psvar has
at least n elements.
_ True if at least n shell con-
structs were started.
%<<string<<
%>>string>>
%[xstring]
Specifies truncation behaviour. The
third form is equivalent to
`%xstringx', i.e. x may be `<' or
`>'. The numeric argument, which in
the third form may appear immedi-
ately after the `[', specifies the
maximum permitted length of the var-
ious strings that can be displayed
in the prompt. If this integer is
zero, or missing, truncation is dis-
abled. Truncation is initially dis-
abled. The forms with `<' truncate
at the left of the string, and the
forms with `>' truncate at the right
of the string. For example, if the
current directory is `/home/pike',
the prompt `%8<..<%/' will expand to
`..e/pike'. The string will be dis-
played in place of the truncated
portion of any string. In this
string, the terminating character
(`<', `>' or `]'), or in fact any
character, may be quoted by a pre-
ceding `\'. % sequences are not
treated specially. If the string is
longer than the specified truncation
length, it will appear in full, com-
pletely replacing the truncated
string.
PS2 The secondary prompt, printed when the shell
needs more information to complete a com-
mand. Recognizes the same escape sequences
as $PS1. The default is "%_> ", which dis-
plays any shell constructs or quotation
marks which are currently being processed.
PS3 Selection prompt used within a select loop.
Recognizes the same escape sequences as
$PS1. The default is "?# ".
PS4 The execution trace prompt. Default is "+
".
PROMPT
PROMPT2
PROMPT3
PROMPT4
Same as PS1, PS2, PS3, and PS4, respec-
tively. These parameters do not have any
special meaning in sh/ksh compatibility
mode.
psvar (PSVAR)
An array (colon-separated list) whose first
nine values can be used in PROMPT strings.
Setting psvar also sets PSVAR, and vice
versa.
prompt Same as PS1. It has no special meaning in
sh/ksh compatibility mode.
READNULLCMD
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.
RPROMPT
RPS1 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.
Recognizes the same escape sequences as
PROMPT.
SAVEHIST
The maximum number of history events to save
in the history file.
SPROMPT
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 argu-
ments in order to set up the terminal before
executing the command. The modes apply only
to the command, and are reset when it fin-
ishes or is suspended. If the command is
suspended and continued later with the fg or
wait builtins it will see the modes speci-
fied 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.
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 sec-
onds 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 parametr after exececuting 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. Oth-
erwise 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 (WATCH)
An array (colon-separated list) of
login/logout events to report. If it con-
tains 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 con-
sist 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 arbi-
trary; 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 expres-
sions 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 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
A list of nonalphanumeric characters consid-
ered part of a word by the line editor.
ZDOTDIR
The directory to search for shell startup
files (.zshrc, etc), if not $HOME.