1ZSHALL(1) General Commands Manual ZSHALL(1)
2
6 zshall - the Z shell meta-man page
7
9 Because zsh contains many features, the zsh manual has been split into
10 a number of sections. This manual page includes all the separate man‐
11 ual pages in the following order:
12 zshmisc Anything not fitting into the other sections
14 zshexpn Zsh command and parameter expansion
15 zshparam Zsh parameters
16 zshoptions Zsh options
17 zshbuiltins Zsh built-in functions
18 zshzle Zsh command line editing
19 zshcompwid Zsh completion widgets
20 zshcompsys Zsh completion system
21 zshcompctl Zsh completion control
22 zshmodules Zsh loadable modules
23 zshzftpsys Zsh built-in FTP client
24
26 Zsh is a UNIX command interpreter (shell) usable as an interactive
27 login shell and as a shell script command processor. Of the standard
28 shells, zsh most closely resembles ksh but includes many enhancements.
29 Zsh has command line editing, builtin spelling correction, programmable
30 command completion, shell functions (with autoloading), a history mech‐
31 anism, and a host of other features.
32
34 Zsh was originally written by Paul Falstad <pf@zsh.org>. Zsh is now
35 maintained by the members of the zsh-workers mailing list <zsh-work‐
36 ers@sunsite.dk>. The development is currently coordinated by Peter
37 Stephenson <pws@zsh.org>. The coordinator can be contacted at <coordi‐
38 nator@zsh.org>, but matters relating to the code should generally go to
39 the mailing list.
40
42 Zsh is available from the following anonymous FTP sites. These mirror
43 sites are kept frequently up to date. The sites marked with (H) may be
44 mirroring ftp.cs.elte.hu instead of the primary site.
45 Primary site
47 ftp://ftp.zsh.org/pub/zsh/
48 http://www.zsh.org/pub/zsh/
49 Australia
51 ftp://ftp.zsh.org/pub/zsh/
52 http://www.zsh.org/pub/zsh/
53 Denmark
55 ftp://sunsite.dk/pub/unix/shells/zsh/
56 Finland
58 ftp://ftp.funet.fi/pub/unix/shells/zsh/
59 Germany
61 ftp://ftp.fu-berlin.de/pub/unix/shells/zsh/ (H)
62 ftp://ftp.gmd.de/packages/zsh/
63 ftp://ftp.uni-trier.de/pub/unix/shell/zsh/
64 Hungary
66 ftp://ftp.cs.elte.hu/pub/zsh/
67 http://www.cs.elte.hu/pub/zsh/
68 ftp://ftp.kfki.hu/pub/packages/zsh/
69 Israel
71 ftp://ftp.math.technion.ac.il/pub/zsh/
72 http://www.math.technion.ac.il/pub/zsh/
73 Japan
75 ftp://ftp.win.ne.jp/pub/shell/zsh/
76 ftp://ftp.ayamura.org/pub/zsh/
77 Korea
79 ftp://linux.sarang.net/mirror/system/shell/zsh/
80 Netherlands
82 ftp://ftp.demon.nl/pub/mirrors/zsh/
83 Norway
85 ftp://ftp.uit.no/pub/unix/shells/zsh/
86 Poland
88 ftp://sunsite.icm.edu.pl/pub/unix/shells/zsh/
89 Romania
91 ftp://ftp.roedu.net/pub/mirrors/ftp.zsh.org/pub/zsh/
92 ftp://ftp.kappa.ro/pub/mirrors/ftp.zsh.org/pub/zsh/
93 Slovenia
95 ftp://ftp.siol.net/mirrors/zsh/
96 Sweden
98 ftp://ftp.lysator.liu.se/pub/unix/zsh/
99 UK
101 ftp://ftp.net.lut.ac.uk/zsh/
102 ftp://sunsite.org.uk/packages/zsh/
103 USA
105 ftp://uiarchive.uiuc.edu/mirrors/ftp/ftp.zsh.org/pub/
106 ftp://ftp.rge.com/pub/shells/zsh/
107 http://zsh.disillusion.org/
108 http://foad.org/zsh/
109 The up-to-date source code is available via anonymous CVS from Source‐
111 forge. See http://sourceforge.net/projects/zsh/ for details.
112
114 Zsh has 3 mailing lists:
115 <zsh-announce@sunsite.dk>
117 Announcements about releases, major changes in the shell and the
118 monthly posting of the Zsh FAQ. (moderated)
119 <zsh-users@sunsite.dk>
121 User discussions.
122 <zsh-workers@sunsite.dk>
124 Hacking, development, bug reports and patches.
125 To subscribe or unsubscribe, send mail to the associated administrative
127 address for the mailing list.
128 <zsh-announce-subscribe@sunsite.dk>
130 <zsh-users-subscribe@sunsite.dk>
131 <zsh-workers-subscribe@sunsite.dk>
132 <zsh-announce-unsubscribe@sunsite.dk>
133 <zsh-users-unsubscribe@sunsite.dk>
134 <zsh-workers-unsubscribe@sunsite.dk>
135 YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED. All
137 submissions to zsh-announce are automatically forwarded to zsh-users.
138 All submissions to zsh-users are automatically forwarded to zsh-work‐
139 ers.
140 If you have problems subscribing/unsubscribing to any of the mailing
142 lists, send mail to <listmaster@zsh.org>. The mailing lists are main‐
143 tained by Karsten Thygesen <karthy@kom.auc.dk>.
144 The mailing lists are archived; the archives can be accessed via the
146 administrative addresses listed above. There is also a hypertext ar‐
147 chive, maintained by Geoff Wing <gcw@zsh.org>, available at
148 http://www.zsh.org/mla/.
149
151 Zsh has a list of Frequently Asked Questions (FAQ), maintained by Peter
152 Stephenson <pws@zsh.org>. It is regularly posted to the newsgroup
153 comp.unix.shell and the zsh-announce mailing list. The latest version
154 can be found at any of the Zsh FTP sites, or at
155 http://www.zsh.org/FAQ/. The contact address for FAQ-related matters
156 is <faqmaster@zsh.org>.
157
159 Zsh has a web page which is located at http://www.zsh.org/. This is
160 maintained by Karsten Thygesen <karthy@zsh.org>, of SunSITE Denmark.
161 The contact address for web-related matters is <webmaster@zsh.org>.
162
164 A userguide is currently in preparation. It is intended to complement
165 the manual, with explanations and hints on issues where the manual can
166 be cabbalistic, hierographic, or downright mystifying (for example, the
167 word `hierographic' does not exist). It can be viewed in its current
168 state at http://zsh.sunsite.dk/Guide/. At the time of writing, chap‐
169 ters dealing with startup files and their contents and the new comple‐
170 tion system were essentially complete.
171
173 A `wiki' website for zsh has been created at http://www.zshwiki.org/.
174 This is a site which can be added to and modified directly by users
175 without any special permission. You can add your own zsh tips and con‐
176 figurations.
177
179 The following flags are interpreted by the shell when invoked to deter‐
180 mine where the shell will read commands from:
181 -c Take the first argument as a command to execute, rather than
183 reading commands from a script or standard input. If any fur‐
184 ther arguments are given, the first one is assigned to $0,
185 rather than being used as a positional parameter.
186 -i Force shell to be interactive.
188 -s Force shell to read commands from the standard input. If the -s
190 flag is not present and an argument is given, the first argument
191 is taken to be the pathname of a script to execute.
192 After the first one or two arguments have been appropriated as
194 described above, the remaining arguments are assigned to the positional
195 parameters.
196 For further options, which are common to invocation and the set
198 builtin, see zshoptions(1).
199 Options may be specified by name using the -o option. -o acts like a
201 single-letter option, but takes a following string as the option name.
202 For example,
203 zsh -x -o shwordsplit scr
205 runs the script scr, setting the XTRACE option by the corresponding
207 letter `-x' and the SH_WORD_SPLIT option by name. Options may be
208 turned off by name by using +o instead of -o. -o can be stacked up
209 with preceding single-letter options, so for example `-xo shwordsplit'
210 or `-xoshwordsplit' is equivalent to `-x -o shwordsplit'.
211 Options may also be specified by name in GNU long option style,
213 `--option-name'. When this is done, `-' characters in the option name
214 are permitted: they are translated into `_', and thus ignored. So, for
215 example, `zsh --sh-word-split' invokes zsh with the SH_WORD_SPLIT
216 option turned on. Like other option syntaxes, options can be turned
217 off by replacing the initial `-' with a `+'; thus `+-sh-word-split' is
218 equivalent to `--no-sh-word-split'. Unlike other option syntaxes,
219 GNU-style long options cannot be stacked with any other options, so for
220 example `-x-shwordsplit' is an error, rather than being treated like
221 `-x --shwordsplit'.
222 The special GNU-style option `--version' is handled; it sends to stan‐
224 dard output the shell's version information, then exits successfully.
225 `--help' is also handled; it sends to standard output a list of options
226 that can be used when invoking the shell, then exits successfully.
227 Option processing may be finished, allowing following arguments that
229 start with `-' or `+' to be treated as normal arguments, in two ways.
230 Firstly, a lone `-' (or `+') as an argument by itself ends option pro‐
231 cessing. Secondly, a special option `--' (or `+-'), which may be spec‐
232 ified on its own (which is the standard POSIX usage) or may be stacked
233 with preceding options (so `-x-' is equivalent to `-x --'). Options
234 are not permitted to be stacked after `--' (so `-x-f' is an error), but
235 note the GNU-style option form discussed above, where `--shwordsplit'
236 is permitted and does not end option processing.
237 Except when the sh/ksh emulation single-letter options are in effect,
239 the option `-b' (or `+b') ends option processing. `-b' is like `--',
240 except that further single-letter options can be stacked after the `-b'
241 and will take effect as normal.
242
244 Zsh tries to emulate sh or ksh when it is invoked as sh or ksh respec‐
245 tively; more precisely, it looks at the first letter of the name by
246 which it was invoked, excluding any initial `r' (assumed to stand for
247 `restricted'), and if that is `s' or `k' it will emulate sh or ksh.
248 Furthermore, if invoked as su (which happens on certain systems when
249 the shell is executed by the su command), the shell will try to find an
250 alternative name from the SHELL environment variable and perform emula‐
251 tion based on that.
252 In sh and ksh compatibility modes the following parameters are not spe‐
254 cial and not initialized by the shell: ARGC, argv, cdpath, fignore,
255 fpath, HISTCHARS, mailpath, MANPATH, manpath, path, prompt, PROMPT,
256 PROMPT2, PROMPT3, PROMPT4, psvar, status, watch.
257 The usual zsh startup/shutdown scripts are not executed. Login shells
259 source /etc/profile followed by $HOME/.profile. If the ENV environment
260 variable is set on invocation, $ENV is sourced after the profile
261 scripts. The value of ENV is subjected to parameter expansion, command
262 substitution, and arithmetic expansion before being interpreted as a
263 pathname. Note that the PRIVILEGED option also affects the execution
264 of startup files.
265 The following options are set if the shell is invoked as sh or ksh:
267 NO_BAD_PATTERN, NO_BANG_HIST, NO_BG_NICE, NO_EQUALS, NO_FUNC‐
268 TION_ARGZERO, GLOB_SUBST, NO_GLOBAL_EXPORT, NO_HUP, INTERACTIVE_COM‐
269 MENTS, KSH_ARRAYS, NO_MULTIOS, NO_NOMATCH, NO_NOTIFY, POSIX_BUILTINS,
270 NO_PROMPT_PERCENT, RM_STAR_SILENT, SH_FILE_EXPANSION, SH_GLOB,
271 SH_OPTION_LETTERS, SH_WORD_SPLIT. Additionally the BSD_ECHO and
272 IGNORE_BRACES options are set if zsh is invoked as sh. Also, the
273 KSH_OPTION_PRINT, LOCAL_OPTIONS, PROMPT_BANG, PROMPT_SUBST and SIN‐
274 GLE_LINE_ZLE options are set if zsh is invoked as ksh.
275
277 When the basename of the command used to invoke zsh starts with the
278 letter `r' or the `-r' command line option is supplied at invocation,
279 the shell becomes restricted. Emulation mode is determined after
280 stripping the letter `r' from the invocation name. The following are
281 disabled in restricted mode:
282 · changing directories with the cd builtin
284 · changing or unsetting the PATH, path, MODULE_PATH, module_path,
286 SHELL, HISTFILE, HISTSIZE, GID, EGID, UID, EUID, USERNAME,
287 LD_LIBRARY_PATH, LD_AOUT_LIBRARY_PATH, LD_PRELOAD and
288 LD_AOUT_PRELOAD parameters
289 · specifying command names containing /
291 · specifying command pathnames using hash
293 · redirecting output to files
295 · using the exec builtin command to replace the shell with another
297 command
298 · using jobs -Z to overwrite the shell process' argument and envi‐
300 ronment space
301 · using the ARGV0 parameter to override argv[0] for external com‐
303 mands
304 · turning off restricted mode with set +r or unsetopt RESTRICTED
306 These restrictions are enforced after processing the startup files.
308 The startup files should set up PATH to point to a directory of com‐
309 mands which can be safely invoked in the restricted environment. They
310 may also add further restrictions by disabling selected builtins.
311 Restricted mode can also be activated any time by setting the
313 RESTRICTED option. This immediately enables all the restrictions
314 described above even if the shell still has not processed all startup
315 files.
316
318 Commands are first read from /etc/zshenv; this cannot be overridden.
319 Subsequent behaviour is modified by the RCS and GLOBAL_RCS options; the
320 former affects all startup files, while the second only affects those
321 in the /etc directory. If one of the options is unset at any point,
322 any subsequent startup file(s) of the corresponding type will not be
323 read. It is also possible for a file in $ZDOTDIR to re-enable
324 GLOBAL_RCS. Both RCS and GLOBAL_RCS are set by default.
325 Commands are then read from $ZDOTDIR/.zshenv. If the shell is a login
327 shell, commands are read from /etc/zprofile and then $ZDOTDIR/.zpro‐
328 file. Then, if the shell is interactive, commands are read from
329 /etc/zshrc and then $ZDOTDIR/.zshrc. Finally, if the shell is a login
330 shell, /etc/zlogin and $ZDOTDIR/.zlogin are read.
331 When a login shell exits, the files $ZDOTDIR/.zlogout and then
333 /etc/zlogout are read. This happens with either an explicit exit via
334 the exit or logout commands, or an implicit exit by reading end-of-file
335 from the terminal. However, if the shell terminates due to exec'ing
336 another process, the logout files are not read. These are also
337 affected by the RCS and GLOBAL_RCS options. Note also that the RCS
338 option affects the saving of history files, i.e. if RCS is unset when
339 the shell exits, no history file will be saved.
340 If ZDOTDIR is unset, HOME is used instead. Those files listed above as
342 being in /etc may be in another directory, depending on the installa‐
343 tion.
344 As /etc/zshenv is run for all instances of zsh, it is important that it
346 be kept as small as possible. In particular, it is a good idea to put
347 code that does not need to be run for every single shell behind a test
348 of the form `if [[ -o rcs ]]; then ...' so that it will not be executed
349 when zsh is invoked with the `-f' option.
350 Any of these files may be pre-compiled with the zcompile builtin com‐
352 mand (see zshbuiltins(1)). If a compiled file exists (named for the
353 original file plus the .zwc extension) and it is newer than the origi‐
354 nal file, the compiled file will be used instead.
355ZSHMISC(1) General Commands Manual ZSHMISC(1)
359
363 zshmisc - everything and then some
364
366 A simple command is a sequence of optional parameter assignments fol‐
367 lowed by blank-separated words, with optional redirections inter‐
368 spersed. The first word is the command to be executed, and the remain‐
369 ing words, if any, are arguments to the command. If a command name is
370 given, the parameter assignments modify the environment of the command
371 when it is executed. The value of a simple command is its exit status,
372 or 128 plus the signal number if terminated by a signal. For example,
373 echo foo
375 is a simple command with arguments.
377 A pipeline is either a simple command, or a sequence of two or more
379 simple commands where each command is separated from the next by `|' or
380 `|&'. Where commands are separated by `|', the standard output of the
381 first command is connected to the standard input of the next. `|&' is
382 shorthand for `2>&1 |', which connects both the standard output and the
383 standard error of the command to the standard input of the next. The
384 value of a pipeline is the value of the last command, unless the pipe‐
385 line is preceded by `!' in which case the value is the logical inverse
386 of the value of the last command. For example,
387 echo foo | sed 's/foo/bar/'
389 is a pipeline, where the output (`foo' plus a newline) of the first
391 command will be passed to the input of the second.
392 If a pipeline is preceded by `coproc', it is executed as a coprocess; a
394 two-way pipe is established between it and the parent shell. The shell
395 can read from or write to the coprocess by means of the `>&p' and `<&p'
396 redirection operators or with `print -p' and `read -p'. A pipeline
397 cannot be preceded by both `coproc' and `!'. If job control is active,
398 the coprocess can be treated in other than input and output as an ordi‐
399 nary background job.
400 A sublist is either a single pipeline, or a sequence of two or more
402 pipelines separated by `&&' or `||'. If two pipelines are separated by
403 `&&', the second pipeline is executed only if the first succeeds
404 (returns a zero value). If two pipelines are separated by `||', the
405 second is executed only if the first fails (returns a nonzero value).
406 Both operators have equal precedence and are left associative. The
407 value of the sublist is the value of the last pipeline executed. For
408 example,
409 dmesg | grep panic && print yes
411 is a sublist consisting of two pipelines, the second just a simple com‐
413 mand which will be executed if and only if the grep command returns a
414 zero value. If it does not, the value of the sublist is that return
415 value, else it is the value returned by the print (almost certainly
416 zero).
417 A list is a sequence of zero or more sublists, in which each sublist is
419 terminated by `;', `&', `&|', `&!', or a newline. This terminator may
420 optionally be omitted from the last sublist in the list when the list
421 appears as a complex command inside `(...)' or `{...}'. When a sub‐
422 list is terminated by `;' or newline, the shell waits for it to finish
423 before executing the next sublist. If a sublist is terminated by a
424 `&', `&|', or `&!', the shell executes the last pipeline in it in the
425 background, and does not wait for it to finish (note the difference
426 from other shells which execute the whole sublist in the background).
427 A backgrounded pipeline returns a status of zero.
428 More generally, a list can be seen as a set of any shell commands what‐
430 soever, including the complex commands below; this is implied wherever
431 the word `list' appears in later descriptions. For example, the com‐
432 mands in a shell function form a special sort of list.
433
435 A simple command may be preceded by a precommand modifier, which will
436 alter how the command is interpreted. These modifiers are shell
437 builtin commands with the exception of nocorrect which is a reserved
438 word.
439 - The command is executed with a `-' prepended to its argv[0]
441 string.
442 noglob Filename generation (globbing) is not performed on any of the
444 words.
445 nocorrect
447 Spelling correction is not done on any of the words. This must
448 appear before any other precommand modifier, as it is inter‐
449 preted immediately, before any parsing is done. It has no
450 effect in non-interactive shells.
451 exec The command is executed in the parent shell without forking.
453 command
455 The command word is taken to be the name of an external command,
456 rather than a shell function or builtin.
457 builtin
459 The command word is taken to be the name of a builtin command,
460 rather than a shell function or external command.
461
463 A complex command in zsh is one of the following:
464 if list then list [ elif list then list ] ... [ else list ] fi
466 The if list is executed, and if it returns a zero exit status,
467 the then list is executed. Otherwise, the elif list is executed
468 and if its value is zero, the then list is executed. If each
469 elif list returns nonzero, the else list is executed.
470 for name ... [ in word ... ] term do list done
472 where term is at least one newline or ;. Expand the list of
473 words, and set the parameter name to each of them in turn, exe‐
474 cuting list each time. If the in word is omitted, use the posi‐
475 tional parameters instead of the words.
476 More than one parameter name can appear before the list of
478 words. If N names are given, then on each execution of the loop
479 the next N words are assigned to the corresponding parameters.
480 If there are more names than remaining words, the remaining
481 parameters are each set to the empty string. Execution of the
482 loop ends when there is no remaining word to assign to the first
483 name. It is only possible for in to appear as the first name in
484 the list, else it will be treated as marking the end of the
485 list.
486 for (( [expr1] ; [expr2] ; [expr3] )) do list done
488 The arithmetic expression expr1 is evaluated first (see the sec‐
489 tion `Arithmetic Evaluation'). The arithmetic expression expr2
490 is repeatedly evaluated until it evaluates to zero and when
491 non-zero, list is executed and the arithmetic expression expr3
492 evaluated. If any expression is omitted, then it behaves as if
493 it evaluated to 1.
494 while list do list done
496 Execute the do list as long as the while list returns a zero
497 exit status.
498 until list do list done
500 Execute the do list as long as until list returns a nonzero exit
501 status.
502 repeat word do list done
504 word is expanded and treated as an arithmetic expression, which
505 must evaluate to a number n. list is then executed n times.
506 case word in [ [(] pattern [ | pattern ] ... ) list (;;|;&) ] ... esac
508 Execute the list associated with the first pattern that matches
509 word, if any. The form of the patterns is the same as that used
510 for filename generation. See the section `Filename Generation'.
511 If the list that is executed is terminated with ;& rather than
512 ;;, the following list is also executed. This continues until
513 either a list is terminated with ;; or the esac is reached.
514 select name [ in word ... term ] do list done
516 where term is one or more newline or ; to terminate the words.
517 Print the set of words, each preceded by a number. If the in
518 word is omitted, use the positional parameters. The PROMPT3
519 prompt is printed and a line is read from the line editor if the
520 shell is interactive and that is active, or else standard input.
521 If this line consists of the number of one of the listed words,
522 then the parameter name is set to the word corresponding to this
523 number. If this line is empty, the selection list is printed
524 again. Otherwise, the value of the parameter name is set to
525 null. The contents of the line read from standard input is
526 saved in the parameter REPLY. list is executed for each selec‐
527 tion until a break or end-of-file is encountered.
528 ( list )
530 Execute list in a subshell. Traps set by the trap builtin are
531 reset to their default values while executing list.
532 { list }
534 Execute list.
535 { try-list } always { always-list }
537 First execute try-list. Regardless of errors, or break, con‐
538 tinue, or return commands encountered within try-list, execute
539 always-list. Execution then continues from the result of the
540 execution of try-list; in other words, any error, or break, con‐
541 tinue, or return command is treated in the normal way, as if
542 always-list were not present. The two chunks of code are
543 referred to as the `try block' and the `always block'.
544 Optional newlines or semicolons may appear after the always;
546 note, however, that they may not appear between the preceeding
547 closing brace and the always.
548 An `error' in this context is a condition such as a syntax error
550 which causes the shell to abort execution of the current func‐
551 tion, script, or list. Syntax errors encountered while the
552 shell is parsing the code do not cause the always-list to be
553 executed. For example, an erroneously constructed if block in
554 try-list would cause the shell to abort during parsing, so that
555 always-list would not be executed, while an erroneous substitu‐
556 tion such as ${*foo*} would cause a run-time error, after which
557 always-list would be executed.
558 An error condition can be tested and reset with the special
560 integer variable TRY_BLOCK_ERROR. Outside an always-list the
561 value is irrelevant, but it is initialised to -1. Inside
562 always-list, the value is 1 if an error occurred in the
563 try-list, else 0. If TRY_BLOCK_ERROR is set to 0 during the
564 always-list, the error condition caused by the try-list is
565 reset, and shell execution continues normally after the end of
566 always-list. Altering the value during the try-list is not use‐
567 ful (unless this forms part of an enclosing always block).
568 Regardless of TRY_BLOCK_ERROR, after the end of always-list the
570 normal shell status $? is the value returned from always-list.
571 This will be non-zero if there was an error, even if
572 TRY_BLOCK_ERROR was set to zero.
573 The following executes the given code, ignoring any errors it
575 causes. This is an alternative to the usual convention of pro‐
576 tecting code by executing it in a subshell.
577 {
579 # code which may cause an error
580 } always {
581 # This code is executed regardless of the error.
582 (( TRY_BLOCK_ERROR = 0 ))
583 }
584 # The error condition has been reset.
585 An exit command encountered in try-list does not cause the exe‐
587 cution of always-list. Instead, the shell exits immediately
588 after any EXIT trap has been executed.
589 function word ... [ () ] [ term ] { list }
591 word ... () [ term ] { list }
592 word ... () [ term ] command
593 where term is one or more newline or ;. Define a function which
594 is referenced by any one of word. Normally, only one word is
595 provided; multiple words are usually only useful for setting
596 traps. The body of the function is the list between the { and
597 }. See the section `Functions'.
598 If the option SH_GLOB is set for compatibility with other
600 shells, then whitespace may appear between between the left and
601 right parentheses when there is a single word; otherwise, the
602 parentheses will be treated as forming a globbing pattern in
603 that case.
604 time [ pipeline ]
606 The pipeline is executed, and timing statistics are reported on
607 the standard error in the form specified by the TIMEFMT parame‐
608 ter. If pipeline is omitted, print statistics about the shell
609 process and its children.
610 [[ exp ]]
612 Evaluates the conditional expression exp and return a zero exit
613 status if it is true. See the section `Conditional Expressions'
614 for a description of exp.
615
617 Many of zsh's complex commands have alternate forms. These particular
618 versions of complex commands should be considered deprecated and may be
619 removed in the future. The versions in the previous section should be
620 preferred instead.
621 The short versions below only work if sublist is of the form `{ list }'
623 or if the SHORT_LOOPS option is set. For the if, while and until com‐
624 mands, in both these cases the test part of the loop must also be suit‐
625 ably delimited, such as by `[[ ... ]]' or `(( ... ))', else the end of
626 the test will not be recognized. For the for, repeat, case and select
627 commands no such special form for the arguments is necessary, but the
628 other condition (the special form of sublist or use of the SHORT_LOOPS
629 option) still applies.
630 if list { list } [ elif list { list } ] ... [ else { list } ]
632 An alternate form of if. The rules mean that
633 if [[ -o ignorebraces ]] {
635 print yes
636 }
637 works, but
639 if true { # Does not work!
641 print yes
642 }
643 does not, since the test is not suitably delimited.
645 if list sublist
647 A short form of the alternate `if'. The same limitations on the
648 form of list apply as for the previous form.
649 for name ... ( word ... ) sublist
651 A short form of for.
652 for name ... [ in word ... ] term sublist
654 where term is at least one newline or ;. Another short form of
655 for.
656 for (( [expr1] ; [expr2] ; [expr3] )) sublist
658 A short form of the arithmetic for command.
659 foreach name ... ( word ... ) list end
661 Another form of for.
662 while list { list }
664 An alternative form of while. Note the limitations on the form
665 of list mentioned above.
666 until list { list }
668 An alternative form of until. Note the limitations on the form
669 of list mentioned above.
670 repeat word sublist
672 This is a short form of repeat.
673 case word { [ [(] pattern [ | pattern ] ... ) list (;;|;&) ] ... }
675 An alternative form of case.
676 select name [ in word term ] sublist
678 where term is at least one newline or ;. A short form of
679 select.
680
682 The following words are recognized as reserved words when used as the
683 first word of a command unless quoted or disabled using disable -r:
684 do done esac then elif else fi for case if while function repeat time
686 until select coproc nocorrect foreach end ! [[ { }
687 Additionally, `}' is recognized in any position if the IGNORE_BRACES
689 option is not set.
690
692 In noninteractive shells, or in interactive shells with the INTERAC‐
693 TIVE_COMMENTS option set, a word beginning with the third character of
694 the histchars parameter (`#' by default) causes that word and all the
695 following characters up to a newline to be ignored.
696
698 Every token in the shell input is checked to see if there is an alias
699 defined for it. If so, it is replaced by the text of the alias if it
700 is in command position (if it could be the first word of a simple com‐
701 mand), or if the alias is global. If the text ends with a space, the
702 next word in the shell input is treated as though it were in command
703 position for purposes of alias expansion. An alias is defined using
704 the alias builtin; global aliases may be defined using the -g option to
705 that builtin.
706 Alias expansion is done on the shell input before any other expansion
708 except history expansion. Therefore, if an alias is defined for the
709 word foo, alias expansion may be avoided by quoting part of the word,
710 e.g. \foo. But there is nothing to prevent an alias being defined for
711 \foo as well.
712
714 A character may be quoted (that is, made to stand for itself) by pre‐
715 ceding it with a `\'. `\' followed by a newline is ignored.
716 A string enclosed between `$'' and `'' is processed the same way as the
718 string arguments of the print builtin, and the resulting string is con‐
719 sidered to be entirely quoted. A literal `'' character can be included
720 in the string by using the `\'' escape.
721 All characters enclosed between a pair of single quotes ('') that is
723 not preceded by a `$' are quoted. A single quote cannot appear within
724 single quotes unless the option RC_QUOTES is set, in which case a pair
725 of single quotes are turned into a single quote. For example,
726 print ''''
728 outputs nothing apart from a newline if RC_QUOTES is not set, but one
730 single quote if it is set.
731 Inside double quotes (""), parameter and command substitution occur,
733 and `\' quotes the characters `\', ``', `"', and `$'.
734
736 If a command is followed by & and job control is not active, then the
737 default standard input for the command is the empty file /dev/null.
738 Otherwise, the environment for the execution of a command contains the
739 file descriptors of the invoking shell as modified by input/output
740 specifications.
741 The following may appear anywhere in a simple command or may precede or
743 follow a complex command. Expansion occurs before word or digit is
744 used except as noted below. If the result of substitution on word pro‐
745 duces more than one filename, redirection occurs for each separate
746 filename in turn.
747 < word Open file word for reading as standard input.
749 <> word
751 Open file word for reading and writing as standard input. If
752 the file does not exist then it is created.
753 > word Open file word for writing as standard output. If the file does
755 not exist then it is created. If the file exists, and the CLOB‐
756 BER option is unset, this causes an error; otherwise, it is
757 truncated to zero length.
758 >| word
760 >! word
761 Same as >, except that the file is truncated to zero length if
762 it exists, even if CLOBBER is unset.
763 >> word
765 Open file word for writing in append mode as standard output.
766 If the file does not exist, and the CLOBBER option is unset,
767 this causes an error; otherwise, the file is created.
768 >>| word
770 >>! word
771 Same as >>, except that the file is created if it does not
772 exist, even if CLOBBER is unset.
773 <<[-] word
775 The shell input is read up to a line that is the same as word,
776 or to an end-of-file. No parameter expansion, command substitu‐
777 tion or filename generation is performed on word. The resulting
778 document, called a here-document, becomes the standard input.
779 If any character of word is quoted with single or double quotes
781 or a `\', no interpretation is placed upon the characters of the
782 document. Otherwise, parameter and command substitution occurs,
783 `\' followed by a newline is removed, and `\' must be used to
784 quote the characters `\', `$', ``' and the first character of
785 word.
786 Note that word itself does not undergo shell expansion. Back‐
788 quotes in word do not have their usual effect; instead they
789 behave similarly to double quotes, except that the backquotes
790 themselves are passed through unchanged. (This information is
791 given for completeness and it is not recommended that backquotes
792 be used.) Quotes in the form $'...' have their standard effect
793 of expanding backslashed references to special characters.
794 If <<- is used, then all leading tabs are stripped from word and
796 from the document.
797 <<< word
799 Perform shell expansion on word and pass the result to standard
800 input. This is known as a here-string. Compare the use of word
801 in here-documents above, where word does not undergo shell
802 expansion.
803 <& number
805 >& number
806 The standard input/output is duplicated from file descriptor
807 number (see dup2(2)).
808 <& -
810 >& - Close the standard input/output.
811 <& p
813 >& p The input/output from/to the coprocess is moved to the standard
814 input/output.
815 >& word
817 &> word
818 (Except where `>& word' matches one of the above syntaxes; `&>'
819 can always be used to avoid this ambiguity.) Redirects both
820 standard output and standard error (file descriptor 2) in the
821 manner of `> word'. Note that this does not have the same
822 effect as `> word 2>&1' in the presence of multios (see the sec‐
823 tion below).
824 >&| word
826 >&! word
827 &>| word
828 &>! word
829 Redirects both standard output and standard error (file descrip‐
830 tor 2) in the manner of `>| word'.
831 >>& word
833 &>> word
834 Redirects both standard output and standard error (file descrip‐
835 tor 2) in the manner of `>> word'.
836 >>&| word
838 >>&! word
839 &>>| word
840 &>>! word
841 Redirects both standard output and standard error (file descrip‐
842 tor 2) in the manner of `>>| word'.
843 If one of the above is preceded by a digit, then the file descriptor
845 referred to is that specified by the digit instead of the default 0 or
846 1. The order in which redirections are specified is significant. The
847 shell evaluates each redirection in terms of the (file descriptor,
848 file) association at the time of evaluation. For example:
849 ... 1>fname 2>&1
851 first associates file descriptor 1 with file fname. It then associates
853 file descriptor 2 with the file associated with file descriptor 1 (that
854 is, fname). If the order of redirections were reversed, file descrip‐
855 tor 2 would be associated with the terminal (assuming file descriptor 1
856 had been) and then file descriptor 1 would be associated with file
857 fname.
858 The `|&' command separator described in Simple Commands & Pipelines in
860 zshmisc(1) is a shorthand for `2>&1 |'.
861 For output redirections only, if word is of the form `>(list)' then the
863 output is piped to the command represented by list. See Process Sub‐
864 stitution in zshexpn(1).
865
867 If the user tries to open a file descriptor for writing more than once,
868 the shell opens the file descriptor as a pipe to a process that copies
869 its input to all the specified outputs, similar to tee, provided the
870 MULTIOS option is set, as it is by default. Thus:
871 date >foo >bar
873 writes the date to two files, named `foo' and `bar'. Note that a pipe
875 is an implicit redirection; thus
876 date >foo | cat
878 writes the date to the file `foo', and also pipes it to cat.
880 If the MULTIOS option is set, the word after a redirection operator is
882 also subjected to filename generation (globbing). Thus
883 : > *
885 will truncate all files in the current directory, assuming there's at
887 least one. (Without the MULTIOS option, it would create an empty file
888 called `*'.) Similarly, you can do
889 echo exit 0 >> *.sh
891 If the user tries to open a file descriptor for reading more than once,
893 the shell opens the file descriptor as a pipe to a process that copies
894 all the specified inputs to its output in the order specified, similar
895 to cat, provided the MULTIOS option is set. Thus
896 sort <foo <fubar
898 or even
900 sort <f{oo,ubar}
902 is equivalent to `cat foo fubar | sort'.
904 Note that a pipe is an implicit redirection; thus
906 cat bar | sort <foo
908 is equivalent to `cat bar foo | sort' (note the order of the inputs).
910 If the MULTIOS option is unset, each redirection replaces the previous
912 redirection for that file descriptor. However, all files redirected to
913 are actually opened, so
914 echo foo > bar > baz
916 when MULTIOS is unset will truncate bar, and write `foo' into baz.
918 There is a problem when an output multio is attached to an external
920 program. A simple example shows this:
921 cat file >file1 >file2
923 cat file1 file2
924 Here, it is possible that the second `cat' will not display the full
926 contents of file1 and file2 (i.e. the original contents of file
927 repeated twice).
928 The reason for this is that the multios are spawned after the cat
930 process is forked from the parent shell, so the parent shell does not
931 wait for the multios to finish writing data. This means the command as
932 shown can exit before file1 and file2 are completely written. As a
933 workaround, it is possible to run the cat process as part of a job in
934 the current shell:
935 { cat file } >file >file2
937 Here, the {...} job will pause to wait for both files to be written.
939
941 When a simple command consists of one or more redirection operators and
942 zero or more parameter assignments, but no command name, zsh can behave
943 in several ways.
944 If the parameter NULLCMD is not set or the option CSH_NULLCMD is set,
946 an error is caused. This is the csh behavior and CSH_NULLCMD is set by
947 default when emulating csh.
948 If the option SH_NULLCMD is set, the builtin `:' is inserted as a com‐
950 mand with the given redirections. This is the default when emulating
951 sh or ksh.
952 Otherwise, if the parameter NULLCMD is set, its value will be used as a
954 command with the given redirections. If both NULLCMD and READNULLCMD
955 are set, then the value of the latter will be used instead of that of
956 the former when the redirection is an input. The default for NULLCMD
957 is `cat' and for READNULLCMD is `more'. Thus
958 < file
960 shows the contents of file on standard output, with paging if that is a
962 terminal. NULLCMD and READNULLCMD may refer to shell functions.
963
965 If a command name contains no slashes, the shell attempts to locate it.
966 If there exists a shell function by that name, the function is invoked
967 as described in the section `Functions'. If there exists a shell
968 builtin by that name, the builtin is invoked.
969 Otherwise, the shell searches each element of $path for a directory
971 containing an executable file by that name. If the search is unsuc‐
972 cessful, the shell prints an error message and returns a nonzero exit
973 status.
974 If execution fails because the file is not in executable format, and
976 the file is not a directory, it is assumed to be a shell script.
977 /bin/sh is spawned to execute it. If the program is a file beginning
978 with `#!', the remainder of the first line specifies an interpreter for
979 the program. The shell will execute the specified interpreter on oper‐
980 ating systems that do not handle this executable format in the kernel.
981
983 Shell functions are defined with the function reserved word or the spe‐
984 cial syntax `funcname ()'. Shell functions are read in and stored
985 internally. Alias names are resolved when the function is read. Func‐
986 tions are executed like commands with the arguments passed as posi‐
987 tional parameters. (See the section `Command Execution'.)
988 Functions execute in the same process as the caller and share all files
990 and present working directory with the caller. A trap on EXIT set
991 inside a function is executed after the function completes in the envi‐
992 ronment of the caller.
993 The return builtin is used to return from function calls.
995 Function identifiers can be listed with the functions builtin. Func‐
997 tions can be undefined with the unfunction builtin.
998
1000 A function can be marked as undefined using the autoload builtin (or
1001 `functions -u' or `typeset -fu'). Such a function has no body. When
1002 the function is first executed, the shell searches for its definition
1003 using the elements of the fpath variable. Thus to define functions for
1004 autoloading, a typical sequence is:
1005 fpath=(~/myfuncs $fpath)
1007 autoload myfunc1 myfunc2 ...
1008 The usual alias expansion during reading will be suppressed if the
1010 autoload builtin or its equivalent is given the option -U. This is rec‐
1011 ommended for the use of functions supplied with the zsh distribution.
1012 Note that for functions precompiled with the zcompile builtin command
1013 the flag -U must be provided when the .zwc file is created, as the cor‐
1014 responding information is compiled into the latter.
1015 For each element in fpath, the shell looks for three possible files,
1017 the newest of which is used to load the definition for the function:
1018 element.zwc
1020 A file created with the zcompile builtin command, which is
1021 expected to contain the definitions for all functions in the
1022 directory named element. The file is treated in the same manner
1023 as a directory containing files for functions and is searched
1024 for the definition of the function. If the definition is not
1025 found, the search for a definition proceeds with the other two
1026 possibilities described below.
1027 If element already includes a .zwc extension (i.e. the extension
1029 was explicitly given by the user), element is searched for the
1030 definition of the function without comparing its age to that of
1031 other files; in fact, there does not need to be any directory
1032 named element without the suffix. Thus including an element
1033 such as `/usr/local/funcs.zwc' in fpath will speed up the search
1034 for functions, with the disadvantage that functions included
1035 must be explicitly recompiled by hand before the shell notices
1036 any changes.
1037 element/function.zwc
1039 A file created with zcompile, which is expected to contain the
1040 definition for function. It may include other function defini‐
1041 tions as well, but those are neither loaded nor executed; a file
1042 found in this way is searched only for the definition of func‐
1043 tion.
1044 element/function
1046 A file of zsh command text, taken to be the definition for func‐
1047 tion.
1048 In summary, the order of searching is, first, in the parents of direc‐
1050 tories in fpath for the newer of either a compiled directory or a
1051 directory in fpath; second, if more than one of these contains a defi‐
1052 nition for the function that is sought, the leftmost in the fpath is
1053 chosen; and third, within a directory, the newer of either a compiled
1054 function or an ordinary function definition is used.
1055 If the KSH_AUTOLOAD option is set, or the file contains only a simple
1057 definition of the function, the file's contents will be executed. This
1058 will normally define the function in question, but may also perform
1059 initialization, which is executed in the context of the function execu‐
1060 tion, and may therefore define local parameters. It is an error if the
1061 function is not defined by loading the file.
1062 Otherwise, the function body (with no surrounding `funcname() {...}')
1064 is taken to be the complete contents of the file. This form allows the
1065 file to be used directly as an executable shell script. If processing
1066 of the file results in the function being re-defined, the function
1067 itself is not re-executed. To force the shell to perform initializa‐
1068 tion and then call the function defined, the file should contain ini‐
1069 tialization code (which will be executed then discarded) in addition to
1070 a complete function definition (which will be retained for subsequent
1071 calls to the function), and a call to the shell function, including any
1072 arguments, at the end.
1073 For example, suppose the autoload file func contains
1075 func() { print This is func; }
1077 print func is initialized
1078 then `func; func' with KSH_AUTOLOAD set will produce both messages on
1080 the first call, but only the message `This is func' on the second and
1081 subsequent calls. Without KSH_AUTOLOAD set, it will produce the ini‐
1082 tialization message on the first call, and the other message on the
1083 second and subsequent calls.
1084 It is also possible to create a function that is not marked as
1086 autoloaded, but which loads its own definition by searching fpath, by
1087 using `autoload -X' within a shell function. For example, the follow‐
1088 ing are equivalent:
1089 myfunc() {
1091 autoload -X
1092 }
1093 myfunc args...
1094 and
1096 unfunction myfunc # if myfunc was defined
1098 autoload myfunc
1099 myfunc args...
1100 In fact, the functions command outputs `builtin autoload -X' as the
1102 body of an autoloaded function. This is done so that
1103 eval "$(functions)"
1105 produces a reasonable result. A true autoloaded function can be iden‐
1107 tified by the presence of the comment `# undefined' in the body,
1108 because all comments are discarded from defined functions.
1109 To load the definition of an autoloaded function myfunc without execut‐
1111 ing myfunc, use:
1112 autoload +X myfunc
1114
1116 The following functions, if defined, have special meaning to the shell:
1117 chpwd Executed whenever the current working directory is changed.
1119 periodic
1121 If the parameter PERIOD is set, this function is executed every
1122 $PERIOD seconds, just before a prompt.
1123 precmd Executed before each prompt.
1125 preexec
1127 Executed just after a command has been read and is about to be
1128 executed. If the history mechanism is active (and the line was
1129 not discarded from the history buffer), the string that the user
1130 typed is passed as the first argument, otherwise it is an empty
1131 string. The actual command that will be executed (including
1132 expanded aliases) is passed in two different forms: the second
1133 argument is a single-line, size-limited version of the command
1134 (with things like function bodies elided); the third argument
1135 contains the full text that is being executed.
1136 TRAPNAL
1138 If defined and non-null, this function will be executed whenever
1139 the shell catches a signal SIGNAL, where NAL is a signal name as
1140 specified for the kill builtin. The signal number will be
1141 passed as the first parameter to the function.
1142 If a function of this form is defined and null, the shell and
1144 processes spawned by it will ignore SIGNAL.
1145 The return value from the function is handled specially. If it
1147 is zero, the signal is assumed to have been handled, and execu‐
1148 tion continues normally. Otherwise, the normal effect of the
1149 signal is produced; if this causes execution to terminate, the
1150 status returned to the shell is the status returned from the
1151 function.
1152 Programs terminated by uncaught signals typically return the
1154 status 128 plus the signal number. Hence the following causes
1155 the handler for SIGINT to print a message, then mimic the usual
1156 effect of the signal.
1157 TRAPINT() {
1159 print "Caught SIGINT, aborting."
1160 return $(( 128 + $1 ))
1161 }
1162 The functions TRAPZERR, TRAPDEBUG and TRAPEXIT are never exe‐
1164 cuted inside other traps.
1165 TRAPDEBUG
1167 Executed after each command.
1168 TRAPEXIT
1170 Executed when the shell exits, or when the current function
1171 exits if defined inside a function.
1172 TRAPZERR
1174 Executed whenever a command has a non-zero exit status. How‐
1175 ever, the function is not executed if the command occurred in a
1176 sublist followed by `&&' or `||'; only the final command in a
1177 sublist of this type causes the trap to be executed.
1178 The functions beginning `TRAP' may alternatively be defined with the
1180 trap builtin: this may be preferable for some uses, as they are then
1181 run in the environment of the calling process, rather than in their own
1182 function environment. Apart from the difference in calling procedure
1183 and the fact that the function form appears in lists of functions, the
1184 forms
1185 TRAPNAL() {
1187 # code
1188 }
1189 and
1191 trap '
1193 # code
1194 are equivalent.
1196
1198 If the MONITOR option is set, an interactive shell associates a job
1199 with each pipeline. It keeps a table of current jobs, printed by the
1200 jobs command, and assigns them small integer numbers. When a job is
1201 started asynchronously with `&', the shell prints a line to standard
1202 error which looks like:
1203 [1] 1234
1205 indicating that the job which was started asynchronously was job number
1207 1 and had one (top-level) process, whose process ID was 1234.
1208 If a job is started with `&|' or `&!', then that job is immediately
1210 disowned. After startup, it does not have a place in the job table,
1211 and is not subject to the job control features described here.
1212 If you are running a job and wish to do something else you may hit the
1214 key ^Z (control-Z) which sends a TSTP signal to the current job: this
1215 key may be redefined by the susp option of the external stty command.
1216 The shell will then normally indicate that the job has been `sus‐
1217 pended', and print another prompt. You can then manipulate the state
1218 of this job, putting it in the background with the bg command, or run
1219 some other commands and then eventually bring the job back into the
1220 foreground with the foreground command fg. A ^Z takes effect immedi‐
1221 ately and is like an interrupt in that pending output and unread input
1222 are discarded when it is typed.
1223 A job being run in the background will suspend if it tries to read from
1225 the terminal. Background jobs are normally allowed to produce output,
1226 but this can be disabled by giving the command `stty tostop'. If you
1227 set this tty option, then background jobs will suspend when they try to
1228 produce output like they do when they try to read input.
1229 When a command is suspended and continued later with the fg or wait
1231 builtins, zsh restores tty modes that were in effect when it was sus‐
1232 pended. This (intentionally) does not apply if the command is contin‐
1233 ued via `kill -CONT', nor when it is continued with bg.
1234 There are several ways to refer to jobs in the shell. A job can be
1236 referred to by the process ID of any process of the job or by one of
1237 the following:
1238 %number
1240 The job with the given number.
1241 %string
1242 Any job whose command line begins with string.
1243 %?string
1244 Any job whose command line contains string.
1245 %% Current job.
1246 %+ Equivalent to `%%'.
1247 %- Previous job.
1248 The shell learns immediately whenever a process changes state. It nor‐
1250 mally informs you whenever a job becomes blocked so that no further
1251 progress is possible. If the NOTIFY option is not set, it waits until
1252 just before it prints a prompt before it informs you. All such notifi‐
1253 cations are sent directly to the terminal, not to the standard output
1254 or standard error.
1255 When the monitor mode is on, each background job that completes trig‐
1257 gers any trap set for CHLD.
1258 When you try to leave the shell while jobs are running or suspended,
1260 you will be warned that `You have suspended (running) jobs'. You may
1261 use the jobs command to see what they are. If you do this or immedi‐
1262 ately try to exit again, the shell will not warn you a second time; the
1263 suspended jobs will be terminated, and the running jobs will be sent a
1264 SIGHUP signal, if the HUP option is set.
1265 To avoid having the shell terminate the running jobs, either use the
1267 nohup command (see nohup(1)) or the disown builtin.
1268
1270 The INT and QUIT signals for an invoked command are ignored if the com‐
1271 mand is followed by `&' and the MONITOR option is not active. Other‐
1272 wise, signals have the values inherited by the shell from its parent
1273 (but see the TRAPNAL special functions in the section `Functions').
1274
1276 The shell can perform integer and floating point arithmetic, either
1277 using the builtin let, or via a substitution of the form $((...)). For
1278 integers, the shell is usually compiled to use 8-byte precision where
1279 this is available, otherwise precision is 4 bytes. This can be tested,
1280 for example, by giving the command `print - $(( 12345678901 ))'; if the
1281 number appears unchanged, the precision is at least 8 bytes. Floating
1282 point arithmetic is always double precision.
1283 The let builtin command takes arithmetic expressions as arguments; each
1285 is evaluated separately. Since many of the arithmetic operators, as
1286 well as spaces, require quoting, an alternative form is provided: for
1287 any command which begins with a `((', all the characters until a match‐
1288 ing `))' are treated as a quoted expression and arithmetic expansion
1289 performed as for an argument of let. More precisely, `((...))' is
1290 equivalent to `let "..."'. For example, the following statement
1291 (( val = 2 + 1 ))
1293 is equivalent to
1295 let "val = 2 + 1"
1297 both assigning the value 3 to the shell variable val and returning a
1299 zero status.
1300 Integers can be in bases other than 10. A leading `0x' or `0X' denotes
1302 hexadecimal. Integers may also be of the form `base#n', where base is
1303 a decimal number between two and thirty-six representing the arithmetic
1304 base and n is a number in that base (for example, `16#ff' is 255 in
1305 hexadecimal). The base# may also be omitted, in which case base 10 is
1306 used. For backwards compatibility the form `[base]n' is also accepted.
1307 It is also possible to specify a base to be used for output in the form
1309 `[#base]', for example `[#16]'. This is used when outputting arith‐
1310 metical substitutions or when assigning to scalar parameters, but an
1311 explicitly defined integer or floating point parameter will not be
1312 affected. If an integer variable is implicitly defined by an arith‐
1313 metic expression, any base specified in this way will be set as the
1314 variable's output arithmetic base as if the option `-i base' to the
1315 typeset builtin had been used. The expression has no precedence and if
1316 it occurs more than once in a mathematical expression, the last encoun‐
1317 tered is used. For clarity it is recommended that it appear at the
1318 beginning of an expression. As an example:
1319 typeset -i 16 y
1321 print $(( [#8] x = 32, y = 32 ))
1322 print $x $y
1323 outputs first `8#40', the rightmost value in the given output base, and
1325 then `8#40 16#20', because y has been explicitly declared to have out‐
1326 put base 16, while x (assuming it does not already exist) is implicitly
1327 typed by the arithmetic evaluation, where it acquires the output base
1328 8.
1329 If the C_BASES option is set, hexadecimal numbers in the standard C
1331 format, for example 0xFF instead of the usual `16#FF'. If the option
1332 OCTAL_ZEROES is also set (it is not by default), octal numbers will be
1333 treated similarly and hence appear as `077' instead of `8#77'. This
1334 option has no effect on the output of bases other than hexadecimal and
1335 octal, and these formats are always understood on input.
1336 When an output base is specified using the `[#base]' syntax, an appro‐
1338 priate base prefix will be output if necessary, so that the value out‐
1339 put is valid syntax for input. If the # is doubled, for example
1340 `[##16]', then no base prefix is output.
1341 Floating point constants are recognized by the presence of a decimal
1343 point or an exponent. The decimal point may be the first character of
1344 the constant, but the exponent character e or E may not, as it will be
1345 taken for a parameter name.
1346 An arithmetic expression uses nearly the same syntax, precedence, and
1348 associativity of expressions in C. The following operators are sup‐
1349 ported (listed in decreasing order of precedence):
1350 + - ! ~ ++ --
1352 unary plus/minus, logical NOT, complement, {pre,post}{in,de}cre‐
1353 ment
1354 << >> bitwise shift left, right
1355 & bitwise AND
1356 ^ bitwise XOR
1357 | bitwise OR
1358 ** exponentiation
1359 * / % multiplication, division, modulus (remainder)
1360 + - addition, subtraction
1361 < > <= >=
1362 comparison
1363 == != equality and inequality
1364 && logical AND
1365 || ^^ logical OR, XOR
1366 ? : ternary operator
1367 = += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=
1368 assignment
1369 , comma operator
1370 The operators `&&', `||', `&&=', and `||=' are short-circuiting, and
1372 only one of the latter two expressions in a ternary operator is evalu‐
1373 ated. Note the precedence of the bitwise AND, OR, and XOR operators.
1374 Mathematical functions can be called with the syntax `func(args)',
1376 where the function decides if the args is used as a string or a
1377 comma-separated list of arithmetic expressions. The shell currently
1378 defines no mathematical functions by default, but the module zsh/math‐
1379 func may be loaded with the zmodload builtin to provide standard float‐
1380 ing point mathematical functions.
1381 An expression of the form `##x' where x is any character sequence such
1383 as `a', `^A', or `\M-\C-x' gives the ASCII value of this character and
1384 an expression of the form `#foo' gives the ASCII value of the first
1385 character of the value of the parameter foo. Note that this is differ‐
1386 ent from the expression `$#foo', a standard parameter substitution
1387 which gives the length of the parameter foo. `#\' is accepted instead
1388 of `##', but its use is deprecated.
1389 Named parameters and subscripted arrays can be referenced by name
1391 within an arithmetic expression without using the parameter expansion
1392 syntax. For example,
1393 ((val2 = val1 * 2))
1395 assigns twice the value of $val1 to the parameter named val2.
1397 An internal integer representation of a named parameter can be speci‐
1399 fied with the integer builtin. Arithmetic evaluation is performed on
1400 the value of each assignment to a named parameter declared integer in
1401 this manner. Assigning a floating point number to an integer results
1402 in rounding down to the next integer.
1403 Likewise, floating point numbers can be declared with the float
1405 builtin; there are two types, differing only in their output format, as
1406 described for the typeset builtin. The output format can be bypassed
1407 by using arithmetic substitution instead of the parameter substitution,
1408 i.e. `${float}' uses the defined format, but `$((float))' uses a
1409 generic floating point format.
1410 Promotion of integer to floating point values is performed where neces‐
1412 sary. In addition, if any operator which requires an integer (`~',
1413 `&', `|', `^', `%', `<<', `>>' and their equivalents with assignment)
1414 is given a floating point argument, it will be silently rounded down to
1415 the next integer.
1416 Scalar variables can hold integer or floating point values at different
1418 times; there is no memory of the numeric type in this case.
1419 If a variable is first assigned in a numeric context without previously
1421 being declared, it will be implicitly typed as integer or float and
1422 retain that type either until the type is explicitly changed or until
1423 the end of the scope. This can have unforeseen consequences. For
1424 example, in the loop
1425 for (( f = 0; f < 1; f += 0.1 )); do
1427 # use $f
1428 done
1429 if f has not already been declared, the first assignment will cause it
1431 to be created as an integer, and consequently the operation `f += 0.1'
1432 will always cause the result to be truncated to zero, so that the loop
1433 will fail. A simple fix would be to turn the initialization into `f =
1434 0.0'. It is therefore best to declare numeric variables with explicit
1435 types.
1436
1438 A conditional expression is used with the [[ compound command to test
1439 attributes of files and to compare strings. Each expression can be
1440 constructed from one or more of the following unary or binary expres‐
1441 sions:
1442 -a file
1444 true if file exists.
1445 -b file
1447 true if file exists and is a block special file.
1448 -c file
1450 true if file exists and is a character special file.
1451 -d file
1453 true if file exists and is a directory.
1454 -e file
1456 true if file exists.
1457 -f file
1459 true if file exists and is a regular file.
1460 -g file
1462 true if file exists and has its setgid bit set.
1463 -h file
1465 true if file exists and is a symbolic link.
1466 -k file
1468 true if file exists and has its sticky bit set.
1469 -n string
1471 true if length of string is non-zero.
1472 -o option
1474 true if option named option is on. option may be a single char‐
1475 acter, in which case it is a single letter option name. (See
1476 the section `Specifying Options'.)
1477 -p file
1479 true if file exists and is a FIFO special file (named pipe).
1480 -r file
1482 true if file exists and is readable by current process.
1483 -s file
1485 true if file exists and has size greater than zero.
1486 -t fd true if file descriptor number fd is open and associated with a
1488 terminal device. (note: fd is not optional)
1489 -u file
1491 true if file exists and has its setuid bit set.
1492 -w file
1494 true if file exists and is writable by current process.
1495 -x file
1497 true if file exists and is executable by current process. If
1498 file exists and is a directory, then the current process has
1499 permission to search in the directory.
1500 -z string
1502 true if length of string is zero.
1503 -L file
1505 true if file exists and is a symbolic link.
1506 -O file
1508 true if file exists and is owned by the effective user ID of
1509 this process.
1510 -G file
1512 true if file exists and its group matches the effective group ID
1513 of this process.
1514 -S file
1516 true if file exists and is a socket.
1517 -N file
1519 true if file exists and its access time is not newer than its
1520 modification time.
1521 file1 -nt file2
1523 true if file1 exists and is newer than file2.
1524 file1 -ot file2
1526 true if file1 exists and is older than file2.
1527 file1 -ef file2
1529 true if file1 and file2 exist and refer to the same file.
1530 string = pattern
1532 string == pattern
1533 true if string matches pattern. The `==' form is the preferred
1534 one. The `=' form is for backward compatibility and should be
1535 considered obsolete.
1536 string != pattern
1538 true if string does not match pattern.
1539 string1 < string2
1541 true if string1 comes before string2 based on ASCII value of
1542 their characters.
1543 string1 > string2
1545 true if string1 comes after string2 based on ASCII value of
1546 their characters.
1547 exp1 -eq exp2
1549 true if exp1 is numerically equal to exp2.
1550 exp1 -ne exp2
1552 true if exp1 is numerically not equal to exp2.
1553 exp1 -lt exp2
1555 true if exp1 is numerically less than exp2.
1556 exp1 -gt exp2
1558 true if exp1 is numerically greater than exp2.
1559 exp1 -le exp2
1561 true if exp1 is numerically less than or equal to exp2.
1562 exp1 -ge exp2
1564 true if exp1 is numerically greater than or equal to exp2.
1565 ( exp )
1567 true if exp is true.
1568 ! exp true if exp is false.
1570 exp1 && exp2
1572 true if exp1 and exp2 are both true.
1573 exp1 || exp2
1575 true if either exp1 or exp2 is true.
1576 Normal shell expansion is performed on the file, string and pattern
1578 arguments, but the result of each expansion is constrained to be a sin‐
1579 gle word, similar to the effect of double quotes. However, pattern
1580 metacharacters are active for the pattern arguments; the patterns are
1581 the same as those used for filename generation, see zshexpn(1), but
1582 there is no special behaviour of `/' nor initial dots, and no glob
1583 qualifiers are allowed.
1584 In each of the above expressions, if file is of the form `/dev/fd/n',
1586 where n is an integer, then the test applied to the open file whose
1587 descriptor number is n, even if the underlying system does not support
1588 the /dev/fd directory.
1589 In the forms which do numeric comparison, the expressions exp undergo
1591 arithmetic expansion as if they were enclosed in $((...)).
1592 For example, the following:
1594 [[ ( -f foo || -f bar ) && $report = y* ]] && print File exists.
1596 tests if either file foo or file bar exists, and if so, if the value of
1598 the parameter report begins with `y'; if the complete condition is
1599 true, the message `File exists.' is printed.
1600
1602 Prompt sequences undergo a special form of expansion. This type of
1603 expansion is also available using the -P option to the print builtin.
1604 If the PROMPT_SUBST option is set, the prompt string is first subjected
1606 to parameter expansion, command substitution and arithmetic expansion.
1607 See zshexpn(1).
1608 Certain escape sequences may be recognised in the prompt string.
1610 If the PROMPT_BANG option is set, a `!' in the prompt is replaced by
1612 the current history event number. A literal `!' may then be repre‐
1613 sented as `!!'.
1614 If the PROMPT_PERCENT option is set, certain escape sequences that
1616 start with `%' are expanded. Some escapes take an optional integer
1617 argument, which should appear between the `%' and the next character of
1618 the sequence. The following escape sequences are recognized:
1619 Special characters
1621 %% A `%'.
1622 %) A `)'.
1624 Login information
1626 %l The line (tty) the user is logged in on, without `/dev/' prefix.
1627 If the name starts with `/dev/tty', that prefix is stripped.
1628 %M The full machine hostname.
1630 %m The hostname up to the first `.'. An integer may follow the `%'
1632 to specify how many components of the hostname are desired.
1633 With a negative integer, trailing components of the hostname are
1634 shown.
1635 %n $USERNAME.
1637 %y The line (tty) the user is logged in on, without `/dev/' prefix.
1639 This does not treat `/dev/tty' names specially.
1640 Shell state
1642 %# A `#' if the shell is running with privileges, a `%' if not.
1643 Equivalent to `%(!.#.%%)'. The definition of `privileged', for
1644 these purposes, is that either the effective user ID is zero,
1645 or, if POSIX.1e capabilities are supported, that at least one
1646 capability is raised in either the Effective or Inheritable
1647 capability vectors.
1648 %? The return code of the last command executed just before the
1650 prompt.
1651 %_ The status of the parser, i.e. the shell constructs (like `if'
1653 and `for') that have been started on the command line. If given
1654 an integer number that many strings will be printed; zero or
1655 negative or no integer means print as many as there are. This
1656 is most useful in prompts PS2 for continuation lines and PS4 for
1657 debugging with the XTRACE option; in the latter case it will
1658 also work non-interactively.
1659 %d
1661 %/ Present working directory ($PWD). If an integer follows the
1662 `%', it specifies a number of trailing components of $PWD to
1663 show; zero means the whole path. A negative integer specifies
1664 leading components, i.e. %-1d specifies the first component.
1665 %~ As %d and %/, but if $PWD has a named directory as its prefix,
1667 that part is replaced by a `~' followed by the name of the
1668 directory. If it starts with $HOME, that part is replaced by a
1669 `~'.
1670 %h
1672 %! Current history event number.
1673 %i The line number currently being executed in the script, sourced
1675 file, or shell function given by %N. This is most useful for
1676 debugging as part of $PS4.
1677 %j The number of jobs.
1679 %L The current value of $SHLVL.
1681 %N The name of the script, sourced file, or shell function that zsh
1683 is currently executing, whichever was started most recently. If
1684 there is none, this is equivalent to the parameter $0. An inte‐
1685 ger may follow the `%' to specify a number of trailing path com‐
1686 ponents to show; zero means the full path. A negative integer
1687 specifies leading components.
1688 %c
1690 %.
1691 %C Trailing component of $PWD. An integer may follow the `%' to
1692 get more than one component. Unless `%C' is used, tilde con‐
1693 traction is performed first. These are deprecated as %c and %C
1694 are equivalent to %1~ and %1/, respectively, while explicit pos‐
1695 itive integers have the same effect as for the latter two
1696 sequences.
1697 Date and time
1699 %D The date in yy-mm-dd format.
1700 %T Current time of day, in 24-hour format.
1702 %t
1704 %@ Current time of day, in 12-hour, am/pm format.
1705 %* Current time of day in 24-hour format, with seconds.
1707 %w The date in day-dd format.
1709 %W The date in mm/dd/yy format.
1711 %D{string}
1713 string is formatted using the strftime function. See strf‐
1714 time(3) for more details. Three additional codes are available:
1715 %f prints the day of the month, like %e but without any preced‐
1716 ing space if the day is a single digit, and %K/%L correspond to
1717 %k/%l for the hour of the day (24/12 hour clock) in the same
1718 way.
1719 Visual effects
1721 %B (%b)
1722 Start (stop) boldface mode.
1723 %E Clear to end of line.
1725 %U (%u)
1727 Start (stop) underline mode.
1728 %S (%s)
1730 Start (stop) standout mode.
1731 %{...%}
1733 Include a string as a literal escape sequence. The string
1734 within the braces should not change the cursor position. Brace
1735 pairs can nest.
1736 Conditional substrings
1738 %v The value of the first element of the psvar array parameter.
1739 Following the `%' with an integer gives that element of the
1740 array. Negative integers count from the end of the array.
1741 %(x.true-text.false-text)
1743 Specifies a ternary expression. The character following the x
1744 is arbitrary; the same character is used to separate the text
1745 for the `true' result from that for the `false' result. This
1746 separator may not appear in the true-text, except as part of a
1747 %-escape sequence. A `)' may appear in the false-text as `%)'.
1748 true-text and false-text may both contain arbitrarily-nested
1749 escape sequences, including further ternary expressions.
1750 The left parenthesis may be preceded or followed by a positive
1752 integer n, which defaults to zero. A negative integer will be
1753 multiplied by -1. The test character x may be any of the fol‐
1754 lowing:
1755 ! True if the shell is running with privileges.
1757 # True if the effective uid of the current process is n.
1758 ? True if the exit status of the last command was n.
1759 _ True if at least n shell constructs were started.
1760 C
1761 / True if the current absolute path has at least n elements
1762 relative to the root directory, hence / is counted as 0
1763 elements.
1764 c
1765 .
1766 ~ True if the current path, with prefix replacement, has at
1767 least n elements relative to the root directory, hence /
1768 is counted as 0 elements.
1769 D True if the month is equal to n (January = 0).
1770 d True if the day of the month is equal to n.
1771 g True if the effective gid of the current process is n.
1772 j True if the number of jobs is at least n.
1773 L True if the SHLVL parameter is at least n.
1774 l True if at least n characters have already been printed
1775 on the current line.
1776 S True if the SECONDS parameter is at least n.
1777 T True if the time in hours is equal to n.
1778 t True if the time in minutes is equal to n.
1779 v True if the array psvar has at least n elements.
1780 w True if the day of the week is equal to n (Sunday = 0).
1781 %<string<
1783 %>string>
1784 %[xstring]
1785 Specifies truncation behaviour for the remainder of the prompt
1786 string. The third, deprecated, form is equivalent to
1787 `%xstringx', i.e. x may be `<' or `>'. The numeric argument,
1788 which in the third form may appear immediately after the `[',
1789 specifies the maximum permitted length of the various strings
1790 that can be displayed in the prompt. The string will be dis‐
1791 played in place of the truncated portion of any string; note
1792 this does not undergo prompt expansion.
1793 The forms with `<' truncate at the left of the string, and the
1795 forms with `>' truncate at the right of the string. For exam‐
1796 ple, if the current directory is `/home/pike', the prompt
1797 `%8<..<%/' will expand to `..e/pike'. In this string, the ter‐
1798 minating character (`<', `>' or `]'), or in fact any character,
1799 may be quoted by a preceding `\'; note when using print -P, how‐
1800 ever, that this must be doubled as the string is also subject to
1801 standard print processing, in addition to any backslashes
1802 removed by a double quoted string: the worst case is therefore
1803 `print -P "%<\\\\<<..."'.
1804 If the string is longer than the specified truncation length, it
1806 will appear in full, completely replacing the truncated string.
1807 The part of the prompt string to be truncated runs to the end of
1809 the string, or to the end of the next enclosing group of the
1810 `%(' construct, or to the next truncation encountered at the
1811 same grouping level (i.e. truncations inside a `%(' are sepa‐
1812 rate), which ever comes first. In particular, a truncation with
1813 argument zero (e.g. `%<<') marks the end of the range of the
1814 string to be truncated while turning off truncation from there
1815 on. For example, the prompt '%10<...<%~%<<%# ' will print a
1816 truncated representation of the current directory, followed by a
1817 `%' or `#', followed by a space. Without the `%<<', those two
1818 characters would be included in the string to be truncated.
1819ZSHALL(1) General Commands Manual ZSHALL(1)
1823
1827 $ZDOTDIR/.zshenv
1828 $ZDOTDIR/.zprofile
1829 $ZDOTDIR/.zshrc
1830 $ZDOTDIR/.zlogin
1831 $ZDOTDIR/.zlogout
1832 ${TMPPREFIX}* (default is /tmp/zsh*)
1833 /etc/zshenv
1834 /etc/zprofile
1835 /etc/zshrc
1836 /etc/zlogin
1837 /etc/zlogout (installation-specific - /etc is the default)
1838
1840 sh(1), csh(1), tcsh(1), rc(1), bash(1), ksh(1)
1841 IEEE Standard for information Technology - Portable Operating System
1843 Interface (POSIX) - Part 2: Shell and Utilities, IEEE Inc, 1993, ISBN
1844 1-55937-255-9.
1845zsh 4.2.6 November 28, 2005 ZSHALL(1)