// ZSHRS — FULL REFERENCE

# if … then … fi

Standard POSIX conditional. elif branches and an optional else are supported. Status semantics: a Status(0) is truthy in zshrs, so if cmd; then …; fi runs the then arm when cmd exits 0. The compile path emits JumpIfFalse at the end of each conditional probe.

if [[ -d "$dir" ]]; then
  cd "$dir"
elif [[ -f "$dir" ]]; then
  echo "regular file"
else
  echo "no such path"
fi

# while … do … done

Loops while the condition exits 0. Loop-body status is preserved across iterations via a dedicated slot — the loop's exit status is the body's last-command status (or 0 if the body never ran), matching POSIX.

i=0
while (( i < 5 )); do
  echo "iter $i"
  (( i++ ))
done

# until … do … done

Inverse of while — loops while the condition is non-zero. Compiles to the same bytecode shape with the condition jump inverted.

until ping -c1 -W1 example.com >/dev/null; do
  sleep 1
done
echo "online"

# for var in words; do … done

Iterates var over the word list. Words are compiled at runtime — ${arr[@]} splices into N iterations via BUILTIN_ARRAY_FLATTEN. The for-loop preserves break/continue patches as deferred jump sites so nested loops work correctly.

for f in *.rs; do
  echo "compiling $f"
done

arr=(alpha beta gamma)
for x in ${arr[@]}; do
  echo "got $x"
done

# for ((init; cond; step)); do … done

C-style arithmetic for loop. The arithmetic expressions compile through the inline arithmetic compiler (no $((…)) wrapping needed inside the parens).

for ((i = 0; i < 10; i++)); do
  echo "i=$i"
done

# case … esac

Pattern-matched dispatch. Patterns are compiled via compile_case_pattern which preserves $-expansion but does not glob-expand the pattern itself (otherwise case x in *) … would expand * to the cwd listing). Match check uses Op::StrMatch (host-routed glob match).

case "$1" in
  start) echo starting ;;
  stop)  echo stopping ;;
  *)     echo "usage: $0 {start|stop}"; exit 1 ;;
esac

# select var in words; do … done

Interactive numbered-menu loop. Prints 1) word1\n2) word2\n… to stderr, prompts via $PROMPT3 (default ?# ), reads stdin, sets var to the chosen word, runs the body. $REPLY contains the raw input. EOF on stdin exits the loop. The real break keyword exits early via the cross-VM LoopSignal mechanism; the legacy BREAK_SELECT=1 sentinel still works for back-compat.

select choice in build test deploy quit; do
  case $choice in
    build)  cargo build ;;
    test)   cargo test ;;
    deploy) ./deploy.sh ;;
    quit)   break ;;
  esac
done

# () { body } args…

Anonymous function. Defined and immediately invoked with the trailing words as $1…$N. Parser routes Inoutpar (the () token) to parse_anon_funcdef, which generates a unique _zshrs_anon_N name; compile_funcdef registers and calls when auto_call_args is set. () with no body falls back to an empty subshell (POSIX no-op).

() { echo "hi $1, $2 args"; } world 1
# → hi world, 1 args

# case;& fall-through, ;| test-next

Per-arm separators after a case body. ;; exits (default), ;& falls through to the next arm without re-testing its pattern, ;| falls through and does re-test. compile_case tracks a pending_fall patch site so ;& emits a forward jump that the next arm's body-start patches.

case "$x" in
  a) print A ;&     # falls into b's body
  b) print B ;;
  *) print other ;;
esac

# coproc [name] { body }

Forks the body with bidirectional pipes. Two pipes are created (parent→child stdin, child→parent stdout); child setsids and runs the body, parent stores [read_fd, write_fd] in $COPROC (or the given name as an array). Read child output via /dev/fd/${COPROC[1]}, write to its stdin via /dev/fd/${COPROC[2]}. Job-table integration is Phase G6.

coproc { while read line; do echo "ECHO: $line"; done }
echo hello > /dev/fd/${COPROC[2]}
read reply < /dev/fd/${COPROC[1]}
echo "$reply"   # ECHO: hello

# break

Exits the innermost for/while/until. Compiled as a deferred forward Jump(0) patched to land just past the loop's exit point. Inside select use BREAK_SELECT=1 instead until cross-construct loop control lands in Phase G6.

for f in *.log; do
  [[ -s $f ]] || break    # stop on first empty
  process "$f"
done

# continue

Skip to the next iteration. Same patch mechanism as break — patches into the loop's continue target which is the iteration step (e.g. PreIncSlotVoid in the for-loop).

for n in 1 2 3 4 5; do
  (( n % 2 == 0 )) || continue
  echo "even: $n"
done

# return [n]

Return from a function with the given status (default last-status). Compile emits a forward Op::Jump(0) patched to past the chunk's end; standalone-chunk VMs interpret this as halt. Op::Return alone restarts the body from ip=0, which is wrong for top-level scripts.

greet() {
  [[ -z "$1" ]] && return 1
  echo "hello, $1"
}

# ; && || &

Sequential, conditional, and background separators. cmd1 && cmd2 runs cmd2 only if cmd1 succeeded; || is the inverse. & backgrounds the preceding command via BUILTIN_RUN_BG — fork + setsid, parent returns Status(0) immediately. Compiled with deferred short-circuit jumps to avoid double-compilation of the next command.

git pull && cargo test || echo "test failed"
sleep 30 &
echo "going to bg"

# arr=(a b c)

Indexed-array literal assignment. Compile emits N element pushes + name push, then BUILTIN_SET_ARRAY (id 287) which writes a Vec<String> into executor.arrays and clears any prior scalar binding for the same name.

