ZSH(1) ZSH(1)
NAME
zsh - the Z shell
SYNOPSIS
zsh [ +-options ] [ +-o option ] ... [ -c string ] [ arg
... ]
SHELL GRAMMAR
A simple command is a sequence of optional parameter
assignments followed by blank-separated words, with
optional redirections interspersed. The first word is the
command to be executed, and the remaining words, if any,
are arguments to the command. If a command name is given,
the parameter assignments modify the environment of the
command when it is executed. The value of a simple com-
mand is its exit status, or 128 plus the signal number if
terminated by a signal.
If a simple command is preceded by the word exec, it is
executed in the parent shell without forking. If preceded
by command, the command word is taken to be the name of an
external command, rather than a shell function or builtin.
If preceded by noglob, filename generation is not per-
formed on any of the words. If preceded by a -, the com-
mand is executed with a - prepended to its argv[0] string.
If preceded by nocorrect, spelling correction is not done
on any of the words.
A pipeline is a sequence of one or more commands separated
by | or |&. |& is shorthand for 2>&1 |. The standard
output of each command is connected to the standard input
of the next command in the pipeline.
The value of a pipeline is the value of the last command.
If a pipeline is preceded by a !, the value of that
pipeline is the logical NOT of the value of the last com-
mand.
If a pipeline is preceded by coproc, it is executed as a
coprocess; a two-way pipe is established between it and
the parent shell. The shell can read from or write to the
coprocess by means of the >&p and <&p redirection opera-
tors.
A sublist is a sequence of one or more pipelines separated
by && or ||. If two pipelines are separated by &&, the
second pipeline is executed only if the first is success-
ful (returns a zero value). If two pipelines are sepa-
rated by ||, the second is executed only if the first is
unsuccessful (returns a nonzero value).
A list is a sequence of one or more sublists separated by,
and optionally terminated by, ;, &, or a newline. Nor-
mally the shell waits for each list to finish before
1992 May 2 1
ZSH(1) ZSH(1)
executing the next one. If a list is terminated by a &,
the shell executes it in the background, and does not wait
for it to finish.
A complex command is one of the following:
for name [ in word ... ]
do list
done Expand the list of words, and set the param-
eter name to each of them in turn, executing
list each time. If the in word is omitted,
use the positional parameters instead of the
words.
for name [ in word ... ] ; sublist
This is a shorthand for for. Though it may
cause confusion, it is included for conve-
nience; its use in scripts is discouraged,
unless sublist is a command of the form {
list }.
foreach name ( word ... )
list
end Another form of for.
for name in word ...
{
list
} Another form of for.
for name ( word ... ) {
list
} Another form of for.
for name ( word ... ) sublist
Another form of for.
select name [ in word ... ]
do list
done Print the set of words, each preceded by a
number. If the in word is omitted, use the
positional parameters. The PROMPT3 prompt
is printed and a line is read from standard
input. If this line consists of the number
of one of the listed words, then the parame-
ter name is set to the word corresponding to
this number. If this line is empty, the
selection list is printed again. Otherwise,
the value of the parameter name is set to
null. The contents of the line read from
standard input is saved in the parameter
REPLY. list is executed for each selection
until a break or end-of-file is encountered.
1992 May 2 2
ZSH(1) ZSH(1)
select name [ in word ] ; sublist
A short form of select.
case word in [ pattern ) list ;; ] ... esac
Execute the list associated with the first
pattern that matches word, if any. The form
of the patterns is the same as that used for
filename generation. See Filename Genera-
tion below.
case word { [ pattern ) list ;; ] ... }
Another form of case.
if list
then list
[ elif list ; then list ] ...
[ else list ]
fi The if list is executed, and, if it returns
a zero exit status, the then list is exe-
cuted. Otherwise, the elif list is executed
and, if its value is zero, the then list is
executed. If each elif list returns
nonzero, the else list is executed.
if ( list ) sublist
A short form of if.
if ( list ) {
list
} elif ( list ) {
list
} ... else {
list
} An alternate form of if.
while list
do list
done Execute the do list as long as the while
list returns a zero exit status.
while ( list ) {
list
} An alternate form of while.
until list
do list
done Execute the do list as long as until list
returns a nonzero exit status.
repeat word
do list
done word is expanded and treated as an arith-
metic expression, which must evaluate to a
number n. list is then executed n times.
1992 May 2 3
ZSH(1) ZSH(1)
repeat word sublist
This is a short form of repeat.
( list )
Execute list in a subshell.
{ list }
Execute list.
function word [ () ] ... { list }
word ... () { list }
word ... () sublist
Define a function which is referenced by any
one of word. Normally, only one word is
provided; multiple words are usually only
useful for setting traps. The body of the
function is the list between the { and }.
See FUNCTIONS below.
time [ pipeline ]
The pipeline is executed, and timing statis-
tics are reported on the standard error in
the form specified by the TIMEFMT parameter.
If pipeline is omitted, print statistics
about the shell process and its children.
[[ exp ]]
Evaluates the conditional expression exp and
return a zero exit status if it is true.
See Conditional Expressions below for a
description of exp.
RESERVED WORDS
The following words are recognized as reserved words when
used as the first word of a command unless quoted or
removed using the unalias builtin:
do done esac then elif else fi for case if while
function repeat time until exec command select
coproc noglob - nocorrect foreach end
COMMENTS
In noninteractive shells, or in interactive shells with
the INTERACTIVECOMMENTS option set, a word beginning with
the third character of the HISTCHARS parameter (`#' by
default) causes that word and all the following characters
up to a newline to be ignored.
ALIASING
Every token in the shell input is checked to see if there
is an alias defined for it. If so, it is replaced by the
text of the alias if it is in command position (if it
could be the first word of a simple command), or if the
alias is global. If the text ends with a space, the next
1992 May 2 4
ZSH(1) ZSH(1)
word in the shell input is treated as though it were in
command position for purposes of alias expansion. An
alias is defined using the alias builtin; global aliases
may be defined using the -g option to that bulitin.
Alias substitution is done on the shell input before any
other substitution except history substitution. There-
fore, if an alias is defined for the word foo, alias sub-
stitution may be avoided by quoting part of the word, e.g.
\foo. But there is nothing to prevent an alias being
defined for \foo as well.
QUOTING
A character may be quoted (that is, made to stand for
itself) by preceding it with a \. \ followed by a newline
is ignored. All characters enclosed between a pair of
single quotes ('') are quoted. A single quote cannot
appear within single quotes. Inside double quotes (""),
parameter and command substitution occurs, and \ quotes
the characters \, `, ", and $.
EXPANSION
Expansion is performed on the command line after it has
been parsed. The types of expansions performed are file-
name expansion, process substitution, parameter expansion,
command substitution, arithmetic expansion, brace expan-
sion, and filename generation.
Filename Expansion
Each word is checked to see if it begins with an unquoted
~. If it does, then the word up to a / is checked to see
if it matches the name of a named directory. If so, then
the ~ and the matched portion are replaced with the value
of the named directory. A ~ by itself or followed by a /
is replaced by the value of the HOME parameter. A ~ fol-
lowed by a + or a - is replaced by the value of PWD or
OLDPWD, respectively.
Named directories are typically login directories for
users on the system. They may also be defined if the text
after the ~ is the name of a shell parameter whose value
begins with a /. In certain circumstances (in prompts,
for instance), when the shell prints a path, the path is
checked to see if it has a named directory as its prefix.
If so, then the prefix portion is replaced with a ~ fol-
lowed by the name of the directory. The longest match is
preferred.
If a word begins with an unquoted = and the NOEQUALS
option is not set, the remainder of the word is taken as
the name of a command or alias. If a command exists by
that name, the word is replaced by the full pathname of
the command. If an alias exists by that name, the word is
replaced with the text of the alias. Otherwise the word
1992 May 2 5
ZSH(1) ZSH(1)
is checked up to a / to see if it is a number or a -. If
so, the matched portion is replaced with the nth directory
in the directory stack, where n is the number matched, or
the last directory in the directory stack if a - is
matched.
Process Substitution
Each command argument of the form <(list) or >(list) or
=(list) is subject to process substitution. In the case
of the < or > forms, the shell will run process list asyn-
chronously connected to a named pipe (FIFO). The name of
this pipe will become the argument to the command. If the
form with > is selected then writing on this file will
provide input for list. If < is used, then the file
passed as an argument will be a named pipe connected to
the output of the list process. For example,
paste <(cut -f1 file1) <(cut -f3 file2) | tee
>(process1) >(process2) >/dev/null
cuts fields 1 and 3 from the files file1 and file2 respec-
tively, pastes the results together, and sends it to the
processes process1 and process2. Note that the file,
which is passed as an argument to the command, is a system
pipe so programs that expect to lseek(2) on the file will
not work. Also note that the previous example can be more
compactly and efficiently written as:
paste <(cut -f1 file1) <(cut -f3 file2) > >(pro-
cess1) > >(process2)
the shell uses pipes instead of a FIFOs to implement the
latter two process substitutions in the above example.
If = is used, then the file passed as an argument will be
the name of a temporary file containing the output of the
list process. This may be used instead of the < form for
a program that expects to lseek(2) on the input file.
Parameter Expansion
The character $ is used to introduce parameter expansions.
See PARAMETERS below for a description of parameters.
${name}
The value, if any, of the parameter name is
substituted. The braces are required with
name is followed by a letter, digit, or
underscore that is not to be interpreted as
part of its name. If name is an array
parameter, then the values of each element
of name is substituted, one element per
word. Otherwise, the expansion results in
one word only; no word splitting is done on
the result.
1992 May 2 6
ZSH(1) ZSH(1)
${name:-word}
If name is set and is non-null then substi-
tute its value; otherwise substitute word.
${name:=word}
If name is unset and is null then set it to
word; the value of the parameter is then
substituted.
${name:?word}
If name is set and is non-null, then substi-
tute its value; otherwise, print word and
exit from the shell. If word is omitted,
then a standard message is printed.
${name:+word}
If name is set and is non-null then substi-
tute word; otherwise substitute nothing.
${name#pattern}
${name##pattern}
If the pattern matches the beginning of the
value of name, then substitute the value of
name with the matched portion deleted; oth-
erwise, just substitute the value of name.
In the first form, the smallest matching
pattern is preferred; in the second form,
the largest matching pattern is preferred.
${name%pattern}
${name%%pattern}
If the pattern matches the end of the value
of name, then substitute the value of name
with the matched portion deleted; otherwise,
just substitute the value of name. In the
first form, the smallest matching pattern is
preferred; in the second form, the largest
matching pattern is preferred.
${#spec}
If spec is one of the above substitutions,
substitute the length in characters of the
result instead of the result itself. If
spec is an array expression, substitute the
number of elements of the result.
${^spec}
Toggle the value of the RCEXPANDPARAM
option for the evaluation of spec. When
this option is set, array expansions of the
form foo${xx}bar, where the parameter xx is
set to (a b c), are substituted with fooabar
foobbar foocbar instead of the default fooa
b cbar.
1992 May 2 7
ZSH(1) ZSH(1)
${=spec}
Toggle the value of the SHWORDSPLIT option
for the evaluation of spec. When this
option is set, parameter values are split
into separate words using IFS as a delimiter
before substitution. This is done by
default in most other shells.
If the colon is omitted from one of the above expressions
containing a colon, then the shell only checks whether
name is set or not, not whether it is null.
Command Substitution
A command enclosed in parentheses preceded by a dollar
sign, like so: $(...) or quoted with grave accents: `...`
is replaced with its standard output. If the substitution
is not enclosed in double quotes, the output is broken
into words using the IFS parameter. The substitution
$(cat foo) may be replaced by the equivalent but faster
$(<foo).
Arithmetic Expansion
A string of the form $[exp] is substituted with the value
of the arithmetic expression exp. exp is treated as if it
were within single quotes. See ARITHMETIC EVALUATION
below.
Brace Expansion
A string of the form foo{xx,yy,zz}bar is expanded to the
individual words fooxxbar, fooyybar, and foozzbar. Left-
to-right order is preserved. This construct may be
nested. Malformed brace expansion expressions, including
expressions without a comma, are left unchanged by the
shell.
An expression of the form {x-y}, where x and y are single
characters, is expanded to every character between x and
y, inclusive.
Filename Generation
If a word contains an unquoted instance of one of the
characters *, |, <, [, or ?, it is regarded as a pattern
for filename generation, unless the NOGLOB option is set.
If the EXTENDEDGLOB option is set, the ^ and # characters
also denote a pattern; otherwise they are not treated spe-
cially by the shell. The word is replaced with a list of
sorted filenames that match the pattern. If no matching
pattern is found, the shell gives an error message, unless
the NULLGLOB option is set, in which case the word is
deleted; or unless the NONOMATCH option is set, in which
case the word is left unchanged. In filename generation,
the character / must be matched explicitly; also, a . must
be matched explicitly at the beginning of a pattern or
after a /, unless the GLOBDOTS option is set. No filename
1992 May 2 8
ZSH(1) ZSH(1)
generation pattern matches the files "." or "..". In
other instances of pattern matching, the / and . are not
treated specially.
* matches any string, including the null
string.
? matches any character.
[ ... ]
matches any of the enclosed characters.
[^ ... ]
matches any character except the enclosed
characters.
<x-y> matches any number in the range x to y,
inclusive. If x is omitted, the number must
be less than or equal to y. If y is omit-
ted, the number must be greater than or
equal to x. A pattern of the form <-> or
simply <> matches any number.
^x matches anything except the pattern x.
x|y matches either x or y.
x# matches zero or more occurrences of the pat-
tern x.
x## matches one or more occurrences of the pat-
tern x.
Parentheses may be used for grouping. Note that the |
character must be within parentheses, so that the lexical
analyzer does not think it is a pipe character. Also note
that "/" has a higher precedence than "^"; that is:
ls ^foo/bar
will search directories in "." except "./foo" for a file
named bar.
A pathname component of the form (foo/)# matches a path
consisting of zero or more directories matching the pat-
tern foo. As a shorthand, **/ is equivalent to (*/)#.
Thus:
ls (*/)#bar
or
ls **/bar
does a recursive directory search for files named bar.
If used for filename generation, a pattern may contain an
exclusion specifier. Such patterns are of the form
pat1~pat2. This pattern will generate all files matching
pat1, but which do not match pat2. For example, *.c~lex.c
will match all files ending in .c, except the file lex.c.
1992 May 2 9
ZSH(1) ZSH(1)
Patterns used for filename generation may also end in a
list of qualifiers enclosed in parentheses. The quali-
fiers specify which filenames that otherwise match the
given pattern will be inserted in the argument list. A
qualifier may be any one of the following:
/ directories
. plain files
@ symbolic links
= sockets
p named pipes (FIFOs)
* executable plain files (0100)
% device files (character or block special)
r readable files (0400)
w writable files (0200)
x executable files (0100)
R world-readable files (0004)
W world-writable files (0002)
X world-executable files (0001)
s setuid files (04000)
S setgid files (02000)
ddev files on the device dev
lct files having a link count of ct
U files owned by the effective user id
G files owned by the effective group id
unum files owned by user id num
gnum files owned by group id num
^ negates all qualifiers following it
M sets the MARKDIRS option for the current
pattern
N sets the NULLGLOB option for the current
pattern
D sets the GLOBDOTS option for the current
pattern
Thus:
ls *(%W)
lists all world-writable device files in the current
directory, and
ls /tmp/foo*(u0^@)
lists all root-owned files beginning with the string "foo"
in /tmp, ignoring symlinks, and
ls *.*~(lex|parse).[ch](^D^l1)
lists all files having a link count of one whose names
contain a dot (but not those starting with a dot, since
GLOBDOTS is explicitly switched off) except for lex.c,
lex.h, parse.c, and parse.h. A "/" at the end of a pat-
tern is equivalent to "(/)".
1992 May 2 10
ZSH(1) ZSH(1)
REDIRECTION
Before a command is executed, its input and output may be
redirected. The following may appear anywhere in a sim-
ple-command or may precede or follow a complex command.
Substitution occurs before word is used except as noted
below. If the result of substitution on word produces
more than one filename, redirection occurs for each sepa-
rate filename in turn.
<word Open file word as standard input.
>word Open file word as standard output. If the file
does not exist then it is created. If the file
exists, and the NOCLOBBER option is set, this
causes an error; otherwise, it is truncated to zero
length.
>! word
Same as >, except that the file is truncated to
zero length if it exists, even if NOCLOBBER is set.
>>word Open file word as standard output. If the file
exists then output is appended to it. If the file
does not exist, and the NOCLOBBER option is set,
this causes an error; otherwise, the file is cre-
ated.
>>! word
Same as >>, except that the file is created if it
does not exist, even if NOCLOBBER is set.
<<[-] word
The shell input is read up to a line that is the
same as word, or to an end-of-file. No parameter
substitution, command substitution or filename gen-
eration is performed on word. The resulting docu-
ment, called a here-document, becomes the standard
input. If any character of word is quoted with
single or double quotes (a \ alone is not suffi-
cient), no interpretation is placed upon the char-
acters of the document. Otherwise, parameter and
command substitution occurs, \ followed by a new-
line is removed, and \ must be used to quote the
characters \, $, `, and the first character of
word. If <<- is used, then all leading tabs are
stripped from word and from the document.
<<<word
Open a file containing word, after expansion, as
standard input.
<&digit
The standard input is duplicated from file descrip-
tor digit (see dup(2)). Similarly for standard
1992 May 2 11
ZSH(1) ZSH(1)
output using >&digit.
>&word Same as >word 2>&1.
>>&word
Same as >>word 2>&1.
<&- Close the standard input.
>&- Close the standard output.
<&p The input from the coprocess is moved to the stan-
dard input.
>&p The output to the coprocess is moved to the stan-
dard output.
If one of the above is preceded by a digit, then the file
descriptor referred to is that specified by the digit
(instead of the default 0 or 1). The order in which redi-
rections are specified is significant. the shell evalu-
ates each redirection in terms of the (file descriptor,
file) association at the time of evaluation. For example:
... 1>fname 2>&1
first associates file descriptor 1 with file fname. It
then associates file descriptor 2 with the file associated
with file descriptor 1 (that is, fname). If the order of
redirections were reversed, file descriptor 2 would be
associated with the terminal (assuming file descriptor 1
had been) and then file descriptor 1 would be associated
with file fname.
If the user tries to open a file descriptor for writing
more than once, the shell opens the file descriptor as a
pipe to a process that copies its input to all the speci-
fied outputs, similar to tee(1). Thus:
date >foo >bar
writes the date to two files, named "foo" and "bar". Note
that a pipe is an implicit indirection; thus
date >foo | cat
writes the date to the file "foo", and also pipes it to
cat.
If the user tries to open a file descriptor for reading
more than once, the shell opens the file descriptor as a
pipe to a process that copies all the specified inputs to
its output in the order specified, similar to cat(1).
Thus
1992 May 2 12
ZSH(1) ZSH(1)
sort <foo <fubar
or even
sort <f{oo,ubar}
is equivalent to "cat foo bar | sort". Note that a pipe
is in implicit indirection; thus
cat bar | sort <foo
is equivalent to "cat bar foo | sort" (note the order of
the inputs).
If a simple command consists of one or more redirection
operators and zero or more parameter assignments, but no
command name, the command cat is assumed. Thus
< file
prints the contents of file.
If a command is followed by & and job control is not
active, then the default standard input for the command is
the empty file /dev/null. Otherwise, the environment for
the execution of a command contains the file descriptors
of the invoking shell as modified by input/output specifi-
cations.
COMMAND EXECUTION
If a command name contains no slashes, the shell attempts
to locate it. If there exists a shell function by that
name, the function is invoked as described below in FUNC-
TIONS. If there exists a shell builtin by that name, the
builtin is invoked.
Otherwise, the shell searches each element of path for a
directory containing an executable file by that name. If
the search is unsuccessful, the shell prints an error mes-
sage and returns a nonzero exit status.
If execution fails because the file is not in executable
format, and the file is not a directory, it is assumed to
be a shell script. /bin/sh is spawned to execute it. If
the program is a file beginning with #!, the remainder of
the first line specifies an interpreter for the program.
The shell will execute the specified interpreter on oper-
ating systems that do not handle this executable format in
the kernel.
FUNCTIONS
The function reserved word is used to define shell func-
tions. Shell functions are read in and stored internally.
Alias names are resolved when the function is read.
1992 May 2 13
ZSH(1) ZSH(1)
Functions are executed like commands with the arguments
passed as positional parameters. (See Execution below).
Functions execute in the same process as the caller and
share all files and present working directory with the
caller. A trap on EXIT set inside a function is executed
after the function completes in the environment of the
caller.
The return builtin is used to return from function calls.
Function identifiers can be listed with the functions
builtin. Functions can be undefined with the unfunction
builtin.
The following functions, if defined, have special meaning
to the shell:
chpwd Executed whenever the current working directory is
changed.
precmd Executed before each prompt.
periodic
If the parameter PERIOD is set, this function is
executed every PERIOD seconds, just before a
prompt.
TRAPxxx
If defined and non-null, this function will be exe-
cuted whenever the shell catches a signal SIGxxx,
where xxx is a signal name as specified for the
kill builtin (see below). In addition, TRAPERR is
executed whenever a command has a non-zero exit
status, TRAPDEBUG is executed after each command,
and TRAPEXIT is executed when the shell exits, or
when the current function exits if defined inside a
function. If a function of this form is defined
and null, the shell and processes spawned by it
will ignore SIGxxx.
JOBS
If the MONITOR option is set, an interactive shell associ-
ates a job with each pipeline. It keeps a table of cur-
rent jobs, printed by the jobs command, and assigns them
small integer numbers. When a job is started asyn-
chronously with &, the shell prints a line which looks
like:
[1] 1234
indicating that the job which was started asynchronously
was job number 1 and had one (top-level) process, whose
process id was 1234.
If you are running a job and wish to do something else you
may hit the key ^Z (control-Z) which sends a STOP signal
1992 May 2 14
ZSH(1) ZSH(1)
to the current job. the shell will then normally indicate
that the job has been `suspended', and print another
prompt. You can then manipulate the state of this job,
putting it in the background with the bg command, or run
some other commands and then eventually bring the job back
into the foreground with the foreground command fg. A ^Z
takes effect immediately and is like an interrupt in that
pending output and unread input are discarded when it is
typed.
A job being run in the background will suspend if it tries
to read from the terminal. Background jobs are normally
allowed to produce output, but this can be disabled by
giving the command ``stty tostop''. If you set this tty
option, then background jobs will suspend when they try to
produce output like they do when they try to read input.
There are several ways to refer to jobs in the shell. A
job can be referred to by the process id of any process of
the job or by one of the following:
%number
The job with the given number.
%string
Any job whose command line begins with string.
%?string
Any job whose command line contains string.
%% Current job.
%+ Equivalent to %%.
%- Previous job.
The shell learns immediately whenever a process changes
state. It normally informs you whenever a job becomes
blocked so that no further progress is possible. If
notify is not set, it waits until just before it prints a
prompt before it informs you.
When the monitor mode is on, each background job that com-
pletes triggers any trap set for CHLD.
When you try to leave the shell while jobs are running or
suspended, you will be warned that `You have suspended
(running) jobs.' You may use the jobs command to see what
they are. If you do this or immediately try to exit
again, the shell will not warn you a second time; the sus-
pended jobs will be terminated, and the running jobs will
be sent a SIGHUP signal. To avoid having the shell termi-
nate the running jobs, either use the nohup(1) command or
the disown builtin (see below).
SIGNALS
The INT and QUIT signals for an invoked command are
ignored if the command is followed by & and job monitor
option is not active. Otherwise, signals have the values
inherited by the shell from its parent (but see the
1992 May 2 15
ZSH(1) ZSH(1)
TRAPxxx special function above).
HISTORY
History substitution allows you to use words from previous
command lines in the command line you are typing. This
simplifies spelling corrections and the repetition of com-
plicated commands or arguments. Command lines are saved
in the history list, the size of which is controlled by
the HISTSIZE variable. The most recent command is
retained in any case. A history substitution begins with
a ! and may occur anywhere on the command line; history
substitutions do not nest. The ! can be escaped with \
to suppress its special meaning. Single or double quotes
will not work for this.
Input lines containing history substitutions are echoed on
the terminal after being expanded, but before any other
substitutions take place or the command gets executed.
Event Designators
An event designator is a reference to a command-line entry
in the history list.
! Start a history substitution, except when
followed by a blank, newline, =, or (.
!! Refer to the previous command. By itself,
this substitution repeats the previous com-
mand.
!n Refer to command-line n.
!-n Refer to the current command-line minus n.
!str Refer to the most recent command starting
with str.
!?str[?]
Refer to the most recent command containing
str.
!# Refer to the current command line typed in
so far.
!{...} Insulate a history reference from adjacent
characters (if necessary).
Word Designators
A `:' separates the event specification from the word des-
ignator. It can be omitted if the word designator begins
with a , $, *, - or %. If the word is to be selected from
the previous command, the second ! character can be omit-
ted from the event specification. For instance, !!:1 and
!:1 both refer to the first word of the previous command,
while !!$ and !$ both refer to the last word in the previ-
ous command. Word designators include:
0 The first input word (command).
n The n'th argument.
^ The first argument, that is, 1.
$ The last argument.
% The word matched by (the most recent) ?s
search.
1992 May 2 16
ZSH(1) ZSH(1)
x-y A range of words; -y abbreviates 0-y.
* All the arguments, or a null value if there
is just one word in the event.
x* Abbreviates x-$.
x- Like x* but omitting word $.
Modifiers
After the optional word designator, you can add a sequence
of one or more of the following modifiers, each preceded
by a :. These modifiers also work on the result of file-
name and parameter expansion.
h Remove a trailing pathname component, leav-
ing the head.
r Remove a trailing suffix of the form `.xxx',
leaving the basename.
e Remove all but the suffix.
t Remove all leading pathname components,
leaving the tail.
& Repeat the previous substitution.
g Apply the change to the first occurrence of
a match in each word, by prefixing the above
(for example, g&).
p Print the new command but do not execute it.
q Quote the substituted words, escaping fur-
ther substitutions.
x Like q, but break into words at each blank.
l Convert the words to all lowercase.
u Convert the words to all uppercase.
s/l/r[/]
Substitute r for l.
Unless preceded by a g, the substitution is done only for
the first string that matches l.
The left-hand side of substitutions are not regular
expressions, but character strings. Any character can be
used as the delimiter in place of /. A backslash quotes
the delimiter character. The character &, in the right
hand side, is replaced by the text from the left-hand-
side. The & can be quoted with a backslash. A null l
uses the previous string either from a l or from a contex-
tual scan string s from !?s. You can omit the rightmost
delimiter if a newline immediately follows r; the right-
most ? in a context scan can similarly be omitted.
Without an event specification, a history reference refers
either to the previous command, or to a previous history
reference on the command line (if any).
The character sequence ^foo^bar repeats the last command,
replacing the string "foo" with the string "bar".
If the shell encounters the character sequence !" in the
1992 May 2 17
ZSH(1) ZSH(1)
input, the history mechanism is temporarily disabled until
the current list is fully parsed. The !" is removed from
the input, and any subsequent ! characters have no spe-
cial significance.
A less convenient but more comprehensible form of command
history support is provided by the fc builtin (see below).
ARITHMETIC EVALUATION
An ability to perform integer arithmetic is provided with
the builtin let. Evaluations are performed using long
arithmetic. Constants are of the form [base#]n where base
is a decimal number between two and thirty-six represent-
ing the arithmetic base and n is a number in that base.
If base is omitted then base 10 is used.
An arithmetic expression uses nearly the same syntax,
precedence, and associativity of expressions in C. The
following operators are supported (listed in decreasing
order of precedence):
+ - ! ~ ++ --
unary plus/minus, logical NOT, complement,
{pre,post}{in,de}crement
& logical AND
^ logical XOR
| logical OR
* / % multiplication, division, remainder
+ - addition, subtraction
<< >> logical shift left, shift right
< > <= >=
comparison
== != equality and inequality
&& boolean AND
|| ^^ boolean OR, XOR
? : ternary operator
= += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^=
assignment
, comma operator
The operators &&, ||, &&=, and ||= are short-circuiting,
and only one of the latter two expressions in a ternary
operator is evaluated. Note the precedence of the logical
AND, OR, and XOR operators.
Named parameters can be referenced by name within an
arithmetic expression without using the parameter substi-
tution syntax.
An internal integer representation of a named parameter
can be specified with the integer builtin. Arithmetic
evaluation is performed on the value of each assignment to
a named parameter declared integer in this manner.
1992 May 2 18
ZSH(1) ZSH(1)
Since many of the arithmetic operators require quoting, an
alternative form of the let command is provided. For any
command which begins with a ((, all the characters until a
matching )) are treated as a quoted expression. More pre-
cisely, ((...)) is equivalent to let "...".
CONDITIONAL EXPRESSIONS
A conditional expression is used with the [[ compound com-
mand to test attributes of files and to compare strings.
Each expression can be constructed from one or more of the
following unary or binary expressions:
-a file
true if file exists.
-b file
true if file exists and is a block special file.
-c file
true if file exists and is a character special
file.
-d file
true if file exists and is a directory.
-e file
true if file exists.
-f file
true if file exists and is an ordinary file.
-g file
true if file exists and is has its setgid bit set.
-h file
true if file exists and is a symbolic link.
-k file
true if file exists and is has its sticky bit set.
-n string
true if length of string is non-zero.
-o option
true if option named option is on.
-p file
true if file exists and is a fifo special file or a
pipe.
-r file
true if file exists and is readable by current pro-
cess.
-s file
true if file exists and has size greater than zero.
-t fd true if file descriptor number fd is open and asso-
ciated with a terminal device. (note: fd is not
optional)
-u file
true if file exists and is has its setuid bit set.
-w file
true if file exists and is writable by current pro-
cess.
-x file
true if file exists and is executable by current
process. If file exists and is a directory, then
the current process has permission to search in the
1992 May 2 19
ZSH(1) ZSH(1)
directory.
-z string
true if length of string is zero.
-L file
true if file exists and is a symbolic link.
-O file
true if file exists and is owned by the effective
user id of this process.
-G file
true if file exists and its group matches the
effective group id of this process.
-S file
true if file exists and is a socket.
file1 -nt file2
true if file1 exists and is newer than file2.
file1 -ot file2
true if file1 exists and is older than file2.
file1 -ef file2
true if file1 and file2 exist and refer to the same
file.
string = pattern
true if string matches pattern.
string != pattern
true if string does not match pattern.
string1 < string2
true if string1 comes before string2 based on ASCII
value of their characters.
string1 > string2
true if string1 comes after string2 based on ASCII
value of their characters.
exp1 -eq exp2
true if exp1 is equal to exp2.
exp1 -ne exp2
true if exp1 is not equal to exp2.
exp1 -lt exp2
true if exp1 is less than exp2.
exp1 -gt exp2
true if exp1 is greater than exp2.
exp1 -le exp2
true if exp1 is less than or equal to exp2.
exp1 -ge exp2
true if exp1 is greater than or equal to exp2.
( exp )
true if exp is true.
! exp true if exp is false.
exp1 && exp2
true if exp1 and exp2 are both true.
exp1 || exp2
true if either exp1 or exp2 is true.
In each of the above expressions, if file is of the form
/dev/fd/n, where n is an integer, then the test applied to
the open file whose descriptor number is n, even if the
underlying system does not support the /dev/fd directory.
1992 May 2 20
ZSH(1) ZSH(1)
ZSH LINE EDITOR
If the ZLE option is set (it is by default) and the shell
input is attached to the terminal, the user is allowed to
edit command lines.
There are two display modes. The first, multiline mode,
is the default. It only works if the TERM parameter is
set to a valid terminal type that can move the cursor up.
The second, single line mode, is used if TERM is invalid
or incapable of moving the cursor up, or if the SIN-
GLELINEZLE option is set. This mode is similar to ksh,
and uses no termcap sequences.
Bindings
Command bindings may be set using the bindkey builtin.
There are two keymaps-the main keymap and the alternate
keymap. The alternate keymap is bound to vi command mode.
The main keymap is bound to emacs mode by default. To
bind the main keymap to vi insert mode, use bindkey -v, or
set one of the VISUAL or EDITOR environment variables to a
string containing vi.
The following is a list of all the key commands and their
default bindings in emacs and vi command mode.
Movement
vi-backward-blank-word (unbound) (B)
Move backward one word, where a word is defined as
a series of non-blank characters.
backward-char (^B ESC-[D) ()
Move backward one character.
vi-backward-char () (h)
Move backward one character, without changing
lines.
backward-word (ESC-B ESC-b) (unbound)
Move to the beginning of the previous word.
emacs-backward-word
Move to the beginning of the previous word.
vi-backward-word (unbound) (b)
Move to the beginning of the previous word, vi-
style.
beginning-of-line (^A) (0)
Move to the beginning of the line. If already at
the beginning of the line, move to the beginning of
the previous line, if any.
vi-beginning-of-line
Move to the beginning of the line, without changing
1992 May 2 21
ZSH(1) ZSH(1)
lines.
end-of-line (^E)
Move to the end of the line. If already at the end
of the line, move to the end of the next line, if
any.
vi-end-of-line (unbound) ($)
Move to the end of the line.
vi-forward-blank-word (unbound) (W)
Move forward one word, where a word is defined as a
series of non-blank characters.
vi-forward-blank-word-end (unbound) (E)
Move to the end of the current word, or, if at the
end of the current word, to the end of the next
word, where a word is defined as a series of non-
blank characters.
forward-char (^F ESC-[C)
Move forward one character.
vi-forward-char (unbound) (space l)
Move forward one character.
vi-find-next-char (^X^F) (f)
Read a character from the keyboard, and move to the
next occurrence of it in the line.
vi-find-next-char-skip (unbound) (t)
Read a character from the keyboard, and move to the
position just before the next occurrence of it in
the line.
vi-find-prev-char (unbound) (F)
Read a character from the keyboard, and move to the
previous occurrence of it in the line.
vi-find-prev-char-skip (unbound) (T)
Read a character from the keyboard, and move to the
position just after the previous occurrence of it
in the line.
vi-first-non-blank (unbound) (^)
Move to the first non-blank character in the line.
vi-forward-word (unbound) (w)
Move forward one word, vi-style.
forward-word (ESC-F ESC-f) (unbound)
Move to the beginning of the next word. The edi-
tor's idea of a word is specified with the WORD-
CHARS parameter.
1992 May 2 22
ZSH(1) ZSH(1)
emacs-forward-word
Move to the end of the next word.
vi-forward-word-end (unbound) (e)
Move to the end of the next word.
vi-goto-column (ESC-|) (|)
Move to the column specified by the numeric argu-
ment.
vi-goto-mark (unbound) (`)
Move to the specified mark.
vi-goto-mark-line (unbound) (')
Move to beginning of the line containing the speci-
fied mark.
vi-repeat-find (unbound) (;)
Repeat the last vi-find command.
vi-rev-repeat-find (unbound) (,)
Repeat the last vi-find command in the opposite
direction.
History
beginning-of-buffer-or-history (ESC-<)
Move to the beginning of the buffer, or if already
there, move to the first event in the history list.
beginning-of-line-hist
Move to the beginning of the line. If already at
the beginning of the buffer, move to the previous
history line.
beginning-of-history
Move to the first event in the history list.
down-line-or-history (^N ESC-[B) (+ j)
Move down a line in the buffer, or if already at
the bottom line, move to the next event in the his-
tory list.
down-history (unbound) (^N)
Move to the next event in the history list.
end-of-buffer-or-history (ESC->)
Move to the end of the buffer, or if already there,
move to the last event in the history list.
end-of-line-hist
Move to the end of the line. If already at the end
of the buffer, move to the next history line.
1992 May 2 23
ZSH(1) ZSH(1)
end-of-history
Move to the last event in the history list.
vi-fetch-history (unbound) (G)
Fetch the history line specified by the numeric
argument.
history-incremental-search-backward (^R ^Xr)
Search backward incrementally for a specified
string. The string may begin with `^' to anchor
the search to the beginning of the line.
history-incremental-search-forward (^Xs)
Search forward incrementally for a specified
string. The string may begin with `^' to anchor
the search to the beginning of the line.
history-search-backward (ESC-P ESC-p) (K)
Search backward in the history for a line beginning
with the first word in the buffer.
vi-history-search-backward (unbound) (/)
Search backward in the history for a specified
string. The string may begin with `^' to anchor
the search to the beginning of the line.
history-search-forward (ESC-N ESC-n) (J)
Search forward in the history for a line beginning
with the first word in the buffer.
vi-history-search-forward (unbound) (?)
Search forward in the history for a specified
string. The string may begin with `^' to anchor
the search to the beginning of the line.
infer-next-history (^X^N)
Search in the history list for a line matching the
current one and fetch the event following it.
insert-last-word (ESC-_ ESC-.)
Insert the last word from the previous history
event at the cursor position.
vi-repeat-search (unbound) (n)
Repeat the last vi history search.
vi-rev-repeat-search (unbound) (N)
Repeat the last vi history search, but in reverse.
toggle-literal-history (ESC-R ESC-r)
Toggle between literal and lexical history. The
default is lexical history unless the HISTLIT
option is set.
1992 May 2 24
ZSH(1) ZSH(1)
up-line-or-history (^P ESC-[A) (- k)
Move up a line in the buffer, or if already at the
top line, move to the previous event in the history
list.
up-history (unbound) (^P)
Move to the previous event in the history list.
Modifying Text
vi-add-eol (unbound) (A)
Move to the end of the line and enter insert mode.
vi-add-next (unbound) (a)
Move forward one character and enter insert mode.
backward-delete-char (^H ^?) (^?)
Delete the character behind the cursor.
vi-backward-delete-char (unbound) (X)
Delete the character behind the cursor, without
changing lines.
backward-delete-word
Delete the word behind the cursor.
backward-kill-line
Kill from the beginning of the line to the cursor
position.
backward-kill-word (^W ESC-^H ESC-^?)
Kill the word behind the cursor.
vi-backward-kill-word (unbound) (^W)
Kill the word behind the cursor.
capitalize-word (ESC-C ESC-c)
Capitalize the current word and move past it.
vi-change (unbound) (c)
Read a movement command from the keyboard, and kill
from the cursor position to the endpoint of the
movement. Then enter insert mode. If the command
is vi-change, kill the current line.
vi-change-eol (unbound) (C)
Kill to the end of the line and enter insert mode.
vi-change-whole-line (unbound) (S s)
Kill the current line and enter insert mode.
copy-region-as-kill (ESC-W ESC-w)
Copy the area from the cursor to the mark to the
kill buffer.
1992 May 2 25
ZSH(1) ZSH(1)
copy-prev-word (ESC-^_)
Duplicate the word behind the cursor.
vi-delete (unbound) (d)
Read a movement command from the keyboard, and kill
from the cursor position to the endpoint of the
movement. If the command is vi-delete, kill the
current line.
delete-char (unbound) (x)
Delete the character under the cursor.
vi-delete-char (unbound) (x)
Delete the character under the cursor.
delete-word (ESC-D ESC-d)
Delete the current word.
down-case-word (ESC-L ESC-l)
Convert the current word to all lowercase and move
past it.
kill-word
Kill the current word.
gosmacs-transpose-chars
Exchange the two characters behind the cursor.
vi-indent (unbound) (>)
Indent a number of lines.
vi-insert (unbound) (i)
Enter insert mode.
vi-insert-bol (unbound) (I)
Move to the beginning of the line and enter insert
mode.
vi-join (^X^J)
Join the current line with the next one.
kill-line (^K) (D)
Kill from the cursor to the end of the line.
kill-region
Kill from the cursor to the mark.
kill-buffer (^X^U) (^U)
Kill the entire buffer.
kill-whole-line (^U) (unbound)
Kill the current line.
1992 May 2 26
ZSH(1) ZSH(1)
vi-match-bracket (^X^B) (%)
Move to the bracket character (one of {}, (), or
[]) that matches the one under the cursor.
vi-open-line-above (unbound) (O)
Open a line above the cursor and enter insert mode.
vi-open-line-below (unbound) (o)
Open a line below the cursor and enter insert mode.
vi-oper-swap-case
Read a movement command from the keyboard, and swap
the case of all characters from the cursor position
to the endpoint of the movement. If the movement
command is vi-oper-swap-case, swap the case of all
characters on the current line.
overwrite-mode (^X^O)
Toggle between overwrite mode and insert mode.
vi-put-after (unbound) (p)
Insert the contents of the kill buffer after the
cursor.
quoted-insert (^V)
Insert the next character typed into the buffer
literally.
quote-line (ESC-')
Quote the current line; that is, put a ' character
at the beginning and the end, and convert all '
characters to '\''.
quote-region (ESC-")
Quote the region from the cursor to the mark.
vi-replace (unbound) (R)
Enter overwrite mode.
vi-repeat-change (unbound) (.)
Repeat the last vi mode text modification.
vi-replace-chars (unbound) (r)
Replace the character under the cursor with a char-
acter read from the keyboard.
self-insert (printable characters)
Put a character in the buffer at the cursor posi-
tion.
self-insert-unmeta (ESC-^I ESC-^J ESC-^M)
Put a character in the buffer after stripping the
meta bit and converting ^M to ^J.
1992 May 2 27
ZSH(1) ZSH(1)
vi-substitute (unbound) (s)
Substitute the next character(s).
vi-swap-case (unbound) (~)
Swap the case of the character under the cursor and
move past it.
transpose-chars (^T)
Exchange the two characters to the left of the cur-
sor if at end of line, else exchange the character
under the cursor with the character to the left.
transpose-words (ESC-T ESC-t)
Exchange the current word with the one before it.
vi-unindent (unbound) (<)
Unindent a number of lines.
up-case-word (ESC-U ESC-u)
Convert the current word to all caps and move past
it.
yank (^Y) (P)
Insert the contents of the kill buffer at the cur-
sor position.
yank-pop (ESC-y) (unbound)
Remove the text just yanked, rotate the kill-ring,
and yank the new top. Only works following yank or
yank-pop.
vi-yank (unbound) (y)
Read a movement command from the keyboard, and copy
the region from the cursor position to the endpoint
of the movement into the kill buffer. If the com-
mand is vi-yank, copy the current line.
vi-yank-eol (unbound) (Y)
Copy the region from the cursor position to the end
of the line into the kill buffer.
Arguments
digit-argument (ESC-0..ESC-9) (0-9)
Start a new numeric argument, or add to the current
one.
universal-argument
Multiply the argument of the next command by 4.
Completion
accept-and-menu-complete
In a menu completion, insert the current completion
into the buffer, and advance to the next possible
completion.
1992 May 2 28
ZSH(1) ZSH(1)
complete-word (unbound) (\)
Attempt completion on the current word.
delete-char-or-list (^D)
Delete the character under the cursor. If the cur-
sor is at the end of the line, list possible com-
pletions for the current word.
execute-named-cmd (ESC-x)
Read the name of a editor command and execute it.
execute-last-named-cmd (ESC-z)
Redo the last function executed with execute-named-
cmd.
expand-cmd-path
Expand the current command to its full pathname.
expand-or-complete (TAB) (TAB ^X)
Attempt shell expansion on the current word. If
that fails, attempt completion.
expand-history (ESC-space ESC-!)
Perform history expansion on the edit buffer.
expand-word (^X*)
Attempt shell expansion on the current word.
list-choices (ESC-^D) (^D =)
List possible completions for the current word.
list-expand (^Xg ^XG) (^G)
List the expansion of the current word.
magic-space
Perform history expansion and insert a space into
the buffer. This is intended to be bound to space.
menu-complete
Like complete-word, except that menu completion is
used. See the MENUCOMPLETE option below.
menu-expand-or-complete
Like expand-or-complete, except that menu comple-
tion is used.
reverse-menu-complete
See the MENUCOMPLETE option below.
Miscellaneous
accept-and-hold (ESC-A ESC-a)
Push the contents of the buffer on the buffer stack
and execute it.
1992 May 2 29
ZSH(1) ZSH(1)
accept-and-infer-next-history
Execute the contents of the buffer. Then search
the history list for a line matching the current
one and push the event following onto the buffer
stack.
accept-line (^J ^M)
Execute the contents of the buffer.
accept-line-and-down-history (^O)
Execute the current line, and push the next history
event on the the buffer stack.
vi-cmd-mode (^X^V) (^[)
Enter command mode; that is, use the alternate
keymap. Yes, this is bound by default in emacs
mode.
vi-caps-lock-panic (unbound) (H K)
Hang until any lowercase key is pressed. This is
for vi users without the mental capacity to keep
track of their caps lock key (like the author).
clear-screen (^L ESC-^L)
Clear the screen and redraw the prompt.
exchange-point-and-mark (^X^X)
Exchange the cursor position with the position of
the mark.
get-line (ESC-G ESC-g)
Pop the top line off the buffer stack and insert it
at the cursor position.
pound-insert (unbound) (#)
If there is no # character at the beginning of the
current line, add one. If there is one, remove it.
In either case, accept the current line. The
INTERACTIVECOMMENTS option must be set for this to
have any usefulness.
push-line (^Q ESC-Q ESC-q)
Push the current buffer onto the buffer stack and
clear the buffer. Next time the editor starts up,
the buffer will be popped off the top of the buffer
stack and loaded into the editing buffer.
redisplay (unbound) (^R)
Redisplays the edit buffer.
run-help (ESC-H ESC-h)
Push the buffer onto the buffer stack, and execute
the command "run-help cmd", where cmd is the cur-
rent command. run-help is normally aliased to man.
1992 May 2 30
ZSH(1) ZSH(1)
send-break (^C)
Abort the parsing of the current line.
vi-set-buffer (unbound) (")
Specify a buffer to be used in the following com-
mand.
vi-set-mark (unbound) (m)
Set the specified mark at the cursor position.
set-mark-command (^@)
Set the mark at the cursor position.
spell-word (ESC-$ ESC-S ESC-s)
Attempt spelling correction on the current word.
undefined-key
Beep.
undo (^_ ^X^U) (u)
Incrementally undo the last text modification.
which-command (ESC-?)
Push the buffer onto the buffer stack, and execute
the command "which-command cmd", where cmd is the
current command. which-command is normally aliased
to whence.
PARAMETERS
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.
The elements are numbered beginning with 1. A subscript
of the form [*] or [@] evaluates to all elements of an
array; there is no difference between the two except when
they appear within double quotes. "$foo[*]" evaluates to
1992 May 2 31
ZSH(1) ZSH(1)
"$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 subscripts 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 ele-
ment 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.
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.
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.
HOST The current hostname.
HOSTTYPE
A string corresponding to the type of the
host the shell is running on.
LINENO The line number of the current line within
1992 May 2 32
ZSH(1) ZSH(1)
the current script being executed.
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.
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.
USERNAME
LOGNAME
The username corresponding to the user id of
the shell process.
VERSION
The version number of this zsh.
The following parameters are used by the shell:
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.
bindcmds
An write-only array of command names which
take line editor function names as argu-
ments, and which therefore should allow
1992 May 2 33
ZSH(1) ZSH(1)
binding completion.
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 AUTOPUSHD 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.
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.
hostcmds
An write-only array of command names which
take hostnames as arguments, and which
should therefore allow hostname completion.
This sort of completion is also used in
words containing a @ character.
hosts (HOSTS)
An array (colon separated list) of hostnames
to use for hostname completion.
IFS Internal field separators, normally space,
tab, and newline, that are used to separate
1992 May 2 34
ZSH(1) ZSH(1)
words which result from command or parameter
substitution and words read by the read
builtin.
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.
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.
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."
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.
optcmds
An write-only array of commands which take
options as arguments, and which therefore
should allow option completion.
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
1992 May 2 35
ZSH(1) ZSH(1)
strings to reset the terminal.
PROMPT The primary prompt string, printed before a
command is read; the default is "%m%# ".
The following escape sequences are recog-
nized:
%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. May be
followed by a digit to get more than
one component. Unless %C is used,
tilde expansion is performed first.
!
%h
%! Current history event number
%M The full machine hostname.
%m The hostname up to the first '.'.
May be followed by a digit to spec-
ify how many components of the host-
name 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.
%# A '#' if the shell is running as
root, a '%' if not.
1992 May 2 36
ZSH(1) ZSH(1)
%{...%}
Include a string as a literal escape
sequence. The string within the
braces should not change the cursor
position.
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.
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 nonzero, 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, except that termcap sequences like
%s, etc. will not work.
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
1992 May 2 37
ZSH(1) ZSH(1)
executing the command.
TIMEFMT
The format of process time reports with the
time keyword. The default is "%E real %U
user %S system %P". Recognizes the fol-
lowing 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.
%W Number of times the process was
swapped.
%X The average amount in (shared) text
space used in Kbytes.
%D The average amount in (unshared)
data/stack space used in Kbytes.
%K The total space used (%X+%D) in
Kbytes.
%M The maximum memory the process had
in use at any time in Kbytes.
%F The number of major page faults
(page needed to be brought from
disk).
%R The number of minor page faults.
%I The number of input operations.
%O The number of output operations.
%r The number of socket messages
received.
%s The number of socket messages sent.
%k The number of signals received.
%w Number of voluntary context switches
(waits).
%c Number of involuntary context
switches.
%J The name of this job.
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.
varcmds
An write-only array of command names which
take parameter names as arguments, and which
therefore should allow parameter completion.
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. An entry
1992 May 2 38
ZSH(1) ZSH(1)
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.
%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.
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.
OPTIONS
The following options may be set upon invocation of the
shell, or with the set or setopt builtins:
ALLEXPORT (-a)
All parameters subsequently defined are
automatically exported.
AUTOCD (-J)
If a command is not in the hash table, and
1992 May 2 39
ZSH(1) ZSH(1)
there exists an executable directory by that
name, perform the cd command to that direc-
tory.
AUTOLIST (-9)
Automatically list choices on an ambiguous
completion.
AUTOMENU
Automatically use menu completion if the TAB
key is pressed repeatedly.
AUTOPUSHD (-N)
Make cd act like pushd.
AUTORESUME (-W)
Treat single word simple commands without
redirection as candidates for resumption of
an existing job.
BGNICE (-6)
Run all background jobs at a lower priority.
This option is set by default.
BRACECCL
Allow brace expansions of the form {a-zA-Z},
etc.
CDABLEVARS (-T)
If the argument to a cd command is not a
directory, but a parameter exists by the
same name whose value begins with a /, try
to change to the directory specified by the
parameter's value.
CHASELINKS (-w)
Resolve symbolic links to their true values.
CORRECT (-0)
Try to correct the spelling of commands.
CORRECTALL (-O)
Try to correct the spelling of all arguments
in a line.
CSHJUNKIELOOPS
Allow loop bodies to take the form "list;
end" instead of "do list; done".
CSHJUNKIEQUOTES
Complain if a quoted expression runs off the
end of a line; prevent quoted expressions
from containing unescaped newlines.
CSHNULLGLOB
If a pattern for filename generation has no
matches, delete the pattern from the argu-
ment list; do not report an error unless all
the patterns in a command have no matches.
Overrides NULLGLOB.
ERREXIT (-e)
If a command has a non-zero exit status,
execute the ERR trap, if set, and exit.
EXTENDEDGLOB
Treat the # and ^ characters as part of pat-
terns for filename generation, etc.
1992 May 2 40
ZSH(1) ZSH(1)
GLOBCOMPLETE
Like MENUCOMPLETE, except that the current
word is expanded using normal shell expan-
sion instead of completion. If no matches
are found, a * is added to the end of the
word, and expansion is attempted again.
GLOBDOTS (-4)
Do not require a leading . in a filename to
be matched explicitly.
HASHCMDS
Place the location of each command in the
hash table the first time it is executed.
If this option is unset, no path hashing
will be done at all.
HASHDIRS
Whenever a command is executed, hash the
directory containing it, as well as all
directories that occur earlier in the path.
Has no effect if HASHCMDS is unset.
HASHLISTALL
Whenever a command completion is attempted,
make sure the entire command path is hashed
first. This makes the first completion
slower.
HISTIGNOREDUPS (-h)
Do not enter command lines into the history
list if they are duplicates of the previous
event.
HISTIGNORESPACE (-g)
Do not enter command lines into the history
list if they begin with a blank.
HISTLIT (-j)
Use literal (unparsed) versions of the his-
tory lines in the editor.
HISTNOSTORE
Remove the history (fc -l) command from the
history when invoked.
HISTVERIFY
Whenever the user enters a line with history
substitution, don't execute the line
directly; instead, perform history substitu-
tion and reload the line into the editing
buffer.
IGNOREBRACES (-I)
Do not perform brace expansion.
IGNOREEOF (-7)
Do not exit on end-of-file. Require the use
of exit or logout instead.
INTERACTIVE (-i)
This is an interactive shell.
INTERACTIVECOMMENTS (-k)
Allow comments even in interactive shells.
KSHOPTIONPRINT
Alters the way options settings are printed.
1992 May 2 41
ZSH(1) ZSH(1)
LISTTYPES (-X)
When listing files that are possible comple-
tions, show the type of each file with a
trailing identifying mark.
LOGIN (-l)
This is a login shell.
LONGLISTJOBS (-R)
List jobs in the long format by default.
MAILWARNING (-U)
Print a warning message if a mail file has
been accessed since the shell last checked.
MARKDIRS (-8)
Append a trailing / to all directory names
resulting from filename generation (glob-
bing).
MENUCOMPLETE (-Y)
On an ambiguous completion, instead of list-
ing possibilities, insert the first match.
Then when completion is requested again,
remove the first match and insert the second
match, etc. When there are no more matches,
go back to the first one again. reverse-
menu-complete may be used to loop through
the list in the other direction.
MENUCOMPLETEBEEP
Beep on an ambiguous menu completion.
MONITOR (-m)
Allow job control. Set by default in inter-
active shells.
NOBADPATTERN (-2)
If a pattern for filename generation is
badly formed, leave it unchanged in the
argument list instead of printing an error.
NOBANGHIST (-K)
Do not perform textual history substitution.
Do not treat the ! character specially.
NOBEEP (-B)
Do not beep.
NOCLOBBER (-1)
Prevents > redirection from truncating
existing files. >! may be used to truncate
a file instead. Also prevents >> from cre-
ating files. >>! may be used instead.
NOEQUALS
Don't perform = filename substitution.
NOEXEC (-n)
Read commands and check them for syntax
errors, but do not execute them.
NOGLOB (-F)
Disable filename generation.
NOHISTBEEP
Don't beep when an attempt is made to access
a history entry which isn't there.
NOHUP Don't send the HUP signal to running jobs
1992 May 2 42
ZSH(1) ZSH(1)
when the shell exits.
NOLISTBEEP
Don't beep on an ambiguous completion.
NONOMATCH (-3)
If a pattern for filename generation has no
matches, leave it unchanged in the argument
list instead of printing an error.
NOPROMPTCR (-V)
Don't print a carriage return just before
printing a prompt in the line editor.
NORCS (-f)
Do not source the .zshenv, .zshrc, .zlogin,
.zlogout, or .zprofile files.
NOSHORTLOOPS
Disallow the short forms of for, select, if,
and function constructs.
NOTIFY (-5)
Report the status of background jobs immedi-
ately, rather than waiting until just before
printing a prompt.
NOUNSET (-u)
Treat unset parameters as an error when sub-
stituting.
NULLGLOB (-G)
If a pattern for filename generation has no
matches, delete the pattern from the argu-
ment list instead of reporting an error.
Overrides NONOMATCH.
NUMERICGLOBSORT
If numeric filenames are matched by a file-
name generation pattern, sort the filenames
numerically rather than lexicographically.
OVERSTRIKE
Start up the line editor in overstrike mode.
PATHDIRS (-Q)
Perform a path search even on command names
with slashes in them. Thus if
"/usr/local/bin" is in the user's path, and
he types "X11/xinit", the command
"/usr/local/bin/X11/xinit" will be executed
(assuming it exists).
PRINTEXITVALUE (-C)
Print the exit value of programs with non-
zero exit status.
PUSHDIGNOREDUPS
Don't push multiple copies of the same
directory onto the directory stack.
PUSHDMINUS
See popd below.
PUSHDSILENT (-E)
Do not print the directory stack after pushd
or popd.
PUSHDTOHOME (-D)
Have pushd with no arguments act like pushd
1992 May 2 43
ZSH(1) ZSH(1)
$HOME.
RCEXPANDPARAM (-P)
See Parameter Expansion.
RCQUOTES
Allow the character sequence '' to signify a
single quote within singly quoted strings.
RECEXACT (-S)
In completion, recognize exact matches even
if they are ambiguous.
RMSTARSILENT (-H)
Do not query the user before executing "rm
*" or "rm path/*".
SHINSTDIN (-s)
Read commands from the standard input.
SHWORDSPLIT (-y)
See Parameter Expansion.
SINGLELINEZLE (-M)
Use single-line command line editing instead
of multi-line.
SUNKEYBOARDHACK (-L)
If a line ends with a backquote, and there
are an odd number of backquotes on the line,
ignore the trailing backquote. This is use-
ful on some keyboards where the return key
is too small, and the backquote key lies
annoyingly close to it.
VERBOSE (-v)
Print shell input lines as they are read.
XTRACE (-x)
Print commands and their arguments as they
are executed.
ZLE (-Z)
Use the zsh line editor.
SHELL BUILTIN COMMANDS
. file [ arg ... ]
Read and execute commands from file in the current
shell environment. If file does not contain a
slash, the shell looks in the components of path to
find the directory containing file. If any argu-
ments 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 exe-
cuted.
: [ arg ... ]
This command only expands parameters. A zero exit
code is returned.
alias [ -g ] [ name[=value] ] ...
With no arguments, print the list of aliases in the
form name=value on the standard output. For each
name with a corresponding value, define an alias
1992 May 2 44
ZSH(1) ZSH(1)
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. The exit
status is nonzero if a name (with no value) given
for which no alias has been defined.
autoload [ name ... ]
For each of the names (which are names of func-
tions), create a function marked undefined. The
fpath variable will be searched to find the actual
function definition when the function is first ref-
erenced.
bg [ job ... ]
job ... &
Put each specified job in the background, or the
current job if none is specified.
bindkey -mevd
bindkey -r in-string ...
bindkey [ -a ] in-string [ command ] ...
bindkey -s [ -a ] in-string out-string ...
If one of the -e, -v, or -d options is given, reset
the keymaps for emacs mode, vi mode, or the default
mode, respectively; if the -m option is also given,
allow the use of a meta key. If the -r option is
given, remove any binding for each in-string. If
the -s option is not specified, bind each in-string
to a specified command. If no command is speci-
fied, 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. 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.
For either in-string or out-string, control charac-
ters may be specified in the form ^X, and the back-
slash 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 escape
1992 May 2 45
ZSH(1) ZSH(1)
\nnn character code in octal
\M-xxx character or escape sequence with
meta bit set
In all other cases, \ escapes the following charac-
ter. Delete is written as `^?'.
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 direc-
tory.
The third form of cd is equivalent to popd.
chdir Same as cd.
compctl [ -cfhovbCD ] [ -k name ] [ arg ... ]
Control the editor's completion behavior when one
of arg is the current command. With the -D flag,
control default completion behavior for commands
not assigned any special behavior; with -C, control
completion when there is no current command. The
remaining options specify the type of command argu-
ments to look for during completion. For example,
compctl -hf rlogin is equivalent to
hostcmds=(rlogin).
-c Expect command names.
-f Expect filenames and filesystem paths.
-h Expect hostnames taken from the $hosts vari-
able.
-o Expect option names.
1992 May 2 46
ZSH(1) ZSH(1)
-v Expect variable names.
-b Expect key binding names.
-k name
Expect names taken from the elements of
$name.
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 nth enclosing loop.
declare [ arg ... ]
Same as typeset.
dirs [ -v ] [ arg ... ]
With no arguments, print the contents of the direc-
tory stack. If the -v option is given, number the
directories in the stack when printing. Directo-
ries are added to this stack with the pushd com-
mand, and removed with the cd or popd commands. If
arguments are specified, load them onto the direc-
tory stack, replacing anything that was there, and
push the current directory onto the stack.
disable arg ...
Disable the builtin arg temporarily. This allows
you to use an external command with the same name
as a shell builtin. Actually the same as unhash.
Builtins can be enabled with the enable command.
disown 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.
echo [ -n ] [ arg ... ]
Write each arg on the standard output, with a space
separating each one. If the -n flag is not pre-
sent, print a newline at the end. echo recognizes
the following escape sequences:
\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
\xxx character code in octal
1992 May 2 47
ZSH(1) ZSH(1)
echotc cap [ arg ... ]
Output the termcap string corresponding to the
capability cap, with optional arguments.
enable arg ...
Enable the specified builtin commands, presumably
disabled earlier with disable.
eval [ arg ... ]
Read the arguments as input to the shell and exe-
cute the resulting command(s) in the current shell
process.
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 IGNOREEOF
option is set.
export [ name[=value] ... ]
The specified names are marked for automatic export
to the environment of subsequently executed com-
mands.
false Do nothing and return an exit code of 1.
fc [ -e ename ] [ -nlrdD ] [ old=new ... ] [ first [ last
] ]
fc -ARW [ 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 nega-
tive 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.
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 exe-
cuted. 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 list-
ing. Also when listing, -d prints datestamps for
each command, and -D prints real execution times.
fc -R reads the history from the given file, fc -W
1992 May 2 48
ZSH(1) ZSH(1)
writes the history out to the given file, and fc -A
appends the history out to the given file.
fg [ job ... ]
job ...
Bring the specified jobs to the foreground. If no
job is specified, use the current job.
functions [ +-tu ] [ 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.
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 name path
Puts name in the command hash table, associating it
with the pathname path. Whenever name is used as a
command argument, the shell will try to execute the
file given by path.
history [ -nr ] [ first [ last ] ]
Same as fc -l.
integer
Same as typeset -i.
jobs [ -lp ] [ job ... ]
Lists information about each given job, or all jobs
1992 May 2 49
ZSH(1) ZSH(1)
if job is omitted. The -l flag lists process ids,
and the -p flag lists process groups.
kill [ -sig ] job ...
kill -l
Sends either SIGTERM or the specified signal to the
given jobs or processes. Signals are given by num-
ber or by names (with the prefix "SIG" removed).
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 second form,
kill -l, the signal names are listed.
let arg ...
Evaluate each arg as an arithmetic expression. See
ARITHMETIC EVALUATION above for a description of
arithmetic expressions. The exit status is 0 if
the value of the last expression is nonzero, and 1
otherwise.
limit [ -h ] [ resource [ limit ] ] ...
limit -s
Limit the resource consumption of children of the
current shell. 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
Maximum resident set size.
descriptors
Maximum value for a file descriptor.
limit is a number, with an optional scaling factor,
as follows:
nh hours.
nk kilobytes. This is the default for all but
cputime.
1992 May 2 50
ZSH(1) ZSH(1)
nm megabytes or minutes.
mm:ss minutes and seconds.
local Same as typeset.
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.
popd [ +-n ]
Removes entries from the directory stack. With no
arguments, removes the top directory from the
stack, and performs a cd to the new top directory.
With an argument of the form +n, remove the nth
entry counting from the left of the list shown by
the dirs command, starting with zero, and change to
that directory. With an argument of the form -n,
remove the nth entry counting from the right. If
the PUSHDMINUS option is set, the meanings of +
and - in this context are swapped.
print [ -RnrslzpNDP ] [ -un ] [ arg ... ]
With no flags or with flag -, the arguments are
printed on the standard output as described by
echo.
-R, -r ignore the escape conventions of echo. The
-R option will print all subsequent argu-
ments and options.
-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.
-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 cur-
rent directory onto the directory stack. In the
first form, change the current directory to arg.
1992 May 2 51
ZSH(1) ZSH(1)
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
PUSHDTOHOME 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
PUSHDSILENT 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 direc-
tory.
The third form of pushd is equivalent to popd.
pwd Equivalent to print -R $PWD.
r Equivalent to fc -e -.
read [ -rzp ] [ -un ] [ name?prompt ] [ name ... ]
Read one line and break it into fields using the
characters in IFS as separators. In raw mode, -r,
a \ at the end of a line does not signify line con-
tinuation. If the -z flag is set, 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. If name is omitted then REPLY is used.
If -un is specified, then input is read from file
descriptor n; if -p is specified, then input is
read from the coprocess. The exit status is 0
unless end-of-file is encountered. 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 [ -f ]
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.
1992 May 2 52
ZSH(1) ZSH(1)
return [ n ]
Causes a shell function or . script to return to
the invoking script with the return status speci-
fied by n. If n is omitted then the return status
is that of the last command executed.
sched [+]hh:mm command ...
sched [ -item ]
Make an entry in the scheduled list of commands to
execute. The time may be specified in either abso-
lute 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 posi-
tional parameters, or declare an array. For the
meaning of the flags, see OPTIONS above. Flags may
be specified by name using the -o option. If the
-A flag is specified, name is set to an array con-
taining the given args. 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 argu-
ment is +, the names of all parameters are printed.
setopt [ +-options ] [ name ... ]
Set the options for the shell. All options speci-
fied 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.
shift [ n ]
The positional parameters from $n+1 ... are renamed
$1, where n is an arithmetic expression that
defaults to 1.
source Same as ..
suspend [ -f ]
Suspend the execution of the shell (send it a SIGT-
STP) 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 compat-
ibility; use conditional expressions instead.
times Print the accumulated user and system times for the
shell and for processes run from the shell.
1992 May 2 53
ZSH(1) ZSH(1)
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 val-
ues. If arg is the null string, then this signal
is ignored by the shell and by the commands it
invokes. If sig is ERR 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 unfreezes it.
When the tty is frozen, no changes made to the tty
settings by external programs will be honored by
the shell; 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.
type Same as whence -v.
typeset [ +-LRZfilrtux [n]] [ name[=value] ] ...
Set attributes and values for shell parameters.
When invoked inside a function, if name is not
already defined, a new parameter is created which
will be unset when the function completes. 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 deter-
mined 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 if 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.
-Z Right justify and fill with leading zeros if
1992 May 2 54
ZSH(1) ZSH(1)
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.
-i Use an internal integer representation. If
i is nonzero it defines the output arith-
metic base, otherwise it is determined by
the first assignment.
-l Convert to lower case.
-r The given names are marked readonly.
-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.
ulimit [ -HSacdfmnt ] [ limit ]
Set or display a resource limit. The value of
limit can be a number in the unit specified below
or the value unlimited. The H and S flags specify
whether the hard limit or the soft limit for the
given resource is set.
-a Lists all of the current resource limits.
-c The number of 512-byte blocks on the size of
core dumps.
-d The number of K-bytes on the size of the
data segment.
-f The number of 512-byte blocks on the size of
files written.
-m The number of K-bytes on the size of physi-
cal memory.
-n The number of file descriptors.
-s The number of K-bytes on the size of the
stack.
-t The number of CPU seconds to be used.
1992 May 2 55
ZSH(1) ZSH(1)
umask [ 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.
unalias name ...
The alias definition, if any, for each name is
removed.
unfunction name ...
The function definition, if any, for each name is
removed.
unhash name ...
The entry in the command hash table, if any, for
each name is removed.
unlimit [ -h ] 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.
unset name ...
Each named parameter is unset.
unsetopt [ +-options ] [ name ... ]
Unset the options for the shell. All options spec-
ified either with flags or by name are unset.
vared 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.
wait [ job ... ]
Wait for the specified jobs or processes. If job
is not given then all currently active child pro-
cesses 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 [ -acpv ] 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 -p flag does a path
search for name even if it is a shell function,
alias, or reserved word. The -c flag prints the
results in a csh-like format. The -a flag does a
search for all occurences of name throughout the
command path.
1992 May 2 56
ZSH(1) ZSH(1)
which Same as whence -c.
INVOCATION
Commands are first read from /etc/zshenv. Then, if the
NORCS option is unset, commands are read from $ZDOT-
DIR/.zshenv. (If ZDOTDIR is unset, HOME is used instead).
Then, if the shell is interactive and the NORCS option is
unset, commands are read from /etc/zshrc and $ZDOT-
DIR/.zshrc, in that order, if either file exists. If the
first character of argument zero passed to the shell is -,
then the shell is assumed to be a login shell, and com-
mands are read from /etc/zprofile and $ZDOTDIR/.zprofile
before .zshrc is read, then /etc/zlogin and $ZDOT-
DIR/.zlogin after .zshrc is read. If the NORCS option is
set, only /etc/zshrc /etc/zlogin, and /etc/zprofile may be
read. If the -s flag is not present and an argument is
given, the first argument is taken to be the pathname of a
script to execute. The remaining arguments are assigned
to the positional parameters. The following flags are
interpreted by the shell when invoked:
-c string
Read commands from string.
-s Read command from the standard input.
-i If this flag is present or the shell input and out-
put are attached to a terminal, this shell is
interactive.
SEE ALSO
sh(1), csh(1), tcsh(1), itcsh(1), rc(1), bash(1), ash(1),
ksh(1), clam(1), strftime(3).
FILES
$ZDOTDIR/.zshenv
$ZDOTDIR/.zshrc
$ZDOTDIR/.zlogin
$ZDOTDIR/.zlogout
$ZDOTDIR/.zprofile
/tmp/zsh*
/etc/zshenv
/etc/zprofile
/etc/zshrc
/etc/zlogin
AUTHOR
Paul Falstad (pfalstad@phoenix.princeton.edu)
UNDOCUMENTED FEATURES
None known, but many suspected. Please mail the author if
you find any.
1992 May 2 57