Z-Shell Frequently-Asked Questions

Chapter 3: How to get various things to work

3.1: Why does $var where var="foo bar" not do what I expect?

In most Bourne-shell derivatives, multiple-word variables such as

var="foo bar" are split into words when passed to a command or used in a for foo in $var loop. By default, zsh does not have that behaviour: the variable remains intact. (This is not a bug! See below.) An option (shwordsplit) exists to provide compatibility.

For example, defining the function args to show the number of its arguments:

args() { echo $#; } and with our definition of `var', args $var produces the output `1'. After setopt shwordsplit the same function produces the output `2', as with sh and ksh.

Unless you need strict sh/ksh compatibility, you should ask yourself whether you really want this behaviour, as it can produce unexpected effects for variables with entirely innocuous embedded spaces. This can cause horrendous quoting problems when invoking scripts from other shells. The natural way to produce word-splitting behaviour in zsh is via arrays. For example,

set -A array one two three twenty (or array=(one two three twenty) if you prefer), followed by args $array produces the output `4', regardless of the setting of shwordsplit. Arrays are also much more versatile than single strings. Probably if this mechanism had always been available there would never have been automatic word splitting in scalars, which is a sort of uncontrollable poor man's array.

Note that this happens regardless of the value of the internal field separator, $IFS; in other words, with IFS=:; foo=a:b; args $foo you get the answer 1.

Other ways of causing word splitting include a judicious use of `eval':

sentence="Longtemps, je me suis couch\\'e de bonne heure." eval "words=($sentence)" after which $words is an array with the words of $sentence (note characters special to the shell, such as the ' in this example, must already be quoted), or, less standard but more reliable, turning on shwordsplit for one variable only: args ${=sentence} always returns 8 with the above definition of args. (In older versions of zsh, ${=foo} toggled shwordsplit; now it forces it on.)

Note also the "$@" method of word splitting is always available in zsh functions and scripts (though strictly this does array splitting, not word splitting).

Shwordsplit is set when zsh is invoked with the names `ksh' or `sh', or (entirely equivalent) when emulate ksh or emulate sh is in effect.

3.2: What is the difference between `export' and the ALL_EXPORT option?

Normally, you would put a variable into the environment by using export var. The command setopt allexport causes all variables which are subsequently set (N.B. not all the ones which already exist) to be put into the environment.

This may seem a useful shorthand, but in practice it can have unhelpful side effects:

  1. Since every variable is in the environment as well as remembered by the shell, the memory for it needs to be allocated twice. This is bigger as well as slower.
  2. It really is every variable which is exported, even loop variables in for loops. This is probably a waste.
  3. An arbitrary variable created by the user might have a special meaning to a command. Since all shell variables are visible to commands, there is no protection against this.
For these reasons it is usually best to avoid ALL_EXPORT unless you have a specific use for it. One safe use is to set it before creating a list of variables in an initialisation file, then unset it immediately afterwards. Only those variables will be automatically exported.

3.3: How do I turn off spelling correction/globbing for a single command?

In the first case, you presumably have setopt correctall in an initialisation file, so that zsh checks the spelling of each word in the command line. You probably do not want this behaviour for commands which do not operate on existing files.

The answer is to alias the offending command to itself with nocorrect stuck on the front, e.g.

alias mkdir='nocorrect mkdir'

To turn off globbing, the rationale is identical:

alias mkdir='noglob mkdir' You can have both nocorrect and noglob, if you like, but the nocorrect must come first, since it is needed by the line editor, while noglob is only handled when the command is examined.

Note also that a shell function won't work: the no... directives must be expanded before the rest of the command line is parsed.

3.4: How do I get the meta key to work on my xterm?

As stated in the manual, zsh needs to be told about the meta key by using bindkey -me or bindkey -mv in your .zshrc or on the command line. You probably also need to tell the terminal driver to allow the `meta' bit of the character through; stty pass8 is the usual incantation. Sample .zshrc entry:

[[ $TERM = "xterm" ]] && stty pass8 && bindkey -me or, on SYSVR4-ish systems without pass8, [[ $TERM = "xterm" ]] && stty -parenb -istrip cs8 && bindkey -me (disable parity detection, don't strip high bit, use 8-bit characters). Make sure this comes before any bindkey entries in your .zshrc which redefine keys normally defined in the emacs/vi keymap.

You don't need the bindkey to be able to define your own sequences with the meta key, though you still need the stty.

3.5: How do I automatically display the directory in my xterm title bar?

You should use the special function chpwd, which is called when the directory changes. The following checks that standard output is a terminal, then puts the directory in the title bar if the terminal is an xterm or a sun-cmd.

chpwd() { [[ -t 1 ]] || return case $TERM in sun-cmd) print -Pn "\e]l%~\e\\" ;; xterm) print -Pn "\e]2;%~\a" ;; esac }

Change %~ if you want the message to be different. (The -P option interprets such sequences just like in prompts, in this case producing the current directory; you can of course use $PWD here, but that won't use the ~ notation which I find clearer.) Note that when the xterm starts up you will probably want to call chpwd directly: just put chpwd in .zshrc after it is defined or autoloaded.

3.6: How do I make the completion list use eight bit characters?

A traditional UNIX environment (character terminal and ASCII character sets) is not sufficient to be able to handle non-ASCII characters, and there are so many possible enhancements that in general this is hard. However, if you have something like an xterm using a standard character set like ISO-8859-1 (which is often the default for xterm), read on. You should also note question 3.4 on the subject of eight bit characters.

You are probably creating files with names including non-ASCII accented characters, and find they show up in the completion list as

\M-i or something such. This is because the library routines (not zsh itself) which test whether a character is printable have replied that it is not; zsh has simply found a way to show them anyway.

The answer, under a modern POSIXy operating system, is to find a locale where these are treated as printable characters. Zsh has handling for locales built in and will recognise when you set a relevant variable. You need to look in /usr/lib/locale to find one which suits you; the subdirectories correspond to the locale names. The simplest possibility is likely to be en_US, so that the simplest answer to your problem is to set

LC_CTYPE=en_US

when your terminal is capable of showing eight bit characters. If you only have a default domain (called C), you may need to have some additional files installed on your system.

3.7: Why does my terminal act funny in some way?

If you are using an OpenWindows cmdtool as your terminal, any escape sequences (such as those produced by cursor keys) will be swallowed up and never reach zsh. Either use shelltool or avoid commands with escape sequences. You can also disable scrolling from the cmdtool pane menu (which effectively turns it into a shelltool). If you still want scrolling, try using an xterm with the scrollbar activated.

If that's not the problem, and you are using stty to change some tty settings, make sure you haven't asked zsh to freeze the tty settings: type

ttyctl -u before any stty commands you use.

On the other hand, if you aren't using stty and have problems you may need the opposite: ttyctl -f freezes the terminal to protect it from hiccups introduced by other programmes (kermit has been known to do this).

If that's not the problem, and you are having difficulties with external commands (not part of zsh), and you think some terminal setting is wrong (e.g. ^V is getting interpreted as `literal next character' when you don't want it to be), try

ttyctl -u STTY='lnext "^-"' commandname (in this example), or just export STTY for all commands to see. Note that zsh doesn't reset the terminal completely afterwards: just the modes it uses itself and a number of special processing characters (see the stty(1) manual page).

At some point there may be an overhaul which allows the terminal modes used by the shell to be modified separately from those seen by external programmes. This is partially implemented already: from 2.5, the shell is less susceptible to mode changes inherited from programmes than it used to be.

3.8: Why does zsh not work in an Emacs shell mode any more?

(This information comes from Bart Schaefer and other zsh-workers.)

Emacs 19.29 or thereabouts stopped using a terminal type of "emacs" in shell buffers, and instead sets it to "dumb". Zsh only kicks in its special I'm-inside-emacs initialization when the terminal type is "emacs".

Probably the most reliable way of dealing with this is to look for the environment variable $EMACS, which is set to t in Emacs' shell mode. Putting

[[ $EMACS = t ]] && unsetopt zle in your .zshrc should be sufficient.

Another method is to put

#!/bin/sh TERM=emacs exec zsh into a file ~/bin/eshell, then chmod +x ~/bin/eshell, and tell emacs to use that as the shell by adding (setenv "ESHELL" "~/bin/eshell") to ~/.emacs.

3.9: Why do my autoloaded functions not autoload [the first time]?

The problem is that there are two possible ways of autoloading a function (see the AUTOLOADING FUNCTIONS section of the zsh manual page zshmisc for more detailed information):

  1. The file contains just the body of the function, i.e. there should be no line at the beginning saying function foo { or foo () {, and consequently no matching } at the end. This is the traditional zsh method. The advantage is that the file is called exactly like a script, so can double as both. To define a function xhead () { print -n "\033]2;$*\a"; }, the file would just contain print -n "\033]2;$*\a".
  2. The file contains the entire definition, and maybe even other code: it is run when the function needs to be loaded, then the function itself is called up. This is the method in ksh. To define the same function xhead, the whole of the usual definition should be in the file.

In old versions of zsh, before 3.0, only the first behaviour was allowed, so you had to make sure the file found for autoload just contained the function body. You could still define other functions in the file with the standard form for definitions, though they would be redefined each time you called the main function.

In version 3.0.x, the second behaviour is activated if the file defines the autoloaded function. Unfortunately, this is incompatible with the old zsh behaviour which allowed you to redefine the function when you called it.

From version 3.1, there is an option KSHAUTOLOAD to allow full ksh compatiblity, i.e. the function must be in the second form above. If that is not set, zsh tries to guess which form you are using: if the file contains only a complete definition of the function in the second form, and nothing else apart from comments and whitespace, it will use the function defined in the file; otherwise, it will assume the old behaviour. The option is set if emulate ksh is in effect, of course.

(A neat trick to autoload all functions in a given directory is to include a line like autoload ~/fns/*(:t) in .zshrc; the bit in parentheses removes the directory part of the filenames, leaving just the function names.)

3.10: How does base arithmetic work?

The ksh syntax is now understood, i.e.

let 'foo = 16#ff' or equivalently (( foo = 16#ff )) or even foo=$[16#ff] (note that `foo=$((16#ff))' is now supported). The original syntax was (( foo = [16]ff )) --- this was based on a misunderstanding of the ksh manual page. It still works but its use is deprecated. Then echo $foo gives the answer `255'. It is possible to declare variables explicitly to be integers, via typeset -i foo which has a different effect: namely the base used in the first assignment (hexadecimal in the example) is subsequently used whenever `foo' is displayed (although the internal representation is unchanged). To ensure foo is always displayed in decimal, declare it as typeset -i 10 foo which requests base 10 for output. You can change the output base of an existing variable in this fashion. Using the $(( ... )) method will always display in decimal.

3.11: How do I get a newline in my prompt?

You can place a literal newline in quotes, i.e.

PROMPT="Hi Joe, what now?%# " If you have the bad taste to set the option cshjunkiequotes, which inhibits such behaviour, you will have to bracket this with unsetopt cshjunkiequotes and setopt cshjunkiequotes, or put it in your .zshrc before the option is set.

Arguably the prompt code should handle `print'-like escapes. Feel free to write this :-). Otherwise, you can use

PROMPT=$(print "Hi Joe,\nwhat now?%# ") in your initialisation file.

3.12: Why does bindkey ^a command-name or stty intr ^- do something funny?

You probably have the extendedglob option set in which case ^ and # are metacharacters. ^a matches any file except one called a, so the line is interpreted as bindkey followed by a list of files. Quote the ^ with a backslash or put quotation marks around ^a.

3.13: Why can't I bind \C-s and \C-q any more?

The control-s and control-q keys now do flow control by default, unless you have turned this off with stty -ixon or redefined the keys which control it with stty start or stty stop. (This is done by the system, not zsh; the shell simply respects these settings.) In other words, \C-s stops all output to the terminal, while \C-q resumes it.

There is an option NO_FLOW_CONTROL to stop zsh from allowing flow control and hence restoring the use of the keys: put setopt noflowcontrol in .zshrc.

3.14: How do I execute command foo within function foo?

The command command foo does just that. You don't need this with aliases, but you do with functions. Note that error messages like

zsh: job table full or recursion limit exceeded are a good sign that you tried calling `foo' in function `foo' without using `command'. If foo is a builtin rather than an external command, use builtin foo instead.

3.15: Why do history substitutions with single bangs do something funny?

If you have a command like "echo !-2:$ !$", the first history substitution then sets a default to which later history substitutions with single unqualified bangs refer, so that !$ becomes equivalent to !-2:$. The option CSH_JUNKIE_HISTORY makes all single bangs refer to the last command.

3.16: Why does zsh kill off all my background jobs when I logout?

Simple answer: you haven't asked it not to. Zsh (unlike [t]csh) gives you the option of having background jobs killed or not: the nohup option exists if you don't want them killed. Note that you can always run programs with nohup in front of the pipeline whether or not the option is set, which will prevent that job from being killed on logout. (nohup is actually an external command.)

The disown builtin is very useful in this respect: if zsh informs you that you have background jobs when you try to logout, you can disown all the ones you don't want killed when you exit. This is also a good way of making jobs you don't need the shell to know about (such as commands which create new windows) invisible to the shell.

3.17: How do I list all my history entries?

Tell zsh to start from entry 1: history 1. Those entries at the start which are no longer in memory will be silently omitted.

3.18: How does the alternative loop syntax, e.g. while {...} {...} work?

Zsh provides an alternative to the traditional sh-like forms with do,

while TEST; do COMMANDS; done allowing you to have the COMMANDS delimited with some other command structure, often {...}. The rules are quite complicated and in most scripts it is probably safer --- and certainly more compatible --- to stick with the sh-like rules. If you are wondering, the following is a rough guide.

To make it work you must make sure the TEST itself is clearly delimited. For example, this works:

while (( i++ < 10 )) { echo i is $i; } but this does not: while let "i++ < 10"; { echo i is $i; } # Wrong! The reason is that after while, any sort of command list is valid. This includes the whole list let "i++ < 10"; { echo i $i; }; the parser simply doesn't know when to stop. Furthermore, it is wrong to miss out the semicolon, as this makes the {...} part of the argument to let. A newline behaves the same as a semicolon, so you can't put the brace on the next line as in C.

So when using this syntax, the test following the while must be wrapped up: any of ((...)), [[...]], {...} or (...) will have this effect. (They have their usual syntactic meanings too, of course; they are not interchangeable.) Note that here too it is wrong to put in the semicolon, as then the case becomes identical to the preceding one:

while (( i++ < 10 )); { echo i is $i; } # Wrong!

The same is true of the if and until constructs:

if { true } { echo yes } else { echo no } but with for, which only needs a list of words, you can get away with it: for foo in a b; { echo foo is $a; bar=$foo; } since the parser knows it only needs everything up to the first semicolon. For the same reason, there is no problem with the repeat, case or select constructs; in fact, repeat doesn't even need the semicolon since it knows the repeat count is just one word.

This is independent of the behaviour of the SHORTLOOPS option (see manual), which you are in any case encouraged even more strongly not to use in programs as it can be very confusing.