arr=(alpha beta "two words" gamma)
echo ${#arr[@]}    # 4

# arr+=(d e)

Append elements to an existing array (or create if missing). Routes through BUILTIN_APPEND_ARRAY (id 295) which extends executor.arrays[name].

arr=(a b)
arr+=(c d)
echo ${arr[@]}    # a b c d

# ${arr[N]}

Indexed access. zsh is 1-based for positive indices; negative indices count from the end (${arr[-1]} = last). Routes through BUILTIN_ARRAY_INDEX (id 289). For assoc arrays the same form does string-key lookup.

arr=(alpha beta gamma)
echo ${arr[1]}     # alpha
echo ${arr[-1]}    # gamma

# ${arr[@]}

Splice all elements as separate argv slots. Pushes a Value::Array which fusevm's Op::Exec/Op::ExecBg/Op::CallFunction and pop_args flatten into individual args. Without the splice, the array would collapse to one space-joined scalar.

arr=(--verbose --color=always /etc /var)
ls "${arr[@]}"     # ls --verbose --color=always /etc /var

# ${#arr[@]}

Number of elements. Routes through BUILTIN_ARRAY_LENGTH (id 291).

arr=(a b c d)
echo ${#arr[@]}    # 4

# for x in ${arr[@]}

Iterate over array elements. The for-loop word-list compile path calls BUILTIN_ARRAY_FLATTEN (id 293) which flattens nested arrays one level — so for x in start ${arr[@]} end produces N+2 iterations, not 3.

arr=(red green blue)
for c in ${arr[@]}; do
  echo "color: $c"
done

# arr=()

Empty-array literal. ${#arr[@]} returns 0; iteration runs zero times.

arr=()
for x in ${arr[@]}; do echo "never"; done
echo "len=${#arr[@]}"   # len=0

# typeset -A name / declare -A name

Declare an associative array. The executor's builtin_typeset handles -A and pre-creates the HashMap<String, String> entry in executor.assoc_arrays. Optional — name[key]=val creates the assoc on demand too.

typeset -A user
user[name]=Jacob
user[role]=eng
echo "${user[name]}"   # Jacob

# name[key]=value

Assoc-array key set. Compile detects name[key] shape on the LHS of an assignment and routes to BUILTIN_SET_ASSOC (id 288) which stores into executor.assoc_arrays[name][key].

db[host]=localhost
db[port]=5432
db[user]=admin
echo "${db[host]}:${db[port]}"

# ${name[key]}

Assoc-array lookup. BUILTIN_ARRAY_INDEX checks assoc_arrays first; if the name has an assoc binding the string key is used directly. Missing keys return empty string.

typeset -A m
m[a]=1; m[b]=2
echo "a=${m[a]} b=${m[b]}"
echo "missing=[${m[nope]}]"   # missing=[]

# ${(k)name}

List the keys of an associative array. Order is HashMap iteration order (implementation-defined). See the Zsh Parameter Flags chapter for the full flag set.

typeset -A m
m[apple]=1; m[banana]=2
for k in "${(k)m}"; do echo $k; done | sort

# ${(v)name}

List the values of an associative array. ${name[@]} on an assoc returns the same value list.

typeset -A m
m[apple]=1; m[banana]=2
for v in "${(v)m}"; do echo $v; done | sort

# m[k]=new overwrites

Re-assigning a key replaces the prior value. The set-builtin always inserts; use += for append-on-existing-key semantics.

m[k]=first
m[k]=second
echo "${m[k]}"   # second

# m[k]+=tail

Append onto an existing assoc value (string concat). If the key is missing, behaves like a plain set. Routes through BUILTIN_APPEND_ASSOC (id 298).

m[host]=localhost
m[host]+=":5432"
echo "${m[host]}"    # localhost:5432

# ${var:-default}

Use default if var is unset or empty. Lowers to Op::ExpandParam(DEFAULT). The default expression is itself compiled (variables, command substitution, etc. all expand at use time).

name=${1:-anonymous}
log_level=${LOG_LEVEL:-info}
target=${1:-$(date +%Y%m%d)}

# ${var:=default}

Assign default to var if unset/empty, then expand. Lowers to Op::ExpandParam(ASSIGN). The variable is set in executor.variables as a side effect.

: ${CACHE_DIR:=$HOME/.cache}
echo "$CACHE_DIR"   # CACHE_DIR is now set

# ${var:?msg}

Print error and exit if var is unset/empty. Lowers to Op::ExpandParam(ERROR). Common in script preamble for required env vars.

: ${API_TOKEN:?must be set}
: ${DEPLOY_TARGET:?usage: deploy <target>}

# ${var:+alt}

Expand to alt if var is set and non-empty, else empty. Lowers to Op::ExpandParam(ALTERNATE).

flag=${VERBOSE:+--verbose}
cargo build $flag

# ${#var}

String length of scalar (or via ${(#)arr} the element count of an array — see Zsh Flags). Lowers to Op::ExpandParam(LENGTH).

name=Jacob
echo ${#name}   # 5

# ${var:offset:length}

Substring extraction. Lowers to Op::ExpandParam(SLICE). Negative offsets count from the end. Length is optional (omitted = to end).

s=abcdefgh
echo ${s:2:3}    # cde
echo ${s:-3}     # fgh    (last 3 chars)
echo ${s:2}      # cdefgh  (offset 2 to end)

# ${var#pat} / ${var##pat}

Strip shortest / longest matching prefix. # = shortest, ## = longest. Lowers to STRIP_SHORT / STRIP_LONG.

path=/usr/local/bin/zshrs
echo ${path##*/}   # zshrs   (basename via longest-prefix-strip)
echo ${path#*/}    # usr/local/bin/zshrs

# ${var%pat} / ${var%%pat}

Strip shortest / longest matching suffix. % = shortest, %% = longest. Lowers to RSTRIP_SHORT / RSTRIP_LONG.

file=archive.tar.gz
echo ${file%.gz}    # archive.tar
echo ${file%%.*}    # archive    (dirname via longest-suffix-strip)

# ${var/pat/repl}

Replace first match of pat with repl. Lowers to SUBST_FIRST. repl may use & for the matched text in some shells; zshrs follows zsh's literal-replace semantics.

s="foo bar foo"
echo ${s/foo/baz}    # baz bar foo

# ${var//pat/repl}

Replace all matches. Lowers to SUBST_ALL. Heavily used by zpwr-style idioms (path normalization, sigil replacement).

s="hello world hello"
echo ${s//hello/HI}     # HI world HI
path="/a/b/c"
echo ${path//\//.}      # .a.b.c

# ${var:u} / ${(U)var}

Uppercase. The :u postfix lowers to Op::ExpandParam(UPPER); the (U) flag form goes through BUILTIN_PARAM_FLAG and supports stacking with other flags.

x=hello
echo ${x:u}      # HELLO
echo ${(U)x}     # HELLO

# ${var:l} / ${(L)var}

Lowercase. Same dual-form pattern as upper.

x=HELLO
echo ${x:l}      # hello
echo ${(L)x}     # hello

# $?

Exit status of the last command. Routed through BUILTIN_GET_VAR("?") which reads vm.last_status synced into the executor.

cargo test
if (( $? != 0 )); then echo "tests failed"; fi

# $$

Current shell PID (std::process::id()).

tmpdir=/tmp/build_$$
mkdir -p "$tmpdir"

# $1 $2 … $@ $* $#

Positional parameters. $@ / $* expand to the full list (joined by IFS), $# is the count, numeric $N is the Nth positional. Native fast-path: "$@" and ${arr[@]} reach BUILTIN_GET_VAR / BUILTIN_ARRAY_ALL as Value::Array and spread through BUILTIN_ARRAY_FLATTEN.

greet() {
  echo "got $# args"
  for arg in "$@"; do echo "- $arg"; done
}
greet alpha "two words" gamma

# $! $_ $-

Auxiliary special params. $! = PID of the most recent backgrounded job. $_ = last argument of the previous command (or empty at script start). $- = current shell flag set as a single string. All routed through BUILTIN_GET_VAR.

# $RANDOM $SECONDS $EPOCHSECONDS $LINENO

Dynamic special parameters resolved on each read in get_variable:

• $RANDOM — 15-bit pseudorandom int. Mixes nanos+pid via Knuth's hash, masked to 15 bits. No seedable state today (independent draws).
• $SECONDS — seconds since shell start, derived from __zshrs_start_secs baseline.
• $EPOCHSECONDS — Unix time, SystemTime::now().
• $LINENO — current line in the script (falls back to 1 today; full line tracking is Phase G work).

tmp="/tmp/build_$$_$RANDOM"
echo "elapsed: $SECONDS s"
echo "now: $EPOCHSECONDS"

# $PIPESTATUS / $pipestatus

Per-stage exit codes of the most recent pipeline. BUILTIN_RUN_PIPELINE collects each stage's status and writes both pipestatus (zsh convention) and PIPESTATUS (bash convention). Useful for set -e-style scripts that need to differentiate which stage failed.

seq 100 | grep '^5' | wc -l
echo "${pipestatus[@]}"   # 0 0 0
false | true
echo "${pipestatus[1]}"   # 1   (zsh: 1-indexed)

# [[ -v var ]] — existence test

BUILTIN_VAR_EXISTS (id 306) checks every binding table — scalar variables, arrays, assoc_arrays, plus the process env — and returns true if any matches. Useful for "set but empty" vs "unset" disambiguation that -z conflates.

x=""
[[ -v x ]] && echo "set"        # set (even though empty)
[[ -z $x ]] && echo "empty"      # empty
unset x
[[ -v x ]] || echo "unset"        # unset

# $((expr))

Arithmetic substitution. The expression compiles through the inline arithmetic compiler — no runtime parser invocation. Integers are i64; supports + - * / % ** & | ^ << >> && || and pre/post inc/dec.

(( total = 1 + 2 * 3 ))
echo $((2 ** 16))    # 65536
echo $((0xff & 0x0f))

# $(cmd) / ` cmd `

Command substitution. zshrs runs the inner command on a nested VM and captures stdout via os_pipe::pipe() + dup2 — no fork. Trailing newlines are stripped per POSIX.

now=$(date +%s)
files=$(ls *.rs | wc -l)
echo "$files files at $now"

# (L) — lowercase

Lowercases the value. For arrays, lowercases each element.

x=Hello
echo ${(L)x}   # hello

arr=(One Two Three)
echo ${(L)arr}   # one two three

# (U) — uppercase

Uppercases.

echo ${(U)x}   # HELLO

# (j:sep:) — join

Join array elements with sep. The delimiter char following j sets the bracket — :, ., ,, | are common. j with no delimiter joins with a single space (IFS-default).

arr=(one two three)
echo ${(j:-:)arr}   # one-two-three
echo ${(j:|:)arr}   # one|two|three
echo ${(j)arr}      # one two three

# (s:sep:) — split

Split a scalar on sep into an array. The result splices into argv via the standard array-flatten path.

csv="alpha,beta,gamma"
for x in "${(s:,:)csv}"; do
  echo "[$x]"
done

# (f) — split on newlines

Shorthand for (s:\n:) — split on newlines. Common with command substitution.

for line in "${(f)$(ls)}"; do
  echo "FILE: $line"
done

# (o) — sort ascending

Lexicographic sort.

arr=(charlie alpha bravo)
echo ${(o)arr}   # alpha bravo charlie

# (O) — sort descending

Reverse lexicographic sort.

echo ${(O)arr}   # charlie bravo alpha

# (P) — indirect

Use the value of the variable as another variable name and look that up. Useful for dynamic dispatch tables.

real=42
ref=real
echo ${(P)ref}    # 42

# (@) — force array

Coerce a scalar to a single-element array (so subsequent flags treat it as array-shape).

x=hello
echo ${#x}        # 5  (string length)
echo ${(#)${(@)x}}  # 1  (array length after @-coerce)

# (k) — keys of assoc

Returns the keys of an associative array as an array. Order is HashMap iteration order.

typeset -A m
m[apple]=1; m[banana]=2
for k in "${(k)m}"; do echo "$k"; done

# (v) — values of assoc

Returns the values of an associative array as an array.

echo ${(v)m}    # 1 2

# (#) — count

Element count for arrays, character count for scalars. Different from ${#var} in that it can be combined with other flags via stacking.

arr=(a b c d)
echo ${(#)arr}    # 4

echo ${(#L)x}     # length after lowercasing

# (q) / (qq) / (qqq) — quote

Wrap each value with shell-safe quoting. Consecutive qs raise the quoting level: q = POSIX single-quote (escaping inner '), qq = double-quote (escaping $/`/"/\), qqq = ANSI-C $'…' form (escaping control chars + backslashes).

x="hi 'world'"
echo ${(q)x}     # 'hi '\''world'\'''
echo ${(qq)x}    # "hi 'world'"
s=$(printf 'a\tb')
echo ${(qqq)s}   # $'a\tb'

# (g) — backslash-escape unwrap

Process backslash escapes (\n, \t, \r, \\, \xNN). Useful when reading lines from a config that stored real newlines as literal \n.

s='hello\nworld'
echo "${(g)s}"
# hello
# world

# (n) — natural-numeric sort

Compare digit runs as integers and other runs lexicographically. file2 sorts before file10 (vs lex order which would put file10 first). Combine with (o)/(O) for ascending/descending.

arr=(file10 file2 file1 file20)
echo ${(on)arr}    # file1 file2 file10 file20

# (i) — case-insensitive sort

Sort comparing lowercase forms while preserving original case in the output.

arr=(Banana apple Cherry)
echo ${(i)arr}    # apple Banana Cherry

# (t) — type query

Returns the variable's typeset shape: scalar, array, association, or empty (unset). Useful in scripts that branch on whether a name is an indexed vs assoc array.

arr=(a b)
typeset -A m; m[k]=v
sc=str
echo "${(t)arr}|${(t)m}|${(t)sc}"
# array|association|scalar

# (%) — prompt expansion

Process %F/%B/%f/%{/%} etc. via expand_prompt_string. Useful for storing prompt fragments in variables and rendering them at use time.

fragment='%F{cyan}>>%f '
echo "${(%)fragment}"

# (e) — re-evaluate

Run the value as a shell command and return its captured stdout. Equivalent to $(eval "$value") but uses the in-process pipe-capture path (no fork). Late-bound config strings.

cmd='echo "user is $(whoami)"'
echo "${(e)cmd}"   # user is jacob

# (p) — print-style escapes

Process backslash escapes the same way print -e does. Same set as (g) with \e / \E mapped to ESC.

fmt='\e[36mcolor\e[0m'
echo "${(p)fmt}"   # cyan "color"

# cmd > file — write

Truncates and writes stdout to file. Bracketed in a redirect scope so subsequent commands see the original fd 1.

echo hello > out.txt

# cmd >> file — append

Appends stdout. Creates the file if missing.

date >> access.log

# cmd < file — read

Connects file to stdin.

sort < data.txt

# cmd 2> file — stderr

Redirect stderr (fd 2). Use 2>&1 to merge into stdout.

cargo build 2> build.err
make 2>&1 | tee build.log

# cmd &> file — write both

Redirect both stdout and stderr (zsh/bash extension). &>> appends.

./run.sh &> combined.log

# cmd <<EOF — heredoc (with variants)

Multi-line stdin literal. Three flavors:

• <<EOF — variables, command sub, arithmetic all expand inside the body. Body trailing newline trimmed before HereString emit so stdin is byte-identical to source.
• <<-EOF — leading tabs stripped from each body line and from the closing-terminator-line check. Lets you indent the heredoc body inside a function body.
• <<'EOF' / <<"EOF" — quoted terminator → body is verbatim, no expansion. Detected by SNULL/DNULL markers in the lexer's terminator string; HereDocInfo.quoted drives compile-side behavior.

Body capture happens in a parser post-pass (fill_heredoc_bodies) — the lexer collects bodies into self.heredocs[] at process_heredocs (called on Newlin/Endinput); the parser records a heredoc_idx per redir during parse_redirection; the post-pass walks the AST resolving indices into ZshRedir.heredoc.

cat <<EOF
hello $USER
host: $(hostname)
EOF

cat <<-EOF
	indented
	body
	EOF

cat <<'EOF'
$USER stays literal
EOF

# cmd <<< "string" — herestring

Pass a single string (with trailing newline) as stdin.

tr a-z A-Z <<< "hello"   # HELLO

# cmd1 | cmd2 — pipeline

Connect cmd1's stdout to cmd2's stdin via a pipe. zshrs's pipeline is bytecode-native: each stage compiles to a sub-chunk; BUILTIN_RUN_PIPELINE creates N-1 pipes, forks N children, wires fds, runs each stage's bytecode on a fresh VM. SIGPIPE works correctly.

seq 100 | sort | uniq | wc -l

# cmd1 |& cmd2 — pipe stdout+stderr

zsh extension: pipes both fd 1 and fd 2 of the LHS to RHS.

cargo test |& head -40

# ! cmd — invert status

Negate the pipeline's exit status. ! cmd exits 0 if cmd failed, 1 if cmd succeeded.

! grep -q ERROR log   # status 0 means no ERROR found

# <(cmd) — process sub (input)

Spawn cmd, present its stdout as a path readable by the consumer. zshrs uses worker pool threads instead of fork — the FIFO/temp file is wired to a thread that runs the bytecode for cmd.

diff <(sort a.txt) <(sort b.txt)

# >(cmd) — process sub (output)

Spawn cmd, present its stdin as a path writable by the producer.

tar c . | tee >(gzip > backup.tgz) > backup.tar

# cmd N>&M — duplicate fd

Duplicate fd M to fd N. Common idiom: 2>&1 merges stderr into stdout. <&fd defaults the destination to fd 0; >&fd defaults to fd 1. Variable-expanded fd targets work: read line <&${COPROC[1]}.

find / 2>&1 | grep '\.zsh$' | head

coproc { echo from-child; }
read reply <&${COPROC[1]}
echo "$reply"   # from-child

# cmd N<&- / cmd N>&- — close fd

Close fd N. POSIX form for explicitly tearing down a previously-opened fd (typically after exec FD< file).

exec 5< data.txt
read line <&5
exec 5<&-     # close fd 5

# { cmds; } > file — block redirect

Apply a redirect to a compound command. WithRedirectsBegin/End bracket the inner ops so the parent shell's fds are restored after.

{
  echo header
  date
  uname -a
} > report.txt

# cd [dir]

Change directory. With no argument, goes to $HOME. cd - jumps to $OLDPWD. Updates $PWD.

cd ~/repos/zshrs
cd -      # back to previous

# pwd

Print working directory.

echo "now in $(pwd)"

# echo [args]

Print arguments space-separated with trailing newline. -n suppresses newline; -e enables backslash escapes.

echo hello world
echo -n "no newline"
echo -e "tab:\there"

# print

zsh's enhanced echo. -r raw, -n no newline, -l one arg per line, -z push to history.

print -l alpha beta gamma   # one per line
print -P "%F{cyan}cyan%f"   # prompt expansion

# printf format args…

C-style formatted output. Format directives: %s %d %f %x %o %b; backslash escapes \n \t etc.

printf "%-10s %5d\n" "items" 42

# export VAR=value

Mark a variable for export to subprocesses (writes to std::env).

export PATH="/opt/bin:$PATH"
export RUST_LOG=debug

# unset VAR…

Remove a variable. Removes from variables, arrays, assoc_arrays, and exported env.

unset DEBUG_FLAG
unset -f myfunc   # remove function

# source file / . file

Execute a script in the current shell. zshrs's source path uses bytecode caching: first run compiles + stores to SQLite; subsequent runs deserialize cached chunks. Plugin delta cache replays state changes (functions, aliases, vars, hooks, zstyles, options) in microseconds.

source ~/.zshrc
. /etc/profile.d/lang.sh

# exit [n]

Exit the shell with status n (default last status). Aliases: bye, logout. Compile emits a forward jump patched past chunk-end (halts the VM). EXIT trap fires before halt.

[[ -z $1 ]] && { echo "missing arg"; exit 2; }

# true / false / :

Status helpers. true and : exit 0; false exits 1. : is also the no-op for argument expansion side effects.

: ${VAR:=default}   # set if unset; expansion side effect, no command
while true; do …; done

# test EXPR / [ EXPR ]

POSIX conditional test. Use [[ … ]] for the zsh extended form (in-shell, no fork). Operators: -f -d -e -r -w -x -s -z -n = != < > -eq -ne -lt -le -gt -ge.

[ -f /etc/passwd ] && echo "exists"
[[ $count -gt 10 && -n $name ]]

# local VAR[=value]

Function-local scope. zshrs's local-scope semantics: declared vars are pushed onto a scope stack at function entry, popped at return. Assignment-without-declare-at-top-of-function is allowed (zsh idiom) but has caveats — see CLAUDE.md "Never use `local` inside loops".

my_func() {
  local count=0
  local result
  …
}

# typeset / declare

Declare a variable with attributes. -a indexed array, -A assoc array, -i integer, -r readonly, -x exported, -l lowercase, -u uppercase, -g global (in func scope), -f function-scoped.

typeset -i count=0
typeset -A config
typeset -r APP_VERSION=1.0
declare -a names=(alice bob carol)

# readonly VAR=val

Mark a variable read-only. Subsequent assignments error.

readonly RELEASE_BRANCH=main

# integer VAR=expr

Declare an integer-typed variable. Subsequent assignments evaluate as arithmetic.

integer i=10
i=i+5
echo $i    # 15

# float VAR=expr

Declare a float-typed variable.

float pi=3.14159
echo $((pi * 2))

# read VAR…

Read a line from stdin into one or more variables. Flags: -r raw (no backslash escapes), -n N N chars, -t SEC timeout, -s silent, -p prompt, -A arr read into array.

echo -n "name? "
read name
read -r line < /etc/hostname
read -A words <<< "alpha beta gamma"

# mapfile / readarray

Read each line of a file (or stdin) into successive elements of an array. Bash compat alias.

mapfile -t lines < /etc/hosts
echo "${#lines[@]} hosts"

# shift [n]

Remove the first n positional parameters (default 1).

process() {
  cmd=$1; shift
  do_thing "$cmd" "$@"
}

# eval string

Re-parse and execute the joined-args string as shell code. Single-quoted args defer expansion correctly (the lexer's \0-sentinel for single-quoted specials is honored by the compile path's trigger detection).

x=10
eval 'echo $x'    # 10  (expansion deferred to eval-time)
eval "$(starship init zsh)"

# exec [cmd args]

Replace the current shell with cmd. With no command, applies redirections to the current shell (e.g. exec > log redirects subsequent output).

exec > build.log 2>&1
exec /usr/local/bin/newshell

# command [-pvV] cmd

Bypass functions/aliases and run the underlying command. -v prints how the name would resolve; -V verbose form.

command rm /tmp/junk    # bypass user's `rm` function
command -v cargo        # /Users/wizard/.cargo/bin/cargo

# builtin cmd

Force builtin dispatch (skip functions/aliases).

builtin cd /tmp     # zshrs's cd, never a user override

# let "expr"

Evaluate arithmetic expression(s); exit 0 if last result is non-zero.

let "i = 1 + 2"
let "i++"

# set [-eux] [args…]

Set shell options or positional parameters. -e exit on error, -u nounset, -x trace, -o pipefail propagate pipeline status.

set -euo pipefail
set -- alpha beta gamma   # set $1 $2 $3

# setopt / unsetopt

Toggle zsh-style options. Options live in executor.options; setopt foo turns on, unsetopt foo turns off.

setopt extended_glob
setopt null_glob
unsetopt nomatch

# shopt

Bash-compat option toggling. Maps onto the same options table as setopt.

shopt -s globstar

# emulate [-LR] [shell]

Switch emulation mode (zsh, sh, ksh, csh). -L local-to-function, -R reset all options to that shell's defaults.

emulate -L zsh    # function-local zsh defaults

# getopts spec var

POSIX option parsing. Iterates flags from $@, sets $var to each option, $OPTARG to its value.

while getopts "vh:" opt; do
  case $opt in
    v) verbose=1 ;;
    h) host=$OPTARG ;;
  esac
done

# zparseopts

zsh's richer option parser. -A arr stores into an assoc array; supports long options.

zparseopts -A opts -- v h: c::
echo "${opts[-h]}"

# autoload [name…]

Mark a function for lazy loading from $fpath. zshrs's autoload path uses SQLite-cached bytecodes: first invocation deserializes a chunk; subsequent invocations skip lex/parse/compile entirely.

autoload -Uz compinit
compinit

# functions [name]

List defined functions, or print a function's body. +f prints names only.

functions               # all functions
functions my_func       # body of my_func

# unfunction name

Remove a function definition. Same as unset -f.

unfunction old_helper

# trap 'cmd' SIG

Install a signal handler. Special pseudo-signals: EXIT (run at shell exit), DEBUG (before each command), ERR (on non-zero status), ZERR (zsh-specific).

trap 'rm -rf $tmpdir' EXIT
trap 'echo got SIGINT' INT

# pushd / popd / dirs

Directory stack manipulation. pushd dir changes to dir and pushes onto the stack; popd pops and changes back. dirs -v lists.

pushd ~/work/proj
…
popd

# alias name='cmd'

Define a command alias. With no args lists all aliases. alias -g creates a global alias (substitutes anywhere on the command line).

alias ll='ls -lAh'
alias -g G='| grep'

# unalias [-m pattern] name

Remove an alias. -m matches by glob pattern.

unalias ll
unalias -m 'g*'   # remove all aliases starting with g

# type / whence / where / which

Resolve a name to its source: alias, function, builtin, or external. whence -p shows path only; whence -a shows all matches.

type ls
whence -a cargo
which gcc

# hash / rehash / unhash

Command-name → path cache. rehash rebuilds the cache from $PATH (parallel scan across worker pool). unhash -dm 'pat' removes named-directory entries by glob.

rehash             # after installing new binaries
hash               # show cache
unhash -dm 'tmp*'  # remove tmp* hashed dir refs

# ulimit / limit / unlimit

Resource limit query/set. -n open files, -s stack size, -u max processes, -c core dump.

ulimit -n 65536
ulimit -a    # show all

# umask [mask]

Set/show file-creation mask.

umask 077    # owner-only by default

# times

Print user + system times for the shell and its children.

times

# caller

Print the line + filename of the caller of the current function. Useful in error reporters and debuggers.

my_assert() {
  [[ $1 -eq $2 ]] || { echo "assertion failed at $(caller)"; exit 1; }
}

# help [name]

Print help for a builtin (or list builtins).

help echo
help

# enable / disable

Enable/disable a builtin by name. Useful for testing external-vs-builtin behavior.

disable cat       # falls back to /bin/cat
enable cat        # restore zshrs's cat builtin

# noglob cmd

Run cmd with glob expansion disabled for its arguments. Equivalent to setopt noglob; cmd; unsetopt noglob as a one-liner.

noglob find . -name '*.rs'   # don't pre-glob *.rs

# ttyctl -f / ttyctl -u

Freeze / unfreeze the tty state. Used by completion code that reads stdin.

ttyctl -f       # freeze
ttyctl -u       # unfreeze

# sync

Force the OS to flush its buffer cache to disk. Direct sync(2) syscall.

cp big.iso /mnt/usb/
sync

# zmodload [-i] mod

Load a zsh module. zshrs's modules are statically linked, so zmodload is a no-op-and-succeed for compat (-i idempotent flag).

zmodload zsh/datetime
zmodload zsh/regex

# zsleep n

Subsecond-precision sleep. zsleep 0.5 sleeps 500ms. Different from coreutils sleep only in supporting fractional seconds reliably across implementations.

zsleep 0.25       # 250ms

# zsystem subcmd

zsh/system module operations. zsystem flock file for file locking; zsystem getflags for flag dumps.

zsystem flock /tmp/lockfile

# strftime fmt [time]

Format a unix timestamp using strftime(3) directives. Default time is now.

strftime "%Y-%m-%d %H:%M:%S"

# mkdir [-p] dirs…

Create directories. -p creates parents and doesn't fail if exists.

mkdir -p ~/.config/myapp/{cache,logs}

# vared VAR

Edit a variable's value via the line editor. Handy for interactive config edits.

vared PATH

# zformat -f var fmt args…

Sprintf with %X:value argument bindings; common in completion display formatting.

zformat -f line "%name (%size)" name:foo size:42

# zregexparse

State-machine regex parser used by completion and filename rewriting.

zregexparse vname tname regex

# zcompile file

Pre-compile a zsh script to .zwc. zshrs treats .zwc as one of its bytecode-cache inputs and deserializes the chunk directly when sourcing the original file.

zcompile ~/.zshrc

# cmd & — background

Run cmd in the background. The compile path detects ListOp::Amp, compiles cmd into a sub-chunk, emits CallBuiltin(BUILTIN_RUN_BG, 1). The handler forks; child setsids and runs the chunk on a fresh VM; parent returns Status(0) immediately.

sleep 30 &
make all & make docs & wait

# jobs

List background jobs known to the shell. Note: pids spawned via BUILTIN_RUN_BG aren't yet registered in the JobTable (Phase G6); externally-launched bg cmds via std::process::Command::spawn() are.

jobs                # active jobs
jobs -l             # with pids

# fg [%jobspec]

Bring a background/stopped job to the foreground. %1, %2 select by job number; %name by command-name prefix.

fg %1
fg %vim

# bg [%jobspec]

Resume a stopped job in the background.

bg %1

# kill [-SIG] pid|%job

Send a signal. Default is SIGTERM. Builtin form supports both PID and jobspec.

kill -INT 12345
kill %1
kill -l            # list signals

# wait [pid|%job]

Wait for a child to exit; with no args, waits for all bg children. Status is the wait-on'd child's exit code.

worker1.sh & pid1=$!
worker2.sh & pid2=$!
wait $pid1 $pid2

# disown [%job]

Remove a job from the job table without killing it. The process keeps running but is no longer tracked.

long_task &
disown %1

# suspend

Stop the current shell (sends SIGTSTP to itself). Common idiom in nested shells.

suspend

# async 'cmd'

Ship work to the worker pool and return an opaque ID. Unlike &, this runs on a thread within the same process — no fork, no setsid.

id=$(async 'sleep 5; curl https://api.example.com')

# await ID

Wait for an async task by ID and capture its stdout.

id=$(async 'expensive-job')
result=$(await $id)

# $! — last bg pid

PID of the most-recently-backgrounded command. Used to wait/signal it later.

long_task &
echo "spawned $!"
wait $!

# cat [files…]

Concatenate files to stdout. With no args, copies stdin. -n numbers lines; -A shows non-printable. No fork.

cat /etc/hosts
cat *.log | grep ERROR

# head [-n N] [files…]

First N lines (default 10). -c N first N bytes.

head -20 /var/log/system.log

# tail [-n N] [-f] [files…]

Last N lines. -f follow (in-process).

tail -f access.log

# wc [-lwc] [files…]

Line / word / char count.

wc -l *.rs        # total Rust LOC

# sort [-n -r -u -k] [files…]

Sort lines. -n numeric, -r reverse, -u unique, -k N sort on key.

du -h * | sort -hr

# find path [predicates]

Walk directories applying predicates. -name, -type, -size, -mtime, -exec. In-process walk.

find . -name '*.rs' -size +1k

# uniq [-c -d -u] [files…]

Filter adjacent duplicates. -c prefix counts, -d show duplicates only.

cat history.log | sort | uniq -c | sort -nr

# cut [-d delim] -f fields

Extract fields from each line.

cut -d: -f1 /etc/passwd     # all usernames

# tr SET1 SET2

Translate or delete characters.

echo HELLO | tr A-Z a-z
tr -d '\r' < crlf.txt > lf.txt

# seq [start] [step] end

Print a sequence of numbers.

for i in $(seq 1 10); do …; done
seq 0 0.5 5

# rev

Reverse each line character-wise.

echo hello | rev   # olleh

# tee [-a] file…

Copy stdin to stdout AND to one or more files. -a appends.

build.sh 2>&1 | tee build.log

# basename path [suffix]

Strip directory and optionally a trailing suffix.

basename /tmp/file.txt    # file.txt
basename /tmp/file.txt .txt   # file

# dirname path

Strip the trailing component.

dirname /tmp/file.txt    # /tmp

# touch [-a -m -t time] file…

Update file timestamps; create empty file if missing.

touch deploy.lock

# realpath path

Resolve symlinks and relative paths to a canonical absolute path.

realpath ./src/exec.rs

# sleep seconds

Pause for seconds (fractional supported).

sleep 0.5

# whoami

Effective username (direct geteuid + getpwuid syscalls).

echo "running as $(whoami)"

# id [-u -g -n] [user]

User/group ID info.

id -u           # numeric uid
id -un          # username

# hostname [-s -f]

System hostname. Direct syscall.

hostname            # short
hostname -f         # FQDN

# uname [-a -s -r -m]

Kernel name / release / arch. Direct uname(3).

uname -srm

# date [+fmt]

Print current date/time. +fmt uses strftime directives. Direct syscall.

date
date +%s
date "+%Y-%m-%d %H:%M:%S"

# mktemp [-d] [template]

Atomic temp file/dir creation.

tmp=$(mktemp)
tmpdir=$(mktemp -d)

# pmap 'cmd {}' args…

Parallel map across worker pool. Output preserves input order. The {} placeholder gets each arg.

pmap 'gzip {}' *.log
pmap 'sha256sum {}' **/*.iso

# pgrep 'pred {}' args…

Parallel filter. Predicate runs concurrently; matching args are collected in input order.

pgrep 'grep -q TODO {}' **/*.rs    # files containing TODO

# peach 'cmd {}' args…

Parallel for-each, unordered. Fire each task and don't preserve order — useful when output order doesn't matter.

peach 'convert {} {}.png' *.svg

# barrier 'cmd1' ::: 'cmd2' ::: 'cmd3'

Run all commands in parallel; wait for all to complete. Final status is the worst (highest) of all child statuses.

barrier 'cargo test' ::: 'cargo doc' ::: 'cargo audit'

# barrier --fail-fast …

Cancel remaining tasks as soon as one fails. Useful for guarded fan-out (compile, test, lint) where one failure makes the rest moot.

barrier --fail-fast 'rustfmt --check src/' ::: 'cargo clippy'

# intercept before pat { code }

Run code before any command matching pat. $INTERCEPT_NAME, $INTERCEPT_ARGS, $INTERCEPT_CMD are bound. Pattern is glob: git, git*, _*.

intercept before git { echo "[$(date)] $INTERCEPT_CMD" >> ~/git.log }

# intercept after pat { code }

Run after the matched command finishes. Adds $INTERCEPT_MS (elapsed) and $INTERCEPT_STATUS.

intercept after '_*' {
  echo "$INTERCEPT_NAME took ${INTERCEPT_MS}ms"
}

# intercept around pat { code } + intercept_proceed

Wrap the command. Call intercept_proceed from inside to invoke the original; skip it to suppress the original entirely. Replaces defer, profile, memo, retry, timeout with one primitive.

intercept around expensive_func {
  local cache=/tmp/cache_${INTERCEPT_ARGS// /_}
  if [[ -f $cache ]]; then
    cat $cache
  else
    intercept_proceed | tee $cache
  fi
}

# doctor

Full diagnostic dump: worker-pool metrics, SQLite cache stats, bytecode coverage, registered intercepts, history db size, options table.

doctor

# dbview [table] [filter]

Browse SQLite caches without writing SQL. Lists tables + row counts; with arguments shows specific entries.

dbview                        # tables + row counts
dbview autoloads _git         # one autoload entry
dbview comps git              # completion search
dbview history docker         # history search

# profile cmd

In-process profiling with nanosecond accuracy. No fork, no strace. Reports CPU time, syscalls, allocations.

profile cargo build

# zprof

Function-level profile (zsh module compat). Enable with zmodload zsh/zprof; print accumulated stats with zprof.

zmodload zsh/zprof
source ~/.zshrc
zprof | head -20

# history [-n N] [pattern]

Browse command history. Backed by SQLite + FTS5 — full-text search, frequency-ranked, with timestamps and exit status per command.

history -10                   # last 10
history docker                # FTS search

# compinit

Initialize the completion system. zshrs's compinit is async: fpath is scanned + bytecode-compiled in the background while the prompt drops.

autoload -Uz compinit && compinit

# compdef func cmd

Bind a completion function to a command name.

compdef _docker docker
compdef _kubectl kubectl k

# compadd [-J group] words…

Add candidate completions. -J groups them; -d desc attaches descriptions.

compadd -J commands start stop status restart

# compset

Manipulate the completion state — peel off prefixes, set the position, etc.

compset -P 'http://'
compset -S '*.com'

# compopt

Toggle completion options for the current invocation.

compopt -o nospace

# compgen [opts] word

Bash-compat completion candidate generator.

compgen -c git           # all commands starting with "git"

# complete

Bash-compat completion definition.

complete -W "start stop status" myservice

# zstyle

Style configuration for completion + prompt. zsh's universal config DSL.

zstyle ':completion:*' menu select
zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'

# cdreplay

Replay deferred compdef calls accumulated during async compinit.

compinit; cdreplay -q

# promptinit + prompt

Theme system for prompts.

autoload -Uz promptinit && promptinit
prompt redhat

# zle widget [-N name handler]

Manipulate the line editor. -N name handler defines a user widget; zle name invokes one.

my-widget() { LBUFFER+=" --verbose"; }
zle -N my-widget
bindkey '^Xv' my-widget

# bindkey [seq widget]

Bind a key sequence to a widget. -M map targets a specific keymap.

bindkey '^R' history-incremental-search-backward
bindkey -M vicmd 'k' up-line-or-beginning-search

# vared VAR (line-edit form)

Use ZLE to edit a variable's value interactively.

vared LS_COLORS

# Abbreviations

Fish-style abbreviations: type the abbrev + space, the full command expands inline. Configured via the fish/abbrs.rs backend.

abbr gco='git checkout'
abbr -g G='| grep'

# pcre_compile pattern

Compile a PCRE pattern; bound to $ZPCRE_OP.

pcre_compile '^(\d+)\s+(\w+)$'

# pcre_match string

Match against the most-recently compiled pattern. Captures land in $match, $mbegin, $mend.

pcre_compile '(\w+)@(\w+\.\w+)'
if pcre_match "alice@example.com"; then
  echo "user: ${match[1]}, domain: ${match[2]}"
fi

# pcre_study

Optimize the compiled pattern for repeated use.

pcre_compile '\b\d{4}-\d{2}-\d{2}\b'
pcre_study

# [[ string =~ pattern ]]

POSIX/PCRE regex match inside the conditional. Routed through Op::RegexMatch (host method regex_match).

if [[ $version =~ ^([0-9]+)\.([0-9]+)\.([0-9]+) ]]; then
  major=${match[1]}; minor=${match[2]}; patch=${match[3]}
fi

# extendedglob ~ exclusion at PATH level

Direct port of pattern.c P_EXCLUDE: matches RHS as a pattern against each LHS candidate's basename + full path, not as a separate CWD glob.

setopt extendedglob
echo /tmp/dir/*.txt~*README*   # all .txt except README.txt

# /^pat at any path component

Negation operator now triggers in any path component, not just the leading word.

setopt extendedglob
echo /tmp/dir/^skipme   # everything in /tmp/dir except files matching skipme

# $D/*, $D/(a|b) — glob meta after var ref

New BUILTIN_GLOB_EXPAND (id 343): pops a scalar pattern, runs expand_glob, pushes Value::Array. Compile path detects glob meta in literal segments only (so $?/$#/etc don't trigger).

D=/tmp/build
echo $D/*       # globs after $D substitution
echo $D/(a|b)   # alternation after $D substitution

# **/* recursive sort by full path

Recursive globs sort by full-path lex order (zsh's depth-first walk). Non-recursive globs keep basename-sorted output.

echo /tmp/dir/**/*  # f, sub, sub/g — not f, g, sub

# ${${a%.txt}#hel} — outer strip on inner result

Direct port of subst.c getarg machinery — same dispatch for inner and outer.

a=hello.txt
echo "${${a%.txt}#hel}"   # lo

# ${(s. .)${(j. .)a}} — outer flag on inner expansion

Flag handler now recurses on leading ${ in rest; applies U/L/C/Split/Join/SplitWords/SplitLines to inner result.

a=(a b c)
echo "${(s. .)${(j. .)a}}"   # a b c (split-then-rejoin)

# ${(flags)$(...)} — cmd-subst as flag operand

Branch added for cmd-subst operands. (P) indirect honored: captured output is treated as a variable name and looked up.

a=hi; echo "${(P)$(echo a)}"   # hi  (NOT "a")
echo "${(U)$(echo hello)}"     # HELLO
echo "${(z)$(echo a b c)}"     # a b c

# ${(U)${(s. .)s}[N]} — [N] subscript after inner expansion

Splits the flag-applied joined-scalar back to parts, indexes, re-applies case-transform flags.

s="x y z"
echo "${(U)${(s. .)s}[1]}"   # X

# ${(l:N::s2:)val} — pad with empty s1 + s2 fallback

Pad parser collects both strings; when s1 empty and s2 given, s2 acts as fill char.

echo "${(l:5::0:)42}"   # 00000  (zsh-faithful)

# ${(j[+])a}, ${(s[|])s} — bracket-pair flag delimiters

zsh subst.c get_strarg accepts matched bracket pairs as flag delimiters: [/], {/}, (/), </>. Both flag-parser sites updated.

a=(a b c)
echo "${(j[+])a}"      # a+b+c
echo "${(j<X>)a}"      # aXbXc
echo "${(s[|])\"x|y|z\"}" # x y z

# :Q modifier — backslash escape removal

hist.c remquote: strips paired '/" AND \X backslash escapes. Both :Q paths fixed.

a="a\\ b"
echo ${a:Q}   # a b

# ${a//\X/repl} — backslash unescape for non-meta chars

Pattern pre-pass strips \X when X is not a glob meta. \?/\*/\[/\]/\(/\)/\|/\\ still escape.

a="x:y:z"
echo "${a//\:/-}"     # x-y-z
echo "${a//\./X}"     # works on dots too

# "${(o)a[@]}", "${(O)a[@]}", "${(n)a[@]}" — sort flags survive DQ when [@] given

Compile path encodes the at-subscript context through a new \u{03} sentinel in the flags string so the runtime DQ-stripper preserves array-only flags.

a=(c a b)
echo "${(o)a[@]}"      # a b c
echo "${(O)a[@]}"      # c b a
a=(10 2 1 22)
echo "${(n)a[@]}"      # 1 2 10 22

# ${SECONDS-default} — zsh-special params always-set

Whitelist treats SECONDS, EPOCHSECONDS, EPOCHREALTIME, RANDOM, LINENO, HISTCMD, PPID, UID, EUID, GID, EGID, SHLVL as set even when not in self.variables. HISTCMD getter also added.

echo "${SECONDS-default}"   # 0  (or current value)
echo "${UID-default}"       # 501
echo "${HISTCMD-default}"   # 0

# Associative-array key insertion order

Storage switched from HashMap to indexmap::IndexMap so ${(k)h} / ${(kv)h} iterate in insertion order matching zsh's HashTable hnodes.

typeset -A h
h=(a 1 b 2 c 3)
echo ${(k)h}       # a b c
echo ${(kv)h}      # a 1 b 2 c 3

# for k v in arr — multi-name for loop

Direct port of parse.c par_for: parser collects all leading identifiers; compiler emits N-stride iteration with empty-string fill on short tail.

arr=(a 1 b 2 c 3)
for k v in $arr; do echo "$k=$v"; done

typeset -A h=(a 1 b 2)
for k v in ${(kv)h}; do echo "$k=$v"; done

# b=("${a[@]}") — array-to-array splice preserves boundaries

New scalar_assign_depth separate from assign_context_depth — only scalar RHS forces JOIN_STAR. Array init keeps splice.

a=("1 2" "3 4")
b=("${a[@]}")
echo ${#b}   # 2  (preserves both elements)

# $a[@], $a[*] — bare (no-braces) splice

array_splice_ref extended to accept the no-braces form, identical semantics to ${a[@]}.

a=(x y z)
printf "%s\n" $a[@]    # x, y, z (3 lines)
f() { echo $#; }; f $a[@]   # 3

# b="${a[@]}" — scalar assignment joins via JOIN_STAR

Compile path forces BUILTIN_ARRAY_JOIN_STAR when scalar_assign_depth > 0 (zsh subst.c forces single-string for scalar RHS).

a=(1 2 3)
b="${a[@]}"
echo $b   # 1 2 3

# a[$n]=() — variable subscript element-remove

Compile path now routes the subscript through compile_word_str when key has $ or backtick.

a=(1 2 3 4)
n=3
a[$n]=()       # remove 3rd element
echo "${a[@]}" # 1 2 4
a=(1 2 3 4)
a[$#a]=()      # remove last
echo "${a[@]}" # 1 2 3

# ${h[(I)pat]}, ${h[(R)pat]} on assoc — return ALL matches

(I)/(R) return all matching keys/values space-joined; (i)/(r) return first. (i)/(I) search keys; (r)/(R) search values.

typeset -A h=(a 1 b 2)
echo "${h[(I)*]}"      # a b
echo "${h[(i)*]}"      # a
echo "${h[(I)a]}"      # a (single match)
typeset -A h=(a 1 b 1 c 2)
echo "${h[(R)1]}"      # 1 1

# typeset -a a preserves existing array at top scope

Bare-declaration path now guards with in_function || !exists. typeset -aU dedupes in place.

a=(1 2 3); typeset -a a; echo $a       # 1 2 3 (was empty)
a=(a b a c b); typeset -aU a; echo $a  # a b c (was empty)

# ((i=a[2])) — RHS array subscript pre-resolve

[ added to needs_eval trigger so MathEval (which runs pre_resolve_array_subscripts) handles it.

a=(10 20 30)
((i=a[2])); echo $i              # 20
((sum=a[1]+a[2]+a[3])); echo $sum # 60

# ((h[a]++)), ((h[a]+=v)) — compound ops on assoc

Direct port of zsh's math.c LVAL_NUM_SUBSC: subscript receiver retains lvalue identity through compound operators.

typeset -A h
h[a]=5
((h[a]++))      # h[a] = 6
((h[a]+=10))    # h[a] = 16

# ((++a[i])), ((++h[k])) — pre-increment on subscript

New parse_subscript_arith_pre_inc + compile-side subscripted_arith_compound_check accepts the pre-op shape. Pre-op returns NEW value, post-op OLD.

a=(10 20 30)
((++a[2])); echo $a   # 10 21 30
typeset -A h
h[a]=5
((++h[a])); echo $h[a] # 6

# ((a = cond ? T : F)) — ternary in assignment

? added to needs_eval triggers so MathEval handles ternary fully. ArithCompiler can't write back through ?:.

((a = 5 > 3 ? 99 : 0)); echo $a   # 99

# abs/min/max/int/floor/ceil/trunc — int-preserving

Int-input return int (not 5.). Float input still returns float.

echo $((abs(-5)))      # 5  (was 5.)
echo $((max(3,5,7)))   # 7
echo $((abs(-5.5)))    # 5.5  (still float)

# [[ a == a && (b == b || c == c) ]] — cond grouping parens

Lexer's incondpat resets on &&, ||, (, ), !, ]] per cond.c par_cond_3.

[[ a == a && (b == b || c == c) ]] && echo y

# case W in (P|Q)) BODY ;; — wrapped pattern with alternation

Parser accepts both bare (P) BODY and wrapped (P)) BODY (the (...) is the pattern wrapper, the second ) is the arm-close).

case foo in
  (foo|bar)) echo y;;
  (*)) echo n;;
esac

# . file.sh ARG1 ARG2 — source passes positionals

Save outer positional_params, install args[1..] as new positionals, restore on exit.

# file.sh: echo "$1=$2"
. ./file.sh hi bye   # hi=bye

set -- a b c
. ./file.sh inner    # inside file.sh: $1=inner
echo "$@"            # outside: a b c (preserved)

# typeset -A h=(...) in function shadows outer

New local_assoc_save_stack mirrors local_array_save_stack lifecycle. Both call_function paths (legacy + bytecode) updated.

typeset -A h=(a 1)
f() { typeset -A h=(b 2); echo $h[b]; }
f                       # 2
echo $h[a]              # 1 (outer preserved)
echo "[${h[b]-empty}]"  # [empty] (inner didn't leak)

# Subshell umask snapshot+restore

SubshellSnapshot snapshots libc::umask; subshell_end restores. zsh forks for (...) so umask dies with child; we run in-process so we manually reset.

umask 022
(umask 077)   # subshell
umask         # 022 (parent unchanged)

# Subshell EXIT trap fires at subshell end

Was firing at process exit. Now fires before parent continues. SubshellSnapshot snapshots+restores parent traps; inner trap fires with traps.remove("EXIT") so the inner execute_script doesn't recurse.

(trap "echo trapped" EXIT; true)
echo done   # output: trapped\ndone (was: done\ntrapped)

# {one,${a},three} — brace expansion after var substitution

Segment-concat path now emits BUILTIN_BRACE_EXPAND after concat when any literal segment contains { or }.

a=hi
echo {one,${a},three}        # one hi three
echo pre{1,${a},2}post       # pre1post prehipost pre2post

# print -C N — column-padded output

Per-column width padding with 2-space separator (zsh format). Trailing partial rows skip padding after the last present item.

print -C 2 a b c d
# a  c
# b  d
print -C 2 alpha beta gamma delta
# alpha  gamma
# beta   delta

# read -e / read -E — echo line

zsh's bin_read calls fputs(buf, stdout) under both. -e echoes only (no assign); -E echoes AND assigns.

echo "abc" | { read -E v; echo "[$v]"; }
# abc
# [abc]
echo "abc" | { read -e v; echo "[$v]"; }
# abc
# []

# trap "..." ZERR / trap "..." ERR — fires on non-zero status

Wired into BUILTIN_ERREXIT_CHECK. Runs the trap body before the errexit decision; last_status saved/restored to prevent recursion on trap-body failures.

trap "echo zerr" ZERR
false
echo done
# zerr
# done

- ¶

The command is executed with a "-" prepended to its argv[0] string.

. ¶

Read commands from file and execute them in the current shell environment.

If file does not contain a slash, or if PATH_DIRS is set, the shell looks in the components of $path to find the directory containing file. Files in the current directory are not read unless "." appears somewhere in $path. If a file named _file_.zwc' is found, is newer than _file_, and is the compiled form (created with the zcompile builtin) of _file_, then commands are read from that file instead of _file_.

If any arguments arg are given, they become the positional parameters; the old positional parameters are restored when the file is done executing. However, if no arguments are given, the positional parameters remain those of the calling context, and no restoring is done.

If file was not found the return status is 127; if file was found but contained a syntax error the return status is 126; else the return status is the exit status of the last command executed.

: ¶

Null command. Returns true. Side-effects of argument expansion still happen.

[ ¶

POSIX test command (also spelled test). Same conditional semantics as POSIX test. Prefer [[ … ]] in zsh — it's safer (no word splitting) and supports more operators.

alias ¶

For each name with a corresponding value, define an alias with that value. A trailing space in value causes the next word to be checked for alias expansion. If the -g flag is present, define a global alias; global aliases are expanded even if they do not occur in command position:

% perldoc --help 2>&1 | grep 'built-in functions' -f Search Perl built-in functions % alias -g HG='--help 2>&1 | grep' % perldoc HG 'built-in functions' -f Search Perl built-in functions

If the -s flag is present, define a suffix alias: if the command word on a command line is in the form _text_."name", where text is any non-empty string, it is replaced by the text _value_ _text_."name". Note that name is treated as a literal string, not a pattern. A trailing space in value is not special in this case. For example,

alias -s ps='gv --'

will cause the command "*.ps" to be expanded to "gv -- *.ps". As alias expansion is carried out earlier than globbing, the "*.ps" will then be expanded. Suffix aliases constitute a different name space from other aliases (so in the above example it is still possible to create an alias for the command ps) and the two sets are never listed together.

For each name with no value, print the value of name, if any. With no arguments, print all currently defined aliases other than suffix aliases. If the -m flag is given the arguments are taken as patterns (they should be quoted to preserve them from being interpreted as glob patterns), and the aliases matching these patterns are printed. When printing aliases and one of the -g, -r or -s flags is present, restrict the printing to global, regular or suffix aliases, respectively; a regular alias is one which is neither a global nor a suffix alias. Using "+" instead of "-", or ending the option list with a single "+", prevents the values of the aliases from being printed.

If the -L flag is present, then print each alias in a manner suitable for putting in a startup script. The exit status is nonzero if a name (with no value) is given for which no alias has been defined.

For more on aliases, including common problems, see Aliasing (zshmisc).

autoload ¶

vindex(fpath, searching) See Autoloading Functions (zshmisc) for full details. The fpath parameter will be searched to find the function definition when the function is first referenced.

If name consists of an absolute path, the function is defined to load from the file given (searching as usual for dump files in the given location). The name of the function is the basename (non-directory part) of the file. It is normally an error if the function is not found in the given location; however, if the option -d is given, searching for the function defaults to $fpath. If a function is loaded by absolute path, any functions loaded from it that are marked for autoload without an absolute path have the load path of the parent function temporarily prepended to $fpath.

If the option -r or -R is given, the function is searched for immediately and the location is recorded internally for use when the function is executed; a relative path is expanded using the value of $PWD. This protects against a change to $fpath after the call to autoload. With -r, if the function is not found, it is silently left unresolved until execution; with -R, an error message is printed and command processing aborted immediately the search fails, i.e. at the autoload command rather than at function execution..

The flag -X may be used only inside a shell function. It causes the calling function to be marked for autoloading and then immediately loaded and executed, with the current array of positional parameters as arguments. This replaces the previous definition of the function. If no function definition is found, an error is printed and the function remains undefined and marked for autoloading. If an argument is given, it is used as a directory (i.e. it does not include the name of the function) in which the function is to be found; this may be combined with the -d option to allow the function search to default to $fpath if it is not in the given location.

The flag +X attempts to load each name as an autoloaded function, but does not execute it. The exit status is zero (success) if the function was not previously defined and a definition for it was found. This does not replace any existing definition of the function. The exit status is nonzero (failure) if the function was already defined or when no definition was found. In the latter case the function remains undefined and marked for autoloading. If ksh-style autoloading is enabled, the function created will contain the contents of the file plus a call to the function itself appended to it, thus giving normal ksh autoloading behaviour on the first call to the function. If the -m flag is also given each name is treated as a pattern and all functions already marked for autoload that match the pattern are loaded.

With the -t flag, turn on execution tracing; with -T, turn on execution tracing only for the current function, turning it off on entry to any called functions that do not also have tracing enabled.

With the -U flag, alias expansion is suppressed when the function is loaded.

With the -w flag, the _name_s are taken as names of files compiled with the zcompile builtin, and all functions defined in them are marked for autoloading.

The flags -z and -k mark the function to be autoloaded using the zsh or ksh style, as if the option KSH_AUTOLOAD were unset or were set, respectively. The flags override the setting of the option at the time the function is loaded.

Note that the autoload command makes no attempt to ensure the shell options set during the loading or execution of the file have any particular value. For this, the emulate command can be used:

emulate zsh -c 'autoload -Uz func'

arranges that when func is loaded the shell is in native zsh emulation, and this emulation is also applied when func is run.

Some of the functions of autoload are also provided by functions -u or functions -U, but autoload is a more comprehensive interface.

bg ¶

Put each specified job in the background, or the current job if none is specified.

bindkey ¶

bindkey's options can be divided into three categories: keymap selection for the current command, operation selection, and others. The keymap selection options are:

- -e — Selects keymap "emacs" for any operations by the current command, and also links "emacs" to "main" so that it is selected by default the next time the editor starts.

- -v — Selects keymap "viins" for any operations by the current command, and also links "viins" to "main" so that it is selected by default the next time the editor starts.

- -a — Selects keymap "vicmd" for any operations by the current command.

- -M keymap — The keymap specifies a keymap name that is selected for any operations by the current command.

If a keymap selection is required and none of the options above are used, the "main" keymap is used. Some operations do not permit a keymap to be selected, namely:

- -l — List all existing keymap names; if any arguments are given, list just those keymaps.

If the -L option is also used, list in the form of bindkey commands to create or link the keymaps. bindkey -lL main' shows which keymap is linked to "main", if any, and hence if the standard emacs or vi emulation is in effect. This option does not show the .safe keymap because it cannot be created in that fashion; however, neither is "bindkey -lL .safe" reported as an error, it simply outputs nothing.

- -d — Delete all existing keymaps and reset to the default state.

- -D keymap ... — Delete the named _keymap_s.

- -A old-keymap new-keymap — Make the new-keymap name an alias for old-keymap, so that both names refer to the same keymap. The names have equal standing; if either is deleted, the other remains. If there is already a keymap with the new-keymap name, it is deleted.

- -N new-keymap [ old-keymap ] — Create a new keymap, named new-keymap. If a keymap already has that name, it is deleted. If an old-keymap name is given, the new keymap is initialized to be a duplicate of it, otherwise the new keymap will be empty.

To use a newly created keymap, it should be linked to main. Hence the sequence of commands to create and use a new keymap "mymap" initialized from the emacs keymap (which remains unchanged) is:

bindkey -N mymap emacs bindkey -A mymap main

Note that while bindkey -A _newmap_ main' will work when _newmap_ is emacs or viins, it will not work for vicmd, as switching from vi insert to command mode becomes impossible.

The following operations act on the "main" keymap if no keymap selection option was given:

- -m — Add the built-in set of meta-key bindings to the selected keymap. Only keys that are unbound or bound to self-insert are affected.

- -r in-string ... — Unbind the specified _in-string_s in the selected keymap. This is exactly equivalent to binding the strings to undefined-key.

When -R is also used, interpret the _in-string_s as ranges.

When -p is also used, the _in-string_s specify prefixes. Any binding that has the given in-string as a prefix, not including the binding for the in-string itself, if any, will be removed. For example,

bindkey -rpM viins '^['

will remove all bindings in the vi-insert keymap beginning with an escape character (probably cursor keys), but leave the binding for the escape character itself (probably vi-cmd-mode). This is incompatible with the option -R.

- -s in-string out-string ... — Bind each in-string to each out-string. When in-string is typed, out-string will be pushed back and treated as input to the line editor. When -R is also used, interpret the _in-string_s as ranges.

Note that both in-string and out-string are subject to the same form of interpretation, as described below.

- in-string command ... — Bind each in-string to each command. When -R is used, interpret the _in-string_s as ranges.

- [ in-string ] — List key bindings. If an in-string is specified, the binding of that string in the selected keymap is displayed. Otherwise, all key bindings in the selected keymap are displayed. (As a special case, if the -e or -v option is used alone, the keymap is not displayed - the implicit linking of keymaps is the only thing that happens.)

When the option -p is used, the in-string must be present. The listing shows all bindings which have the given key sequence as a prefix, not including any bindings for the key sequence itself.

When the -L option is used, the list is in the form of bindkey commands to create the key bindings.

When the -R option is used as noted above, a valid range consists of two characters, with an optional "-" between them. All characters between the two specified, inclusive, are bound as specified.

For either in-string or out-string, the following escape sequences are recognised:

- \a — bell character - \b — backspace - \e, \E — escape - \f — form feed

- \n — linefeed (newline)

- \r — carriage return - \t — horizontal tab - \v — vertical tab - \NNN — character code in octal - \xNN — character code in hexadecimal - \uNNNN — unicode character code in hexadecimal - \UNNNNNNNN — unicode character code in hexadecimal - \M[-]X — character with meta bit set - \C[-]X — control character - ^X — control character

In all other cases, "\" escapes the following character. Delete is written as "^?". Note that "\M^?" and "^\M?" are not the same, and that (unlike emacs), the bindings \M-"X" and \e"X" are entirely distinct, although they are initialized to the same bindings by "bindkey -m".

break ¶

Exit from an enclosing for, while, until, select or repeat loop. If an arithmetic expression n is specified, then break n levels instead of just one.

builtin ¶

The command word is taken to be the name of a builtin command, rather than a shell function or external command.

bye ¶

Alias for exit. Exit the shell with the given status.

cap ¶

Change the shell's process capability sets to the specified capabilities, otherwise display the shell's current capabilities.

cd ¶

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 previous directory.

Otherwise, if arg begins with a slash, attempt to change to the directory given by arg.

If arg does not begin with a slash, the behaviour depends on whether the current directory "." occurs in the list of directories contained in the shell parameter cdpath. If it does not, first attempt to change to the directory arg under the current directory, and if that fails but cdpath is set and contains at least one element attempt to change to the directory arg under each component of cdpath in turn until successful. If "." occurs in cdpath, then cdpath is searched strictly in order so that "." is only tried at the appropriate point.

The order of testing cdpath is modified if the option POSIX_CD is set, as described in the documentation for the option.

If no directory is found, the option CDABLE_VARS is set, and a parameter named arg exists whose value begins with a slash, treat its value as the directory. In that case, the parameter is added to the named directory hash table.

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

The third form of cd extracts an entry from the directory stack, and changes to that directory. An argument of the form +"n" identifies a stack entry by counting from the left of the list shown by the dirs command, starting with zero. An argument of the form -"n" counts from the right. If the PUSHD_MINUS option is set, the meanings of "+" and "-" in this context are swapped. If the POSIX_CD option is set, this form of cd is not recognised and will be interpreted as the first form.

If the -q (quiet) option is specified, the hook function chpwd and the functions in the array chpwd_functions are not called. This is useful for calls to cd that do not change the environment seen by an interactive user.

If the -s option is specified, cd refuses to change the current directory if the given pathname contains symlinks. If the -P option is given or the CHASE_LINKS option is set, symbolic links are resolved to their true values. If the -L option is given symbolic links are retained in the directory (and not resolved) regardless of the state of the CHASE_LINKS option.

chdir ¶

Alias for cd. Change the working directory.

chgrp ¶

Changes group of files specified. This is equivalent to chown with a user-spec argument of :"group".

chmod ¶

Changes mode of files specified.

The specified mode must be in octal.

The -R option causes chmod to recursively descend into directories, changing the mode of all files in the directory after changing the mode of the directory itself.

The -s option is a zsh extension to chmod functionality. It enables paranoid behaviour, intended to avoid security problems involving a chmod being tricked into affecting files other than the ones intended. It will refuse to follow symbolic links, so that (for example) ""chmod 600 /tmp/foo/passwd"" can't accidentally chmod /etc/passwd if /tmp/foo happens to be a link to /etc. It will also check where it is after leaving directories, so that a recursive chmod of a deep directory tree can't end up recursively chmoding /usr as a result of directories being moved up the tree.

chown ¶

Changes ownership and group of files specified.

The user-spec can be in four forms:

- user — change owner to user; do not change group - user:: — change owner to user; do not change group - user:" — change owner to _user_; change group to _user_"s primary group - _user_:_group_ — change owner to _user_; change group to _group_ - :_group_ — do not change owner; change group to _group_

In each case, the ":" may instead be a ".". The rule is that if there is a ":" then the separator is ":", otherwise if there is a "." then the separator is ".", otherwise there is no separator.

Each of user and group may be either a username (or group name, as appropriate) or a decimal user ID (group ID). Interpretation as a name takes precedence, if there is an all-numeric username (or group name).

If the target is a symbolic link, the -h option causes chown to set the ownership of the link instead of its target.

The -R option causes chown to recursively descend into directories, changing the ownership of all files in the directory after changing the ownership of the directory itself.

The -s option is a zsh extension to chown functionality. It enables paranoid behaviour, intended to avoid security problems involving a chown being tricked into affecting files other than the ones intended. It will refuse to follow symbolic links, so that (for example) ""chown luser /tmp/foo/passwd"" can't accidentally chown /etc/passwd if /tmp/foo happens to be a link to /etc. It will also check where it is after leaving directories, so that a recursive chown of a deep directory tree can't end up recursively chowning /usr as a result of directories being moved up the tree.

clone ¶

Creates a forked instance of the current shell, attached to the specified tty. In the new shell, the PID, PPID and TTY special parameters are changed appropriately. $! is set to zero in the new shell, and to the new shell's PID in the original shell.

The return status of the builtin is zero in both shells if successful, and non-zero on error.

The target of clone should be an unused terminal, such as an unused virtual console or a virtual terminal created by

xterm -e sh -c 'trap : INT QUIT TSTP; tty; while :; do sleep 100000000; done'

Some words of explanation are warranted about this long xterm command line: when doing clone on a pseudo-terminal, some other session ("session" meant as a unix session group, or SID) is already owning the terminal. Hence the cloned zsh cannot acquire the pseudo-terminal as a controlling tty. That means two things:

startitemize() itemiz(the job control signals will go to the sh-started-by-xterm process group (that's why we disable INT QUIT and TSTP with trap; otherwise the while loop could get suspended or killed)) itemiz(the cloned shell will have job control disabled, and the job control keys (control-C, control-\ and control-Z) will not work.) enditemize()

This does not apply when cloning to an unused vc.

Cloning to a used (and unprepared) terminal will result in two processes reading simultaneously from the same terminal, with input bytes going randomly to either process.

clone is mostly useful as a shell built-in replacement for openvt.

command ¶

The command word is taken to be the name of an external command, rather than a shell function or builtin. If the POSIX_BUILTINS option is set, builtins will also be executed but certain special properties of them are suppressed. The -p flag causes a default path to be searched instead of that in $path. With the -v flag, command is similar to whence and with -V, it is equivalent to whence -v.

compadd ¶

This builtin command can be used to add matches directly and control all the information the completion code stores with each possible completion. The return status is zero if at least one match was added and non-zero if no matches were added.

The completion code breaks each match into seven fields in the order:

<ipre><apre><hpre><body><hsuf><asuf><isuf>

The first field is an ignored prefix taken from the command line, the contents of the IPREFIX parameter plus the string given with the -i option. With the -U option, only the string from the -i option is used. The field <apre> is an optional prefix string given with the -P option. The <hpre> field is a string that is considered part of the match but that should not be shown when listing completions, given with the -p option; for example, functions that do filename generation might specify a common path prefix this way. <body> is the part of the match that should appear in the list of matches shown to the user. The suffixes <hsuf>, <asuf> and <isuf> correspond to the prefixes <hpre>, <apre> and <ipre> and are given by the options -s, -S and -I, respectively.

The supported flags are:

- -P prefix — This gives a string to be inserted before each match. The string given is not considered as part of the match and any shell metacharacters in it will not be quoted when the string is inserted.

- -S suffix — Like -P, but gives a string to be inserted after each match.

- -p hidden-prefix — This gives a string that should be inserted before each match but that should not appear in the list of matches. Unless the -U option is given, this string must be matched as part of the string on the command line.

- -s hidden-suffix — Like "-p", but gives a string to insert after each match.

- -i ignored-prefix — This gives a string to insert just before any string given with the "-P" option. Without "-P" the string is inserted before the string given with "-p" or directly before each match.

- -I ignored-suffix — Like -i, but gives an ignored suffix.

- -a — With this flag the completions are taken as names of arrays and the actual completions are their values. If only some elements of the arrays are needed, the completions may also contain subscripts, as in "foo[2,-1]".

- -k — With this flag the completions are taken as names of associative arrays and the actual completions are their keys. As for -a, the words may also contain subscripts, as in "tt(foo[(R)*bar*])".

- -d array — This adds per-completion display strings. The array should contain one element per completion given. The completion code will then display the first element instead of the first completion, and so on. The array may be given as the name of an array parameter or directly as a space-separated list of words in parentheses.

If there are fewer display strings than completions, the leftover completions will be displayed unchanged and if there are more display strings than completions, the leftover display strings will be silently ignored.

- -l — This option only has an effect if used together with the -d option. If it is given, the display strings are listed one per line, not arrayed in columns.

- -o [ order ] — This controls the order in which matches are sorted. order is a comma-separated list comprising the following possible values. These values can be abbreviated to their initial two or three characters. Note that the order forms part of the group name space so matches with different orderings will not be in the same group; additionally, since ordering flags are not respected on the default group, a group name must be given explicitly. See -J and -V below.

- match — If given, the order of the output is determined by the match strings; otherwise it is determined by the display strings (i.e. the strings given by the -d option). This is the default if "-o" is specified but the order argument is omitted.

- nosort — This specifies that the completions are pre-sorted and their order should be preserved. This value only makes sense alone and cannot be combined with any others.

- numeric — If the matches include numbers, sort them numerically rather than lexicographically.

- reverse — Arrange the matches backwards by reversing the sort ordering.

- -J group-name — Gives the name of the group that the matches should be stored in.

- -V group-name — Like -J but naming an unsorted group. This option is identical to the combination of -J and -o nosort.

- -1 — If given together with the -V option, makes only consecutive duplicates in the group be removed. If combined with the -J option, this has no visible effect. Note that groups with and without this flag are in different name spaces.

- -2 — If given together with the -J or -V option, makes all duplicates be kept. Again, groups with and without this flag are in different name spaces.

- -X explanation — The explanation string will be printed with the list of matches, above the group currently selected.

Within the explanation, the following sequences may be used to specify output attributes as described in Expansion of Prompt Sequences (zshmisc): "%B", "%S", "%U", "%F", "%K" and their lower case counterparts, as well as "%H" and %{...%}'. "%F", "%K", "%H" and %{...%}' take arguments in the same form as prompt expansion. (Note that the sequence "%G" is not available; an argument to "%{" should be used instead.) The sequence "%%" produces a literal "%".

These sequences are most often employed by users when customising the format style (see subref(Standard Styles)(zshcompsys)), but they must also be taken into account when writing completion functions, as passing descriptions with unescaped "%" characters to utility functions such as _arguments and _message may produce unexpected results. If arbitrary text is to be passed in a description, it can be escaped using e.g. ${my_str//\%/%%}.

- -x message — Like -X, but the message will be printed even if there are no matches in the group.

- -q — The suffix given with -S will be automatically removed if the next character typed is a blank or does not insert anything, or if the suffix consists of only one character and the next character typed is the same character.

- -r remove-chars — This is a more versatile form of the -q option. The suffix given with -S or the slash automatically added after completing directories will be automatically removed if the next character typed inserts one of the characters given in the remove-chars. This string is parsed as a characters class and understands the backslash sequences used by the print command. For example, "-r "a-z\t"" removes the suffix if the next character typed inserts a lower case character or a TAB, and "-r "^0-9"" removes the suffix if the next character typed inserts anything but a digit. One extra backslash sequence is understood in this string: "\-" stands for all characters that insert nothing. Thus "-S "=" -q" is the same as "-S "=" -r "= \t\n\-"".

This option may also be used without the -S option; then any automatically added space will be removed when one of the characters in the list is typed.

- -R remove-func — This is another form of the -r option. When a match has been accepted and a suffix has been inserted, the function remove-func will be called after the next character typed. It is passed the length of the suffix as an argument and can use the special parameters available in ordinary (non-completion) zle widgets (see User-Defined Widgets (zshzle) ) to analyse and modify the command line.

- -f — If this flag is given, all of the matches built from the completions are marked as being the names of files. They are not required to be actual filenames, but if they are, and the option LIST_TYPES is set, the characters describing the types of the files in the completion lists will be shown. This also forces a slash to be added when the name of a directory is completed.

- -e — This flag can be used to tell the completion code that the matches added are parameter names for a parameter expansion. This will make the AUTO_PARAM_SLASH and AUTO_PARAM_KEYS options be used for the matches.

- -W file-prefix — This string is a pathname that will be prepended to each match together with any prefix specified by the -p option to form a complete filename for testing. Hence it is only useful if combined with the -f flag, as the tests will not otherwise be performed.

- -F array — Specifies an array containing patterns. completions that match one of these patterns are ignored, that is, not considered to be matches.

The array may be the name of an array parameter or a list of literal patterns enclosed in parentheses and quoted, as in tt(-F "(*?.o *?.h)")'. If the name of an array is given, the elements of the array are taken as the patterns. )

- -Q — This flag instructs the completion code not to quote any metacharacters in the matches when inserting them into the command line.

- -M match-spec — This gives local match specifications as described below in (Completion Matching Control). This option may be given more than once. In this case all _match-spec_s given are concatenated with spaces between them to form the specification string to use. Note that they will only be used if the -U option is not given.

- -n — Specifies that matching completions are to be added to the set of matches, but are not to be listed to the user.

- -U — If this flag is given, all completions are added to the set of matches and no matching will be done by the completion code. Normally this is used in functions that do the matching themselves.

- -O array — If this option is given, the completions are not added to the set of matches. Instead, matching is done as usual and all of the completions that match will be stored in the array parameter whose name is given as array.

- -A array — As the -O option, except that instead of those of the completions which match being stored in array, the strings generated internally by the completion code are stored. For example, with a match specification of "-M "L:|no="", a current word of "nof" and completions of "foo", this option stores the string "nofoo" in the array, whereas the -O option stores the "foo" originally given.

- -D array — As with -O, the completions are not added to the set of matches. Instead, whenever the _n_th completion does not match, the _n_th element of the array is removed. Elements for which the corresponding completion matches are retained. This option can be used more than once to remove elements from multiple arrays.

- -C — This option adds a special match which expands to all other matches when inserted into the line, even those that are added after this option is used. Together with the -d option it is possible to specify a string that should be displayed in the list for this special match. If no string is given, it will be shown as a string containing the strings that would be inserted for the other matches, truncated to the width of the screen.

- -E number — This option adds number empty matches after matching completions have been added. An empty match takes up space in completion listings but will never be inserted in the line and can't be selected with menu completion or menu selection. This makes empty matches only useful to format completion lists and to make explanatory string be shown in completion lists (since empty matches can be given display strings with the -d option). And because all but one empty string would otherwise be removed, this option implies the -V and -2 options (even if an explicit -J option is given). This can be important to note as it affects the name space into which matches are added.

- -

- -- — This flag ends the list of flags and options. All arguments after it will be taken as the completions even if they begin with hyphens.

Except for the -M flag, if any of these flags is given more than once, the first one (and its argument) will be used.

comparguments ¶

This is used by the _arguments function to do the argument and command line parsing. Like compdescribe it has an option -i to do the parsing and initialize some internal state and various options to access the state information to decide what should be completed.

compcall ¶

This allows the use of completions defined with the compctl builtin from within completion widgets. The list of matches will be generated as if one of the non-widget completion functions (complete-word, etc.) had been called, except that only compctls given for specific commands are used. To force the code to try completions defined with the -T option of compctl and/or the default completion (whether defined by compctl -D or the builtin default) in the appropriate places, the -T and/or -D flags can be passed to compcall.

The return status can be used to test if a matching compctl definition was found. It is non-zero if a compctl was found and zero otherwise.

Note that this builtin is defined by the zsh/compctl module.

compctl ¶

Old completion control (compctl mechanism). Largely superseded by compdef / compsys.

compdescribe ¶

This is used by the _describe function to build the displays for the matches and to get the strings to add as matches with their options. On the first call one of the options -i or -I should be supplied as the first argument. In the first case, display strings without the descriptions will be generated, in the second case, the string used to separate the matches from their descriptions must be given as the second argument and the descriptions (if any) will be shown. All other arguments are like the definition arguments to _describe itself.

Once compdescribe has been called with either the -i or the -I option, it can be repeatedly called with the -g option and the names of four parameters as its arguments. This will step through the different sets of matches and store the value of compstate[list] in the first scalar, the options for compadd in the second array, the matches in the third array, and the strings to be displayed in the completion listing in the fourth array. The arrays may then be directly given to compadd to register the matches with the completion code.

compfiles ¶

Used by the _path_files function to optimize complex recursive filename generation (globbing). It does three things. With the -p and -P options it builds the glob patterns to use, including the paths already handled and trying to optimize the patterns with respect to the prefix and suffix from the line and the match specification currently used. The -i option does the directory tests for the ignore-parents style and the -r option tests if a component for some of the matches are equal to the string on the line and removes all other matches if that is true.

compgroups ¶

Used by the _tags function to implement the internals of the group-order style. This only takes its arguments as names of completion groups and creates the groups for it (all six types: sorted and unsorted, both without removing duplicates, with removing all duplicates and with removing consecutive duplicates).

compquote ¶

There may be reasons to write completion functions that have to add the matches using the -Q option to compadd and perform quoting themselves. Instead of interpreting the first character of the all_quotes key of the compstate special association and using the q flag for parameter expansions, one can use this builtin command. The arguments are the names of scalar or array parameters and the values of these parameters are quoted as needed for the innermost quoting level. If the -p option is given, quoting is done as if there is some prefix before the values of the parameters, so that a leading equal sign will not be quoted.

The return status is non-zero in case of an error and zero otherwise.

compset ¶

This command simplifies modification of the special parameters, while its return status allows tests on them to be carried out.

The options are:

- -p number — If the value of the PREFIX parameter is at least number characters long, the first number characters are removed from it and appended to the contents of the IPREFIX parameter.

- -P [ number ] pattern — If the value of the PREFIX parameter begins with anything that matches the pattern, the matched portion is removed from PREFIX and appended to IPREFIX.

Without the optional number, the longest match is taken, but if number is given, anything up to the _number_th match is moved. If the number is negative, the _number_th longest match is moved. For example, if PREFIX contains the string "a=b=c", then "compset -P "*\=' will move the string "a=b=" into the IPREFIX" parameter, but "compset -P 1 "*\=" will move only the string "a=".

- -s number — As -p, but transfer the last number characters from the value of SUFFIX to the front of the value of ISUFFIX.

- -S [ number ] pattern — As -P, but match the last portion of SUFFIX and transfer the matched portion to the front of the value of ISUFFIX.

- -n begin [ end ] — If the current word position as specified by the parameter CURRENT is greater than or equal to begin, anything up to the _begin_th word is removed from the words array and the value of the parameter CURRENT is decremented by begin.

If the optional end is given, the modification is done only if the current word position is also less than or equal to end. In this case, the words from position end onwards are also removed from the words array.

Both begin and end may be negative to count backwards from the last element of the words array.

- -N beg-pat [ end-pat ] — If one of the elements of the words array before the one at the index given by the value of the parameter CURRENT matches the pattern beg-pat, all elements up to and including the matching one are removed from the words array and the value of CURRENT is changed to point to the same word in the changed array.

If the optional pattern end-pat is also given, and there is an element in the words array matching this pattern, the parameters are modified only if the index of this word is higher than the one given by the CURRENT parameter (so that the matching word has to be after the cursor). In this case, the words starting with the one matching end-pat are also removed from the words array. If words contains no word matching end-pat, the testing and modification is performed as if it were not given.

- -q — The word currently being completed is split on spaces into separate words, respecting the usual shell quoting conventions. The resulting words are stored in the words array, and CURRENT, PREFIX, SUFFIX, QIPREFIX, and QISUFFIX are modified to reflect the word part that is completed.

In all the above cases the return status is zero if the test succeeded and the parameters were modified and non-zero otherwise. This allows one to use this builtin in tests such as:

if compset -P '*\='; then ...

This forces anything up to and including the last equal sign to be ignored by the completion code.

comptags ¶

These implement the internals of the tags mechanism.

comptry ¶

These implement the internals of the tags mechanism.

compvalues ¶

Like comparguments, but for the _values function.

continue ¶

Resume the next iteration of the enclosing for, while, until, select or repeat loop. If an arithmetic expression n is specified, break out of n-1 loops and resume at the _n_th enclosing loop.

declare ¶

Alias for typeset. Set variable attributes. -a array, -A assoc, -i integer, -r readonly.

dirs ¶

With no arguments, print the contents of the directory stack. Directories are added to this stack with the pushd command, and removed with the cd or popd commands. If arguments are specified, load them onto the directory stack, replacing anything that was there, and push the current directory onto the stack.

- -c — clear the directory stack.

- -l — print directory names in full instead of using ~ expressions (see Filename Expansion (zshexpn)).

- -p — print directory entries one per line.

- -v — number the directories in the stack when printing.

disable ¶

Temporarily disable the _name_d hash table elements or patterns. The default is to disable builtin commands. This allows you to use an external command with the same name as a builtin command. The -a option causes disable to act on regular or global aliases. The -s option causes disable to act on suffix aliases. The -f option causes disable to act on shell functions. The -r options causes disable to act on reserved words. Without arguments all disabled hash table elements from the corresponding hash table are printed. With the -m flag the arguments are taken as patterns (which should be quoted to prevent them from undergoing filename expansion), and all hash table elements from the corresponding hash table matching these patterns are disabled. Disabled objects can be enabled with the enable command.

With the option -p, name ... refer to elements of the shell's pattern syntax as described in Filename Generation (zshexpn). Certain elements can be disabled separately, as given below.

Note that patterns not allowed by the current settings for the options EXTENDED_GLOB, KSH_GLOB and SH_GLOB are never enabled, regardless of the setting here. For example, if EXTENDED_GLOB is not active, the pattern ^ is ineffective even if "disable -p "^"" has not been issued. The list below indicates any option settings that restrict the use of the pattern. It should be noted that setting SH_GLOB has a wider effect than merely disabling patterns as certain expressions, in particular those involving parentheses, are parsed differently.

The following patterns may be disabled; all the strings need quoting on the command line to prevent them from being interpreted immediately as patterns and the patterns are shown below in single quotes as a reminder.

- '?' — The pattern character ? wherever it occurs, including when preceding a parenthesis with KSH_GLOB.

- '*' — The pattern character * wherever it occurs, including recursive globbing and when preceding a parenthesis with KSH_GLOB.

- [ — Character classes.

- '<' (NO_SH_GLOB) — Numeric ranges.

- '|' (NO_SH_GLOB) — Alternation in grouped patterns, case statements, or KSH_GLOB parenthesised expressions.

- ( (NO_SH_GLOB) — Grouping using single parentheses. Disabling this does not disable the use of parentheses for KSH_GLOB where they are introduced by a special character, nor for glob qualifiers (use setopt NO_BARE_GLOB_QUAL' to disable glob qualifiers that use parentheses only).

- '~' (EXTENDED_GLOB) — Exclusion in the form A~B.

- '^' (EXTENDED_GLOB) — Exclusion in the form A^B.

- '#' (EXTENDED_GLOB) — The pattern character # wherever it occurs, both for repetition of a previous pattern and for indicating globbing flags.

- ?( (KSH_GLOB) — The grouping form ?(...). Note this is also disabled if '?' is disabled.

- *( (KSH_GLOB) — The grouping form *(...). Note this is also disabled if '*' is disabled.

- +( (KSH_GLOB) — The grouping form +(...).

- !( (KSH_GLOB) — The grouping form !(...).

- @( (KSH_GLOB) — The grouping form @(...).

disown ¶

Remove the specified _job_s from the job table; the shell will no longer report their status, and will not complain if you try to exit an interactive shell with them running or stopped. If no job is specified, disown the current job.

If the _job_s are currently stopped and the AUTO_CONTINUE option is not set, a warning is printed containing information about how to make them running after they have been disowned. If one of the latter two forms is used, the _job_s will automatically be made running, independent of the setting of the AUTO_CONTINUE option.

echo ¶

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

- \a — bell character - \b — backspace - \c — suppress subsequent characters and final newline - \e — escape - \f — form feed

- \n — linefeed (newline)

- \r — carriage return - \t — horizontal tab - \v — vertical tab - \\ — backslash - \0NNN — character code in octal - \xNN — character code in hexadecimal - \uNNNN — unicode character code in hexadecimal - \UNNNNNNNN — unicode character code in hexadecimal

pindex(BSD_ECHO, use of) The -E flag, or the BSD_ECHO option, can be used to disable these escape sequences. In the latter case, -e flag can be used to enable them.

Note that for standards compliance a double dash does not terminate option processing; instead, it is printed directly. However, a single dash does terminate option processing, so the first dash, possibly following options, is not printed, but everything following it is printed as an argument. The single dash behaviour is different from other shells. For a more portable way of printing text, see printf, and for a more controllable way of printing text within zsh, see print.

echotc ¶

Output the termcap value corresponding to the capability cap, with optional arguments.

echoti ¶

Output the terminfo value corresponding to the capability cap, instantiated with arg if applicable.

emulate ¶

Without any argument print current emulation mode.

With single argument set up zsh options to emulate the specified shell as much as possible. csh will never be fully emulated. If the argument is not one of the shells listed above, zsh will be used as a default; more precisely, the tests performed on the argument are the same as those used to determine the emulation at startup based on the shell name, see Compatibility (zsh). In addition to setting shell options, the command also restores the pristine state of pattern enables, as if all patterns had been enabled using enable -p.

If the emulate command occurs inside a function that has been marked for execution tracing with functions -t then the xtrace option will be turned on regardless of emulation mode or other options. Note that code executed inside the function by the ., source, or eval commands is not considered to be running directly from the function, hence does not provoke this behaviour.

If the -R switch is given, all settable options are reset to their default value corresponding to the specified emulation mode, except for certain options describing the interactive environment; otherwise, only those options likely to cause portability problems in scripts and functions are altered. If the -L switch is given, the options LOCAL_OPTIONS, LOCAL_PATTERNS and LOCAL_TRAPS will be set as well, causing the effects of the emulate command and any setopt, disable -p or enable -p, and trap commands to be local to the immediately surrounding shell function, if any; normally these options are turned off in all emulation modes except ksh. The -L switch is mutually exclusive with the use of -c in flags.

If there is a single argument and the -l switch is given, the options that would be set or unset (the latter indicated with the prefix "no") are listed. -l can be combined with -L or -R and the list will be modified in the appropriate way. Note the list does not depend on the current setting of options, i.e. it includes all options that may in principle change, not just those that would actually change.

The flags may be any of the invocation-time flags described in Invocation (zsh), except that "-o EMACS" and "-o VI" may not be used.

If -c arg appears in flags, arg is evaluated while the requested emulation is temporarily in effect. In this case the emulation mode and all options are restored to their previous values before emulate returns. The -R switch may precede the name of the shell to emulate; note this has a meaning distinct from including -R in flags.

Use of -c enables "sticky" emulation mode for functions defined within the evaluated expression: the emulation mode is associated thereafter with the function so that whenever the function is executed the emulation (respecting the -R switch, if present) and all options are set (and pattern disables cleared) before entry to the function, and the state is restored after exit. If the function is called when the sticky emulation is already in effect, either within an emulate _shell_ -c' expression or within another function with the same sticky emulation, entry and exit from the function do not cause options to be altered (except due to standard processing such as the LOCAL_OPTIONS option). This also applies to functions marked for autoload within the sticky emulation; the appropriate set of options will be applied at the point the function is loaded as well as when it is run.

For example:

example(emulate sh -c 'fni+() { setopt cshnullglob; } fno+() { fni; }' fno)

The two functions fni and fno are defined with sticky sh emulation. fno is then executed, causing options associated with emulations to be set to their values in sh. fno then calls fni; because fni is also marked for sticky sh emulation, no option changes take place on entry to or exit from it. Hence the option cshnullglob, turned off by sh emulation, will be turned on within fni and remain on return to fno. On exit from fno, the emulation mode and all options will be restored to the state they were in before entry to the temporary emulation.

The documentation above is typically sufficient for the intended purpose of executing code designed for other shells in a suitable environment. More detailed rules follow.

- 1. — The sticky emulation environment provided by emulate _shell_ -c' is identical to that provided by entry to a function marked for sticky emulation as a consequence of being defined in such an environment. Hence, for example, the sticky emulation is inherited by subfunctions defined within functions with sticky emulation. - 2. — No change of options takes place on entry to or exit from functions that are not marked for sticky emulation, other than those that would normally take place, even if those functions are called within sticky emulation. - 3. — No special handling is provided for functions marked for autoload nor for functions present in wordcode created by the zcompile command. - 4. — The presence or absence of the -R switch to emulate corresponds to different sticky emulation modes, so for example "emulate sh -c", "emulate -R sh -c" and "emulate csh -c" are treated as three distinct sticky emulations. - 5. — Difference in shell options supplied in addition to the basic emulation also mean the sticky emulations are different, so for example "emulate zsh -c" and "emulate zsh -o cbases -c" are treated as distinct sticky emulations.

enable ¶

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

enable -p reenables patterns disabled with disable -p. Note that it does not override globbing options; for example, enable -p "~"' does not cause the pattern character ~ to be active unless the EXTENDED_GLOB option is also set. To enable all possible patterns (so that they may be individually disabled with disable -p), use "setopt EXTENDED_GLOB KSH_GLOB NO_SH_GLOB".

eval ¶

Read the arguments as input to the shell and execute the resulting command+(s+) in the current shell process. The return status is the same as if the commands had been executed directly by the shell; if there are no args or they contain no commands (i.e. are an empty string or whitespace) the return status is zero.

example ¶

Displays the flags and arguments it is invoked with.

exec ¶

The following command together with any arguments is run in place of the current process, rather than as a sub-process. The shell does not fork and is replaced. The shell does not invoke TRAPEXIT, nor does it source zlogout files. The options are provided for compatibility with other shells.

The -c option clears the environment.

The -l option is equivalent to the - precommand modifier, to treat the replacement command as a login shell; the command is executed with a - prepended to its argv[0] string. This flag has no effect if used together with the -a option.

The -a option is used to specify explicitly the argv[0] string (the name of the command as seen by the process itself) to be used by the replacement command and is directly equivalent to setting a value for the ARGV0 environment variable.

exit ¶

Exit the shell with the exit status specified by an arithmetic expression n; if none is specified, use the exit status from the last command executed. pindex(IGNORE_EOF, use of) An EOF condition will also cause the shell to exit, unless the IGNORE_EOF option is set.

See notes at the end of Signals (zshmisc) for some possibly unexpected interactions of the exit command with jobs.

export ¶

The specified _name_s are marked for automatic export to the environment of subsequently executed commands. Equivalent to typeset -gx. If a parameter specified does not already exist, it is created in the global scope.

false ¶

Do nothing and return an exit status of 1.

fc ¶

The fc command controls the interactive history mechanism. Note that reading and writing of history options is only performed if the shell is interactive. Usually this is detected automatically, but it can be forced by setting the interactive option when starting the shell.

The first two forms of this command select a range of events from first to last from the history list. The arguments first and last may be specified as a number or as a string. A negative number is used as an offset to the current history event number. A string specifies the most recent event beginning with the given string. All substitutions old=new, if any, are then performed on the text of the events.

The range of events selected by numbers can be narrowed further by the following flags.

- -I — restricts to only internal events (not from $HISTFILE)

- -L — restricts to only local events (not from other shells, see SHARE_HISTORY in nmref(Description of Options)(zshoptions) -- note that $HISTFILE is considered local when read at startup)

- -m — takes the first argument as a pattern (which should be quoted) and only the history events matching this pattern are considered

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. However, if the current event has added entries to the history with "print -s" or "fc -R", then the default last for -l includes all new history entries since the current event began.

When the -l flag is given, the resulting events are listed on standard output. Otherwise the editor program specified by -e ename is invoked on a file containing these history events. If -e is not given, the value of the parameter FCEDIT is used; if that is not set the value of the parameter EDITOR is used; if that is not set a builtin default, usually "vi" is used. If ename is "-", no editor is invoked. When editing is complete, the edited command is executed.

The flag "-s" is equivalent to "-e -". The flag -r reverses the order of the events and the flag -n suppresses event numbers when listing.

Also when listing,

- -d — prints timestamps for each event - -f — prints full time-date stamps in the US _MM_/_DD_/_YY_ _hh_:"mm" format - -E — prints full time-date stamps in the European _dd_._mm_._yyyy_ _hh_:"mm" format - -i — prints full time-date stamps in ISO8601 _yyyy_-_mm_-_dd_ _hh_:"mm" format

- -t fmt — prints time and date stamps in the given format; fmt is formatted with the strftime function with the zsh extensions described for the %D{string} prompt format in Simple Prompt Escapes (zshmisc). The resulting formatted string must be no more than 256 characters or will not be printed

- -D — prints elapsed times; may be combined with one of the options above

cindex(history, stack) cindex(stack, history) "fc -p" pushes the current history list onto a stack and switches to a new history list. If the -a option is also specified, this history list will be automatically popped when the current function scope is exited, which is a much better solution than creating a trap function to call "fc -P" manually. If no arguments are specified, the history list is left empty, $HISTFILE is unset, and $HISTSIZE & $SAVEHIST are set to their default values. If one argument is given, $HISTFILE is set to that filename, $HISTSIZE & $SAVEHIST are left unchanged, and the history file is read in (if it exists) to initialize the new list. If a second argument is specified, $HISTSIZE & $SAVEHIST are instead set to the single specified numeric value. Finally, if a third argument is specified, $SAVEHIST is set to a separate value from $HISTSIZE. You are free to change these environment values for the new history list however you desire in order to manipulate the new history list.

"fc -P" pops the history list back to an older list saved by "fc -p". The current list is saved to its $HISTFILE before it is destroyed (assuming that $HISTFILE and $SAVEHIST are set appropriately, of course). The values of $HISTFILE, $HISTSIZE, and $SAVEHIST are restored to the values they had when "fc -p" was called. Note that this restoration can conflict with making these variables "local", so your best bet is to avoid local declarations for these variables in functions that use "fc -p". The one other guaranteed-safe combination is declaring these variables to be local at the top of your function and using the automatic option (-a) with "fc -p". Finally, note that it is legal to manually pop a push marked for automatic popping if you need to do so before the function exits.

cindex(history, file) cindex(file, history) "fc -R" reads the history from the given file, "fc -W" writes the history out to the given file, and "fc -A" appends the history out to the given file. If no filename is specified, the $HISTFILE is assumed. If the -I option is added to -R, only those events that are not already contained within the internal history list are added. If the -I option is added to -A or -W, only those events that are new since last incremental append/write to the history file are appended/written. In any case, the created file will have no more than $SAVEHIST entries.

fg ¶

Bring each specified job in turn to the foreground. If no job is specified, resume the current job.

float ¶

Equivalent to typeset -E, except that options irrelevant to floating point numbers are not permitted.

functions ¶

Equivalent to typeset -f, with the exception of the -c, -x, -M and -W options. For functions -u and functions -U, see autoload, which provides additional options. For functions -t and functions -T, see typeset -f.

The -x option indicates that any functions output will have each leading tab for indentation, added by the shell to show syntactic structure, expanded to the given number num of spaces. num can also be 0 to suppress all indentation.

The -W option turns on the option WARN_NESTED_VAR for the named function or functions only. The option is turned off at the start of nested functions (apart from anonymous functions) unless the called function also has the -W attribute.

The -c option causes oldfn to be copied to newfn. The copy is efficiently handled internally by reference counting. If oldfn was marked for autoload it is first loaded and if this fails the copy fails. Either function may subsequently be redefined without affecting the other. A typical idiom is that oldfn is the name of a library shell function which is then redefined to call newfn, thereby installing a modified version of the function.

The -M_ and +M flags_ cindex(defining mathematical functions) cindex(functions, defining mathematical)

Use of the -M option may not be combined with any of the options handled by typeset -f.

functions -M mathfn defines mathfn as the name of a mathematical function recognised in all forms of arithmetical expressions; see Arithmetic Evaluation (zshmisc). By default mathfn may take any number of comma-separated arguments. If min is given, it must have exactly min args; if min and max are both given, it must have at least min and at most max args. max may be -1 to indicate that there is no upper limit.

By default the function is implemented by a shell function of the same name; if shellfn is specified it gives the name of the corresponding shell function while mathfn remains the name used in arithmetical expressions. The name of the function in $0 is mathfn (not shellfn as would usually be the case), provided the option FUNCTION_ARGZERO is in effect. The positional parameters in the shell function correspond to the arguments of the mathematical function call.

The result of the last arithmetical expression evaluated inside the shell function gives the result of the mathematical function. This is not limited to arithmetic substitutions of the form tt($+(+()...++)), but also includes arithmetical expressions evaluated in any other way, including by the let builtin, by tt(+(+()...++)) statements, and even by the return builtin and by array subscripts. Therefore, care must be taken not to use syntactical constructs that perform arithmetic evaluation after evaluating what is to be the result of the function. For example:

findex(zmath_cube) findex(cube) example(# WRONG zmath_cube+(+) { (( $1 * $1 * $1 )) return 0 } functions -M cube 1 1 zmath_cube print $(( cube+(3+) )))

This will print "0" because of the return.

Commenting the return out would lead to a different problem: the tt(+(+()...++)) statement would become the last statement in the function, so the return status ($?) of the function would be non-zero (indicating failure) whenever the arithmetic result of the function would happen to be zero (numerically):

example(# WRONG zmath_cube+(+) { (( $1 * $1 * $1 )) } functions -M cube 1 1 zmath_cube print $(( cube+(0+) )))

Instead, the true builtin can be used:

example(# RIGHT zmath_cube+(+) { (( $1 * $1 * $1 )) true } functions -M cube 1 1 zmath_cube print $(( cube+(3+) )))

If the additional option -s is given to functions -M, the argument to the function is a single string: anything between the opening and matching closing parenthesis is passed to the function as a single argument, even if it includes commas or white space. The minimum and maximum argument specifiers must therefore be 1 if given. An empty argument list is passed as a zero-length string. Thus, the following string function takes a single argument, including the commas, and prints 11:

example(stringfn+() { (( $#1 )); true } functions -Ms stringfn print $(( stringfn+(foo,bar,rod+) )))

functions -M with no arguments lists all such user-defined functions in the same form as a definition. With the additional option -m and a list of arguments, all functions whose mathfn matches one of the pattern arguments are listed.

function +M removes the list of mathematical functions; with the additional option -m the arguments are treated as patterns and all functions whose mathfn matches the pattern are removed. Note that the shell function implementing the behaviour is not removed (regardless of whether its name coincides with mathfn).

getcap ¶

This is a built-in implementation of the POSIX standard utility. It displays the capability sets on each specified filename.

getln ¶

Read the top value from the buffer stack and put it in the shell parameter name. Equivalent to read -zr.

getopts ¶

Checks the _arg_s for legal options. If the _arg_s are 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. Note that a single "-" is not considered a valid option argument. optstring contains the letters that getopts recognizes. If a letter is followed by a ":", that option requires 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. vindex(OPTIND, use of) vindex(OPTARG, use of)

The first option to be examined may be changed by explicitly assigning to OPTIND. OPTIND has an initial value of 1, and is normally set to 1 upon entry to a shell function and restored upon exit. (The POSIX_BUILTINS option disables this, and also changes the way the value is calculated to match other shells.) OPTARG is not reset and retains its value from the most recent call to getopts. If either of OPTIND or OPTARG is explicitly unset, it remains unset, and the index or option argument is not stored. The option itself is still stored in name in this case.

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

hash ¶

hash can be used to directly modify the contents of the command hash table, and the named directory hash table. Normally one would modify these tables by modifying one's PATH (for the command hash table) or by creating appropriate shell parameters (for the named directory hash table). The choice of hash table to work on is determined by the -d option; without the option the command hash table is used, and with the option the named directory hash table is used.

A command name starting with a / or with a relative path starting with ./ or ../ is never executed by lookup in the command hash table, and these can only be added to the table by explicit use of the hash command. Such a command is always found by direct look up in the file system.

Given no arguments, and neither the -r or -f options, the selected hash table will be listed in full.

The -r option causes the selected hash table to be emptied. It will be subsequently rebuilt in the normal fashion. The -f option causes the selected hash table to be fully rebuilt immediately. For the command hash table this hashes all (and only) the absolute directories in the PATH, and for the named directory hash table this adds all users' home directories. These two options cannot be used with any arguments. Both options remove any explicitly-added elements.

The -m option causes the arguments to be taken as patterns (which should be quoted) and the elements of the hash table matching those patterns are printed. This is the only way to display a limited selection of hash table elements.

For each name with a corresponding value, put "name" in the selected hash table, associating it with the pathname "value". In the command hash table, this means that whenever "name" is used as a command argument, the shell will try to execute the file given by "value". In the named directory hash table, this means that "value" may be referred to as ~"name".

For each name with no corresponding value, attempt to add name to the hash table, checking what the appropriate value is in the normal manner for that hash table. If an appropriate value" can"t be found, then the hash table will be unchanged.

The -v option causes hash table entries to be listed as they are added by explicit specification. If has no effect if used with -f.

If the -L flag is present, then each hash table entry is printed in the form of a call to hash.

hashinfo ¶

Print internal hash-table statistics. Debug builtin in zsh/parameter-adjacent code.

history ¶

Search backward in the history for a line beginning with the current line up to the cursor. This leaves the cursor in its original position.

integer ¶

Equivalent to typeset -i, except that options irrelevant to integers are not permitted.

jobs ¶

Lists information about each given job, or all jobs if job is omitted. The -l flag lists process IDs, and the -p flag lists process groups. If the -r flag is specified only running jobs will be listed and if the -s flag is given only stopped jobs are shown. If the -d flag is given, the directory from which the job was started (which may not be the current directory of the job) will also be shown.

The -Z" option replaces the shell"s argument and environment space with the given string, truncated if necessary to fit. This will normally be visible in ps (manref(ps)(1)) listings. This feature is typically used by daemons, to indicate their state.

Full job control is only available in the top-level interactive shell, not in commands run in the left hand side of pipelines or within the tt(()...) construct. However, a snapshot of the job state at that point is taken, so it is still possible to use the jobs builtin, or any parameter providing job information. This gives information about the state of jobs at the point the subshell was created. If background processes are created within the subshell, then instead information about those processes is provided.

For example,

example(sleep 10 & # Job in background ( # Shell forks jobs # Shows information about "sleep 10 &" sleep 5 & # Process in background (no job control) jobs # Shows information about "sleep 5 &" ))

kill ¶

Sends either SIGTERM or the specified signal to the given jobs or processes. Signals are given by number or by names, with or without the "SIG" prefix. If the signal being sent is not "KILL" or "CONT", then the job will be sent a "CONT" signal if it is stopped. The argument job can be the process ID of a job not in the job list. In the second form, kill -l, if sig is not specified the signal names are listed. Otherwise, for each sig that is a name, the corresponding signal number is listed. For each sig that is a signal number or a number representing the exit status of a process which was terminated or stopped by a signal the name of the signal is printed. The final form with -L lists each signal name with its corresponding number.

On some systems, alternative signal names are allowed for a few signals. Typical examples are SIGCHLD and SIGCLD or SIGPOLL and SIGIO, assuming they correspond to the same signal number. kill -l will only list the preferred form, however kill -l alt will show if the alternative form corresponds to a signal number. For example, under Linux kill -l IO and kill -l POLL both output 29, hence kill -IO and kill -POLL have the same effect.

Many systems will allow process IDs to be negative to kill a process group or zero to kill the current process group.

The -q option allows an integer value to be sent with the signal on systems that support tt(sigqueue+()).

let ¶

Evaluate each arg as an arithmetic expression. See Arithmetic Evaluation (zshmisc) for a description of arithmetic expressions. The exit status is 0 if the value of the last expression is nonzero, 1 if it is zero, and 2 if an error occurred.

limit ¶

Set or display resource limits. Unless the -s flag is given, the limit applies only the children of the shell. If -s is given without other arguments, the resource limits of the current shell is set to the previously set resource limits of the children.

If limit is not specified, print the current limit placed on resource, otherwise set the limit to the specified value. If the -h flag is given, use hard limits instead of soft limits. If no resource is given, print all limits.

When looping over multiple resources, the shell will abort immediately if it detects a badly formed argument. However, if it fails to set a limit for some other reason it will continue trying to set the remaining limits.

resource can be one of:

- addressspace — Maximum amount of address space used. - aiomemorylocked — Maximum amount of memory locked in RAM for AIO operations. - aiooperations — Maximum number of AIO operations. - cachedthreads — Maximum number of cached threads. - coredumpsize — Maximum size of a core dump. - cputime — Maximum CPU seconds per process.

- datasize — Maximum data size (including stack) for each process.

- descriptors — Maximum value for a file descriptor. - filesize — Largest single file allowed. - kqueues — Maximum number of kqueues allocated. - maxfilelocks — Maximum number of file locks. - maxproc — Maximum number of processes. - maxpthreads — Maximum number of threads per process. - memorylocked — Maximum amount of memory locked in RAM. - memoryuse — Maximum resident set size. - msgqueue — Maximum number of bytes in POSIX message queues. - nice — Maximum nice value. - pipebuf — Maximum size of buffers for pipes/fifos. - posixlocks — Maximum number of POSIX locks per user. - pseudoterminals — Maximum number of pseudo-terminals. - resident — Maximum resident set size. - rt_priority — Maximum real-time priority. - rt_time — Maximum CPU time without a blocking system call. - sigpending — Maximum number of pending signals. - sockbufsize — Maximum size of all socket buffers. - stacksize — Maximum stack size for each process. - swapsize — Maximum amount of swap used. - umtxp — Maximum number of POSIX thread library objects. - vmemorysize — Maximum amount of virtual memory. - vnodemonitors — Maximum number of open vnode monitors.

Which of these resource limits are available depends on the system. resource can be abbreviated to any unambiguous prefix. It can also be an integer, which corresponds to the integer defined for the resource by the operating system.

If argument corresponds to a number which is out of the range of the resources configured into the shell, the shell will try to read or write the limit anyway, and will report an error if this fails. As the shell does not store such resources internally, an attempt to set the limit will fail unless the -s option is present.

limit is a number, with an optional scaling factor, as follows:

- nh — hours

- nk — kilobytes (default)

- nm — megabytes or minutes - ng — gigabytes - [mm:]ss — minutes and seconds

The limit command is not made available by default when the shell starts in a mode emulating another shell. It can be made available with the command "zmodload -F zsh/rlimits b:limit".

ln ¶

for symbolic links. If this has the special value target, symbolic links are dereferenced and the target file used to determine the display format.

local ¶

Same as typeset, except that the options -g, and -f are not permitted. In this case the -x option does not force the use of -g, i.e. exported variables will be local to functions.

log ¶

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

logout ¶

Same as exit, except that it only works in a login shell.

mem ¶

Print zsh memory-allocator statistics. Debug builtin compiled only with --enable-zsh-mem.

mkdir ¶

Creates directories. With the -p option, non-existing parent directories are first created if necessary, and there will be no complaint if the directory already exists. The -m option can be used to specify (in octal) a set of file permissions for the created directories, otherwise mode 777 modified by the current umask (see manref(umask)(2)) is used.

mv ¶

Moves files. In the first form, the specified filename is moved to the specified _dest_ination. In the second form, each of the _filename_s is taken in turn, and moved to a pathname in the specified _dir_ectory that has the same last pathname component.

By default, the user will be queried before replacing any file that the user cannot write to, but writable files will be silently removed. The -i option causes the user to be queried about replacing any existing files. The -f option causes any existing files to be silently deleted, without querying. -f takes precedence.

Note that this mv will not move files across devices. Historical versions of mv, when actual renaming is impossible, fall back on copying and removing files; if this behaviour is desired, use cp and rm manually. This may change in a future version.

nameref ¶

Equivalent to typeset -n pname=rname

However, nameref is a builtin command rather than a reserved word, so when rname uses subscript syntax it must be quoted against globbing. Subscripts in referenced parameters are not supported in ksh93, so this is not a significant compatibility issue.

noglob ¶

Filename generation (globbing) is not performed on any of the words.

patdebug ¶

Print pattern-matcher internals for a glob/regex. Debug builtin from zsh/pattern.

pcre_compile ¶

Compiles a perl-compatible regular expression.

Option -a will force the pattern to be anchored. Option -i will compile a case-insensitive pattern. Option -m will compile a multi-line pattern; that is, ^ and $ will match newlines within the pattern. Option -x will compile an extended pattern, wherein whitespace and # comments are ignored. Option -s makes the dot metacharacter match all characters, including those that indicate newline.

pcre_match ¶

Returns successfully if string matches the previously-compiled PCRE.

Upon successful match, if the expression captures substrings within parentheses, pcre_match will set the array match to those substrings, unless the -a option is given, in which case it will set the array arr. Similarly, the variable MATCH will be set to the entire matched portion of the string, unless the -v option is given, in which case the variable var will be set. Furthermore, any named captures will be stored in the associative array .pcre.match unless an alternative is given with -A. No variables are altered if there is no successful match. A -n option starts searching for a match from the byte offset position in string. If the -b option is given, the variable ZPCRE_OP will be set to an offset pair string, representing the byte offset positions of the entire matched portion within the string. For example, a ZPCRE_OP set to "32 45" indicates that the matched portion began on byte offset 32 and ended on byte offset 44. Here, byte offset position 45 is the position directly after the matched portion. Keep in mind that the byte position isn't necessarily the same as the character position when UTF-8 characters are involved. Consequently, the byte offset positions are only to be relied on in the context of using them for subsequent searches on string, using an offset position as an argument to the -n option. This is mostly used to implement the "find all non-overlapping matches" functionality.

A simple example of "find all non-overlapping matches":

example(string="The following zip codes: 78884 90210 99513" pcre_compile -m "\d{5}" accum=() pcre_match -b -- $string while [[ $? -eq 0 ]] do b=($=ZPCRE_OP) accum+=$MATCH pcre_match -b -n $b[2] -- $string done print -l $accum)

pcre_study ¶

Requests JIT compilation for the previously-compiled PCRE which may result in faster matching.

popd ¶

Remove an entry from the directory stack, and perform a cd to the new top directory. With no argument, the current top entry is removed. An argument of the form +"n" identifies a stack entry by counting from the left of the list shown by the dirs command, starting with zero. An argument of the form -n counts from the right. pindex(PUSHD_MINUS, use of) If the PUSHD_MINUS option is set, the meanings of "+" and "-" in this context are swapped.

If the -q (quiet) option is specified, the hook function chpwd and the functions in the array $chpwd_functions are not called, and the new directory stack is not printed. This is useful for calls to popd that do not change the environment seen by an interactive user.

print ¶

With the "-f" option the arguments are printed as described by printf. With no flags or with the flag "-", the arguments are printed on the standard output as described by echo, with the following differences: the escape sequence \M-"x" (or \M"x") metafies the character x (sets the highest bit), \C-"x" (or \C"x") produces a control character ("\C-@" and "\C-?" give the characters NULL and delete), a character code in octal is represented by \"NNN" (instead of \0"NNN"), and "\E" is a synonym for "\e". Finally, if not in an escape sequence, "\" escapes the following character and is not printed.

- -a — Print arguments with the column incrementing first. Only useful with the -c and -C options.

- -b — Recognize all the escape sequences defined for the bindkey command, see Zle Builtins (zshzle).

- -c — Print the arguments in columns. Unless -a is also given, arguments are printed with the row incrementing first.

- -C cols — Print the arguments in cols columns. Unless -a is also given, arguments are printed with the row incrementing first.

- -D — Treat the arguments as paths, replacing directory prefixes with ~ expressions corresponding to directory names, as appropriate.

- -i — If given together with -o or -O, sorting is performed case-independently.

- -l — Print the arguments separated by newlines instead of spaces. Note: if the list of arguments is empty, print -l will still output one empty line. To print a possibly-empty list of arguments one per line, use print -C1, as in "print -rC1 -- "$list[@]"".

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

- -n — Do not add a newline to the output.

- -N — Print the arguments separated and terminated by nulls. Again, print -rNC1 -- "$list[@]" is a canonical way to print an arbitrary list as null-delimited records.

- -o — Print the arguments sorted in ascending order.

- -O — Print the arguments sorted in descending order.

- -p — Print the arguments to the input of the coprocess.

- -P — Perform prompt expansion (see Expansion of Prompt Sequences (zshmisc)). In combination with "-f", prompt escape sequences are parsed only within interpolated arguments, not within the format string.

- -r — Ignore the escape conventions of echo.

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

- -s — Place the results in the history list instead of on the standard output. Each argument to the print command is treated as a single word in the history, regardless of its content.

- -S — Place the results in the history list instead of on the standard output. In this case only a single argument is allowed; it will be split into words as if it were a full shell command line. The effect is similar to reading the line from a history file with the HIST_LEX_WORDS option active.

- -u n — Print the arguments to file descriptor n.

- -v name — Store the printed arguments as the value of the parameter name.

- -x tab-stop — Expand leading tabs on each line of output in the printed string assuming a tab stop every tab-stop characters. This is appropriate for formatting code that may be indented with tabs. Note that leading tabs of any argument to print, not just the first, are expanded, even if print is using spaces to separate arguments (the column count is maintained across arguments but may be incorrect on output owing to previous unexpanded tabs).

The start of the output of each print command is assumed to be aligned with a tab stop. Widths of multibyte characters are handled if the option MULTIBYTE is in effect. This option is ignored if other formatting options are in effect, namely column alignment or printf style, or if output is to a special location such as shell history or the command line editor.

- -X tab-stop — This is similar to -x, except that all tabs in the printed string are expanded. This is appropriate if tabs in the arguments are being used to produce a table format.

- -z — Push the arguments onto the editing buffer stack, separated by spaces.

If any of "-m", "-o" or "-O" are used in combination with "-f" and there are no arguments (after the removal process in the case of "-m") then nothing is printed.

printf ¶

Print the arguments according to the format specification. Formatting rules are the same as used in C. The same escape sequences as for echo are recognised in the format. All C conversion specifications ending in one of csdiouxXeEfgGn are handled. In addition to this, "%b" can be used instead of "%s" to cause escape sequences in the argument to be recognised and "%q" can be used to quote the argument in such a way that allows it to be reused as shell input. With the numeric format specifiers, if the corresponding argument starts with a quote character, the numeric value of the following character is used as the number to print; otherwise the argument is evaluated as an arithmetic expression. See Arithmetic Evaluation (zshmisc) for a description of arithmetic expressions. With "%n", the corresponding argument is taken as an identifier which is created as an integer parameter.

Normally, conversion specifications are applied to each argument in order but they can explicitly specify the _n_th argument is to be used by replacing "%" by %_n_$' and "*" by *n$'. It is recommended that you do not mix references of this explicit style with the normal style and the handling of such mixed styles may be subject to future change.

If arguments remain unused after formatting, the format string is reused until all arguments have been consumed. With the print builtin, this can be suppressed by using the -r option. If more arguments are required by the format than have been specified, the behaviour is as if zero or an empty string had been specified as the argument.

The -v option causes the output to be stored as the value of the parameter name, instead of printed. If name is an array and the format string is reused when consuming arguments then one array element will be used for each use of the format string.

private ¶

The private builtin accepts all the same options and arguments as local (nmref(Shell Builtin Commands)(zshbuiltins)) except for the -"T" option. Tied parameters may not be made private.

The -"p" option is presently disabled because the state of private parameters cannot reliably be reloaded. When typeset -"p" outputs a private parameter, it is treated as a local with the -"h" (hide) option enabled.

If used at the top level (outside a function scope), private creates a normal parameter in the same manner as declare or typeset. A warning about this is printed if WARN_CREATE_GLOBAL is set (nmref(Options)(zshoptions)). Used inside a function scope, private creates a local parameter similar to one declared with local, except having special properties noted below.

Special parameters which expose or manipulate internal shell state, such as ARGC, argv, COLUMNS, LINES, UID, EUID, IFS, PROMPT, RANDOM, SECONDS, etc., cannot be made private unless the -"h" option is used to hide the special meaning of the parameter. This may change in the future.

pushd ¶

Change the current directory, and push the old current directory onto the directory stack. In the first form, change the current directory to arg. If arg is not specified, change to the second directory on the stack (that is, exchange the top two entries), or change to $HOME if the PUSHD_TO_HOME option is set or if there is only one entry on the stack. Otherwise, arg is interpreted as it would be by cd. The meaning of old and new in the second form is also the same as for cd.

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

If the -q (quiet) option is specified, the hook function chpwd and the functions in the array $chpwd_functions are not called, and the new directory stack is not printed. This is useful for calls to pushd that do not change the environment seen by an interactive user.

If the option -q is not specified and the shell option PUSHD_SILENT is not set, the directory stack will be printed after a pushd is performed.

The options -s, -L and -P have the same meanings as for the cd builtin.

pushln ¶

Equivalent to print -nz.

pwd ¶

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

r ¶

Re-execute the previous command. Shorthand for fc -e -.

read ¶

vindex(REPLY, use of) vindex(reply, use of) Read one line and break it into fields using the characters in $IFS as separators, except as noted below. 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 for scalars and reply for arrays.

- -r — Raw mode: a "\" at the end of a line does not signify line continuation and backslashes in the line don't quote the following character and are not removed.

- -s — Don't echo back characters if reading from the terminal.

- -q — Read only one character from the terminal and set name to "y" if this character was "y" or "Y" and to "n" otherwise. With this flag set the return status is zero only if the character was "y" or "Y". This option may be used with a timeout (see -t); if the read times out, or encounters end of file, status 2 is returned. Input is read from the terminal unless one of -u or -p is present. This option may also be used within zle widgets.

- -k [ num ] — Read only one (or num) characters. All are assigned to the first name, without word splitting. This flag is ignored when -q is present. Input is read from the terminal unless one of -u or -p is present. This option may also be used within zle widgets.

Note that despite the mnemonic "key" this option does read full characters, which may consist of multiple bytes if the option MULTIBYTE is set.

- -z — Read one entry from the editor buffer stack and assign it to the first name, without word splitting. Text is pushed onto the stack with "print -z" or with push-line from the line editor (see nmref(Zsh Line Editor)(zshzle)). This flag is ignored when the -k or -q flags are present.

- -e

- -E — The input read is printed (echoed) to the standard output. If the -e flag is used, no input is assigned to the parameters.

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

- -c

- -l — These flags are allowed only if called inside a function used for completion (specified with the -K flag to compctl). If the -c flag is given, the words of the current command are read. If the -l flag is given, the whole line is assigned as a scalar. If both flags are present, -l is used and -c is ignored.

- -n — Together with -c, the number of the word the cursor is on is read. With -l, the index of the character the cursor is on is read. Note that the command name is word number 1, not word 0, and that when the cursor is at the end of the line, its character index is the length of the line plus one.

- -u n — Input is read from file descriptor n.

- -p — Input is read from the coprocess.

- -d delim — Input is terminated by the first character of delim instead of by newline. For compatibility with other shells, if delim is an empty string, input is terminated at the first NUL.

- -t [ num ] — Test if input is available before attempting to read. If num is present, it must begin with a digit and will be evaluated to give a number of seconds, which may be a floating point number; in this case the read times out if input is not available within this time. If num is not present, it is taken to be zero, so that read returns immediately if no input is available. If no input is available, return status 1 and do not set any variables. ifzman( ) This option is not available when reading from the editor buffer with -z, when called from within completion with -c or -l, with -q which clears the input queue before reading, or within zle where other mechanisms should be used to test for input. ifzman( ) Note that read does not attempt to alter the input processing mode. The default mode is canonical input, in which an entire line is read at a time, so usually "read -t" will not read anything until an entire line has been typed. However, when reading from the terminal with -k input is processed one key at a time; in this case, only availability of the first character is tested, so that e.g. "read -t -k 2" can still block on the second character. Use two instances of "read -t -k" if this is not what is wanted.

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 value (exit status) of read is 1 when an end-of-file is encountered, or when -c or -l is present and the command is not called from a compctl function, or as described for -q. Otherwise the value is 0.

The behavior of some combinations of the -k, -p, -q, -u and -z flags is undefined. Presently -q cancels all the others, -p cancels -u, -k cancels -z, and otherwise -z cancels both -p and -u.

The -c or -l flags cancel any and all of -kpquz.

readonly ¶

Same as typeset -r. With the POSIX_BUILTINS option set, same as typeset -gr.

rehash ¶

If this is set when completing external commands, the internal list (hash) of commands will be updated for each search by issuing the rehash command. There is a speed penalty for this which is only likely to be noticeable when directories in the path have slow file access.

return ¶

Causes a shell function or "." script to return to the invoking script with the return status specified by an arithmetic expression n. Also causes a non-interactive shell to exit, allowing files containing shell code to be used both as scripts and as autoloadable shell functions. For example, the following prints "42":

example(() { integer foo=40; return "foo + 2" } echo $?)

If n is omitted, the return status is that of the last command executed.

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

rm ¶

Removes files and directories specified.

Normally, rm will not remove directories (except with the -R or -r options). The -d option causes rm to try removing directories with unlink (see manref(unlink)(2)), the same method used for files. Typically only the super-user can actually succeed in unlinking directories in this way. -d takes precedence over -R and -r.

By default, the user will be queried before removing any file that the user cannot write to, but writable files will be silently removed. The -i option causes the user to be queried about removing any files. The -f option causes files to be silently deleted, without querying, and suppresses all error indications. -f takes precedence.

The -R and -r options cause rm to recursively descend into directories, deleting all files in the directory before removing the directory with the rmdir system call (see manref(rmdir)(2)).

The -s option is a zsh extension to rm functionality. It enables paranoid behaviour, intended to avoid common security problems involving a root-run rm being tricked into removing files other than the ones intended. It will refuse to follow symbolic links, so that (for example) ""rm /tmp/foo/passwd"" can't accidentally remove /etc/passwd if /tmp/foo happens to be a link to /etc. It will also check where it is after leaving directories, so that a recursive removal of a deep directory tree can't end up recursively removing /usr as a result of directories being moved up the tree.

rmdir ¶

Removes empty directories specified.

sched ¶

Make an entry in the scheduled list of commands to execute. The time may be specified in either absolute or relative time, and either as hours, minutes and (optionally) seconds separated by a colon, or seconds alone. An absolute number of seconds indicates the time since the epoch (1970/01/01 00:00); this is useful in combination with the features in the zsh/datetime module, see The zsh/datetime Module (zshmodules).

With no arguments, prints the list of scheduled commands. If the scheduled command has the -o flag set, this is shown at the start of the command.

With the argument -"item", removes the given item from the list. The numbering of the list is continuous and entries are in time order, so the numbering can change when entries are added or deleted.

Commands are executed either immediately before a prompt, or while the shell's line editor is waiting for input. In the latter case it is useful to be able to produce output that does not interfere with the line being edited. Providing the option -o causes the shell to clear the command line before the event and redraw it afterwards. This should be used with any scheduled event that produces visible output to the terminal; it is not needed, for example, with output that updates a terminal emulator's title bar.

To effect changes to the editor buffer when an event executes, use the "zle" command with no arguments to test whether the editor is active, and if it is, then use zle "widget" to access the editor via the named widget.

The sched builtin is not made available by default when the shell starts in a mode emulating another shell. It can be made available with the command "zmodload -F zsh/sched b:sched".

set ¶

Set the options for the shell and/or set the positional parameters, or declare and set an array. If the -s option is given, it causes the specified arguments to be sorted before assigning them to the positional parameters (or to the array name if -A is used). With +s sort arguments in descending order. For the meaning of the other flags, see nmref(Options)(zshoptions). Flags may be specified by name using the -o option. If no option name is supplied with -o, the current option states are printed: see the description of setopt below for more information on the format. With +o they are printed in a form that can be used as input to the shell.

If the -A flag is specified, name is set to an array containing the given _arg_s; if no name is specified, all arrays are printed together with their values.

If +A is used and name is an array, the given arguments will replace the initial elements of that array; if no name is specified, all arrays are printed without their values.

The behaviour of arguments after -A name or +A name depends on whether the option KSH_ARRAYS is set. If it is not set, all arguments following name are treated as values for the array, regardless of their form. If the option is set, normal option processing continues at that point; only regular arguments are treated as values for the array. This means that

set -A array -x -- foo

sets array to -x -"- foo" if KSH_ARRAYS is not set, but sets the array to foo and turns on the option "-x" if it is set.

If the -A flag is not present, but there are arguments beyond the options, the positional parameters are set. If the option list (if any) is terminated by -"-", and there are no further arguments, the positional parameters will be unset.

If no arguments and no -"-" are given, then the names and values of all parameters are printed on the standard output. If the only argument is "+", the names of all parameters are printed.

For historical reasons, "set -" is treated as "set +xv" and set -" args" as set +xv --" args" when in any other emulation mode than zsh's native mode.

setcap ¶

This is a built-in implementation of the POSIX standard utility. It sets the capability sets on each specified filename to the specified capabilities.

setopt ¶

Set the options for the shell. All options specified either with flags or by name are set.

If no arguments are supplied, the names of all options currently set are printed. The form is chosen so as to minimize the differences from the default options for the current emulation (the default emulation being native zsh, shown as <Z> in Description of Options (zshoptions)). Options that are on by default for the emulation are shown with the prefix no only if they are off, while other options are shown without the prefix no and only if they are on. In addition to options changed from the default state by the user, any options activated automatically by the shell (for example, SHIN_STDIN or INTERACTIVE) will be shown in the list. The format is further modified by the option KSH_OPTION_PRINT, however the rationale for choosing options with or without the no prefix remains the same in this case.

If the -m flag is given the arguments are taken as patterns (which should be quoted to protect them from filename expansion), and all options with names matching these patterns are set.

Note that a bad option name does not cause execution of subsequent shell code to be aborted; this is behaviour is different from that of set -o'. This is because set is regarded as a special builtin by the POSIX standard, but setopt is not.

shift ¶

The positional parameters ${n+1tt(}) ... are renamed to $1 ..., where n is an arithmetic expression that defaults to 1. If any _name_s are given then the arrays with these names are shifted instead of the positional parameters.

If the option -p is given arguments are instead removed (popped) from the end rather than the start of the array.

source ¶

Same as ".", except that the current directory is always searched and is always searched first, before directories in $path.

stat ¶

The command acts as a front end to the stat system call (see manref(stat)(2)). The same command is provided with two names; as the name stat is often used by an external command it is recommended that only the zstat form of the command is used. This can be arranged by loading the module with the command zmodload -F zsh/stat b:zstat'.

If the stat call fails, the appropriate system error message printed and status 1 is returned. The fields of struct stat give information about the files provided as arguments to the command. In addition to those available from the stat call, an extra element "link" is provided. These elements are:

- device — The number of the device on which the file resides.

- inode — The unique number of the file on this device ("inode" number).

- mode — The mode of the file; that is, the file's type and access permissions. With the -s option, this will be returned as a string corresponding to the first column in the display of the ls -l command.

- nlink — The number of hard links to the file.

- uid — The user ID of the owner of the file. With the -s option, this is displayed as a user name.

- gid — The group ID of the file. With the -s option, this is displayed as a group name.

- rdev — The raw device number. This is only useful for special devices.

- size — The size of the file in bytes.

- atime

- mtime

- ctime — The last access, modification and inode change times of the file, respectively, as the number of seconds since midnight GMT on 1st January, 1970. With the -s option, these are printed as strings for the local time zone; the format can be altered with the -F option, and with the -g option the times are in GMT.

- blksize — The number of bytes in one allocation block on the device on which the file resides.

- block — The number of disk blocks used by the file.

- link — If the file is a link and the -L option is in effect, this contains the name of the file linked to, otherwise it is empty. Note that if this element is selected (""zstat +link"") then the -L option is automatically used.

A particular element may be selected by including its name preceded by a "+" in the option list; only one element is allowed. The element may be shortened to any unique set of leading characters. Otherwise, all elements will be shown for all files.

Options:

- -A array — Instead of displaying the results on standard output, assign them to an array, one struct stat element per array element for each file in order. In this case neither the name of the element nor the name of the files appears in array unless the -t or -n options were given, respectively. If -t is given, the element name appears as a prefix to the appropriate array element; if -n is given, the file name appears as a separate array element preceding all the others. Other formatting options are respected.

- -H hash — Similar to -A, but instead assign the values to hash. The keys are the elements listed above. If the -n option is provided then the name of the file is included in the hash with key name.

- -f fd — Use the file on file descriptor fd instead of named files; no list of file names is allowed in this case.

- -F fmt — Supplies a strftime (see manref(strftime)(3)) string for the formatting of the time elements. The format string supports all of the zsh extensions (see the description of %D{string} prompt escape in Simple Prompt Escapes (zshmisc)). In particular, -F %s.%N can be used to show timestamps with nanosecond precision if supported by the system. The -s option is implied.

- -g — Show the time elements in the GMT time zone. The -s option is implied.

- -l — List the names of the type elements (to standard output or an array as appropriate) and return immediately; arguments, and options other than -A, are ignored.

- -L — Perform an lstat (see manref(lstat)(2)) rather than a stat system call. In this case, if the file is a link, information about the link itself rather than the target file is returned. This option is required to make the link element useful. It's important to note that this is the exact opposite from manref(ls)(1), etc.

- -n — Always show the names of files. Usually these are only shown when output is to standard output and there is more than one file in the list.

- -N — Never show the names of files.

- -o — If a raw file mode is printed, show it in octal, which is more useful for human consumption than the default of decimal. A leading zero will be printed in this case. Note that this does not affect whether a raw or formatted file mode is shown, which is controlled by the -r and -s options, nor whether a mode is shown at all.

- -r — Print raw data (the default format) alongside string data (the -s format); the string data appears in parentheses after the raw data.

- -s — Print mode, uid, gid and the three time elements as strings instead of numbers. In each case the format is like that of ls -l.

- -t — Always show the type names for the elements of struct stat. Usually these are only shown when output is to standard output and no individual element has been selected.

- -T — Never show the type names of the struct stat elements.

strftime ¶

Output the date in the format specified. With no epochtime, the current system date/time is used; optionally, epochtime may be used to specify the number of seconds since the epoch, and nanoseconds may additionally be used to specify the number of nanoseconds past the second (otherwise that number is assumed to be 0). See manref(strftime)(3) for details. The zsh extensions described under %D{string} prompt eqcape in Simple Prompt Escapes (zshmisc) are also available.

- -n — Suppress printing a newline after the formatted string.

- -q — Run quietly; suppress printing of all error messages described below. Errors for invalid epochtime values are always printed.

- -r — With the option -r (reverse), use format to parse the input string timestring and output the number of seconds since the epoch at which the time occurred. The parsing is implemented by the system function strptime; see manref(strptime)(3). This means that zsh format extensions are not available, but for reverse lookup they are not required.

In most implementations of strptime any timezone in the timestring is ignored and the local timezone declared by the TZ environment variable is used; other parameters are set to zero if not present.

If timestring does not match format the command returns status 1 and prints an error message. If timestring matches format but not all characters in timestring were used, the conversion succeeds but also prints an error message.

If either of the system functions strptime or mktime is not available, status 2 is returned and an error message is printed.

- -s scalar — Assign the date string (or epoch time in seconds if -r is given) to scalar instead of printing it.

Note that depending on the system's declared integral time type, strftime may produce incorrect results for epoch times greater than 2147483647 which corresponds to 2038-01-19 03:14:07 +0000.

suspend ¶

Suspend the execution of the shell (send it a SIGTSTP) until it receives a SIGCONT. Unless the -f option is given, this will refuse to suspend a login shell.

sync ¶

Calls the system call of the same name (see manref(sync)(2)), which flushes dirty buffers to disk. It might return before the I/O has actually been completed.

syserror ¶

This command prints out the error message associated with errno, a system error number, followed by a newline to standard error.

Instead of the error number, a name errname, for example ENOENT, may be used. The set of names is the same as the contents of the array errnos, see below.

If the string prefix is given, it is printed in front of the error message, with no intervening space.

If errvar is supplied, the entire message, without a newline, is assigned to the parameter names errvar and nothing is output.

A return status of 0 indicates the message was successfully printed (although it may not be useful if the error number was out of the system's range), a return status of 1 indicates an error in the parameters, and a return status of 2 indicates the error name was not recognised (no message is printed for this).

sysopen ¶

This command opens a file. The -r, -w and -a flags indicate whether the file should be opened for reading, writing and appending, respectively. The -m option allows the initial permissions to use when creating a file to be specified in octal form. The file descriptor is specified with -u. Either an explicit file descriptor in the range 0 to 9 can be specified or a variable name can be given to which the file descriptor number will be assigned.

The -o option allows various system specific options to be specified as a comma-separated list. The following is a list of possible options. Note that, depending on the system, some may not be available.

- cloexec — mark file to be closed when other programs are executed (else the file descriptor remains open in subshells and forked external executables)

- create

- creat — create file if it does not exist

- excl — create file, error if it already exists

- noatime — suppress updating of the file atime

- nofollow — fail if file is a symbolic link

- nonblock — the file is opened in nonblocking mode

- sync — request that writes wait until data has been physically written

- truncate

- trunc — truncate file to size 0

A return status of 0 indicates the descriptor was successfully opened, otherwise an error message is printed, and 1 is returned for an error in the parameters to the command, or 2 is returned for a system error. The parameter ERRNO is nonzero for system errors.

To close the file, use one of the following:

exec {fd}<&- exec {fd}>&-

sysread ¶

Perform a single system read from file descriptor infd, or zero if that is not given. The result of the read is stored in param or REPLY if that is not given. If countvar is given, the number of bytes read is assigned to the parameter named by countvar.

The maximum number of bytes read is bufsize or 8192 if that is not given, however the command returns as soon as any number of bytes was successfully read.

If timeout is given, it specifies a timeout in seconds, which may be zero to poll the file descriptor. This is handled by the poll system call if available, otherwise the select system call if available.

If outfd is given, an attempt is made to write all the bytes just read to the file descriptor outfd. If this fails, because of a system error other than EINTR or because of an internal zsh error during an interrupt, the bytes read but not written are stored in the parameter named by param if supplied (no default is used in this case), and the number of bytes read but not written is stored in the parameter named by countvar if that is supplied. If it was successful, countvar contains the full number of bytes transferred, as usual, and param is not set.

The error EINTR (interrupted system call) is handled internally so that shell interrupts are transparent to the caller. Any other error causes a return.

The possible return statuses are

- 0 — At least one byte of data was successfully read and, if appropriate, written.

- 1 — There was an error in the parameters to the command. This is the only error for which a message is printed to standard error.

- 2 — There was an error on the read, or on polling the input file descriptor for a timeout. The parameter ERRNO identifies the error.

- 3 — Data were successfully read, but there was an error writing them to outfd. The parameter ERRNO identifies the error.

- 4 — The attempt to read timed out. Note this does not set ERRNO as this is not a system error.

- 5 — No system error occurred, but zero bytes were read. This usually indicates end of file. The parameters are set according to the usual rules; no write to outfd is attempted.

sysseek ¶

The current file position at which future reads and writes will take place is adjusted to the specified byte offset. The offset is evaluated as a math expression. The -u option allows the file descriptor to be specified. By default the offset is specified relative to the start or the file but, with the -w option, it is possible to specify that the offset should be relative to the current position or the end of the file.

The return status may be 0 for success, 1 for an error in the parameters to the command, or 2 for an error on the seek; no error message is printed in the last case, but the parameter ERRNO reflects the error that occurred.

syswrite ¶

The data (a single string of bytes) are written to the file descriptor outfd, or 1 if that is not given, using the write system call. Multiple write operations may be used if the first does not write all the data.

If countvar is given, the number of byte written is stored in the parameter named by countvar; this may not be the full length of data if an error occurred.

The error EINTR (interrupted system call) is handled internally by retrying; otherwise an error causes the command to return. For example, if the file descriptor is set to non-blocking output, an error EAGAIN (on some systems, EWOULDBLOCK) may result in the command returning early.

The return status may be 0 for success, 1 for an error in the parameters to the command, or 2 for an error on the write; no error message is printed in the last case, but the parameter ERRNO reflects the error that occurred.

test ¶

Like the system version of test. Added for compatibility; use conditional expressions instead (see Conditional Expressions (zshmisc)). The main differences between the conditional expression syntax and the test and [ builtins are: these commands are not handled syntactically, so for example an empty variable expansion may cause an argument to be omitted; syntax errors cause status 2 to be returned instead of a shell error; and arithmetic operators expect integer arguments rather than arithmetic expressions.

The command attempts to implement POSIX and its extensions where these are specified. Unfortunately there are intrinsic ambiguities in the syntax; in particular there is no distinction between test operators and strings that resemble them. The standard attempts to resolve these for small numbers of arguments (up to four); for five or more arguments compatibility cannot be relied on. Users are urged wherever possible to use the "[[" test syntax which does not have these ambiguities.

times ¶

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

trap ¶

arg is a series of commands (usually quoted to protect it from immediate evaluation by the shell) to be read and executed when the shell receives any of the signals specified by one or more sig args. Each sig can be given as a number, or as the name of a signal either with or without the string SIG in front (e.g. 1, HUP, and SIGHUP are all the same signal).

If arg is "-", then the specified signals are reset to their defaults, or, if no sig args are present, all traps are reset.

If arg is an empty string, then the specified signals are ignored by the shell (and by the commands it invokes).

If arg is omitted but one or more sig args are provided (i.e. the first argument is a valid signal number or name), the effect is the same as if arg had been specified as "-".

The trap command with no arguments prints a list of commands associated with each signal.

If sig is ZERR then arg will be executed after each command with a nonzero exit status. ERR is an alias for ZERR on systems that have no SIGERR signal (this is the usual case).

If sig is DEBUG then arg will be executed before each command if the option DEBUG_BEFORE_CMD is set (as it is by default), else after each command. Here, a "command" is what is described as a "sublist" in the shell grammar, see Simple Commands & Pipelines (zshmisc). If DEBUG_BEFORE_CMD is set various additional features are available. First, it is possible to skip the next command by setting the option ERR_EXIT; see the description of the ERR_EXIT option in nmref(Description of Options)(zshoptions). Also, the shell parameter ZSH_DEBUG_CMD is set to the string corresponding to the command to be executed following the trap. Note that this string is reconstructed from the internal format and may not be formatted the same way as the original text. The parameter is unset after the trap is executed.

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. The value of $? at the start of execution is the exit status of the shell or the return status of the function exiting. 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 runs before any zshexit hook functions.

ZERR, DEBUG, and EXIT traps are not executed inside other traps. ZERR and DEBUG traps are kept within subshells, while other traps are reset.

Note that traps defined with the trap builtin are slightly different from those defined as TRAP"NAL () { ... }", as the latter have their own function environment (line numbers, local variables, etc.) while the former use the environment of the command in which they were called. For example,

trap 'print $LINENO' DEBUG

will print the line number of a command executed after it has run, while

example(TRAPDEBUG+() { print $LINENO; })

will always print the number zero.

Alternative signal names are allowed as described under kill above. Defining a trap under either name causes any trap under an alternative name to be removed. However, it is recommended that for consistency users stick exclusively to one name or another.

true ¶

Do nothing and return an exit status of 0.

ttyctl ¶

The -f option freezes the tty (i.e. terminal or terminal emulator), 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, except for changes in the size of the screen; the shell will simply reset the settings to their previous values as soon as each command exits or is suspended. Thus, stty and similar programs have no effect when the tty is frozen. Freezing the tty does not cause the current state to be remembered: instead, it causes future changes to the state to be blocked.

Without options it reports whether the terminal is frozen or not.

Note that, regardless of whether the tty is frozen or not, the shell needs to change the settings when the line editor starts, so unfreezing the tty does not guarantee settings made on the command line are preserved. Strings of commands run between editing the command line will see a consistent tty state. See also the shell variable STTY for a means of initialising the tty before running external commands and/or freezing the tty around a single command.

type ¶

Equivalent to whence -v.

typeset ¶

Set or display attributes and values for shell parameters.

Except as noted below for control flags that change the behavior, a parameter is created for each name that does not already refer to one. When inside a function, a new parameter is created for every name (even those that already exist), and is unset again when the function completes. See Local Parameters (zshparam). The same rules apply to special shell parameters, which retain their special attributes when made local.

For each name=value assignment, the parameter name is set to value. If the assignment is omitted and name does not refer to an existing parameter, a new parameter is initialized to empty string, zero, or empty array (as appropriate), unless the shell option TYPESET_TO_UNSET is set. When that option is set, the parameter attributes are recorded but the parameter remains unset.

If the shell option TYPESET_SILENT is not set, for each remaining name that refers to a parameter that is already set, the name and value of the parameter are printed in the form of an assignment. Nothing is printed for newly-created parameters, or when any attribute flags listed below are given along with the name. Using "+" instead of minus to introduce an attribute turns it off.

If no name is present, the names and values of all parameters are printed. In this case the attribute flags restrict the display to only those parameters that have the specified attributes, and using "+" rather than "-" to introduce the flag suppresses printing of the values of parameters when there is no parameter name.

All forms of the command handle scalar assignment. Array assignment is possible if any of the reserved words declare, export, float, integer, local, readonly or typeset is matched when the line is parsed (N.B. not when it is executed). In this case the arguments are parsed as assignments, except that the "+=" syntax and the GLOB_ASSIGN option are not supported, and scalar values after = are not split further into words, even if expanded (regardless of the setting of the KSH_TYPESET option; this option is obsolete).

Examples of the differences between command and reserved word parsing:

example(# Reserved word parsing typeset svar=$(echo one word) avar=(several words))

The above creates a scalar parameter svar and an array parameter avar as if the assignments had been

example(svar="one word" avar=(several words))

On the other hand:

example(# Normal builtin interface builtin typeset svar=$(echo two words))

The builtin keyword causes the above to use the standard builtin interface to typeset in which argument parsing is performed in the same way as for other commands. This example creates a scalar svar containing the value two and another scalar parameter words with no value. An array value in this case would either cause an error or be treated as an obscure set of glob qualifiers.

Arbitrary arguments are allowed if they take the form of assignments after command line expansion; however, these only perform scalar assignment:

var='svar=val' typeset $var

The above sets the scalar parameter svar to the value val. Parentheses around the value within var would not cause array assignment as they will be treated as ordinary characters when $var is substituted. Any non-trivial expansion in the name part of the assignment causes the argument to be treated in this fashion:

typeset {var1,var2,var3}=name

The above syntax is valid, and has the expected effect of setting the three parameters to the same value, but the command line is parsed as a set of three normal command line arguments to typeset after expansion. Hence it is not possible to assign to multiple arrays by this means.

Note that each interface to any of the commands may be disabled separately. For example, "disable -r typeset" disables the reserved word interface to typeset, exposing the builtin interface, while "disable typeset" disables the builtin. Note that disabling the reserved word interface for typeset may cause problems with the output of "typeset -p", which assumes the reserved word interface is available in order to restore array and associative array values.

Unlike parameter assignment statements, typeset's exit status on an assignment that involves a command substitution does not reflect the exit status of the command substitution. Therefore, to test for an error in a command substitution, separate the declaration of the parameter from its initialization:

example(# WRONG typeset var1=$(exit 1) || echo "Trouble with var1"

# RIGHT typeset var1 && var1=$(exit 1) || echo "Trouble with var1" )

To initialize a parameter param to a command output and mark it readonly, use typeset -r param or readonly param after the parameter assignment statement.

cindex(named reference) cindex(reference, named) The flag -n creates a named reference to another parameter. The second parameter need not exist at the time the reference is created. Only the -H, -g, and -r flags may be used in conjunction with -n, having their usual meanings. The -u flag is special and may be applied to alter the scope of the reference. The name so created may not be an array element nor use a subscript, but the value assigned may be any valid parameter name syntax, even a subscripted array element (including an associative array element) or an array slice, which is evaluated when the named reference is expanded. It is an error for a named reference to refer to itself, even indirectly through a chain of references. When -u is applied to a named reference, the parameter identified by value is always found in the calling function scope rather than the current local scope. In this case, if there is no such parameter in the calling scope, assignments to the named reference may fail, setting $? to 1. See Parameter Expansion (zshexpn) and Named References (zshparam) for details of the behavior of named references.

Local function scoping rules for "typeset" do apply with "-n", so a declaration within a function persists only until the end of the function unless "-g -n" is specified, and any local parameter (of any type) with the same name supplants a named reference from a surrounding scope.

A scalar parameter, including an existing named reference, may be converted to a new named reference by typeset -n "name", so the "-p" option must be included to display the value of a specific named reference name.

If no attribute flags are given, and either no name arguments are present or the flag +m is used, then each parameter name printed is preceded by a list of the attributes of that parameter (array, association, exported, float, integer, readonly, or undefined for autoloaded parameters not yet loaded). If +m is used with attribute flags, and all those flags are introduced with +, the matching parameter names are printed but their values are not.

The following control flags change the behavior of typeset:

- + — If "+" appears by itself in a separate word as the last option, then the names of all parameters (functions with -f) are printed, but the values (function bodies) are not. If name arguments appear, both those names and their values are printed in the form of assignments. It is an error for any other options to follow "+", but the effect of "+" is as if all attribute flags which precede it were given with a "+" prefix. For example, "typeset -U +" is equivalent to "typeset +U" and displays the names of all arrays having the uniqueness attribute, whereas "typeset -f -U +" displays the names of all autoloadable functions. If + is the only option, then type information (array, readonly, etc.) is also printed for each parameter, in the same manner as "typeset +m "*"".

- -g — The -g (global) means that any resulting parameter will not be restricted to local scope. Note that this does not necessarily mean that the parameter will be global, as the flag will apply to any existing parameter (even if unset) from an enclosing function. This flag does not affect the parameter after creation, hence it has no effect when listing existing parameters, nor does the flag +g have any effect except in combination with -m (see below).

- -m — If the -m flag is given the name arguments are taken as patterns (use quoting to prevent these from being interpreted as file patterns). With no attribute flags, all parameters (or functions with the -f flag) with matching names are printed (the shell option TYPESET_SILENT is not used in this case).

If the +g flag is combined with -m, a new local parameter is created for every matching parameter that is not already local. Otherwise -m applies all other flags or assignments to the existing parameters, except that the -n option cannot create named references in this way.

Except when assignments are made with name=value, using +m forces the matching parameters and their attributes to be printed, even inside a function. Note that -m is ignored if no patterns are given, so "typeset -m" displays attributes but "typeset -a +m" does not. Ordinary scalar string parameters have no attributes, so for those +m prints only the names.

- -p [ n ] — If the -p option is given, parameters and values are printed in the form of a typeset command with an assignment, regardless of other flags and options. Note that the -H flag on parameters is respected; no value will be shown for these parameters.

-p may be followed by an optional integer argument. Currently only the value 1 is supported. In this case arrays and associative arrays are printed with newlines between indented elements for readability.

The names and values of readonly special parameters (most of the parameters marked "<S>" in Parameters Set by the Shell (zshparam), except those documented as settable) are not printed with -"p" because to execute those typeset commands would cause errors. However, these parameters are printed when they have been made local to the scope where "typeset -p" is run.

- -T [ scalar[=value] array[=()_value_ ...] [ sep ] ] — This flag has a different meaning when used with -f; see below. Otherwise the -T option requires zero, two, or three arguments to be present. With no arguments, the list of parameters created in this fashion is shown. With two or three arguments, the first two are the name of a scalar and of an array parameter (in that order) that will be tied together in the manner of $PATH and $path. The optional third argument is a single-character separator which will be used to join the elements of the array to form the scalar; if absent, a colon is used, as with $PATH. Only the first character of the separator is significant; any remaining characters are ignored. Multibyte characters are not yet supported.

Only one of the scalar and array parameters may be assigned an initial value (the restrictions on assignment forms described above also apply).

Both the scalar and the array may be manipulated as normal. If one is unset, the other will automatically be unset too. There is no way of untying the variables without unsetting them, nor of converting the type of one of them with another typeset command; +T does not work, assigning an array to scalar is an error, and assigning a scalar to array sets it to be a single-element array.

Note that both "typeset -xT ..." and "export -T ..." work, but only the scalar will be marked for export. Setting the value using the scalar version causes a split on all separators (which cannot be quoted). It is possible to apply -T to two previously tied variables but with a different separator character, in which case the variables remain joined as before but the separator is changed.

When an existing scalar is tied to a new array, the value of the scalar is preserved but no attribute other than export will be preserved.

Attribute flags that transform the final value (-L, -R, -Z, -l, -u) are only applied to the expanded value at the point of a parameter expansion expression using "$". They are not applied when a parameter is retrieved internally by the shell for any purpose.

The following attribute flags may be specified:

- -A — The names refer to associative array parameters; see Array Parameters (zshparam).

- -L [ n ] — Left justify and remove leading blanks from the value when the parameter is expanded. If n is nonzero, it defines the width of the field. If n is zero, the width is determined by the width of the value of the first assignment. In the case of numeric parameters, the length of the complete value assigned to the parameter is used to determine the width, not the value that would be output.

The width is the count of characters, which may be multibyte characters if the MULTIBYTE option is in effect. Note that the screen width of the character is not taken into account; if this is required, use padding with parameter expansion flags tt(${+(ml)...)...} as described in subref(Parameter Expansion Flags)(zshexpn).

When the parameter is expanded, it is filled on the right with blanks or truncated if necessary to fit the field. Note truncation can lead to unexpected results with numeric parameters. Leading zeros are removed if the -Z flag is also set.

- -R [ n ] — Similar to -L, except that right justification is used; when the parameter is expanded, the field is left filled with blanks or truncated from the end. May not be combined with the -Z flag.

- -U — For arrays (but not for associative arrays), keep only the first occurrence of each duplicated value. This may also be set for tied parameters (see -T) or colon-separated special parameters like PATH or FIGNORE, etc. Note the flag takes effect on assignment, and the type of the variable being assigned to is determinative; for variables with shared values it is therefore recommended to set the flag for all interfaces, e.g. "typeset -U PATH path".

This flag has a different meaning when used with -f; see below.

- -Z [ n ] — Specially handled if set along with the -L flag. Otherwise, similar to -R, except that leading zeros are used for padding instead of blanks if the first non-blank character is a digit. Numeric parameters are specially handled: they are always eligible for padding with zeroes, and the zeroes are inserted at an appropriate place in the output.

- -a — The names refer to array parameters. An array parameter may be created this way, but it may be assigned to in the typeset statement only if the reserved word form of typeset is enabled (as it is by default). When displaying, both normal and associative arrays are shown.

- -f — The names refer to functions rather than parameters. No assignments can be made, and the only other valid flags are -t, -T, -k, -u, -U and -z. The flag -t turns on execution tracing for this function; the flag -T does the same, but turns off tracing for any named (not anonymous) function called from the present one, unless that function also has the -t or -T flag. The -u and -U flags cause the function to be marked for autoloading; -U also causes alias expansion to be suppressed when the function is loaded. See the description of the "autoload" builtin for details.

Note that the builtin functions provides the same basic capabilities as typeset -f but gives access to a few extra options; autoload gives further additional options for the case typeset -fu and typeset -fU.

- -h — Hide: only useful for special parameters (those marked "<S>" in the table in Parameters Set by the Shell (zshparam)), and for local parameters with the same name as a special parameter, though harmless for others. A special parameter with this attribute will not retain its special effect when made local. Thus after typeset -h PATH', a function containing "typeset PATH" will create an ordinary local parameter without the usual behaviour of PATH. Alternatively, the local parameter may itself be given this attribute; hence inside a function "typeset -h PATH" creates an ordinary local parameter and the special PATH parameter is not altered in any way. It is also possible to create a local parameter using typeset +h "_special_", where the local copy of _special_ will retain its special properties regardless of having the -h attribute. Global special parameters loaded from shell modules (for example, those in zsh/mapfile and zsh/parameter) are automatically given the -h attribute to avoid name clashes.

- -H — Hide value: specifies that typeset will not display the value of the parameter when listing parameters; the display for such parameters is always as if the "+" flag were given, but use of the parameter is in other respects normal. This effect does not apply when the parameter is specified by name or by pattern with the -m option. This is on by default for the parameters in the zsh/parameter and zsh/mapfile modules. Note, however, that unlike the -h flag this is also useful for non-special parameters.

- -i [ n ] — Use an internal integer representation. If n is nonzero it defines the output arithmetic base, otherwise it is determined by the first assignment. Bases from 2 to 36 inclusive are allowed.

- -E [ n ] — Use an internal double-precision floating point representation. On output the variable will be converted to scientific notation. If n is nonzero it defines the number of significant figures to display; the default is ten.

- -F [ n ] — Use an internal double-precision floating point representation. On output the variable will be converted to fixed-point decimal notation. If n is nonzero it defines the number of digits to display after the decimal point; the default is ten.

- -l — Convert the result to lower case whenever the parameter is expanded. The value is not converted when assigned.

- -r — The given _name_s are marked readonly. Note that if name is a special parameter, the readonly attribute can be turned on, but cannot then be turned off.

If the POSIX_BUILTINS option is set, the readonly attribute is more restrictive: unset variables can be marked readonly and cannot then be set; furthermore, the readonly attribute cannot be removed from any variable.

It is still possible to change other attributes of the variable though, some of which like -U or -Z would affect the value. More generally, the readonly attribute should not be relied on as a security mechanism.

Note that in zsh (like in pdksh but unlike most other shells) it is still possible to create a local variable of the same name as this is considered a different variable (though this variable, too, can be marked readonly). Special variables that have been made readonly retain their value and readonly attribute when made local.

- -t — Tags the named parameters. Tags only exist to flag the parameter for the user's own purposes --- the list of tagged parameters can be queried using "typeset -t". Tags have no other use. Note that the -t flag has a different meaning when used with -f; see above.

- -u — Convert the result to upper case whenever the parameter is expanded. The value is not converted when assigned. This flag has different meanings when used with -f or -n; see above.

- -x — Mark for automatic export to the environment of subsequently executed commands. If the option GLOBAL_EXPORT is set, this implies the option -g, unless +g is also explicitly given; in other words the parameter is not made local to the enclosing function. This is for compatibility with previous versions of zsh.

ulimit ¶

Set or display resource limits of the shell and the processes started by the shell. The value of limit can be a number in the unit specified below or one of the values "unlimited", which removes the limit on the resource, or "hard", which uses the current value of the hard limit on the resource.

By default, only soft limits are manipulated. If the -H flag is given use hard limits instead of soft limits. If the -S flag is given together with the -H flag set both hard and soft limits.

If no options are used, the file size limit (-f) is assumed.

If limit is omitted the current value of the specified resources are printed. When more than one resource value is printed, the limit name and unit is printed before each value.

When looping over multiple resources, the shell will abort immediately if it detects a badly formed argument. However, if it fails to set a limit for some other reason it will continue trying to set the remaining limits.

Not all the following resources are supported on all systems. Running ulimit -a will show which are supported.

- -a — List all of the current resource limits.

- -b — Socket buffer size in bytes (N.B. not kilobytes+)

- -c — 512-byte blocks on the size of core dumps. - -d — Kilobytes on the size of the data segment. - -e — Maximum nice value. - -f — 512-byte blocks on the size of files written. - -i — The number of pending signals. - -k — The number of kqueues allocated. - -l — Kilobytes on the size of locked-in memory. - -m — Kilobytes on the size of physical memory. - -n — Open file descriptors. - -o — Maximum number of POSIX thread library objects. - -p — The number of pseudo-terminals. - -q — Bytes in POSIX message queues. - -r — Maximum real time priority. On some systems where this is not available, such as NetBSD, this has the same effect as -T for compatibility with sh. - -s — Kilobytes on the size of the stack. - -T — The number of simultaneous threads available to the user. - -t — CPU seconds to be used. - -u — The number of processes available to the user. - -v — Kilobytes on the size of virtual memory. On some systems this refers to the limit called "address space". - -w — Kilobytes on the size of swapped out memory. - -x — The number of locks on files. - -y — Maximum size of buffers for pipes/fifos.

A resource may also be specified by integer in the form -N _resource_', where _resource_ corresponds to the integer defined for the resource by the operating system. This may be used to set the limits for resources known to the shell which do not correspond to option letters. Such limits will be shown by number in the output of "ulimit -a".

The number may alternatively be out of the range of limits compiled into the shell. The shell will try to read or write the limit anyway, and will report an error if this fails.

umask ¶

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

unalias ¶

Removes aliases. This command works the same as unhash -a, except that the -a option removes all regular or global aliases, or with -s all suffix aliases: in this case no name arguments may appear. The options -m (remove by pattern) and -s without -a (remove listed suffix aliases) behave as for unhash -a. Note that the meaning of -a is different between unalias and unhash.

unfunction ¶

Remove a function definition. Equivalent to unhash -f / unset -f name.

unhash ¶

Remove the element named name from an internal hash table. The default is remove elements from the command hash table. The -a option causes unhash to remove regular or global aliases; note when removing a global aliases that the argument must be quoted to prevent it from being expanded before being passed to the command. The -s option causes unhash to remove suffix aliases. The -f option causes unhash to remove shell functions. The -d options causes unhash to remove named directories. If the -m flag is given the arguments are taken as patterns (should be quoted) and all elements of the corresponding hash table with matching names will be removed.

unlimit ¶

The resource limit for each resource is set to the hard limit. If the -h flag is given and the shell has appropriate privileges, the hard resource limit for each resource is removed. The resources of the shell process are only changed if the -s flag is given.

The unlimit command is not made available by default when the shell starts in a mode emulating another shell. It can be made available with the command "zmodload -F zsh/rlimits b:unlimit".

unset ¶

Each named parameter is unset. Local parameters remain local even if unset; they appear unset within scope, but the previous value will still reappear when the scope ends.

Individual elements of associative array parameters may be unset by using subscript syntax on name, which should be quoted (or the entire command prefixed with noglob) to protect the subscript from filename generation.

If the -m flag is specified the arguments are taken as patterns (should be quoted) and all parameters with matching names are unset. Note that this cannot be used when unsetting associative array elements, as the subscript will be treated as part of the pattern.

The -v flag specifies that name refers to parameters. This is the default behaviour. If the -n option is supplied, and name is a a named reference, name will be unset rather than the variable it references.

unset -f is equivalent to unfunction. The -n option has no effect with -f.

unsetopt ¶

Unset the options for the shell. All options specified either with flags or by name are unset. If no arguments are supplied, the names of all options currently unset are printed. If the -m flag is given the arguments are taken as patterns (which should be quoted to preserve them from being interpreted as glob patterns), and all options with names matching these patterns are unset.

vared ¶

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. When the -c" flag is given, the parameter is created if it doesn"t already exist. The -a flag may be given with -c to create an array parameter, or the -A flag to create an associative array. If the type of an existing parameter does not match the type to be created, the parameter is unset and recreated. The -g flag may be given to suppress warnings from the WARN_CREATE_GLOBAL and WARN_NESTED_VAR options.

If an array or array slice is being edited, separator characters as defined in $IFS will be shown quoted with a backslash, as will backslashes themselves. Conversely, when the edited text is split into an array, a backslash quotes an immediately following separator character or backslash; no other special handling of backslashes, or any handling of quotes, is performed.

Individual elements of existing array or associative array parameters may be edited by using subscript syntax on name. New elements are created automatically, even without -c.

If the -p flag is given, the following string will be taken as the prompt to display at the left. If the -r flag is given, the following string gives the prompt to display at the right. If the -h flag is specified, the history can be accessed from ZLE. If the -e flag is given, typing ^D (Control-D) in an empty buffer causes vared to exit immediately with a non-zero return value.

The -M option gives a keymap to link to the main keymap during editing, and the -m option gives a keymap to link to the vicmd keymap during editing. For vi-style editing, this allows a pair of keymaps to override viins and vicmd. For emacs-style editing, only -M is normally needed but the -m option may still be used. On exit, the previous keymaps will be restored.

Vared calls the usual "zle-line-init" and "zle-line-finish" hooks before and after it takes control. Using the -i and -f options, it is possible to replace these with other custom widgets.

If -t" tty" is given, tty is the name of a terminal device to be used instead of the default /dev/tty. If tty does not refer to a terminal an error is reported.

wait ¶

Wait for the specified jobs or processes. If job is not given then all currently active child processes are waited for. Each job can be either a job specification or the process ID of a job in the job table. The exit status from this command is that of the job waited for. If job represents an unknown job or process ID, a warning is printed (unless the POSIX_BUILTINS option is set) and the exit status is 127.

It is possible to wait for recent processes (specified by process ID, not by job) that were running in the background even if the process has exited. Typically the process ID will be recorded by capturing the value of the variable $! immediately after the process has been started. There is a limit on the number of process IDs remembered by the shell; this is given by the value of the system configuration parameter CHILD_MAX. When this limit is reached, older process IDs are discarded, least recently started processes first.

Note there is no protection against the process ID wrapping, i.e. if the wait is not executed soon enough there is a chance the process waited for is the wrong one. A conflict implies both process IDs have been generated by the shell, as other processes are not recorded, and that the user is potentially interested in both, so this problem is intrinsic to process IDs.

whence ¶

For each name, indicate how it would be interpreted if used as a command name.

If name is not an alias, built-in command, external command, shell function, hashed command, or a reserved word, the exit status shall be non-zero, and DASH()- if -v, -c, or -w was passed DASH()- a message will be written to standard output. (This is different from other shells that write that message to standard error.)

whence is most useful when name is only the last path component of a command, i.e. does not include a "/"; in particular, pattern matching only succeeds if just the non-directory component of the command is passed.

- -v — Produce a more verbose report.

- -c — Print the results in a csh-like format. This takes precedence over -v.

- -w — For each name, print _name_:" word" where word is one of alias, builtin, command, function, hashed, reserved or none, according as name corresponds to an alias, a built-in command, an external command, a shell function, a command defined with the hash builtin, a reserved word, or is not recognised. This takes precedence over -v and -c.

- -f — Causes the contents of a shell function to be displayed, which would otherwise not happen unless the -c flag were used.

- -p — Do a path search for name even if it is an alias, reserved word, shell function or builtin.

- -a — Do a search for all occurrences of name throughout the command path. Normally only the first occurrence is printed. When combined with -m, only names appearing in the command hash table are searched, but all occurrences of those names are printed.

- -m — The arguments are taken as patterns (pattern characters should be quoted), and the information is displayed for each entry in the command hash table matching one of these patterns. The hash table is first refilled, in case of changes to PATH.

- -s — If a pathname contains symlinks, print the symlink-free pathname as well.

- -S — As -s, but if the pathname had to be resolved by following multiple symlinks, the intermediate steps are printed, too. The symlink resolved at each step might be anywhere in the path.

- -x num — Expand tabs when outputting shell functions using the -c option. This has the same effect as the -x option to the functions builtin.

where ¶

Equivalent to whence -ca.

which ¶

Equivalent to whence -c.

zcompile ¶

This builtin command can be used to compile functions or scripts, storing the compiled form in a file, and to examine files containing the compiled form. This allows faster autoloading of functions and sourcing of scripts by avoiding parsing of the text when the files are read.

The first form (without the -c, -a or -t options) creates a compiled file. If only the file argument is given, the output file has the name _file_.zwc' and will be placed in the same directory as the _file_. The shell will load the compiled file instead of the normal function file when the function is autoloaded; see _Autoloading Functions_ (zshmisc) for a description of how autoloaded functions are searched. The extension .zwc stands for "zsh word code".

vindex(fpath, with zcompile) If there is at least one name argument, all the named files are compiled into the output file given as the first argument. If file does not end in .zwc, this extension is automatically appended. Files containing multiple compiled functions are called "digest" files, and are intended to be used as elements of the FPATH/fpath special array.

The second form, with the -c or -a options, writes the compiled definitions for all the named functions into file. For -c, the names must be functions currently defined in the shell, not those marked for autoloading. Undefined functions that are marked for autoloading may be written by using the -a option, in which case the fpath is searched and the contents of the definition files for those functions, if found, are compiled into file. If both -c and -a are given, names of both defined functions and functions marked for autoloading may be given. In either case, the functions in files written with the -c or -a option will be autoloaded as if the KSH_AUTOLOAD option were unset.

The reason for handling loaded and not-yet-loaded functions with different options is that some definition files for autoloading define multiple functions, including the function with the same name as the file, and, at the end, call that function. In such cases the output of "zcompile -c" does not include the additional functions defined in the file, and any other initialization code in the file is lost. Using "zcompile -a" captures all this extra information.

If the -m option is combined with -c or -a, the _name_s are used as patterns and all functions whose names match one of these patterns will be written. If no name is given, the definitions of all functions currently defined or marked as autoloaded will be written.

Note the second form cannot be used for compiling functions that include redirections as part of the definition rather than within the body of the function; for example

example(fn1() { { ... } >~/logfile })

can be compiled but

example(fn1() { ... } >~/logfile)

cannot. It is possible to use the first form of zcompile to compile autoloadable functions that include the full function definition instead of just the body of the function.

The third form, with the -t option, examines an existing compiled file. Without further arguments, the names of the original files compiled into it are listed. The first line of output shows the version of the shell which compiled the file and how the file will be used (i.e. by reading it directly or by mapping it into memory). With arguments, nothing is output and the return status is set to zero if definitions for all _name_s were found in the compiled file, and non-zero if the definition for at least one name was not found.

Other options:

- -U — Aliases are not expanded when compiling the _name_d files.

- -R — When the compiled file is read, its contents are copied into the shell's memory, rather than memory-mapped (see -M). This happens automatically on systems that do not support memory mapping.

When compiling scripts instead of autoloadable functions, it is often desirable to use this option; otherwise the whole file, including the code to define functions which have already been defined, will remain mapped, consequently wasting memory.

- -M — The compiled file is mapped into the shell's memory when read. This is done in such a way that multiple instances of the shell running on the same host will share this mapped file. If neither -R nor -M is given, the zcompile builtin decides what to do based on the size of the compiled file.

- -k

- -z — These options are used when the compiled file contains functions which are to be autoloaded. If -z is given, the function will be autoloaded as if the KSH_AUTOLOAD option is not set, even if it is set at the time the compiled file is read, while if the -k is given, the function will be loaded as if KSH_AUTOLOAD is set. These options also take precedence over any -k or -z options specified to the autoload builtin. If neither of these options is given, the function will be loaded as determined by the setting of the KSH_AUTOLOAD option at the time the compiled file is read. ifzman( ) These options may also appear as many times as necessary between the listed _name_s to specify the loading style of all following functions, up to the next -k or -z.

ifnzman( ) The created file always contains two versions of the compiled format, one for big-endian machines and one for small-endian machines. The upshot of this is that the compiled file is machine independent and if it is read or mapped, only one half of the file is actually used (and mapped). ifzman()

zcurses ¶

Manipulate curses windows. All uses of this command should be bracketed by "zcurses init" to initialise use of curses, and "zcurses end" to end it; omitting "zcurses end" can cause the terminal to be in an unwanted state.

The subcommand addwin creates a window with nlines lines and ncols columns. Its upper left corner will be placed at row _begin_y_ and column _begin_x_ of the screen. targetwin is a string and refers to the name of a window that is not currently assigned. Note in particular the curses convention that vertical values appear before horizontal values.

If addwin is given an existing window as the final argument, the new window is created as a subwindow of parentwin. This differs from an ordinary new window in that the memory of the window contents is shared with the parent's memory. Subwindows must be deleted before their parent. Note that the coordinates of subwindows are relative to the screen, not the parent, as with other windows.

Use the subcommand delwin to delete a window created with addwin. Note that end does not implicitly delete windows, and that delwin does not erase the screen image of the window.

The window corresponding to the full visible screen is called stdscr; it always exists after "zcurses init" and cannot be delete with delwin.

The subcommand refresh will refresh window targetwin; this is necessary to make any pending changes (such as characters you have prepared for output with char) visible on the screen. refresh without an argument causes the screen to be cleared and redrawn. If multiple windows are given, the screen is updated once at the end.

The subcommand touch marks the _targetwin_s listed as changed. This is necessary before refreshing windows if a window that was in front of another window (which may be stdscr) is deleted.

The subcommand move moves the cursor position in targetwin to new coordinates _new_y_ and _new_x_. Note that the subcommand string (but not the subcommand char) advances the cursor position over the characters added.

The subcommand clear erases the contents of targetwin. One (and no more than one) of three options may be specified. With the option redraw, in addition the next refresh of targetwin will cause the screen to be cleared and repainted. With the option eol, targetwin is only cleared to the end of the current cursor line. With the option bot, targetwin is cleared to the end of the window, i.e everything to the right and below the cursor is cleared.

The subcommand position writes various positions associated with targetwin into the array named array. These are, in order:

- - — The y and x coordinates of the cursor relative to the top left of targetwin - - — The y and x coordinates of the top left of targetwin on the screen - - — The size of targetwin in y and x dimensions.

Outputting characters and strings are achieved by char and string respectively.

To draw a border around window targetwin, use border. Note that the border is not subsequently handled specially: in other words, the border is simply a set of characters output at the edge of the window. Hence it can be overwritten, can scroll off the window, etc.

The subcommand attr" will set _targetwin_"s attributes or foreground/background color pair for any successive character output. Each _attribute_ given on the line may be prepended by a + to set or a - to unset that attribute; + is assumed if absent. The attributes supported are blink, bold, dim, reverse, standout, and underline.

Each _fg_col_/_bg_col_ attribute (to be read as "_fg_col_ on _bg_col_") sets the foreground and background color for character output. The color default is sometimes available (in particular if the library is ncurses), specifying the foreground or background color with which the terminal started. The color pair default/default is always available. To use more than the 8 named colors (red, green, etc.) construct the _fg_col_/_bg_col_ pairs where _fg_col_ and _bg_col_ are decimal integers, e.g 128/200. The maximum color value is 254 if the terminal supports 256 colors.

bg overrides the color and other attributes of all characters in the window. Its usual use is to set the background initially, but it will overwrite the attributes of any characters at the time when it is called. In addition to the arguments allowed with attr, an argument @char specifies a character to be shown in otherwise blank areas of the window. Owing to limitations of curses this cannot be a multibyte character (use of ASCII characters only is recommended). As the specified set of attributes override the existing background, turning attributes off in the arguments is not useful, though this does not cause an error.

The subcommand scroll can be used with on or off to enabled or disable scrolling of a window when the cursor would otherwise move below the window due to typing or output. It can also be used with a positive or negative integer to scroll the window up or down the given number of lines without changing the current cursor position (which therefore appears to move in the opposite direction relative to the window). In the second case, if scrolling is off it is temporarily turned on to allow the window to be scrolled.

The subcommand input reads a single character from the window without echoing it back. If param is supplied the character is assigned to the parameter param, else it is assigned to the parameter REPLY.

If both param and kparam are supplied, the key is read in "keypad" mode. In this mode special keys such as function keys and arrow keys return the name of the key in the parameter kparam. The key names are the macros defined in the curses.h or ncurses.h with the prefix "KEY_" removed; see also the description of the parameter zcurses_keycodes below. Other keys cause a value to be set in param as before. On a successful return only one of param or kparam contains a non-empty string; the other is set to an empty string.

If mparam is also supplied, input attempts to handle mouse input. This is only available with the ncurses library; mouse handling can be detected by checking for the exit status of "zcurses mouse" with no arguments. If a mouse button is clicked (or double- or triple-clicked, or pressed or released with a configurable delay from being clicked) then kparam is set to the string MOUSE, and mparam is set to an array consisting of the following elements:

- - — An identifier to discriminate different input devices; this is only rarely useful.

- - — The x, y and z coordinates of the mouse click relative to the full screen, as three elements in that order (i.e. the y coordinate is, unusually, after the x coordinate). The z coordinate is only available for a few unusual input devices and is otherwise set to zero.

- - — Any events that occurred as separate items; usually there will be just one. An event consists of PRESSED, RELEASED, CLICKED, DOUBLE_CLICKED or TRIPLE_CLICKED followed immediately (in the same element) by the number of the button.

- - — If the shift key was pressed, the string SHIFT. - - — If the control key was pressed, the string CTRL. - - — If the alt key was pressed, the string ALT.

Not all mouse events may be passed through to the terminal window; most terminal emulators handle some mouse events themselves. Note that the ncurses manual implies that using input both with and without mouse handling may cause the mouse cursor to appear and disappear.

The subcommand mouse can be used to configure the use of the mouse. There is no window argument; mouse options are global. "zcurses mouse" with no arguments returns status 0 if mouse handling is possible, else status 1. Otherwise, the possible arguments (which may be combined on the same command line) are as follows. delay num sets the maximum delay in milliseconds between press and release events to be considered as a click; the value 0 disables click resolution, and the default is one sixth of a second. motion proceeded by an optional "+" (the default) or - turns on or off reporting of mouse motion in addition to clicks, presses and releases, which are always reported. However, it appears reports for mouse motion are not currently implemented.

The subcommand timeout specifies a timeout value for input from targetwin. If intval is negative, "zcurses input" waits indefinitely for a character to be typed; this is the default. If intval is zero, "zcurses input" returns immediately; if there is typeahead it is returned, else no input is done and status 1 is returned. If intval is positive, "zcurses input" waits intval milliseconds for input and if there is none at the end of that period returns status 1.

The subcommand querychar queries the character at the current cursor position. The return values are stored in the array named param if supplied, else in the array reply. The first value is the character (which may be a multibyte character if the system supports them); the second is the color pair in the usual _fg_col_/_bg_col_ notation, or 0 if color is not supported. Any attributes other than color that apply to the character, as set with the subcommand attr, appear as additional elements.

The subcommand resize resizes stdscr and all windows to given dimensions (windows that stick out from the new dimensions are resized down). The underlying curses extension (resize_term call) can be unavailable. To verify, zeroes can be used for height and width. If the result of the subcommand is 0, resize_term is available (2 otherwise). Tests show that resizing can be normally accomplished by calling zcurses end and zcurses refresh. The resize subcommand is provided for versatility. Multiple system configurations have been checked and zcurses end and zcurses refresh are still needed for correct terminal state after resize. To invoke them with resize, use endwin argument. Using nosave argument will cause new terminal state to not be saved internally by zcurses. This is also provided for versatility and should normally be not needed.

zdelattr ¶

Remove the extended attribute attribute from the specified filename.

zf_chgrp ¶

zftp: change group of remote files. Mirrors chgrp(1).

zf_chmod ¶

zftp: change mode of remote files. Mirrors chmod(1).

zf_chown ¶

zftp: change owner of remote files. Mirrors chown(1).

zf_ln ¶

zftp: link / rename remote files. Mirrors ln(1).

zf_mkdir ¶

zftp: create remote directories. Mirrors mkdir(1).

zf_mv ¶

zftp: move / rename remote files. Mirrors mv(1).

zf_rm ¶

zftp: remove remote files. Mirrors rm(1).

zf_rmdir ¶

zftp: remove remote directories. Mirrors rmdir(1).

zf_sync ¶

zftp: flush pending writes on the FTP control channel.

zformat ¶

This builtin provides different forms of formatting. The first form is selected with the -f option. In this case the format string will be modified by replacing sequences starting with a percent sign in it with strings from the _spec_s. Each spec should be of the form _char_:"string" which will cause every appearance of the sequence %"char" in format to be replaced by the string. The "%" sequence may also contain optional minimum and maximum field width specifications between the "%" and the "char" in the form %_min_._max_c', i.e. the minimum field width is given first and if the maximum field width is used, it has to be preceded by a dot. Specifying a minimum field width makes the result be padded with spaces to the right if the _string_ is shorter than the requested width. Padding to the left can be achieved by giving a negative minimum field width. If a maximum field width is specified, the _string_ will be truncated after that many characters. After all "%" sequences for the given _spec_s have been processed, the resulting string is stored in the parameter _param_.

The %-escapes also understand ternary expressions in the form used by prompts. The % is followed by a "tt(()" and then an ordinary format specifier character as described above. There may be a set of digits either before or after the "tt(()"; these specify a test number, which defaults to zero. Negative numbers are also allowed. An arbitrary delimiter character follows the format specifier, which is followed by a piece of "true" text, the delimiter character again, a piece of "false" text, and a closing parenthesis. The complete expression (without the digits) thus looks like tt(%()_X_._text1_._text2_")", except that the "." character is arbitrary. The value given for the format specifier in the char:string expressions is evaluated as a mathematical expression, and compared with the test number. If they are the same, text1 is output, else text2 is output. A parenthesis may be escaped in text2 as %). Either of text1 or text2 may contain nested %-escapes.

For example:

example(zformat -f REPLY "The answer is '%3(c.yes.no)'." c:3)

outputs "The answer is 'yes'." to REPLY since the value for the format specifier c is 3, agreeing with the digit argument to the ternary expression.

With -F instead of -f, ternary expressions choose between the "true" or "false" text on the basis of whether the format specifier is present and non-empty. A test number indicates a minimum width for the value given in the format specifier. Negative numbers reverse this, so the test is for whether the value exceeds a maximum width.

The form, using the -a option, can be used for aligning strings. Here, the _spec_s are of the form _left_:"right" where "left" and "right" are arbitrary strings. These strings are modified by replacing the colons by the sep string and padding the left strings with spaces to the right so that the sep strings in the result (and hence the right strings after them) are all aligned if the strings are printed below each other. All strings without a colon are left unchanged and all strings with an empty right string have the trailing colon removed. In both cases the lengths of the strings are not used to determine how the other strings are to be aligned. A colon in the left string can be escaped with a backslash. The resulting strings are stored in the array.

zftp ¶

The zsh/zftp module is a client for FTP (file transfer protocol). It is implemented as a builtin to allow full use of shell command line editing, file I/O, and job control mechanisms. Often, users will access it via shell functions providing a more powerful interface; a set is provided with the zsh distribution and is described in nmref(Zftp Function System)(zshzftpsys). However, the zftp command is entirely usable in its own right.

All commands consist of the command name zftp followed by the name of a subcommand. These are listed below. The return status of each subcommand is supposed to reflect the success or failure of the remote operation. See a description of the variable ZFTP_VERBOSE for more information on how responses from the server may be printed.

zgdbmpath ¶

Put path to database file assigned to parametername into REPLY scalar.

zgetattr ¶

Get the extended attribute attribute from the specified filename. If the optional argument parameter is given, the attribute is set on that parameter instead of being printed to stdout.

zle ¶

The zle builtin performs a number of different actions concerning ZLE.

With no options and no arguments, only the return status will be set. It is zero if ZLE is currently active and widgets could be invoked using this builtin command and non-zero otherwise. Note that even if non-zero status is returned, zle may still be active as part of the completion system; this does not allow direct calls to ZLE widgets.

Otherwise, which operation it performs depends on its options:

- -l [ -L | -a ] [ string ] — List all existing user-defined widgets. If the -L option is used, list in the form of zle commands to create the widgets.

When combined with the -a option, all widget names are listed, including the builtin ones. In this case the -L option is ignored.

If at least one string is given, and -a is present or -L is not used, nothing will be printed. The return status will be zero if all _string_s are names of existing widgets and non-zero if at least one string is not a name of a defined widget. If -a is also present, all widget names are used for the comparison including builtin widgets, else only user-defined widgets are used.

If at least one string is present and the -L option is used, user-defined widgets matching any string are listed in the form of zle commands to create the widgets.

- -D widget ... — Delete the named _widget_s.

- -A old-widget new-widget — Make the new-widget name an alias for old-widget, so that both names refer to the same widget. The names have equal standing; if either is deleted, the other remains. If there is already a widget with the new-widget name, it is deleted.

- -N widget [ function ] — Create a user-defined widget. If there is already a widget with the specified name, it is overwritten. When the new widget is invoked from within the editor, the specified shell function is called. If no function name is specified, it defaults to the same name as the widget. For further information, see Zle Widgets (below).

- -f flag [ flag... ] — Set various flags on the running widget. Possible values for flag are:

yank for indicating that the widget has yanked text into the buffer. If the widget is wrapping an existing internal widget, no further action is necessary, but if it has inserted the text manually, then it should also take care to set YANK_START and YANK_END correctly. yankbefore does the same but is used when the yanked text appears after the cursor.

kill for indicating that text has been killed into the cutbuffer. When repeatedly invoking a kill widget, text is appended to the cutbuffer instead of replacing it, but when wrapping such widgets, it is necessary to call "zle -f kill" to retain this effect.

vichange for indicating that the widget represents a vi change that can be repeated as a whole with "vi-repeat-change". The flag should be set early in the function before inspecting the value of NUMERIC or invoking other widgets. This has no effect for a widget invoked from insert mode. If insert mode is active when the widget finishes, the change extends until next returning to command mode.

cindex(completion widgets, creating)

- -C widget completion-widget function — Create a user-defined completion widget named widget. The completion widget will behave like the built-in completion-widget whose name is given as completion-widget. To generate the completions, the shell function function will be called. For further information, see nmref(Completion Widgets)(zshcompwid).

- -R [ -c ] [ display-string ] [ string ... ] — Redisplay the command line. If a display-string is given and not empty, this is shown in the status line (immediately below the line being edited).

If the optional _string_s are given they are listed below the prompt in the same way as completion lists are printed. If no _string_s are given but the -c option is used such a list is cleared.

Note that immediately after returning from running widgets, the command line will be redisplayed and the strings displayed will be erased. Therefore, this option is only useful for widgets that do not exit immediately after using it.

This command can safely be called outside user defined widgets; if zle is active, the display will be refreshed, while if zle is not active, the command has no effect. In this case there will usually be no other arguments.

The status is zero if zle was active, else one.

- -M string — As with the -R option, the string will be displayed below the command line; unlike the -R option, the string will not be put into the status line but will instead be printed normally below the prompt. This means that the string will still be displayed after the widget returns (until it is overwritten by subsequent commands).

- -U string — This pushes the characters in the string onto the input stack of ZLE. After the widget currently executed finishes ZLE will behave as if the characters in the string were typed by the user.

As ZLE uses a stack, if this option is used repeatedly the last string pushed onto the stack will be processed first. However, the characters in each string will be processed in the order in which they appear in the string.

- -K keymap — Selects the keymap named keymap. An error message will be displayed if there is no such keymap.

This keymap selection affects the interpretation of following keystrokes within this invocation of ZLE. Any following invocation (e.g., the next command line) will start as usual with the "main" keymap selected.

- -F [ -L | -w ] [ fd [ handler ] ] — Only available if your system supports one of the "poll" or "select" system calls; most modern systems do.

Installs handler (the name of a shell function) to handle input from file descriptor fd. Installing a handler for an fd which is already handled causes the existing handler to be replaced. Any number of handlers for any number of readable file descriptors may be installed. Note that zle makes no attempt to check whether this fd is actually readable when installing the handler. The user must make their own arrangements for handling the file descriptor when zle is not active.

When zle is attempting to read data, it will examine both the terminal and the list of handled fd's. If data becomes available on a handled fd, zle calls handler with the fd which is ready for reading as the first argument. Under normal circumstances this is the only argument, but if an error was detected, a second argument provides details: "hup" for a disconnect, "nval" for a closed or otherwise invalid descriptor, or "err" for any other condition. Systems that support only the "select" system call always use "err".

If the option -w is also given, the handler is instead a line editor widget, typically a shell function made into a widget using "zle -N". In that case handler can use all the facilities of zle to update the current editing line. Note, however, that as handling fd takes place at a low level changes to the display will not automatically appear; the widget should call "zle -R" to force redisplay. As of this writing, widget handlers only support a single argument and thus are never passed a string for error state, so widgets must be prepared to test the descriptor themselves.

If either type of handler produces output to the terminal, it should call "zle -I" before doing so (see below). Handlers should not attempt to read from the terminal.

If no handler is given, but an fd is present, any handler for that fd is removed. If there is none, an error message is printed and status 1 is returned.

If no arguments are given, or the -L option is supplied, a list of handlers is printed in a form which can be stored for later execution.

An fd (but not a handler) may optionally be given with the -L option; in this case, the function will list the handler if any, else silently return status 1.

Note that this feature should be used with care. Activity on one of the fd's which is not properly handled can cause the terminal to become unusable. Removing an fd handler from within a signal trap may cause unpredictable behavior.

Here is a simple example of using this feature. A connection to a remote TCP port is created using the ztcp command; see The zsh/net/tcp Module (zshmodules). Then a handler is installed which simply prints out any data which arrives on this connection. Note that "select" will indicate that the file descriptor needs handling if the remote side has closed the connection; we handle that by testing for a failed read.

example(if ztcp pwspc 2811; then tcpfd=$REPLY handler+() { zle -I local line if ! read -r line <&$1; then # select marks this fd if we reach EOF, # so handle this specially. print "[Read on fd $1 failed, removing.]" >&2 zle -F $1 return 1 fi print -r - $line } zle -F $tcpfd handler fi)

- -I — Unusually, this option is most useful outside ordinary widget functions, though it may be used within if normal output to the terminal is required. It invalidates the current zle display in preparation for output; typically this will be from a trap function. It has no effect if zle is not active. When a trap exits, the shell checks to see if the display needs restoring, hence the following will print output in such a way as not to disturb the line being edited:

example(TRAPUSR1() { # Invalidate zle display [[ -o zle ]] && zle -I # Show output print Hello })

In general, the trap function may need to test whether zle is active before using this method (as shown in the example), since the zsh/zle module may not even be loaded; if it is not, the command can be skipped.

It is possible to call "zle -I" several times before control is returned to the editor; the display will only be invalidated the first time to minimise disruption.

Note that there are normally better ways of manipulating the display from within zle widgets; see, for example, "zle -R" above.

The returned status is zero if zle was invalidated, even though this may have been by a previous call to "zle -I" or by a system notification. To test if a zle widget may be called at this point, execute zle with no arguments and examine the return status.

- -T — This is used to add, list or remove internal transformations on the processing performed by the line editor. It is typically used only for debugging or testing and is therefore of little interest to the general user.

zle -T" transformation func" specifies that the given transformation (see below) is effected by shell function func.

zle -Tr" transformation" removes the given transformation if it was present (it is not an error if none was).

"zle -TL" can be used to list all transformations currently in operation.

Currently the only transformation is tc. This is used instead of outputting termcap codes to the terminal. When the transformation is in operation the shell function is passed the termcap code that would be output as its first argument; if the operation required a numeric argument, that is passed as a second argument. The function should set the shell variable REPLY to the transformed termcap code. Typically this is used to produce some simply formatted version of the code and optional argument for debugging or testing. Note that this transformation is not applied to other non-printing characters such as carriage returns and newlines.

- widget [ -n num ] [ -f flag ] [ -Nw ] [ -K keymap ] args ... — Invoke the specified widget. This can only be done when ZLE is active; normally this will be within a user-defined widget.

With the options -n and -N, the current numeric argument will be saved and then restored after the call to widget; -n" num" sets the numeric argument temporarily to num, while "-N" sets it to the default, i.e. as if there were none.

With the option -K, keymap will be used as the current keymap during the execution of the widget. The previous keymap will be restored when the widget exits.

Normally, calling a widget in this way does not set the special parameter WIDGET and related parameters, so that the environment appears as if the top-level widget called by the user were still active. With the option -w, WIDGET and related parameters are set to reflect the widget being executed by the zle call.

Normally, when widget returns the special parameter LASTWIDGET will point to it. This can be inhibited by passing the option -f nolast.

Any further arguments will be passed to the widget; note that as standard argument handling is performed, any general argument list should be preceded by --. If it is a shell function, these are passed down as positional parameters; for builtin widgets it is up to the widget in question what it does with them. Currently arguments are only handled by the incremental-search commands, the history-search-forward and -backward and the corresponding functions prefixed by vi-, and by universal-argument. No error is flagged if the command does not use the arguments, or only uses some of them.

The return status reflects the success or failure of the operation carried out by the widget, or if it is a user-defined widget the return status of the shell function.

A non-zero return status causes the shell to beep when the widget exits, unless the BEEP options was unset or the widget was called via the zle command. Thus if a user defined widget requires an immediate beep, it should call the beep widget directly.

zlistattr ¶

List the extended attributes currently set on the specified filename. If the optional argument parameter is given, the list of attributes is set on that parameter instead of being printed to stdout.

zmodload ¶

Performs operations relating to zsh's loadable modules. Loading of modules while the shell is running ("dynamical loading") is not available on all operating systems, or on all installations on a particular operating system, although the zmodload command itself is always available and can be used to manipulate modules built into versions of the shell executable without dynamical loading.

Without arguments the names of all currently loaded binary modules are printed. The -L option causes this list to be in the form of a series of zmodload commands. Forms with arguments are:

- zmodload [ -is ] name ...

- zmodload -u [ -i ] name ... — In the simplest case, zmodload loads a binary module. The module must be in a file with a name consisting of the specified name followed by a standard suffix, usually ".so" (".sl" on HPUX). If the module to be loaded is already loaded the duplicate module is ignored. If zmodload detects an inconsistency, such as an invalid module name or circular dependency list, the current code block is aborted. If it is available, the module is loaded if necessary, while if it is not available, non-zero status is silently returned. The option -i is accepted for compatibility but has no effect.

The _name_d module is searched for in the same way a command is, using $module_path instead of $path. However, the path search is performed even when the module name contains a "/", which it usually does. There is no way to prevent the path search.

If the module supports features (see below), zmodload tries to enable all features when loading a module. If the module was successfully loaded but not all features could be enabled, zmodload returns status 2.

If the option -s is given, no error is printed if the module was not available (though other errors indicating a problem with the module are printed). The return status indicates if the module was loaded. This is appropriate if the caller considers the module optional.

With -u, zmodload unloads modules. The same name must be given that was given when the module was loaded, but it is not necessary for the module to exist in the file system. The -i option suppresses the error if the module is already unloaded (or was never loaded).

Each module has a boot and a cleanup function. The module will not be loaded if its boot function fails. Similarly a module can only be unloaded if its cleanup function runs successfully.

- zmodload -F [ -almLe -P param ] module [ [+-]feature ... ] — zmodload -F allows more selective control over the features provided by modules. With no options apart from -F, the module named module is loaded, if it was not already loaded, and the list of _feature_s is set to the required state. If no _feature_s are specified, the module is loaded, if it was not already loaded, but the state of features is unchanged. Each feature may be preceded by a + to turn the feature on, or - to turn it off; the + is assumed if neither character is present. Any feature not explicitly mentioned is left in its current state; if the module was not previously loaded this means any such features will remain disabled. The return status is zero if all features were set, 1 if the module failed to load, and 2 if some features could not be set (for example, a parameter couldn't be added because there was a different parameter of the same name) but the module was loaded.

The standard features are builtins, conditions, parameters and math functions; these are indicated by the prefix "b:", "c:" ("C:" for an infix condition), "p:" and "f:", respectively, followed by the name that the corresponding feature would have in the shell. For example, "b:strftime" indicates a builtin named strftime and p:EPOCHSECONDS indicates a parameter named EPOCHSECONDS. The module may provide other ("abstract") features of its own as indicated by its documentation; these have no prefix.

With -l or -L, features provided by the module are listed. With -l alone, a list of features together with their states is shown, one feature per line. With -L alone, a zmodload -F command that would cause enabled features of the module to be turned on is shown. With -lL, a zmodload -F command that would cause all the features to be set to their current state is shown. If one of these combinations is given with the option -P param then the parameter param is set to an array of features, either features together with their state or (if -L alone is given) enabled features.

With the option -L the module name may be omitted; then a list of all enabled features for all modules providing features is printed in the form of zmodload -F commands. If -l is also given, the state of both enabled and disabled features is output in that form.

A set of features may be provided together with -l or -L and a module name; in that case only the state of those features is considered. Each feature may be preceded by + or - but the character has no effect. If no set of features is provided, all features are considered.

With -e, the command first tests that the module is loaded; if it is not, status 1 is returned. If the module is loaded, the list of features given as an argument is examined. Any feature given with no prefix is simply tested to see if the module provides it; any feature given with a prefix + or - is tested to see if is provided and in the given state. If the tests on all features in the list succeed, status 0 is returned, else status 1.

With -m, each entry in the given list of features is taken as a pattern to be matched against the list of features provided by the module. An initial + or - must be given explicitly. This may not be combined with the -a option as autoloads must be specified explicitly.

With -a, the given list of features is marked for autoload from the specified module, which may not yet be loaded. An optional + may appear before the feature name. If the feature is prefixed with -, any existing autoload is removed. The options -l and -L may be used to list autoloads. Autoloading is specific to individual features; when the module is loaded only the requested feature is enabled. Autoload requests are preserved if the module is subsequently unloaded until an explicit zmodload -Fa _module_ -"feature" is issued. It is not an error to request an autoload for a feature of a module that is already loaded.

When the module is loaded each autoload is checked against the features actually provided by the module; if the feature is not provided the autoload request is deleted. A warning message is output; if the module is being loaded to provide a different feature, and that autoload is successful, there is no effect on the status of the current command. If the module is already loaded at the time when zmodload -Fa is run, an error message is printed and status 1 returned.

zmodload -Fa can be used with the -l, -L, -e and -P options for listing and testing the existence of autoloadable features. In this case -l is ignored if -L is specified. zmodload -FaL with no module name lists autoloads for all modules.

Note that only standard features as described above can be autoloaded; other features require the module to be loaded before enabling.

- zmodload -d [ -L ] [ name ]

- zmodload -d name dep ...

- zmodload -ud name [ dep ... ] — The -d option can be used to specify module dependencies. The modules named in the second and subsequent arguments will be loaded before the module named in the first argument.

With -d and one argument, all dependencies for that module are listed. With -d and no arguments, all module dependencies are listed. This listing is by default in a Makefile-like format. The -L option changes this format to a list of zmodload -d commands.

If -d and -u are both used, dependencies are removed. If only one argument is given, all dependencies for that module are removed.

- zmodload -ab [ -L ]

- zmodload -ab [ -i ] name [ builtin ... ]

- zmodload -ub [ -i ] builtin ... — The -ab option defines autoloaded builtins. It defines the specified _builtin_s. When any of those builtins is called, the module specified in the first argument is loaded and all its features are enabled (for selective control of features use "zmodload -F -a" as described above). If only the name is given, one builtin is defined, with the same name as the module. -i suppresses the error if the builtin is already defined or autoloaded, but not if another builtin of the same name is already defined.

With -ab and no arguments, all autoloaded builtins are listed, with the module name (if different) shown in parentheses after the builtin name. The -L option changes this format to a list of zmodload -a commands.

If -b is used together with the -u option, it removes builtins previously defined with -ab. This is only possible if the builtin is not yet loaded. -i suppresses the error if the builtin is already removed (or never existed).

Autoload requests are retained if the module is subsequently unloaded until an explicit zmodload -ub" builtin" is issued.

- zmodload -ac [ -IL ]

- zmodload -ac [ -iI ] name [ cond ... ]

- zmodload -uc [ -iI ] cond ... — The -ac option is used to define autoloaded condition codes. The cond strings give the names of the conditions defined by the module. The optional -I option is used to define infix condition names. Without this option prefix condition names are defined.

If given no condition names, all defined names are listed (as a series of zmodload commands if the -L option is given).

The -uc option removes definitions for autoloaded conditions.

- zmodload -ap [ -L ]

- zmodload -ap [ -i ] name [ parameter ... ]

- zmodload -up [ -i ] parameter ... — The -p option is like the -b and -c options, but makes zmodload work on autoloaded parameters instead.

- zmodload -af [ -L ]

- zmodload -af [ -i ] name [ function ... ]

- zmodload -uf [ -i ] function ... — The -f option is like the -b, -p, and -c options, but makes zmodload work on autoloaded math functions instead.

- zmodload -a [ -L ]

- zmodload -a [ -i ] name [ builtin ... ]

- zmodload -ua [ -i ] builtin ... — Equivalent to -ab and -ub.

- zmodload -e [ -A ] [ string ... ] — The -e option without arguments lists all loaded modules; if the -A option is also given, module aliases corresponding to loaded modules are also shown. If arguments are provided, nothing is printed; the return status is set to zero if all _string_s given as arguments are names of loaded modules and to one if at least on string is not the name of a loaded module. This can be used to test for the availability of things implemented by modules. In this case, any aliases are automatically resolved and the -A flag is not used.

- zmodload -A [ -L ] [ modalias[=module] ... ] — For each argument, if both modalias and module are given, define modalias to be an alias for the module module. If the module modalias is ever subsequently requested, either via a call to zmodload or implicitly, the shell will attempt to load module instead. If module is not given, show the definition of modalias. If no arguments are given, list all defined module aliases. When listing, if the -L flag was also given, list the definition as a zmodload command to recreate the alias.

The existence of aliases for modules is completely independent of whether the name resolved is actually loaded as a module: while the alias exists, loading and unloading the module under any alias has exactly the same effect as using the resolved name, and does not affect the connection between the alias and the resolved name which can be removed either by zmodload -R or by redefining the alias. Chains of aliases (i.e. where the first resolved name is itself an alias) are valid so long as these are not circular. As the aliases take the same format as module names, they may include path separators: in this case, there is no requirement for any part of the path named to exist as the alias will be resolved first. For example, "any/old/alias" is always a valid alias.

Dependencies added to aliased modules are actually added to the resolved module; these remain if the alias is removed. It is valid to create an alias whose name is one of the standard shell modules and which resolves to a different module. However, if a module has dependencies, it will not be possible to use the module name as an alias as the module will already be marked as a loadable module in its own right.

Apart from the above, aliases can be used in the zmodload command anywhere module names are required. However, aliases will not be shown in lists of loaded modules with a bare "zmodload".

- zmodload -R modalias ... — For each modalias argument that was previously defined as a module alias via zmodload -A, delete the alias. If any was not defined, an error is caused and the remainder of the line is ignored.

Note that zsh makes no distinction between modules that were linked into the shell and modules that are loaded dynamically. In both cases this builtin command has to be used to make available the builtins and other things defined by modules (unless the module is autoloaded on these definitions). This is true even for systems that don't support dynamic loading of modules.

zparseopts ¶

This builtin simplifies the parsing of options in positional parameters, i.e. the set of arguments given by $*. Each spec describes one option and must be of the form _opt_[="array]". If an option described by opt is found in the positional parameters it is copied into the array specified with the -a option; if the optional ="array" is given, it is instead copied into that array, which should be declared as a normal array and never as an associative array.

Note that it is an error to give any spec without an ="array" unless one of the -a or -A options is used.

Unless the -E option is given, parsing stops at the first string that isn't described by one of the _spec_s. Even with -E, parsing always stops at a positional parameter equal to -"-" or (without -G) "-". See also -F.

The opt description must be one of the following. Any of the special characters can appear in the option name provided it is preceded by a backslash.

- name

- name+ — The name is the name of the option without the leading "-". To specify a GNU-style long option, one of the usual two leading "-" must be included in name; for example, a -"-file" option is represented by a name of "-file".

If a "+" appears after name, the option is appended to array each time it is found in the positional parameters; without the "+" only the last occurrence of the option is preserved.

If one of these forms is used, the option takes no argument, so parsing stops if the next positional parameter does not also begin with "-" (unless the -E option is used).

- name:

- name:-

- name:: — If one or two colons are given, the option takes an argument; with one colon, the argument is mandatory and with two colons it is optional. The argument is appended to the array after the option itself.

An optional argument is put into the same array element as the option name (note that this makes empty strings as arguments indistinguishable). A mandatory argument is added as a separate element unless the ":-" form is used, in which case the argument is put into the same element.

A "+" as described above may appear between the name and the first colon.

By default, option-arguments may appear either immediately following the option in the same positional parameter or in the next one. Even an optional argument may appear in the next parameter, unless it begins with a "-". Additionally, there is no special consideration given to an "=" between an option and its argument. To make parsing use the more common GNU-style conventions, use the -G option.

When the names of two options that take no arguments overlap, the longest one wins, so that parsing for the _spec_s "-foo -foobar" (for example) is unambiguous. However, due to the aforementioned handling of option-arguments, ambiguities may arise when at least one overlapping spec takes an argument, as in "-foo: -foobar". In that case, the last matching spec wins. (This is not an issue with GNU-style parsing.)

The options of zparseopts itself cannot be stacked because, for example, the stack "-DEK" is indistinguishable from a spec for the GNU-style long option -"-DEK". The options of zparseopts itself are:

- -a array — As described above, this names the default array in which to store the recognised options.

- -A assoc — If this is given, the options and their values are also put into an associative array with the option names as keys and the arguments (if any) as the values.

- -D — If this option is given, all options found are removed from the positional parameters of the calling shell or shell function, up to but not including any not described by the _spec_s. If the first such parameter is -"-" or (without -G) "-", it is removed as well. This is similar to using the shift builtin.

- -E — This changes the parsing rules to not stop at the first string that isn't described by one of the _spec_s. It can be used to test for or (if used together with -D) extract options and their arguments, ignoring all other options and arguments that may be in the positional parameters. As indicated above, parsing still stops at the first "-" or -"-" not described by a spec, but it is not removed when used with -D. )

- -F — If this option is given, zparseopts immediately stops at the first option-like parameter not described by one of the _spec_s, prints an error message, and returns status 1. Removal (-D) and extraction (-E) are not performed, and option arrays are not updated. This provides basic validation for the given options.

Note that the appearance in the positional parameters of an option without its required argument always aborts parsing and returns an error as described above regardless of whether this option is used.

- -G — This option specifies that options are parsed in the GNU style, similar to tt(getopt_long+(3+)). In particular:

Given the spec "-foo:", the positional parameter -"-foo=bar" is interpreted as option -"-foo" with argument "bar", rather than argument "=bar" as is the default, whilst the positional parameter -"-foobar" is considered an unknown option (unless another spec describes it). This applies to both singly and doubly hyphenated long options.

An empty option-argument can be given to its long option in the same parameter using a trailing "=".

An optional argument to a long option must be given with the equals syntax, and an optional argument to a short option must follow it immediately in the same parameter; in both cases the following parameter is considered unrelated.

Whenever a long option and its argument are stored in the same array element, an "=" is used to separate them.

A mandatory option-argument given in a separate parameter from its option (as in --foo bar' , or any option-argument given to a short option in the same parameter, is always treated the same regardless of whether this option is in effect.

Lastly, when this option is active, only -"-" is treated as an explicit option-parsing terminator in the parsed arguments; a single "-" is considered a normal operand.

Note: Unlike most tt(getopt_long+(3+)) implementations, zparseopts does not support abbreviating long options. )

- -K — With this option, the arrays specified with the -a option and with the ="array" forms are kept unchanged when none of the _spec_s for them is used. Otherwise the entire array is replaced when any of the _spec_s is used. Individual elements of associative arrays specified with the -A option are preserved by -K. This allows assignment of default values to arrays before calling zparseopts.

- -M — This changes the assignment rules to implement a map among equivalent option names. If any spec uses the ="array" form, the string array is interpreted as the name of another spec, which is used to choose where to store the values. If no other spec is found, the values are stored as usual. This changes only the way the values are stored, not the way $* is parsed, so results may be unpredictable if the _name_+' specifier is used inconsistently.

- -v argv — With this option, the elements of the named array argv are used as the positional parameters to parse, rather than those given by $*. The array may be modified according to the -D option.

For example,

set -- -a -bx -c y -cz baz -cend zparseopts a=foo b:=bar c+:=bar

will have the effect of

example(foo=(-a) bar=(-b x -c y -c z))

The arguments from "baz" on will not be used.

As an example for the -E option, consider:

set -- -a x -b y -c z arg1 arg2 zparseopts -E -D b:=bar

will have the effect of

example(bar=(-b y) set -- -a x -c z arg1 arg2)

I.e., the option -b and its arguments are taken from the positional parameters and put into the array bar.

The -M option can be used like this:

set -- -a -bx -c y -cz baz -cend zparseopts -A bar -M a=foo b+: c:=b

to have the effect of

example(foo=(-a) bar=(-a '' -b xyz))

zprof ¶

Without the -c option, zprof lists profiling results to standard output. The format is comparable to that of commands like gprof.

At the top there is a summary listing all functions that were called at least once. This summary is sorted in decreasing order of the amount of time spent in each. The lines contain the number of the function in order, which is used in other parts of the list in suffixes of the form [_num_]', then the number of calls made to the function. The next three columns list the time in milliseconds spent in the function and its descendants, the average time in milliseconds spent in the function and its descendants per call and the percentage of time spent in all shell functions used in this function and its descendants. The following three columns give the same information, but counting only the time spent in the function itself. The final column shows the name of the function.

After the summary, detailed information about every function that was invoked is listed, sorted in decreasing order of the amount of time spent in each function and its descendants. Each of these entries consists of descriptions for the functions that called the function described, the function itself, and the functions that were called from it. The description for the function itself has the same format as in the summary (and shows the same information). The other lines don't show the number of the function at the beginning and have their function named indented to make it easier to distinguish the line showing the function described in the section from the surrounding lines.

The information shown in this case is almost the same as in the summary, but only refers to the call hierarchy being displayed. For example, for a calling function the column showing the total running time lists the time spent in the described function and its descendants only for the times when it was called from that particular calling function. Likewise, for a called function, this columns lists the total time spent in the called function and its descendants only for the times when it was called from the function described.

Also in this case, the column showing the number of calls to a function also shows a slash and then the total number of invocations made to the called function.

As long as the zsh/zprof module is loaded, profiling will be done and multiple invocations of the zprof builtin command will show the times and numbers of calls since the module was loaded. With the -c option, the zprof builtin command will reset its internal counters and will not show the listing.

zpty ¶

The arguments following name are concatenated with spaces between, then executed as a command, as if passed to the eval builtin. The command runs under a newly assigned pseudo-terminal; this is useful for running commands non-interactively which expect an interactive environment. The name is not part of the command, but is used to refer to this command in later calls to zpty.

With the -e option, the pseudo-terminal is set up so that input characters are echoed.

With the -b option, input to and output from the pseudo-terminal are made non-blocking.

The shell parameter REPLY is set to the file descriptor assigned to the master side of the pseudo-terminal. This allows the terminal to be monitored with ZLE descriptor handlers (see the description of option -F for zle builtin in Zle Builtins (zshzle)) or manipulated with sysread and syswrite builtins (see The zsh/system Module (zshmodules)). Warning: Use of sysread and syswrite is not recommended; use zpty -r and zpty -w unless you know exactly what you are doing.

zregexparse ¶

This implements some internals of the _regex_arguments function.

zselect ¶

The zselect builtin is a front-end to the "select" system call, which blocks until a file descriptor is ready for reading or writing, or has an error condition, with an optional timeout. If this is not available on your system, the command prints an error message and returns status 2 (normal errors return status 1). For more information, see your system's documentation for manref(select)(2). Note there is no connection with the shell builtin of the same name.

Arguments and options may be intermingled in any order. Non-option arguments are file descriptors, which must be decimal integers. By default, file descriptors are to be tested for reading, i.e. zselect will return when data is available to be read from the file descriptor, or more precisely, when a read operation from the file descriptor will not block. After a -r, -w and -e, the given file descriptors are to be tested for reading, writing, or error conditions. These options and an arbitrary list of file descriptors may be given in any order.

(The presence of an "error condition" is not well defined in the documentation for many implementations of the select system call. According to recent versions of the POSIX specification, it is really an exception condition, of which the only standard example is out-of-band data received on a socket. So zsh users are unlikely to find the -e option useful.)

The option -t" timeout" specifies a timeout in hundredths of a second. This may be zero, in which case the file descriptors will simply be polled and zselect will return immediately. It is possible to call zselect with no file descriptors and a non-zero timeout for use as a finer-grained replacement for "sleep"; note, however, the return status is always 1 for a timeout.

The option -a" array" indicates that array should be set to indicate the file descriptor+(s+) which are ready. If the option is not given, the array reply will be used for this purpose. The array will contain a string similar to the arguments for zselect. For example,

zselect -t 0 -r 0 -w 1

might return immediately with status 0 and $reply containing -r 0 -w 1' to show that both file descriptors are ready for the requested operations.

The option -A" assoc" indicates that the associative array assoc should be set to indicate the file descriptor+(s+) which are ready. This option overrides the option -a, nor will reply be modified. The keys of assoc are the file descriptors, and the corresponding values are any of the characters "rwe" to indicate the condition.

The command returns status 0 if some file descriptors are ready for reading. If the operation timed out, or a timeout of 0 was given and no file descriptors were ready, or there was an error, it returns status 1 and the array will not be set (nor modified in any way). If there was an error in the select operation the appropriate error message is printed.

zsetattr ¶

Set the extended attribute attribute on the specified filename to value.

zsocket ¶

zsocket is implemented as a builtin to allow full use of shell command line editing, file I/O, and job control mechanisms.

zstat ¶

The command acts as a front end to the stat system call (see manref(stat)(2)). The same command is provided with two names; as the name stat is often used by an external command it is recommended that only the zstat form of the command is used. This can be arranged by loading the module with the command zmodload -F zsh/stat b:zstat'.

If the stat call fails, the appropriate system error message printed and status 1 is returned. The fields of struct stat give information about the files provided as arguments to the command. In addition to those available from the stat call, an extra element "link" is provided. These elements are:

- device — The number of the device on which the file resides.

- inode — The unique number of the file on this device ("inode" number).

- mode — The mode of the file; that is, the file's type and access permissions. With the -s option, this will be returned as a string corresponding to the first column in the display of the ls -l command.

- nlink — The number of hard links to the file.

- uid — The user ID of the owner of the file. With the -s option, this is displayed as a user name.

- gid — The group ID of the file. With the -s option, this is displayed as a group name.

- rdev — The raw device number. This is only useful for special devices.

- size — The size of the file in bytes.

- atime

- mtime

- ctime — The last access, modification and inode change times of the file, respectively, as the number of seconds since midnight GMT on 1st January, 1970. With the -s option, these are printed as strings for the local time zone; the format can be altered with the -F option, and with the -g option the times are in GMT.

- blksize — The number of bytes in one allocation block on the device on which the file resides.

- block — The number of disk blocks used by the file.

- link — If the file is a link and the -L option is in effect, this contains the name of the file linked to, otherwise it is empty. Note that if this element is selected (""zstat +link"") then the -L option is automatically used.

A particular element may be selected by including its name preceded by a "+" in the option list; only one element is allowed. The element may be shortened to any unique set of leading characters. Otherwise, all elements will be shown for all files.

Options:

- -A array — Instead of displaying the results on standard output, assign them to an array, one struct stat element per array element for each file in order. In this case neither the name of the element nor the name of the files appears in array unless the -t or -n options were given, respectively. If -t is given, the element name appears as a prefix to the appropriate array element; if -n is given, the file name appears as a separate array element preceding all the others. Other formatting options are respected.

- -H hash — Similar to -A, but instead assign the values to hash. The keys are the elements listed above. If the -n option is provided then the name of the file is included in the hash with key name.

- -f fd — Use the file on file descriptor fd instead of named files; no list of file names is allowed in this case.

- -F fmt — Supplies a strftime (see manref(strftime)(3)) string for the formatting of the time elements. The format string supports all of the zsh extensions (see the description of %D{string} prompt escape in Simple Prompt Escapes (zshmisc)). In particular, -F %s.%N can be used to show timestamps with nanosecond precision if supported by the system. The -s option is implied.

- -g — Show the time elements in the GMT time zone. The -s option is implied.

- -l — List the names of the type elements (to standard output or an array as appropriate) and return immediately; arguments, and options other than -A, are ignored.

- -L — Perform an lstat (see manref(lstat)(2)) rather than a stat system call. In this case, if the file is a link, information about the link itself rather than the target file is returned. This option is required to make the link element useful. It's important to note that this is the exact opposite from manref(ls)(1), etc.

- -n — Always show the names of files. Usually these are only shown when output is to standard output and there is more than one file in the list.

- -N — Never show the names of files.

- -o — If a raw file mode is printed, show it in octal, which is more useful for human consumption than the default of decimal. A leading zero will be printed in this case. Note that this does not affect whether a raw or formatted file mode is shown, which is controlled by the -r and -s options, nor whether a mode is shown at all.

- -r — Print raw data (the default format) alongside string data (the -s format); the string data appears in parentheses after the raw data.

- -s — Print mode, uid, gid and the three time elements as strings instead of numbers. In each case the format is like that of ls -l.

- -t — Always show the type names for the elements of struct stat. Usually these are only shown when output is to standard output and no individual element has been selected.

- -T — Never show the type names of the struct stat elements.

zstyle ¶

This makes defining styles a bit simpler by using a single "+" as a special token that allows you to append a context name to the previously used context name. Like this:

zstyle+ ':foo:bar' style1 value1 \ + ':baz' style2 value2 \ + ':frob' style3 value3

This defines style1 with value1 for the context :foo:bar as usual, but it also defines style2 with value2 for the context :foo:bar:baz and style3 with value3 for :foo:bar:frob. Any subcontext may be the empty string to re-use the first context unchanged.

zsystem ¶

The builtin zsystem's subcommand flock performs advisory file locking (via the manref(fcntl)(2) system call) over the entire contents of the given file. This form of locking requires the processes accessing the file to cooperate; its most obvious use is between two instances of the shell itself.

In the first form the named file, which must already exist, is locked by opening a file descriptor to the file and applying a lock to the file descriptor. The lock terminates when the shell process that created the lock exits; it is therefore often convenient to create file locks within subshells, since the lock is automatically released when the subshell exits. Note that use of the print builtin with the -u option will, as a side effect, release the lock, as will redirection to the file in the shell holding the lock. To work around this use a subshell, e.g. "tt((print message) >> )file". Status 0 is returned if the lock succeeds, else status 1.

In the second form the file descriptor given by the arithmetic expression _fd_expr_ is closed, releasing a lock. The file descriptor can be queried by using the -f" var" form during the lock; on a successful lock, the shell variable var is set to the file descriptor used for locking. The lock will be released if the file descriptor is closed by any other means, for example using exec {_var_}>&-'; however, the form described here performs a safety check that the file descriptor is in use for file locking.

By default the shell waits indefinitely for the lock to succeed. The option -t timeout specifies a timeout for the lock in seconds; fractional seconds are allowed. During this period, the shell will attempt to lock the file every interval seconds if the -i interval option is given, otherwise once a second. (This interval is shortened before the last attempt if needed, so that the shell waits only until the timeout and not longer.) If the attempt times out, status 2 is returned.

(Note: timeout is limited to 2^30-1 seconds (about 34 years), and interval to 0.999 * LONG_MAX microseconds (only about 35 minutes on 32-bit systems).)

If the option -e is given, the file descriptor for the lock is preserved when the shell uses exec to start a new process; otherwise it is closed at that point and the lock released.

If the option -r is given, the lock is only for reading, otherwise it is for reading and writing. The file descriptor is opened accordingly.

ztcp ¶

ztcp is implemented as a builtin to allow full use of shell command line editing, file I/O, and job control mechanisms.

If ztcp is run with no options, it will output the contents of its session table.

If it is run with only the option -L, it will output the contents of the session table in a format suitable for automatic parsing. The option is ignored if given with a command to open or close a session. The output consists of a set of lines, one per session, each containing the following elements separated by spaces:

- File descriptor — The file descriptor in use for the connection. For normal inbound (I) and outbound (O) connections this may be read and written by the usual shell mechanisms. However, it should only be close with "ztcp -c".

- Connection type — A letter indicating how the session was created:

- Z — A session created with the zftp command.

- L — A connection opened for listening with "ztcp -l".

- I — An inbound connection accepted with "ztcp -a".

- O — An outbound connection created with ztcp" host ...".

- The local host — This is usually set to an all-zero IP address as the address of the localhost is irrelevant.

- The local port — This is likely to be zero unless the connection is for listening.

- The remote host — This is the fully qualified domain name of the peer, if available, else an IP address. It is an all-zero IP address for a session opened for listening.

- The remote port — This is zero for a connection opened for listening.

ztie ¶

Open the GDBM database identified by filename and, if successful, create the associative array arrayname linked to the file. To create a local tied array, the parameter must first be declared, so commands similar to the following would be executed inside a function scope:

local -A sampledb ztie -d db/gdbm -f sample.gdbm sampledb

The -r option opens the database file for reading only, creating a parameter with the readonly attribute. Without this option, using "ztie" on a file for which the user does not have write permission is an error. If writable, the database is opened synchronously so fields changed in arrayname are immediately written to filename.

Changes to the file modes filename after it has been opened do not alter the state of arrayname, but typeset -r" arrayname" works as expected.

zuntie ¶

Close the GDBM database associated with each arrayname and then unset the parameter. The -u option forces an unset of parameters made readonly with "ztie -r".

This happens automatically if the parameter is explicitly unset or its local scope (function) ends. Note that a readonly parameter may not be explicitly unset, so the only way to unset a global parameter created with "ztie -r" is to use "zuntie -u".

! ¶

Pipeline negation (also a reserved word). ! cmd inverts cmd's exit status — zero becomes 1, non-zero becomes 0. Distinct from ! history expansion (lexer-stage).

[[ ¶

Open zsh conditional expression. [[ EXPR ]] evaluates a boolean. No word splitting / glob inside; supports &&, ||, !, ==, !=, =~, -e, -f, -d, -z, -n, etc. Prefer this over [ ] in zsh.

{ ¶

Command-group open brace. { cmd1; cmd2; } runs the commands in the current shell (no subshell), grouping them as one syntactic unit. Reserved word — must be followed by whitespace or a newline.

} ¶

Command-group close brace. Pairs with { … }. Reserved word — preceded by ; or newline.

case ¶

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 Generation (zshexpn).

Note further that, unless the SH_GLOB option is set, the whole pattern with alternatives is treated by the shell as equivalent to a group of patterns within parentheses, although white space may appear about the parentheses and the vertical bar and will be stripped from the pattern at those points. White space may appear elsewhere in the pattern; this is not stripped. If the SH_GLOB option is set, so that an opening parenthesis can be unambiguously treated as part of the case syntax, the expression is parsed into separate words and these are treated as strict alternatives (as in other shells).

If the list that is executed is terminated with ;& rather than ;;, the following list is also executed. The rule for the terminator of the following list ;;, ;& or ;| is applied unless the esac is reached.

If the list that is executed is terminated with ;| the shell continues to scan the _pattern_s looking for the next match, executing the corresponding list, and applying the rule for the corresponding terminator ;;, ;& or ;|. Note that word is not re-expanded; all applicable _pattern_s are tested with the same word.

coproc ¶

Run a command as a coprocess (background, attached I/O).

declare ¶

Alias for typeset. Set variable attributes. -a array, -A assoc, -i integer, -r readonly.

do ¶

Body-introducer for for/while/until/select/repeat. for v in …; do body; done

done ¶

Closes a for / foreach / while / until / select / repeat loop body. for v in a b c; do echo $v; done. Required terminator.

elif ¶

Alternative test in an if chain. if a; then …; elif b; then …; fi

else ¶

Alternative branch for if. if cmd; then a; else b; fi

end ¶

Closes the alternate-form compound statement (foreach NAME (WORDS) … end, if COND … end, while COND … end). Csh-style syntactic mirror of fi / done / esac for users coming from csh / tcsh.

esac ¶

Closes a case statement. case word in pat) …;; esac

export ¶

The specified _name_s are marked for automatic export to the environment of subsequently executed commands. Equivalent to typeset -gx. If a parameter specified does not already exist, it is created in the global scope.

fi ¶

Closes an if block. if cmd; then body; fi. Required terminator — without it the parser keeps reading until EOF.

float ¶

Equivalent to typeset -E, except that options irrelevant to floating point numbers are not permitted.

for ¶

Expand the list of _word_s, and set the parameter name to each of them in turn, executing list each time. If the in" word" is omitted, use the positional parameters instead of the _word_s. If any name has been declared as a named reference, the corresponding word is treated as the name of a parameter and name is made a reference to that. Note that for the positional parameters, this treats the value of each positional as parameter name rather than creating a reference to the position.

The term consists of one or more newline or ; which terminate the _word_s, and are optional when the in" word" is omitted.

More than one parameter name can appear before the list of _word_s. If N _name_s are given, then on each execution of the loop the next N _word_s are assigned to the corresponding parameters. If there are more _name_s than remaining _word_s, the remaining parameters are each set to the empty string. Execution of the loop ends when there is no remaining word to assign to the first name. It is only possible for in to appear as the first name in the list, else it will be treated as marking the end of the list.

foreach ¶

Another form of for.

function ¶

where term is one or more newline or ;. Define a function which is referenced by any one of word. Normally, only one word is provided; multiple _word_s are usually only useful for setting traps. The body of the function is the list between the { and }. See Functions (blow).

The options of function have the following meanings:

- -T — Enable tracing for this function, as though with functions -T. See the documentation of the -f option to the typeset builtin, in Shell Builtin Commands (zshbuiltins).

If the option SH_GLOB is set for compatibility with other shells, then whitespace may appear between the left and right parentheses when there is a single word; otherwise, the parentheses will be treated as forming a globbing pattern in that case.

In any of the forms above, a redirection may appear outside the function body, for example

example(func+() { ... } 2>&1)

The redirection is stored with the function and applied whenever the function is executed. Any variables in the redirection are expanded at the point the function is executed, but outside the function scope.

if ¶

The if list is executed, and if it returns a zero exit status, the then list is executed. Otherwise, the elif list is executed and if its status is zero, the then list is executed. If each elif list returns nonzero status, the else list is executed.

integer ¶

Equivalent to typeset -i, except that options irrelevant to integers are not permitted.

local ¶

Same as typeset, except that the options -g, and -f are not permitted. In this case the -x option does not force the use of -g, i.e. exported variables will be local to functions.

nocorrect ¶

Spelling correction is not done on any of the words. This must appear before any other precommand modifier, as it is interpreted immediately, before any parsing is done. It has no effect in non-interactive shells.

readonly ¶

Same as typeset -r. With the POSIX_BUILTINS option set, same as typeset -gr.

repeat ¶

word is expanded and treated as an arithmetic expression, which must evaluate to a number n. list is then executed n times.

The repeat syntax is disabled by default when the shell starts in a mode emulating another shell. It can be enabled with the command "enable -r repeat"

select ¶

where term is one or more newline or ; to terminate the _word_s. vindex(REPLY, use of) Print the set of _word_s, 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 the line editor if the shell is interactive and that is active, or else standard input. If this line consists of the number of one of the listed _word_s, then the parameter 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.

then ¶

Body separator for if/elif. if cmd; then body; fi

time ¶

The pipeline is executed, and timing statistics 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.

typeset ¶

Set or display attributes and values for shell parameters.

Except as noted below for control flags that change the behavior, a parameter is created for each name that does not already refer to one. When inside a function, a new parameter is created for every name (even those that already exist), and is unset again when the function completes. See Local Parameters (zshparam). The same rules apply to special shell parameters, which retain their special attributes when made local.

For each name=value assignment, the parameter name is set to value. If the assignment is omitted and name does not refer to an existing parameter, a new parameter is initialized to empty string, zero, or empty array (as appropriate), unless the shell option TYPESET_TO_UNSET is set. When that option is set, the parameter attributes are recorded but the parameter remains unset.

If the shell option TYPESET_SILENT is not set, for each remaining name that refers to a parameter that is already set, the name and value of the parameter are printed in the form of an assignment. Nothing is printed for newly-created parameters, or when any attribute flags listed below are given along with the name. Using "+" instead of minus to introduce an attribute turns it off.

If no name is present, the names and values of all parameters are printed. In this case the attribute flags restrict the display to only those parameters that have the specified attributes, and using "+" rather than "-" to introduce the flag suppresses printing of the values of parameters when there is no parameter name.

All forms of the command handle scalar assignment. Array assignment is possible if any of the reserved words declare, export, float, integer, local, readonly or typeset is matched when the line is parsed (N.B. not when it is executed). In this case the arguments are parsed as assignments, except that the "+=" syntax and the GLOB_ASSIGN option are not supported, and scalar values after = are not split further into words, even if expanded (regardless of the setting of the KSH_TYPESET option; this option is obsolete).

Examples of the differences between command and reserved word parsing:

example(# Reserved word parsing typeset svar=$(echo one word) avar=(several words))

The above creates a scalar parameter svar and an array parameter avar as if the assignments had been

example(svar="one word" avar=(several words))

On the other hand:

example(# Normal builtin interface builtin typeset svar=$(echo two words))

The builtin keyword causes the above to use the standard builtin interface to typeset in which argument parsing is performed in the same way as for other commands. This example creates a scalar svar containing the value two and another scalar parameter words with no value. An array value in this case would either cause an error or be treated as an obscure set of glob qualifiers.