Newsgroups: comp.unix.shell,comp.answers,news.answers From: pws@s-a.amtp.liv.ac.uk (Peter Stephenson) Subject: Z-shell Frequently-Asked Questions Message-ID: Summary: Q's and A's about zsh, a powerful (and free) UNIX shell Organization: DAMTP, University of Liverpool Date: Sun, 23 May 1993 20:08:24 GMT Lines: 639 Archive-Name: unix-faq/shell/zsh Last-Modified: 1993/05/23 Submitted-By: pws@s-a.amtp.liv.ac.uk (Peter Stephenson) Version: $Id: zsh.FAQ,v 1.9 1993/05/23 19:03:59 pws Exp pws $ Frequency: Monthly This document contains a list of frequently-asked (or otherwise significant) questions concerning the Z-shell, a powerful command interpreter for many UNIX systems which is freely available to anyone with FTP access. If you have never heard of `sh', `csh' or `ksh', then you are probably better off to start by reading a general introduction to UNIX rather than this document. Another useful source of information is the collection of FAQ articles posted frequently to the Usenet news groups comp.unix.questions, comp.unix.shells and comp.answers with answers to general questions about UNIX. The fifth of the seven articles deals with shells, including zsh, with a brief description of differences. (This article also talks about shell startup files which would otherwise rate a mention here.) If you just want to know how to get your hands on the latest version, skip to question 4; if you want to know what to do with insoluble problems, go to 20. To encourage you to read on, if you don't know about zsh but are familiar with other UNIX shells, here are some things that zsh is particularly good at. No claim of exclusivity is made, especially as shells copy one another, though in the areas of command line editing and globbing zsh is well ahead of the competition. I am not aware of a major feature in any other freely-available shell which zsh does not also have. Command line editing: programmable completion: incorporates the ability to use the full power of zsh globbing (compctl -g), multi-line commands editable as a single buffer (even files!), variable editing (vared), command buffer stack, print text straight into the buffer for immediate editing (print -z), execution of unbound commands, menu completion, variable, host, editing function and option name completion, inline expansion of variables, history commands. Globbing --- extremely powerful, including: recursive globbing (cf. find), file attribute qualifiers (size, type, etc. also cf. find), full alternation and negation of patterns. Handling of multiple redirections (simpler than tee). Large number of options for tailoring. Path expansion (=foo -> /usr/bin/foo). Adaptable messages for spelling, watch, time as well as prompt (now including conditional expressions). Named directories. Comprehensive integer arithmetic. Manipulation of arrays (including reverse subscripting). Spelling correction (which works). Notation: Quotes `like this' are ordinary textual quotation marks. Other uses of quotation marks are input to the shell. Contents: 1) What is it? 2) On what machines will it run? 3) What's the latest version? 4) Where do I get it? 5) How does zsh differ from sh, ksh, csh,...? 6) Why do my csh aliases not work? (Plus other alias pitfalls.) 7) How do I get the meta key to work on my xterm? 8) Why does my terminal act funny in way x? 9) Why does `$var' where var="foo bar" not do what I expect? 10) My PATH, (MANPATH, ...) sometimes doesn't handle tildes. What gives? 11) How does base arithmetic work? 12) How do I get a newline in my prompt? 13) Why does `bindkey ^a command-name' or 'stty intr ^-' do something funny? 14) How do I reference command `foo' from within function `foo'? 15) Why can't I get zsh to work with SGI's `userenv'? 16) Why do history subsitutions with single bangs do something funny? 17) Why does zsh kill off all my background jobs when I logout? 18) I don't have root access: how do I make zsh my login shell? 19) What bugs are currently known and unfixed? 20) Where do I report bugs, get more info / who's working on zsh? 21) What's on the wish-list? --- End of Contents --- 1) What is it? Zsh is a UNIX command interpreter (shell) which of the standard shells most resembles the Korn shell (ksh), although it is not completely compatible. It includes enhancements of many types, notably in the command-line editor, options for customising its behaviour, filename globbing, features to make C-shell (csh) users feel more at home and extra features drawn from tcsh (another `custom' shell). It was written by Paul Falstad when a student at Princeton; however, Paul doesn't maintain it any more and enquiries should be sent to the mailing list (see question 20). It is freely available to anyone under unrestrictive conditions. For more information, the files doc/intro.txt or doc/intro.troff included with the source distribution are highly recommended. A list of features is given in FEATURES, also with the source. 2) On what machines will it run? Zsh was written for machines of the Berkeley UNIX family; most such machines (and all the most popular) will run it without major surgery. Modifications have been made so that it should work under SYSVR4-based operating systems such as Solaris 2.x and OSF/1. This best thing is to suck it and see. You may not have to change too much: if you do change anything, arrange for the shell script `buildzsh' to set the necessary #define's, etc., without human intervention. Recent additions include Convex, Unicos and Linux support; there is a project to allow POSIX.1 compilation (but note that that zsh is not itself particularly POSIX-compliant at the moment). 3) What's the latest version? The latest production version is 2.3.1. The current beta version is 2.4. New patches occur frequently and are added to the archive (next question). At the time of writing the latest patch level was 90. 4) Where do I get it? Bas de Bakker (bas@phys.uva.nl) is in charge of the archive and the latest version is available for users east of the Atlantic from: carlo.phys.uva.nl (145.18.220.25):/pub/bas/zsh/zsh-2.4.tar.z The latest full release is in zsh-2.3.1.tar.z in the same directory. Note that this is in gzip format: you will need GNU gzip (of which there is now a production version) from your nearest GNU archive to unpack it. There is also a version under RCS control which may be more suitable for source hackers. Rick Ohnemus has a reflector site in the USA: ftp.sterling.com (192.124.9.1):/zsh 5) How does zsh differ from sh, ksh, csh,...? As mentioned, zsh is most similar to ksh, while many of the additions are to please csh users. i) ksh: Most features of ksh (and hence also of sh) are implemented in zsh; problems can arise because the implementation is slightly different. Note also that not all ksh's are the same either. I have based this on SunOS 4, which is essentially the 11/16/88 version of ksh. Differences from ksh which might prove significant for ksh programmers, some of which may be interpreted as bugs (there must be more) include: Syntax: Shell word splitting: see question 14. (This is particularly frequently asked about.) Arrays are more csh-like than ksh-like: subscripts start at 1, not 0; array[0] refers to array[1]; `$array' refers to the whole array, not $array[0]; braces are unnecessary: $a[1] == ${a[1]}, etc. Coprocesses are established by `coproc'; `|&' behaves like csh. Command line substitutions, globbing etc.: The $((...)) version of numeric evaluation is not implemented; use $[...]. Treatment of backslashes within backquotes is different. PS1 does not do parameter substitution by default. Globbing does not allow ksh-style `pattern-lists'. Unquoted assigments do file expansion after ':'s (intended for PATHs). Command execution: The PATH is not searched for commands specified at invocation without -c. There is no ENV variable (use /etc/zshrc, ~/.zshrc; note also ZDOTDIR). Aliases and functions: Functions will call themselves recursively: see question 14. The order in which aliases and functions are defined is significant (function definitions with () expand aliases -- see question 6). Aliases and functions cannot be exported. There are no tracked aliases: command hashing replaces these. The use of aliases for key bindings is replaced by `bindkey'. Traps are not local to functions and are not reset automatically when called. Editing: The options emacs, gmacs, privileged, trackall, viraw are not supported. (Use bindkey to change the editing behaviour.) The `keyword' option does not exist and -k is instead interactivecomments. Management of histories in multiple shells is different. \ does not escape editing chars (use ^V). Not all ksh bindings are set (e.g. `#'). Built-in commands: No built-in commands cause automatic termination of a script. Some built-ins (true, false, r, ...) were aliases in ksh. [ ] is a shell built-in, rather than a call to /bin/test. (but you can disable the built-in). There is no built-in command newgrp: use a shell function. `jobs' has no `-n' flag. In `let "i = foo"', foo is evaluated as a number, not an expression (although in `let "i = $foo"' it is treated as an expression). Other idiosyncracies: `select' always redisplays the list of selections on each loop. The following is particularly near the feature/bug borderline: "$@" always indicates at least one argument (older sh's do this too). ii) csh: Although certain features aim to ease the withdrawal symptoms of Csh (ab)users, the syntax is in general rather different and you should certainly not try to run scripts without modification. The c2z script is provided with the source (in scripts/c2z) to help convert .cshrc and .login files; see also the next question concerning aliases. Csh-compatibility additions include: Logout, rehash, source, (un)limit built-in commands. *rc file for interactive shells. Directory stacks. Cshjunkie*, ignoreeof options. The nonomatch option. >&, |& etc. redirection. foreach ... loops. $PROMPT as well as $PS1, $status as well as $?, $#argv as well as $#, .... Escape sequences via % for prompts. Special array variables $PATH etc. are colon-separated, $path are arrays. !-type history (which may be turned off). Arrays have csh-like features (see i)). iii) tcsh: Certain features have been borrowed from tcsh, including $watch, run-help, $savehist, $histlit, periodic commands etc., extended prompts, sched and which/where built-ins. Programmable completion was inspired by, but is entirely different to, tcsh's `complete'. (There is a perl script called lete2ctl in the scripts directory of the source distribution to convert `complete' to `compctl' statements.) This list is not definitive: some features have gone in the other direction. 6) Why do my csh aliases not work? (Plus other alias pitfalls.) First of all, check you are using the syntax alias newcmd='list of commands' and not alias newcmd 'list of commands' which won't work. (It tells you if `newcmd' and `list of commands' are already defined as aliases.) Otherwise, your aliases probably contain references to the command line of the form `\!*', etc. Zsh does not handle this behaviour as it has shell functions which provide a way of solving this problem more consistent with other forms of argument handling. For example, the csh alias alias cd 'cd \!*; echo $cwd' can be replaced by the zsh function, cd() { builtin cd $*; echo $PWD; } (the `builtin' tells zsh to use its own `cd', avoiding an infinite loop) or, perhaps better, cd() { builtin cd $*; print -D $PWD; } (which converts your home directory to a ~). In fact, this problem is better solved by defining the special function chpwd() (see the manual). Note also that the `;' at the end of the function is optional in zsh, but not in ksh or sh (for sh's where it exists). There is one other serious problem with aliases: consider alias l='/bin/ls -F' l() { /bin/ls -la $* | more } `l' in the function definition is in command position and is expanded as an alias, defining `/bin/ls' and `-F' as functions which call `/bin/ls', which gets a bit recursive. This can be avoided if you use `function' to define a function, which doesn't expand aliases. It is possible to argue for extra warnings somewhere in this mess. If you define `function' as an alias you deserve what you get. Finally, note that to define an alias beginning with a - (as with many other shell commands), you need to add a single `-' after `alias' to prevent the shell interpreting the alias as a flag. Here is Bart Schaefer's guide to converting csh aliases for zsh. 1. If the csh alias references "parameters" (\!:1 \!* etc.), then in zsh you need a function (referencing $1 $* etc.). Otherwise, you can use a zsh alias. 2. If you use a zsh function, you need to refer _at_least_ to $* in the body (inside the { }). Parameters don't magically appear inside the { } the way they get appended to an alias. 3. If the csh alias references its own name (alias rm "rm -i"), then in a zsh function you need the "command" keyword (function rm() { command rm -i $* }), but in a zsh alias you don't (alias rm="rm -i"). 4. If you have aliases that refer to each other (alias ls "ls -C"; alias lf "ls -F" ==> lf == ls -C -F) then you must either: a. convert all of them to zsh functions; or b. after converting, be sure your .zshrc defines all of your aliases before it defines any of your functions. Those first four are all you really need, but here are four more for heavy csh alias junkies: 5. Mapping from csh alias "parameter referencing" into zsh function (assuming shwordsplit is NOT set in zsh): csh zsh ===== ========== \!* $* (or $argv) \!^ $1 (or $argv[1]) \!:1 $1 \!:2 $2 (or $argv[2], etc.) \!$ $*[$#] (or $argv[$#], or $*[-1]) \!:1-4 $*[1,4] \!:1- $*[1,$#-1] (or $*[1,-2]) \!^- $*[1,$#-1] \!*:q "$@" ($*:q doesn't work (yet)) \!*:x $=* ($*:x doesn't work (yet)) 6. Remember that it is NOT a syntax error in a zsh function to refer to a position ($1, $2, etc.) greater than the number of parameters. (E.g., in a csh alias, a reference to \!:5 will cause an error if 4 or fewer arguments are given; in a zsh function, $5 is the empty string if there are 4 or fewer parameters.) 7. To begin a zsh alias with a - (dash, hyphen) character, use "alias --": csh zsh =============== ================== alias - "fg %-" alias -- -="fg %-" 8. Stay away from "alias -g" in zsh until you REALLY know what you're doing. 7) 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. 8) Why does my terminal act funny in way x? 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. 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). 9) Why does `$var' where var="foo bar" not do what I expect? In most Bourne-shell derivatives, multi-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 vble, args $vble 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. 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. Note also the "$@" method of word splitting is always available in zsh functions and scripts (though strictly this does array splitting, not word splitting), also the substitution ${=foo} to toggle word splitting on variable `foo'. 10) My PATH, (MANPATH, ...) sometimes doesn't handle tildes. What gives? The code has recently been overhauled, so take a look at the latest version of 2.4beta. This guarantees that no ~user expansion (or =command expansion, which takes place at the same time) will happen if the tilde is quoted, and also rationalises PATH-type variables by expanding all unquoted assignments as if they are colon-separated lists (so you may need to add or subtract a few extra quotes, but the results are more predictable). In addition typeset, etc., now should behave like ordinary assignments in this respect; previously tildes in typeset assignments were unquotable. 11) How does base arithmetic work? The syntax (e.g. using the `let' builtin is) let 'foo = [16]ff' or equivalently (( foo = [16]ff )) 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. 12) 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. 13) 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. 14) How do I reference command `foo' from within function `foo'? The command `command foo' does just that. You don't need this with aliases, but you do with functions. Note that the error message zsh: job table full or recursion limit exceeded is a good sign that you tried calling `foo' in function `foo' without using `command'. (In ksh, functions were never called recursively.) 15) I can't get zsh to work with SGI's `userenv'. It seems the Silicon Graphics `userenv' command interacts weirdly with the line editor (zsh is not unique in this respect). Add this line to the top of your .zshenv file: if [[ "${ENVONLY:-0}" -eq 1 ]]; then unsetopt zle; fi --- which will turn the line editor off if it sees a `userenv' coming. Don't turn zle back on with setopt until [[ $ENVONLY -ne 1 ]]. 16) Why do history subsitutions 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 substutions 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. 17) 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. 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. 18) I don't have root access: how do I make zsh my login shell? Unfortunately, on many machines you can't use `chsh' to change your shell unless the name of the shell is contained in /etc/shells, so if you have your own copy of zsh you need some sleight-of-hand to use it when you log on. (Simply typing `zsh' is not really a solution since you still have your original login shell waiting for when you exit.) The basic idea is to use `exec ' to replace the current shell with zsh. Often you can do this in a login file such as .profile (if your shell is sh or ksh) or .login (if it's csh). Make sure you have some way of altering the file (e.g. via FTP) before you try this as `exec' is often rather unforgiving. In .profile, try something like [ -f $HOME/bin/zsh ] && exec $HOME/bin/zsh -l and in .login, try something like if ( -f ~/bin/zsh ) exec ~/bin/zsh -l (in each case the -l tells zsh it is a login shell). It's not a good idea to put this (even without the -l) into .cshrc, at least without some tests on what the csh is supposed to be doing, as that will cause _every_ instance of csh to turn into a zsh and will cause csh scripts (yes, unfortunately some people write these) which do not call `csh -f' to fail. If you want to tell xterm to run zsh, change the SHELL environment variable to the full path of zsh at the same time as you exec zsh. If you have to exec zsh from your .cshrc, a minimum safety check is `if ($?prompt) ...'. If you like your login shell to appear in the process list as '-zsh', you can link zsh to -zsh (e.g. by `ln -s ~/bin/zsh ~/bin/-zsh') and change the exec to `exec -zsh'. (Make sure -zsh is in your path.) This has the same effect as the `-l' option. Footnote: if you DO have root access, make sure zsh goes in /etc/shells on all approriate machines, including NIS clients, or you may have problems with FTP to that machine. 19) What bugs are currently known and unfixed? Here are some of the more well-known ones, very roughly in decreasing order of significance. A fuller bug list is now maintained by Carlos Carvalho . Many of these can also be counted against differences from ksh in question 5); note that this applies to the latest beta version and that simple bugs are often fixed quite quickly. (?? Weird command hashing problems e.g. with command completion, only experienced by some users ??) `return' in a shell script should act as `exit'. Lines which spill over the right margin cannot be cut/pasted properly. Pipelines ending in a while/until/for loop are uninterruptible. `eval' causes a memory leak. Compctl options -f and -c interact badly with the others (notably -g), particularly when the text to complete has a '/'. (Sven Wischnowsky has overhauled the completion code, but this has yet to be merged with the general release.) Autoloaded functions with malformed [[...]] constructs dump core. Window-resizing is not always handled properly (system-dependent). Certain built-ins won't allow the `VAR=value command ...' assignment. The ones that do don't unset VAR after use. `bindkey -a -[ed]' modifies the alternate keymap. The `histlit' option adds newlines to lines in the history (and is broken in several other ways, e.g. !:x word selection). The :q modifier doesn't split words and -q and -x don't work for variables. In vi mode, `u' can go past the original modification point, and vi-set-mark and/or vi-goto-mark do not work. $_ returns the last unexpanded word from the previous line (not command). `time' is ignored with builtins and can't be used with {...} or (...). Autocd won't use globbed filenames and sometimes refuses to work. Linked directories can sometimes confuse zsh's idea of its cwd. `cd' is inconsistent with reporting new paths. Problems with search in vi mode. Input processing of e.g. ^V is doing something weird in Solaris 2. Still problems under SCO Unix -- patches from SCO users appreciated. 20) Where do I report bugs, get more info / who's working on zsh? Zsh is now maintained by a motley collection of enthusiasts who subscribe to the mailing list, so any suggestions, complaints, questions and matters for discussion should be addressed to: zsh-list@imd.sterling.com (if you want someone to mail you directly, say so). If you wish to subscribe to the mailing list, send an email message to Majordomo@imd.sterling.com (this is an automated server) containing subscribe zsh-list where can be blank if you want to subscribe from your current email address. Send the message `help' to the same address for help on the list server; `unsubscribe zsh-list' also works. (Don't send this to the list!). The list manager, Rick Ohnemus, can be reached at owner-zsh-list@imd.sterling.com (or `rick' at the same adress). The list (everything since May 1992) is archived in ftp.sterling.com:zsh/zsh-list/YY-MM where YY-MM are the year and month in digits. 21) What's on the wish-list? The shell is getting rather large and any simplifications would be appreciated. Option for glob qualifiers to follow perl syntax. Selective expansion of history, variables, globs on . Option to quote !-history lexically via '' but not "" (hard). Binding of shell functions (or commands?) to key strokes -- requires some way of accessing the editing buffer from functions and probably of executing zle functions as a command. Ksh compatibility could be improved if required. Acknowledgments: Thanks to zsh-list, in particular Bart Schaefer, for suggestions regarding this document; thanks to Jim Mattson and more recently Bas de Bakker for their hard work as archivists, and to Peter Gray for maintaining the mailing list, without which zsh might easily have died, and to the latest list maintainer, Rick Ohnemus. The world is eternally in the debt of Paul Falstad for inventing zsh in the first place. -- Peter Stephenson or (BITNET) Dept. of Applied Mathematics and Theoretical Physics University of Liverpool, P.O. Box 147, Liverpool, L69 3BX, U.K. Tel. +44 51 794 3784 (also fax) or 3791