zshparam
Hurricane Electric Internet Services
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. A subscript of the form [*] or [@]
evaluates to all elements of an array; there is no differ-
ence between the two except when they appear within double
quotes. "$foo[*]" evaluates to "$foo[1] $foo[2] ...",
while "$foo[@]" evaluates 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.
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 the argument is expanded using full shell
expansion first
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)
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 #.
$ 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 *.
@ Same as argv[@].
? The exit value returned by the last command.
status Same as ?.
_ 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 debug-
ging 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.
HOSTTYPE
A string corresponding to the type of the
host the shell is running on. This variable
is obselete and may be removed in a future
version.
LINENO The line number of the current line within
the current script being executed.
LOGNAME
The username corresponding to the user id of
the shell process at the time of login.
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.
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.
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. But if the completion
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
`#').
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.
KEYTIMEOUT
The time the shell waits, in hundredths of
seconds, for another key to be pressed when
reading bound multi-character 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.
LITHISTSIZE
The maximum size of the literal history list
(before history expansion).
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. By default it is set to the
user's system mailbox.
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 sequence $_ in the message
will be replaced by the name of the mail
file. 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 ele-
ment.
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.
PROMPT 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:
%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.
%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. Both the separator and the
right parenthesis may be escaped
with a backslash. True-text and
false-text may both contain arbi-
trarily-nested escape sequences,
including further ternary expres-
sions. 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.
PROMPT2
The secondary prompt, printed when the shell
needs more information to complete a com-
mand. Recognizes the same escape sequences
as $PROMPT. The default is "> ".
PROMPT3
Selection prompt used within a select loop.
Recognizes the same escape sequences as
$PROMPT. The default is "?# ".
PROMPT4
The execution trace prompt. Default is "+
".
PS1
PS2
PS3
PS4 Same as PROMPT, PROMPT2, PROMPT3, and
PROMPT4, respectively.
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 PROMPT.
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 sec-
onds) are greater than this value have tim-
ing 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:
%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
terminate if a command is not entered within
the specified number of seconds after issu-
ing a prompt.
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.
Hurricane Electric Internet Services
Copyright (C) 1998
Hurricane Electric.
All Rights Reserved.