diff options
Diffstat (limited to 'assets/info/zsh.info-1')
| -rw-r--r-- | assets/info/zsh.info-1 | 7487 |
1 files changed, 7487 insertions, 0 deletions
diff --git a/assets/info/zsh.info-1 b/assets/info/zsh.info-1 new file mode 100644 index 00000000..cb22a64e --- /dev/null +++ b/assets/info/zsh.info-1 @@ -0,0 +1,7487 @@ +This is zsh.info, produced by makeinfo version 4.8 from ./zsh.texi. + +INFO-DIR-SECTION Utilities +START-INFO-DIR-ENTRY +* ZSH: (zsh). The Z Shell Manual. +END-INFO-DIR-ENTRY + + +File: zsh.info, Node: Top, Next: The Z Shell Manual, Prev: (dir), Up: (dir) + +The Z Shell Manual +****************** + + This Info file documents Zsh, a freely available UNIX command +interpreter (shell), which of the standard shells most closely +resembles the Korn shell (ksh), although it is not completely +compatible. Zsh is able to emulate POSIX shells, but its default mode +is not POSIX compatible, either. + +Version 5.8.1, last updated February 12, 2022. + +* Menu: + +* The Z Shell Manual:: +* Introduction:: +* Roadmap:: +* Invocation:: +* Files:: +* Shell Grammar:: +* Redirection:: +* Command Execution:: +* Functions:: +* Jobs & Signals:: +* Arithmetic Evaluation:: +* Conditional Expressions:: +* Prompt Expansion:: +* Expansion:: +* Parameters:: +* Options:: +* Shell Builtin Commands:: +* Zsh Line Editor:: +* Completion Widgets:: +* Completion System:: +* Completion Using compctl:: +* Zsh Modules:: +* Calendar Function System:: +* TCP Function System:: +* Zftp Function System:: +* User Contributions:: + +--- Indices --- + +* Concept Index:: +* Variables Index:: +* Options Index:: +* Functions Index:: +* Editor Functions Index:: +* Style and Tag Index:: + +--- The Detailed Node Listing --- + +Introduction + +* Author:: +* Availability:: +* Mailing Lists:: +* The Zsh FAQ:: +* The Zsh Web Page:: +* The Zsh Userguide:: +* See Also:: + +Invocation + +* Compatibility:: +* Restricted Shell:: + +Shell Grammar + +* Simple Commands & Pipelines:: +* Precommand Modifiers:: +* Complex Commands:: +* Alternate Forms For Complex Commands:: +* Reserved Words:: +* Comments:: +* Aliasing:: +* Quoting:: + +Expansion + +* History Expansion:: +* Process Substitution:: +* Parameter Expansion:: +* Command Substitution:: +* Arithmetic Expansion:: +* Brace Expansion:: +* Filename Expansion:: +* Filename Generation:: + +Parameters + +* Array Parameters:: +* Positional Parameters:: +* Local Parameters:: +* Parameters Set By The Shell:: +* Parameters Used By The Shell:: + +Options + +* Specifying Options:: +* Description of Options:: +* Option Aliases:: +* Single Letter Options:: + +Zsh Line Editor + +* Keymaps:: +* Zle Builtins:: +* Zle Widgets:: +* Character Highlighting:: + +Completion Widgets + +* Completion Special Parameters:: +* Completion Builtin Commands:: +* Completion Condition Codes:: +* Completion Matching Control:: +* Completion Widget Example:: + +Completion System + +* Initialization:: +* Completion System Configuration:: +* Control Functions:: +* Bindable Commands:: +* Completion Functions:: +* Completion Directories:: + +Completion Using compctl + +* Command Flags:: +* Option Flags:: +* Alternative Completion:: +* Extended Completion:: +* Example:: + +Zsh Modules + +* The zsh/attr Module:: +* The zsh/cap Module:: +* The zsh/clone Module:: +* The zsh/compctl Module:: +* The zsh/complete Module:: +* The zsh/complist Module:: +* The zsh/computil Module:: +* The zsh/curses Module:: +* The zsh/datetime Module:: +* The zsh/db/gdbm Module:: +* The zsh/deltochar Module:: +* The zsh/example Module:: +* The zsh/files Module:: +* The zsh/langinfo Module:: +* The zsh/mapfile Module:: +* The zsh/mathfunc Module:: +* The zsh/nearcolor Module:: +* The zsh/newuser Module:: +* The zsh/parameter Module:: +* The zsh/pcre Module:: +* The zsh/param/private Module:: +* The zsh/regex Module:: +* The zsh/sched Module:: +* The zsh/net/socket Module:: +* The zsh/stat Module:: +* The zsh/system Module:: +* The zsh/net/tcp Module:: +* The zsh/termcap Module:: +* The zsh/terminfo Module:: +* The zsh/zftp Module:: +* The zsh/zle Module:: +* The zsh/zleparameter Module:: +* The zsh/zprof Module:: +* The zsh/zpty Module:: +* The zsh/zselect Module:: +* The zsh/zutil Module:: + +Calendar Function System + +* Calendar File and Date Formats:: +* Calendar System User Functions:: +* Calendar Styles:: +* Calendar Utility Functions:: +* Calendar Bugs:: + +TCP Function System + +* TCP Functions:: +* TCP Parameters:: +* TCP Examples:: +* TCP Bugs:: + +Zftp Function System + +* Installation:: +* Zftp Functions:: +* Miscellaneous Features:: + +User Contributions + +* Utilities:: +* Recent Directories:: +* Other Directory Functions:: +* Version Control Information:: +* Prompt Themes:: +* ZLE Functions:: +* Exception Handling:: +* MIME Functions:: +* Mathematical Functions:: +* User Configuration Functions:: +* Other Functions:: + + +File: zsh.info, Node: The Z Shell Manual, Next: Introduction, Prev: Top, Up: Top + +1 The Z Shell Manual +******************** + +This document has been produced from the texinfo file zsh.texi, +included in the Doc sub-directory of the Zsh distribution. + +1.1 Producing documentation from zsh.texi +========================================= + +The texinfo source may be converted into several formats: + + +The Info manual + The Info format allows searching for topics, commands, functions, + etc. from the many Indices. The command `makeinfo zsh.texi' is + used to produce the Info documentation. + +The printed manual + The command `texi2dvi zsh.texi' will output zsh.dvi which can then + be processed with `dvips' and optionally `gs' (Ghostscript) to + produce a nicely formatted printed manual. + +The HTML manual + An HTML version of this manual is available at the Zsh web site + via: + + `http://zsh.sourceforge.net/Doc/'. + + (The HTML version is produced with `texi2html', which may be + obtained from `http://www.nongnu.org/texi2html/'. The command is + `texi2html -output . -ifinfo -split=chapter -node-files zsh.texi'. + If necessary, upgrade to version 1.78 of texi2html.) + + +For those who do not have the necessary tools to process texinfo, +precompiled documentation (PostScript, dvi, PDF, info and HTML formats) +is available from the zsh archive site or its mirrors, in the file +zsh-doc.tar.gz. (See *Note Availability:: for a list of sites.) + + +File: zsh.info, Node: Introduction, Next: Roadmap, Prev: The Z Shell Manual, Up: Top + +2 Introduction +************** + +Zsh is a UNIX command interpreter (shell) usable as an interactive +login shell and as a shell script command processor. Of the standard +shells, zsh most closely resembles `ksh' but includes many +enhancements. It does not provide compatibility with POSIX or other +shells in its default operating mode: see the section *Note +Compatibility::. + +Zsh has command line editing, builtin spelling correction, programmable +command completion, shell functions (with autoloading), a history +mechanism, and a host of other features. + +* Menu: + +* Author:: +* Availability:: +* Mailing Lists:: +* The Zsh FAQ:: +* The Zsh Web Page:: +* The Zsh Userguide:: +* See Also:: + + +File: zsh.info, Node: Author, Next: Availability, Up: Introduction + +2.1 Author +========== + +Zsh was originally written by Paul Falstad <pf@zsh.org>. Zsh is now +maintained by the members of the zsh-workers mailing list +<zsh-workers@zsh.org>. The development is currently coordinated by +Peter Stephenson <pws@zsh.org>. The coordinator can be contacted at +<coordinator@zsh.org>, but matters relating to the code should +generally go to the mailing list. + + +File: zsh.info, Node: Availability, Next: Mailing Lists, Prev: Author, Up: Introduction + +2.2 Availability +================ + +Zsh is available from the following HTTP and anonymous FTP site. + +`ftp://ftp.zsh.org/pub/' +`https://www.zsh.org/pub/' ) + +The up-to-date source code is available via Git from Sourceforge. See +`https://sourceforge.net/projects/zsh/' for details. A summary of +instructions for the archive can be found at +`http://zsh.sourceforge.net/'. + + + + +File: zsh.info, Node: Mailing Lists, Next: The Zsh FAQ, Prev: Availability, Up: Introduction + +2.3 Mailing Lists +================= + +Zsh has 3 mailing lists: + + +<zsh-announce@zsh.org> + Announcements about releases, major changes in the shell and the + monthly posting of the Zsh FAQ. (moderated) + +<zsh-users@zsh.org> + User discussions. + +<zsh-workers@zsh.org> + Hacking, development, bug reports and patches. + + +To subscribe or unsubscribe, send mail to the associated administrative +address for the mailing list. + + +<zsh-announce-subscribe@zsh.org> + +<zsh-users-subscribe@zsh.org> + +<zsh-workers-subscribe@zsh.org> + + +<zsh-announce-unsubscribe@zsh.org> + +<zsh-users-unsubscribe@zsh.org> + +<zsh-workers-unsubscribe@zsh.org> + + +YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED. All +submissions to `zsh-announce' are automatically forwarded to +`zsh-users'. All submissions to `zsh-users' are automatically +forwarded to `zsh-workers'. + +If you have problems subscribing/unsubscribing to any of the mailing +lists, send mail to <listmaster@zsh.org>. The mailing lists are +maintained by Karsten Thygesen <karthy@kom.auc.dk>. + +The mailing lists are archived; the archives can be accessed via the +administrative addresses listed above. There is also a hypertext +archive, maintained by Geoff Wing <gcw@zsh.org>, available at +`https://www.zsh.org/mla/'. + + +File: zsh.info, Node: The Zsh FAQ, Next: The Zsh Web Page, Prev: Mailing Lists, Up: Introduction + +2.4 The Zsh FAQ +=============== + +Zsh has a list of Frequently Asked Questions (FAQ), maintained by Peter +Stephenson <pws@zsh.org>. It is regularly posted to the newsgroup +`comp.unix.shell' and the `zsh-announce' mailing list. The latest +version can be found at any of the Zsh FTP sites, or at +`http://www.zsh.org/FAQ/'. The contact address for FAQ-related matters +is <faqmaster@zsh.org>. + + +File: zsh.info, Node: The Zsh Web Page, Next: The Zsh Userguide, Prev: The Zsh FAQ, Up: Introduction + +2.5 The Zsh Web Page +==================== + +Zsh has a web page which is located at `https://www.zsh.org/'. This is +maintained by Karsten Thygesen <karthy@zsh.org>, of SunSITE Denmark. +The contact address for web-related matters is <webmaster@zsh.org>. + + +File: zsh.info, Node: The Zsh Userguide, Next: See Also, Prev: The Zsh Web Page, Up: Introduction + +2.6 The Zsh Userguide +===================== + +A userguide is currently in preparation. It is intended to complement +the manual, with explanations and hints on issues where the manual can +be cabbalistic, hierographic, or downright mystifying (for example, the +word `hierographic' does not exist). It can be viewed in its current +state at `http://zsh.sourceforge.net/Guide/'. At the time of writing, +chapters dealing with startup files and their contents and the new +completion system were essentially complete. + + +File: zsh.info, Node: See Also, Prev: The Zsh Userguide, Up: Introduction + +2.7 See Also +============ + +man page sh(1), man page csh(1), man page tcsh(1), man page rc(1), man +page bash(1), man page ksh(1) + +`IEEE Standard for information Technology - Portable Operating System +Interface (POSIX) - Part 2: Shell and Utilities', IEEE Inc, 1993, ISBN +1-55937-255-9. + + +File: zsh.info, Node: Roadmap, Next: Invocation, Prev: Introduction, Up: Top + +3 Roadmap +********* + +The Zsh Manual, like the shell itself, is large and often complicated. +This section of the manual provides some pointers to areas of the shell +that are likely to be of particular interest to new users, and indicates +where in the rest of the manual the documentation is to be found. + + + +3.1 When the shell starts +========================= + +When it starts, the shell reads commands from various files. These can +be created or edited to customize the shell. See *Note Files::. + +If no personal initialization files exist for the current user, a +function is run to help you change some of the most common settings. +It won't appear if your administrator has disabled the zsh/newuser +module. The function is designed to be self-explanatory. You can run +it by hand with `autoload -Uz zsh-newuser-install; zsh-newuser-install +-f'. See also *Note User Configuration Functions::. + + + +3.2 Interactive Use +=================== + +Interaction with the shell uses the builtin Zsh Line Editor, ZLE. This +is described in detail in *Note Zsh Line Editor::. + +The first decision a user must make is whether to use the Emacs or Vi +editing mode as the keys for editing are substantially different. Emacs +editing mode is probably more natural for beginners and can be selected +explicitly with the command bindkey -e. + +A history mechanism for retrieving previously typed lines (most simply +with the Up or Down arrow keys) is available; note that, unlike other +shells, zsh will not save these lines when the shell exits unless you +set appropriate variables, and the number of history lines retained by +default is quite small (30 lines). See the description of the shell +variables (referred to in the documentation as parameters) HISTFILE, +HISTSIZE and SAVEHIST in *Note Parameters Used By The Shell::. Note +that it's currently only possible to read and write files saving history +when the shell is interactive, i.e. it does not work from scripts. + +The shell now supports the UTF-8 character set (and also others if +supported by the operating system). This is (mostly) handled +transparently by the shell, but the degree of support in terminal +emulators is variable. There is some discussion of this in the shell +FAQ, `http://www.zsh.org/FAQ/'. Note in particular that for combining +characters to be handled the option COMBINING_CHARS needs to be set. +Because the shell is now more sensitive to the definition of the +character set, note that if you are upgrading from an older version of +the shell you should ensure that the appropriate variable, either LANG +(to affect all aspects of the shell's operation) or LC_CTYPE (to affect +only the handling of character sets) is set to an appropriate value. +This is true even if you are using a single-byte character set +including extensions of ASCII such as ISO-8859-1 or ISO-8859-15. See +the description of LC_CTYPE in *Note Parameters::. + + + +3.2.1 Completion +---------------- + +Completion is a feature present in many shells. It allows the user to +type only a part (usually the prefix) of a word and have the shell fill +in the rest. The completion system in zsh is programmable. For +example, the shell can be set to complete email addresses in arguments +to the mail command from your ~/.abook/addressbook; usernames, +hostnames, and even remote paths in arguments to scp, and so on. +Anything that can be written in or glued together with zsh can be the +source of what the line editor offers as possible completions. + +Zsh has two completion systems, an old, so called compctl completion +(named after the builtin command that serves as its complete and only +user interface), and a new one, referred to as compsys, organized as +library of builtin and user-defined functions. The two systems differ +in their interface for specifying the completion behavior. The new +system is more customizable and is supplied with completions for many +commonly used commands; it is therefore to be preferred. + +The completion system must be enabled explicitly when the shell starts. +For more information see *Note Completion System::. + + + +3.2.2 Extending the line editor +------------------------------- + +Apart from completion, the line editor is highly extensible by means of +shell functions. Some useful functions are provided with the shell; +they provide facilities such as: + + +insert-composed-char + composing characters not found on the keyboard + +match-words-by-style + configuring what the line editor considers a word when moving or + deleting by word + +history-beginning-search-backward-end, etc. + alternative ways of searching the shell history + +replace-string, replace-pattern + functions for replacing strings or patterns globally in the + command line + +edit-command-line + edit the command line with an external editor. + + +See *Note ZLE Functions:: for descriptions of these. + + + +3.3 Options +=========== + +The shell has a large number of options for changing its behaviour. +These cover all aspects of the shell; browsing the full documentation is +the only good way to become acquainted with the many possibilities. See +*Note Options::. + + + +3.4 Pattern Matching +==================== + +The shell has a rich set of patterns which are available for file +matching (described in the documentation as `filename generation' and +also known for historical reasons as `globbing') and for use when +programming. These are described in *Note Filename Generation::. + +Of particular interest are the following patterns that are not commonly +supported by other systems of pattern matching: + + +** + for matching over multiple directories + +| + for matching either of two alternatives + +~, ^ + the ability to exclude patterns from matching when the + EXTENDED_GLOB option is set + +(...) + glob qualifiers, included in parentheses at the end of the pattern, + which select files by type (such as directories) or attribute + (such as size). + + + +3.5 General Comments on Syntax +============================== + +Although the syntax of zsh is in ways similar to the Korn shell, and +therefore more remotely to the original UNIX shell, the Bourne shell, +its default behaviour does not entirely correspond to those shells. +General shell syntax is introduced in *Note Shell Grammar::. + +One commonly encountered difference is that variables substituted onto +the command line are not split into words. See the description of the +shell option SH_WORD_SPLIT in *Note Parameter Expansion::. In zsh, you +can either explicitly request the splitting (e.g. ${=foo}) or use an +array when you want a variable to expand to more than one word. See +*Note Array Parameters::. + + + +3.6 Programming +=============== + +The most convenient way of adding enhancements to the shell is typically +by writing a shell function and arranging for it to be autoloaded. +Functions are described in *Note Functions::. Users changing from the +C shell and its relatives should notice that aliases are less used in +zsh as they don't perform argument substitution, only simple text +replacement. + +A few general functions, other than those for the line editor described +above, are provided with the shell and are described in *Note User +Contributions::. Features include: + + +promptinit + a prompt theme system for changing prompts easily, see *Note + Prompt Themes:: + +zsh-mime-setup + a MIME-handling system which dispatches commands according to the + suffix of a file as done by graphical file managers + +zcalc + a calculator + +zargs + a version of xargs that makes the find command redundant + +zmv + a command for renaming files by means of shell patterns. + + + +File: zsh.info, Node: Invocation, Next: Files, Prev: Roadmap, Up: Top + +4 Invocation +************ + + + +4.1 Invocation +============== + +The following flags are interpreted by the shell when invoked to +determine where the shell will read commands from: + + +-c + Take the first argument as a command to execute, rather than + reading commands from a script or standard input. If any further + arguments are given, the first one is assigned to $0, rather than + being used as a positional parameter. + +-i + Force shell to be interactive. It is still possible to specify a + script to execute. + +-s + Force shell to read commands from the standard input. If the -s + flag is not present and an argument is given, the first argument + is taken to be the pathname of a script to execute. + + +If there are any remaining arguments after option processing, and +neither of the options -c or -s was supplied, the first argument is +taken as the file name of a script containing shell commands to be +executed. If the option PATH_SCRIPT is set, and the file name does not +contain a directory path (i.e. there is no `/' in the name), first the +current directory and then the command path given by the variable PATH +are searched for the script. If the option is not set or the file name +contains a `/' it is used directly. + +After the first one or two arguments have been appropriated as +described above, the remaining arguments are assigned to the positional +parameters. + +For further options, which are common to invocation and the set +builtin, see *Note Options::. + +The long option `--emulate' followed (in a separate word) by an +emulation mode may be passed to the shell. The emulation modes are +those described for the emulate builtin, see *Note Shell Builtin +Commands::. The `--emulate' option must precede any other options +(which might otherwise be overridden), but following options are +honoured, so may be used to modify the requested emulation mode. Note +that certain extra steps are taken to ensure a smooth emulation when +this option is used compared with the emulate command within the shell: +for example, variables that conflict with POSIX usage such as path are +not defined within the shell. + +Options may be specified by name using the -o option. -o acts like a +single-letter option, but takes a following string as the option name. +For example, + + + zsh -x -o shwordsplit scr + +runs the script scr, setting the XTRACE option by the corresponding +letter `-x' and the SH_WORD_SPLIT option by name. Options may be +turned _off_ by name by using +o instead of -o. -o can be stacked up +with preceding single-letter options, so for example `-xo shwordsplit' +or `-xoshwordsplit' is equivalent to `-x -o shwordsplit'. + +Options may also be specified by name in GNU long option style, +`--OPTION-NAME'. When this is done, `-' characters in the option name +are permitted: they are translated into `_', and thus ignored. So, for +example, `zsh --sh-word-split' invokes zsh with the SH_WORD_SPLIT +option turned on. Like other option syntaxes, options can be turned +off by replacing the initial `-' with a `+'; thus `+-sh-word-split' is +equivalent to `--no-sh-word-split'. Unlike other option syntaxes, +GNU-style long options cannot be stacked with any other options, so for +example `-x-shwordsplit' is an error, rather than being treated like +`-x --shwordsplit'. + +The special GNU-style option `--version' is handled; it sends to +standard output the shell's version information, then exits +successfully. `--help' is also handled; it sends to standard output a +list of options that can be used when invoking the shell, then exits +successfully. + +Option processing may be finished, allowing following arguments that +start with `-' or `+' to be treated as normal arguments, in two ways. +Firstly, a lone `-' (or `+') as an argument by itself ends option +processing. Secondly, a special option `--' (or `+-'), which may be +specified on its own (which is the standard POSIX usage) or may be +stacked with preceding options (so `-x-' is equivalent to `-x --'). +Options are not permitted to be stacked after `--' (so `-x-f' is an +error), but note the GNU-style option form discussed above, where +`--shwordsplit' is permitted and does not end option processing. + +Except when the `sh'/`ksh' emulation single-letter options are in +effect, the option `-b' (or `+b') ends option processing. `-b' is like +`--', except that further single-letter options can be stacked after +the `-b' and will take effect as normal. + + + +* Menu: + +* Compatibility:: +* Restricted Shell:: + + + +File: zsh.info, Node: Compatibility, Next: Restricted Shell, Up: Invocation + +4.2 Compatibility +================= + +Zsh tries to emulate `sh' or `ksh' when it is invoked as sh or ksh +respectively; more precisely, it looks at the first letter of the name +by which it was invoked, excluding any initial `r' (assumed to stand +for `restricted'), and if that is `b', `s' or `k' it will emulate `sh' +or `ksh'. Furthermore, if invoked as su (which happens on certain +systems when the shell is executed by the su command), the shell will +try to find an alternative name from the SHELL environment variable and +perform emulation based on that. + +In `sh' and `ksh' compatibility modes the following parameters are not +special and not initialized by the shell: ARGC, argv, cdpath, fignore, +fpath, HISTCHARS, mailpath, MANPATH, manpath, path, prompt, PROMPT, +PROMPT2, PROMPT3, PROMPT4, psvar, status, watch. + +The usual zsh startup/shutdown scripts are not executed. Login shells +source /etc/profile followed by $HOME/.profile. If the ENV environment +variable is set on invocation, $ENV is sourced after the profile +scripts. The value of ENV is subjected to parameter expansion, command +substitution, and arithmetic expansion before being interpreted as a +pathname. Note that the PRIVILEGED option also affects the execution +of startup files. + +The following options are set if the shell is invoked as sh or ksh: +NO_BAD_PATTERN, NO_BANG_HIST, NO_BG_NICE, NO_EQUALS, +NO_FUNCTION_ARGZERO, GLOB_SUBST, NO_GLOBAL_EXPORT, NO_HUP, +INTERACTIVE_COMMENTS, KSH_ARRAYS, NO_MULTIOS, NO_NOMATCH, NO_NOTIFY, +POSIX_BUILTINS, NO_PROMPT_PERCENT, RM_STAR_SILENT, SH_FILE_EXPANSION, +SH_GLOB, SH_OPTION_LETTERS, SH_WORD_SPLIT. Additionally the BSD_ECHO +and IGNORE_BRACES options are set if zsh is invoked as sh. Also, the +KSH_OPTION_PRINT, LOCAL_OPTIONS, PROMPT_BANG, PROMPT_SUBST and +SINGLE_LINE_ZLE options are set if zsh is invoked as ksh. + + +File: zsh.info, Node: Restricted Shell, Prev: Compatibility, Up: Invocation + +4.3 Restricted Shell +==================== + +When the basename of the command used to invoke zsh starts with the +letter `r' or the `-r' command line option is supplied at invocation, +the shell becomes restricted. Emulation mode is determined after +stripping the letter `r' from the invocation name. The following are +disabled in restricted mode: + + + * changing directories with the cd builtin + + * changing or unsetting the EGID, EUID, GID, HISTFILE, HISTSIZE, + IFS, LD_AOUT_LIBRARY_PATH, LD_AOUT_PRELOAD, LD_LIBRARY_PATH, + LD_PRELOAD, MODULE_PATH, module_path, PATH, path, SHELL, UID and + USERNAME parameters + + * specifying command names containing / + + * specifying command pathnames using hash + + * redirecting output to files + + * using the exec builtin command to replace the shell with another + command + + * using jobs -Z to overwrite the shell process' argument and + environment space + + * using the ARGV0 parameter to override argv[0] for external commands + + * turning off restricted mode with set +r or unsetopt RESTRICTED + +These restrictions are enforced after processing the startup files. The +startup files should set up PATH to point to a directory of commands +which can be safely invoked in the restricted environment. They may +also add further restrictions by disabling selected builtins. + +Restricted mode can also be activated any time by setting the +RESTRICTED option. This immediately enables all the restrictions +described above even if the shell still has not processed all startup +files. + +A shell _Restricted Mode_ is an outdated way to restrict what users may +do: modern systems have better, safer and more reliable ways to +confine user actions, such as _chroot jails_, _containers_ and _zones_. + +A restricted shell is very difficult to implement safely. The feature +may be removed in a future version of zsh. + +It is important to realise that the restrictions only apply to the +shell, not to the commands it runs (except for some shell builtins). +While a restricted shell can only run the restricted list of commands +accessible via the predefined `PATH' variable, it does not prevent those +commands from running any other command. + +As an example, if `env' is among the list of _allowed_ commands, then +it allows the user to run any command as `env' is not a shell builtin +command and can run arbitrary executables. + +So when implementing a restricted shell framework it is important to be +fully aware of what actions each of the _allowed_ commands or features +(which may be regarded as _modules_) can perform. + +Many commands can have their behaviour affected by environment +variables. Except for the few listed above, zsh does not restrict the +setting of environment variables. + +If a `perl', `python', `bash', or other general purpose interpreted +script it treated as a restricted command, the user can work around the +restriction by setting specially crafted `PERL5LIB', `PYTHONPATH', +`BASHENV' (etc.) environment variables. On GNU systems, any command can +be made to run arbitrary code when performing character set conversion +(including zsh itself) by setting a `GCONV_PATH' environment variable. +Those are only a few examples. + +Bear in mind that, contrary to some other shells, `readonly' is not a +security feature in zsh as it can be undone and so cannot be used to +mitigate the above. + +A restricted shell only works if the allowed commands are few and +carefully written so as not to grant more access to users than +intended. It is also important to restrict what zsh module the user may +load as some of them, such as `zsh/system', `zsh/mapfile' and +`zsh/files', allow bypassing most of the restrictions. + + +File: zsh.info, Node: Files, Next: Shell Grammar, Prev: Invocation, Up: Top + +5 Files +******* + + + +5.1 Startup/Shutdown Files +========================== + +Commands are first read from /etc/zshenv; this cannot be overridden. +Subsequent behaviour is modified by the RCS and GLOBAL_RCS options; the +former affects all startup files, while the second only affects global +startup files (those shown here with an path starting with a /). If +one of the options is unset at any point, any subsequent startup file(s) +of the corresponding type will not be read. It is also possible for a +file in $ZDOTDIR to re-enable GLOBAL_RCS. Both RCS and GLOBAL_RCS are +set by default. + +Commands are then read from $ZDOTDIR/.zshenv. If the shell is a login +shell, commands are read from /etc/zprofile and then $ZDOTDIR/.zprofile. Then, +if the shell is interactive, commands are read from /etc/zshrc and then +$ZDOTDIR/.zshrc. Finally, if the shell is a login shell, /etc/zlogin +and $ZDOTDIR/.zlogin are read. + +When a login shell exits, the files $ZDOTDIR/.zlogout and then +/etc/zlogout are read. This happens with either an explicit exit via +the exit or logout commands, or an implicit exit by reading end-of-file +from the terminal. However, if the shell terminates due to exec'ing +another process, the logout files are not read. These are also +affected by the RCS and GLOBAL_RCS options. Note also that the RCS +option affects the saving of history files, i.e. if RCS is unset when +the shell exits, no history file will be saved. + +If ZDOTDIR is unset, HOME is used instead. Files listed above as being +in /etc may be in another directory, depending on the installation. + +As /etc/zshenv is run for all instances of zsh, it is important that it +be kept as small as possible. In particular, it is a good idea to put +code that does not need to be run for every single shell behind a test +of the form `if [[ -o rcs ]]; then ...' so that it will not be executed +when zsh is invoked with the `-f' option. + +5.2 Files +========= + + +$ZDOTDIR/.zshenv + +$ZDOTDIR/.zprofile + +$ZDOTDIR/.zshrc + +$ZDOTDIR/.zlogin + +$ZDOTDIR/.zlogout + +${TMPPREFIX}* (default is /tmp/zsh*) + +/etc/zshenv + +/etc/zprofile + +/etc/zshrc + +/etc/zlogin + +/etc/zlogout (installation-specific - /etc is the default) + + +Any of these files may be pre-compiled with the zcompile builtin +command (*Note Shell Builtin Commands::). If a compiled file exists +(named for the original file plus the .zwc extension) and it is newer +than the original file, the compiled file will be used instead. + + +File: zsh.info, Node: Shell Grammar, Next: Redirection, Prev: Files, Up: Top + +6 Shell Grammar +*************** + + + +* Menu: + +* Simple Commands & Pipelines:: +* Precommand Modifiers:: +* Complex Commands:: +* Alternate Forms For Complex Commands:: +* Reserved Words:: +* Errors:: +* Comments:: +* Aliasing:: +* Quoting:: + + +File: zsh.info, Node: Simple Commands & Pipelines, Next: Precommand Modifiers, Up: Shell Grammar + +6.1 Simple Commands & Pipelines +=============================== + +A _simple command_ is a sequence of optional parameter assignments +followed by blank-separated words, with optional redirections +interspersed. For a description of assignment, see the beginning of +*Note Parameters::. + +The first word is the command to be executed, and the remaining words, +if any, are arguments to the command. If a command name is given, the +parameter assignments modify the environment of the command when it is +executed. The value of a simple command is its exit status, or 128 +plus the signal number if terminated by a signal. For example, + + + echo foo + +is a simple command with arguments. + +A _pipeline_ is either a simple command, or a sequence of two or more +simple commands where each command is separated from the next by `|' or +`|&'. Where commands are separated by `|', the standard output of the +first command is connected to the standard input of the next. `|&' is +shorthand for `2>&1 |', which connects both the standard output and the +standard error of the command to the standard input of the next. The +value of a pipeline is the value of the last command, unless the +pipeline is preceded by `!' in which case the value is the logical +inverse of the value of the last command. For example, + + + echo foo | sed 's/foo/bar/' + +is a pipeline, where the output (`foo' plus a newline) of the first +command will be passed to the input of the second. + +If a pipeline is preceded by `coproc', it is executed as a coprocess; a +two-way pipe is established between it and the parent shell. The shell +can read from or write to the coprocess by means of the `>&p' and `<&p' +redirection operators or with `print -p' and `read -p'. A pipeline +cannot be preceded by both `coproc' and `!'. If job control is active, +the coprocess can be treated in other than input and output as an +ordinary background job. + +A _sublist_ is either a single pipeline, or a sequence of two or more +pipelines separated by `&&' or `||'. If two pipelines are separated by +`&&', the second pipeline is executed only if the first succeeds +(returns a zero status). If two pipelines are separated by `||', the +second is executed only if the first fails (returns a nonzero status). +Both operators have equal precedence and are left associative. The +value of the sublist is the value of the last pipeline executed. For +example, + + + dmesg | grep panic && print yes + +is a sublist consisting of two pipelines, the second just a simple +command which will be executed if and only if the grep command returns +a zero status. If it does not, the value of the sublist is that return +status, else it is the status returned by the print (almost certainly +zero). + +A _list_ is a sequence of zero or more sublists, in which each sublist +is terminated by `;', `&', `&|', `&!', or a newline. This terminator +may optionally be omitted from the last sublist in the list when the +list appears as a complex command inside `(...)' or `{...}'. When a +sublist is terminated by `;' or newline, the shell waits for it to +finish before executing the next sublist. If a sublist is terminated +by a `&', `&|', or `&!', the shell executes the last pipeline in it in +the background, and does not wait for it to finish (note the difference +from other shells which execute the whole sublist in the background). +A backgrounded pipeline returns a status of zero. + +More generally, a list can be seen as a set of any shell commands +whatsoever, including the complex commands below; this is implied +wherever the word `list' appears in later descriptions. For example, +the commands in a shell function form a special sort of list. + + +File: zsh.info, Node: Precommand Modifiers, Next: Complex Commands, Prev: Simple Commands & Pipelines, Up: Shell Grammar + +6.2 Precommand Modifiers +======================== + +A simple command may be preceded by a _precommand modifier_, which will +alter how the command is interpreted. These modifiers are shell +builtin commands with the exception of nocorrect which is a reserved +word. + + +- + The command is executed with a `-' prepended to its argv[0] string. + +builtin + The command word is taken to be the name of a builtin command, + rather than a shell function or external command. + +command [ -pvV ] + The command word is taken to be the name of an external command, + rather than a shell function or builtin. If the POSIX_BUILTINS + option is set, builtins will also be executed but certain special + properties of them are suppressed. The -p flag causes a default + path to be searched instead of that in $path. With the -v flag, + command is similar to whence and with -V, it is equivalent to + whence -v. + +exec [ -cl ] [ -a ARGV0 ] + The following command together with any arguments is run in place + of the current process, rather than as a sub-process. The shell + does not fork and is replaced. The shell does not invoke + TRAPEXIT, nor does it source zlogout files. The options are + provided for compatibility with other shells. + + The -c option clears the environment. + + The -l option is equivalent to the - precommand modifier, to treat + the replacement command as a login shell; the command is executed + with a - prepended to its argv[0] string. This flag has no effect + if used together with the -a option. + + The -a option is used to specify explicitly the argv[0] string + (the name of the command as seen by the process itself) to be used + by the replacement command and is directly equivalent to setting a + value for the ARGV0 environment variable. + +nocorrect + Spelling correction is not done on any of the words. This must + appear before any other precommand modifier, as it is interpreted + immediately, before any parsing is done. It has no effect in + non-interactive shells. + +noglob + Filename generation (globbing) is not performed on any of the + words. + + + +File: zsh.info, Node: Complex Commands, Next: Alternate Forms For Complex Commands, Prev: Precommand Modifiers, Up: Shell Grammar + +6.3 Complex Commands +==================== + +A _complex command_ in zsh is one of the following: + + +if LIST then LIST [ elif LIST then LIST ] ... [ else LIST ] fi + The if LIST is executed, and if it returns a zero exit status, the + then LIST is executed. Otherwise, the elif LIST is executed and + if its status is zero, the then LIST is executed. If each elif + LIST returns nonzero status, the else LIST is executed. + +for NAME ... [ in WORD ... ] TERM do LIST done + Expand the list of WORDs, and set the parameter NAME to each of + them in turn, executing LIST each time. If the `in WORD' is + omitted, use the positional parameters instead of the WORDs. + + The TERM consists of one or more newline or ; which terminate the + WORDs, and are optional when the `in WORD' is omitted. + + More than one parameter NAME can appear before the list of WORDs. + If N NAMEs are given, then on each execution of the loop the next + N WORDs are assigned to the corresponding parameters. If there + are more NAMEs than remaining WORDs, the remaining parameters are + each set to the empty string. Execution of the loop ends when + there is no remaining WORD to assign to the first NAME. It is + only possible for in to appear as the first NAME in the list, else + it will be treated as marking the end of the list. + +for (( [EXPR1] ; [EXPR2] ; [EXPR3] )) do LIST done + The arithmetic expression EXPR1 is evaluated first (see *Note + Arithmetic Evaluation::). The arithmetic expression EXPR2 is + repeatedly evaluated until it evaluates to zero and when non-zero, + LIST is executed and the arithmetic expression EXPR3 evaluated. + If any expression is omitted, then it behaves as if it evaluated + to 1. + +while LIST do LIST done + Execute the do LIST as long as the while LIST returns a zero exit + status. + +until LIST do LIST done + Execute the do LIST as long as until LIST returns a nonzero exit + status. + +repeat WORD do LIST done + WORD is expanded and treated as an arithmetic expression, which + must evaluate to a number N. LIST is then executed N times. + + The repeat syntax is disabled by default when the shell starts in + a mode emulating another shell. It can be enabled with the + command `enable -r repeat' + +case WORD in [ [(] PATTERN [ | PATTERN ] ... ) LIST (;;|;&|;|) ] ... esac + Execute the LIST associated with the first PATTERN that matches + WORD, if any. The form of the patterns is the same as that used + for filename generation. See *Note Filename Generation::. + + Note further that, unless the SH_GLOB option is set, the whole + pattern with alternatives is treated by the shell as equivalent to + a group of patterns within parentheses, although white space may + appear about the parentheses and the vertical bar and will be + stripped from the pattern at those points. White space may appear + elsewhere in the pattern; this is not stripped. If the SH_GLOB + option is set, so that an opening parenthesis can be unambiguously + treated as part of the case syntax, the expression is parsed into + separate words and these are treated as strict alternatives (as in + other shells). + + If the LIST that is executed is terminated with ;& rather than ;;, + the following list is also executed. The rule for the terminator + of the following list ;;, ;& or ;| is applied unless the esac is + reached. + + If the LIST that is executed is terminated with ;| the shell + continues to scan the PATTERNs looking for the next match, + executing the corresponding LIST, and applying the rule for the + corresponding terminator ;;, ;& or ;|. Note that WORD is not + re-expanded; all applicable PATTERNs are tested with the same WORD. + +select NAME [ in WORD ... TERM ] do LIST done + where TERM is one or more newline or ; to terminate the WORDs. Print + the set of WORDs, each preceded by a number. If the in WORD is + omitted, use the positional parameters. The PROMPT3 prompt is + printed and a line is read from the line editor if the shell is + interactive and that is active, or else standard input. If this + line consists of the number of one of the listed WORDs, then the + parameter NAME is set to the WORD corresponding to this number. + If this line is empty, the selection list is printed again. + Otherwise, the value of the parameter NAME is set to null. The + contents of the line read from standard input is saved in the + parameter REPLY. LIST is executed for each selection until a + break or end-of-file is encountered. + +( LIST ) + Execute LIST in a subshell. Traps set by the trap builtin are + reset to their default values while executing LIST. + +{ LIST } + Execute LIST. + +{ TRY-LIST } always { ALWAYS-LIST } + First execute TRY-LIST. Regardless of errors, or break or + continue commands encountered within TRY-LIST, execute + ALWAYS-LIST. Execution then continues from the result of the + execution of TRY-LIST; in other words, any error, or break or + continue command is treated in the normal way, as if ALWAYS-LIST + were not present. The two chunks of code are referred to as the + `try block' and the `always block'. + + Optional newlines or semicolons may appear after the always; note, + however, that they may _not_ appear between the preceding closing + brace and the always. + + An `error' in this context is a condition such as a syntax error + which causes the shell to abort execution of the current function, + script, or list. Syntax errors encountered while the shell is + parsing the code do not cause the ALWAYS-LIST to be executed. For + example, an erroneously constructed if block in TRY-LIST would + cause the shell to abort during parsing, so that ALWAYS-LIST would + not be executed, while an erroneous substitution such as ${*foo*} + would cause a run-time error, after which ALWAYS-LIST would be + executed. + + An error condition can be tested and reset with the special integer + variable TRY_BLOCK_ERROR. Outside an ALWAYS-LIST the value is + irrelevant, but it is initialised to -1. Inside ALWAYS-LIST, the + value is 1 if an error occurred in the TRY-LIST, else 0. If + TRY_BLOCK_ERROR is set to 0 during the ALWAYS-LIST, the error + condition caused by the TRY-LIST is reset, and shell execution + continues normally after the end of ALWAYS-LIST. Altering the + value during the TRY-LIST is not useful (unless this forms part of + an enclosing always block). + + Regardless of TRY_BLOCK_ERROR, after the end of ALWAYS-LIST the + normal shell status $? is the value returned from TRY-LIST. This + will be non-zero if there was an error, even if TRY_BLOCK_ERROR + was set to zero. + + The following executes the given code, ignoring any errors it + causes. This is an alternative to the usual convention of + protecting code by executing it in a subshell. + + + { + # code which may cause an error + } always { + # This code is executed regardless of the error. + (( TRY_BLOCK_ERROR = 0 )) + } + # The error condition has been reset. + + When a try block occurs outside of any function, a return or a + exit encountered in TRY-LIST does _not_ cause the execution of + ALWAYS-LIST. Instead, the shell exits immediately after any EXIT + trap has been executed. Otherwise, a return command encountered + in TRY-LIST will cause the execution of ALWAYS-LIST, just like + break and continue. + + + +function WORD ... [ () ] [ TERM ] { LIST } +WORD ... () [ TERM ] { LIST } +WORD ... () [ TERM ] COMMAND + where TERM is one or more newline or ;. Define a function which + is referenced by any one of WORD. Normally, only one WORD is + provided; multiple WORDs are usually only useful for setting traps. + The body of the function is the LIST between the { and }. See + *Note Functions::. + + If the option SH_GLOB is set for compatibility with other shells, + then whitespace may appear between the left and right parentheses + when there is a single WORD; otherwise, the parentheses will be + treated as forming a globbing pattern in that case. + + In any of the forms above, a redirection may appear outside the + function body, for example + + + func() { ... } 2>&1 + + The redirection is stored with the function and applied whenever + the function is executed. Any variables in the redirection are + expanded at the point the function is executed, but outside the + function scope. + +time [ PIPELINE ] + The PIPELINE is executed, and timing statistics are reported on + the standard error in the form specified by the TIMEFMT parameter. + If PIPELINE is omitted, print statistics about the shell process + and its children. + +[[ EXP ]] + Evaluates the conditional expression EXP and return a zero exit + status if it is true. See *Note Conditional Expressions:: for a + description of EXP. + + + +File: zsh.info, Node: Alternate Forms For Complex Commands, Next: Reserved Words, Prev: Complex Commands, Up: Shell Grammar + +6.4 Alternate Forms For Complex Commands +======================================== + +Many of zsh's complex commands have alternate forms. These are +non-standard and are likely not to be obvious even to seasoned shell +programmers; they should not be used anywhere that portability of shell +code is a concern. + +The short versions below only work if SUBLIST is of the form `{ LIST }' +or if the SHORT_LOOPS option is set. For the if, while and until +commands, in both these cases the test part of the loop must also be +suitably delimited, such as by `[[ ... ]]' or `(( ... ))', else the end +of the test will not be recognized. For the for, repeat, case and +select commands no such special form for the arguments is necessary, +but the other condition (the special form of SUBLIST or use of the +SHORT_LOOPS option) still applies. + + +if LIST { LIST } [ elif LIST { LIST } ] ... [ else { LIST } ] + An alternate form of if. The rules mean that + + + if [[ -o ignorebraces ]] { + print yes + } + + works, but + + + if true { # Does not work! + print yes + } + + does _not_, since the test is not suitably delimited. + +if LIST SUBLIST + A short form of the alternate if. The same limitations on the + form of LIST apply as for the previous form. + +for NAME ... ( WORD ... ) SUBLIST + A short form of for. + +for NAME ... [ in WORD ... ] TERM SUBLIST + where TERM is at least one newline or ;. Another short form of + for. + +for (( [EXPR1] ; [EXPR2] ; [EXPR3] )) SUBLIST + A short form of the arithmetic for command. + +foreach NAME ... ( WORD ... ) LIST end + Another form of for. + +while LIST { LIST } + An alternative form of while. Note the limitations on the form of + LIST mentioned above. + +until LIST { LIST } + An alternative form of until. Note the limitations on the form of + LIST mentioned above. + +repeat WORD SUBLIST + This is a short form of repeat. + +case WORD { [ [(] PATTERN [ | PATTERN ] ... ) LIST (;;|;&|;|) ] ... } + An alternative form of case. + +select NAME [ in WORD ... TERM ] SUBLIST + where TERM is at least one newline or ;. A short form of select. + +function WORD ... [ () ] [ TERM ] SUBLIST + This is a short form of function. + + + +File: zsh.info, Node: Reserved Words, Next: Errors, Prev: Alternate Forms For Complex Commands, Up: Shell Grammar + +6.5 Reserved Words +================== + +The following words are recognized as reserved words when used as the +first word of a command unless quoted or disabled using disable -r: + +do done esac then elif else fi for case if while function repeat time +until select coproc nocorrect foreach end ! [[ { } declare export float +integer local readonly typeset + +Additionally, `}' is recognized in any position if neither the +IGNORE_BRACES option nor the IGNORE_CLOSE_BRACES option is set. + + +File: zsh.info, Node: Errors, Next: Comments, Prev: Reserved Words, Up: Shell Grammar + +6.6 Errors +========== + +Certain errors are treated as fatal by the shell: in an interactive +shell, they cause control to return to the command line, and in a +non-interactive shell they cause the shell to be aborted. In older +versions of zsh, a non-interactive shell running a script would not +abort completely, but would resume execution at the next command to be +read from the script, skipping the remainder of any functions or shell +constructs such as loops or conditions; this somewhat illogical +behaviour can be recovered by setting the option CONTINUE_ON_ERROR. + +Fatal errors found in non-interactive shells include: + + + * Failure to parse shell options passed when invoking the shell + + * Failure to change options with the set builtin + + * Parse errors of all sorts, including failures to parse + mathematical expressions + + * Failures to set or modify variable behaviour with typeset, local, + declare, export, integer, float + + * Execution of incorrectly positioned loop control structures + (continue, break) + + * Attempts to use regular expression with no regular expression + module available + + * Disallowed operations when the RESTRICTED options is set + + * Failure to create a pipe needed for a pipeline + + * Failure to create a multio + + * Failure to autoload a module needed for a declared shell feature + + * Errors creating command or process substitutions + + * Syntax errors in glob qualifiers + + * File generation errors where not caught by the option BAD_PATTERN + + * All bad patterns used for matching within case statements + + * File generation failures where not caused by NO_MATCH or similar + options + + * All file generation errors where the pattern was used to create a + multio + + * Memory errors where detected by the shell + + * Invalid subscripts to shell variables + + * Attempts to assign read-only variables + + * Logical errors with variables such as assignment to the wrong type + + * Use of invalid variable names + + * Errors in variable substitution syntax + + * Failure to convert characters in $'...' expressions + +If the POSIX_BUILTINS option is set, more errors associated with shell +builtin commands are treated as fatal, as specified by the POSIX +standard. + + + + +File: zsh.info, Node: Comments, Next: Aliasing, Prev: Errors, Up: Shell Grammar + +6.7 Comments +============ + +In non-interactive shells, or in interactive shells with the +INTERACTIVE_COMMENTS option set, a word beginning with the third +character of the histchars parameter (`#' by default) causes that word +and all the following characters up to a newline to be ignored. + + +File: zsh.info, Node: Aliasing, Next: Quoting, Prev: Comments, Up: Shell Grammar + +6.8 Aliasing +============ + +Every eligible _word_ in the shell input is checked to see if there is +an alias defined for it. If so, it is replaced by the text of the +alias if it is in command position (if it could be the first word of a +simple command), or if the alias is global. If the replacement text +ends with a space, the next word in the shell input is always eligible +for purposes of alias expansion. An alias is defined using the alias +builtin; global aliases may be defined using the -g option to that +builtin. + +A _word_ is defined as: + + + * Any plain string or glob pattern + + * Any quoted string, using any quoting method (note that the quotes + must be part of the alias definition for this to be eligible) + + * Any parameter reference or command substitution + + * Any series of the foregoing, concatenated without whitespace or + other tokens between them + + * Any reserved word (case, do, else, etc.) + + * With global aliasing, any command separator, any redirection + operator, and `(' or `)' when not part of a glob pattern + +Alias expansion is done on the shell input before any other expansion +except history expansion. Therefore, if an alias is defined for the +word foo, alias expansion may be avoided by quoting part of the word, +e.g. \foo. Any form of quoting works, although there is nothing to +prevent an alias being defined for the quoted form such as \foo as well. + +When POSIX_ALIASES is set, only plain unquoted strings are eligible for +aliasing. The alias builtin does not reject ineligible aliases, but +they are not expanded. + +For use with completion, which would remove an initial backslash +followed by a character that isn't special, it may be more convenient +to quote the word by starting with a single quote, i.e. 'foo; +completion will automatically add the trailing single quote. + + + +6.8.1 Alias difficulties +------------------------ + +Although aliases can be used in ways that bend normal shell syntax, not +every string of non-white-space characters can be used as an alias. + +Any set of characters not listed as a word above is not a word, hence no +attempt is made to expand it as an alias, no matter how it is defined +(i.e. via the builtin or the special parameter aliases described in +*Note The zsh/parameter Module::). However, as noted in the case of +POSIX_ALIASES above, the shell does not attempt to deduce whether the +string corresponds to a word at the time the alias is created. + +For example, an expression containing an = at the start of a command +line is an assignment and cannot be expanded as an alias; a lone = is +not an assignment but can only be set as an alias using the parameter, +as otherwise the = is taken part of the syntax of the builtin command. + +It is not presently possible to alias the `((' token that introduces +arithmetic expressions, because until a full statement has been parsed, +it cannot be distinguished from two consecutive `(' tokens introducing +nested subshells. Also, if a separator such as && is aliased, \&& +turns into the two tokens \& and &, each of which may have been aliased +separately. Similarly for \<<, \>|, etc. + +There is a commonly encountered problem with aliases illustrated by the +following code: + + + alias echobar='echo bar'; echobar + +This prints a message that the command echobar could not be found. +This happens because aliases are expanded when the code is read in; the +entire line is read in one go, so that when echobar is executed it is +too late to expand the newly defined alias. This is often a problem in +shell scripts, functions, and code executed with `source' or `.'. +Consequently, use of functions rather than aliases is recommended in +non-interactive code. + +Note also the unhelpful interaction of aliases and function definitions: + + + alias func='noglob func' + func() { + echo Do something with $* + } + +Because aliases are expanded in function definitions, this causes the +following command to be executed: + + + noglob func() { + echo Do something with $* + } + +which defines noglob as well as func as functions with the body given. +To avoid this, either quote the name func or use the alternative +function definition form `function func'. Ensuring the alias is +defined after the function works but is problematic if the code +fragment might be re-executed. + + + + +File: zsh.info, Node: Quoting, Prev: Aliasing, Up: Shell Grammar + +6.9 Quoting +=========== + +A character may be _quoted_ (that is, made to stand for itself) by +preceding it with a `\'. `\' followed by a newline is ignored. + +A string enclosed between `$'' and `'' is processed the same way as the +string arguments of the print builtin, and the resulting string is +considered to be entirely quoted. A literal `'' character can be +included in the string by using the `\'' escape. + +All characters enclosed between a pair of single quotes ('') that is +not preceded by a `$' are quoted. A single quote cannot appear within +single quotes unless the option RC_QUOTES is set, in which case a pair +of single quotes are turned into a single quote. For example, + + + print '''' + +outputs nothing apart from a newline if RC_QUOTES is not set, but one +single quote if it is set. + +Inside double quotes (""), parameter and command substitution occur, +and `\' quotes the characters `\', ``', `"', `$', and the first +character of $histchars (default `!'). + + +File: zsh.info, Node: Redirection, Next: Command Execution, Prev: Shell Grammar, Up: Top + +7 Redirection +************* + +If a command is followed by & and job control is not active, then the +default standard input for the command is the empty file /dev/null. +Otherwise, the environment for the execution of a command contains the +file descriptors of the invoking shell as modified by input/output +specifications. + +The following may appear anywhere in a simple command or may precede or +follow a complex command. Expansion occurs before WORD or DIGIT is +used except as noted below. If the result of substitution on WORD +produces more than one filename, redirection occurs for each separate +filename in turn. + + +< WORD + Open file WORD for reading as standard input. It is an error to + open a file in this fashion if it does not exist. + +<> WORD + Open file WORD for reading and writing as standard input. If the + file does not exist then it is created. + +> WORD + Open file WORD for writing as standard output. If the file does + not exist then it is created. If the file exists, and the CLOBBER + option is unset, this causes an error; otherwise, it is truncated + to zero length. + +>| WORD +>! WORD + Same as >, except that the file is truncated to zero length if it + exists, regardless of CLOBBER. + +>> WORD + Open file WORD for writing in append mode as standard output. If + the file does not exist, and the CLOBBER and APPEND_CREATE options + are both unset, this causes an error; otherwise, the file is + created. + +>>| WORD +>>! WORD + Same as >>, except that the file is created if it does not exist, + regardless of CLOBBER and APPEND_CREATE. + +<<[-] WORD + The shell input is read up to a line that is the same as WORD, or + to an end-of-file. No parameter expansion, command substitution or + filename generation is performed on WORD. The resulting document, + called a _here-document_, becomes the standard input. + + If any character of WORD is quoted with single or double quotes or + a `\', no interpretation is placed upon the characters of the + document. Otherwise, parameter and command substitution occurs, + `\' followed by a newline is removed, and `\' must be used to + quote the characters `\', `$', ``' and the first character of WORD. + + Note that WORD itself does not undergo shell expansion. Backquotes + in WORD do not have their usual effect; instead they behave + similarly to double quotes, except that the backquotes themselves + are passed through unchanged. (This information is given for + completeness and it is not recommended that backquotes be used.) + Quotes in the form $'...' have their standard effect of expanding + backslashed references to special characters. + + If <<- is used, then all leading tabs are stripped from WORD and + from the document. + +<<< WORD + Perform shell expansion on WORD and pass the result to standard + input. This is known as a _here-string_. Compare the use of WORD + in here-documents above, where WORD does not undergo shell + expansion. + +<& NUMBER +>& NUMBER + The standard input/output is duplicated from file descriptor + NUMBER (see man page dup2(2)). + +<& - +>& - + Close the standard input/output. + +<& p +>& p + The input/output from/to the coprocess is moved to the standard + input/output. + +>& WORD +&> WORD + (Except where `>& WORD' matches one of the above syntaxes; `&>' + can always be used to avoid this ambiguity.) Redirects both + standard output and standard error (file descriptor 2) in the + manner of `> WORD'. Note that this does _not_ have the same + effect as `> WORD 2>&1' in the presence of multios (see the + section below). + +>&| WORD +>&! WORD +&>| WORD +&>! WORD + Redirects both standard output and standard error (file descriptor + 2) in the manner of `>| WORD'. + +>>& WORD +&>> WORD + Redirects both standard output and standard error (file descriptor + 2) in the manner of `>> WORD'. + +>>&| WORD +>>&! WORD +&>>| WORD +&>>! WORD + Redirects both standard output and standard error (file descriptor + 2) in the manner of `>>| WORD'. + + +If one of the above is preceded by a digit, then the file descriptor +referred to is that specified by the digit instead of the default 0 or +1. The order in which redirections are specified is significant. The +shell evaluates each redirection in terms of the (_file descriptor_, +_file_) association at the time of evaluation. For example: + + + + ... 1>FNAME 2>&1 + +first associates file descriptor 1 with file FNAME. It then associates +file descriptor 2 with the file associated with file descriptor 1 (that +is, FNAME). If the order of redirections were reversed, file +descriptor 2 would be associated with the terminal (assuming file +descriptor 1 had been) and then file descriptor 1 would be associated +with file FNAME. + +The `|&' command separator described in *Note Simple Commands & +Pipelines:: is a shorthand for `2>&1 |'. + +The various forms of process substitution, `<(LIST)', and `=(LIST)' for +input and `>(LIST)' for output, are often used together with +redirection. For example, if WORD in an output redirection is of the +form `>(LIST)' then the output is piped to the command represented by +LIST. See *Note Process Substitution::. + +7.1 Opening file descriptors using parameters +============================================= + + + +When the shell is parsing arguments to a command, and the shell option +IGNORE_BRACES is not set, a different form of redirection is allowed: +instead of a digit before the operator there is a valid shell identifier +enclosed in braces. The shell will open a new file descriptor that is +guaranteed to be at least 10 and set the parameter named by the +identifier to the file descriptor opened. No whitespace is allowed +between the closing brace and the redirection character. For example: + + + + ... {myfd}>&1 + +This opens a new file descriptor that is a duplicate of file descriptor +1 and sets the parameter myfd to the number of the file descriptor, +which will be at least 10. The new file descriptor can be written to +using the syntax >&$myfd. The file descriptor remains open in subshells +and forked external executables. + +The syntax {VARID}>&-, for example {myfd}>&-, may be used to close a +file descriptor opened in this fashion. Note that the parameter given +by VARID must previously be set to a file descriptor in this case. + +It is an error to open or close a file descriptor in this fashion when +the parameter is readonly. However, it is not an error to read or +write a file descriptor using <&$PARAM or >&$PARAM if PARAM is readonly. + +If the option CLOBBER is unset, it is an error to open a file +descriptor using a parameter that is already set to an open file +descriptor previously allocated by this mechanism. Unsetting the +parameter before using it for allocating a file descriptor avoids the +error. + +Note that this mechanism merely allocates or closes a file descriptor; +it does not perform any redirections from or to it. It is usually +convenient to allocate a file descriptor prior to use as an argument to +exec. The syntax does not in any case work when used around complex +commands such as parenthesised subshells or loops, where the opening +brace is interpreted as part of a command list to be executed in the +current shell. + +The following shows a typical sequence of allocation, use, and closing +of a file descriptor: + + + integer myfd + exec {myfd}>~/logs/mylogfile.txt + print This is a log message. >&$myfd + exec {myfd}>&- + +Note that the expansion of the variable in the expression >&$myfd +occurs at the point the redirection is opened. This is after the +expansion of command arguments and after any redirections to the left +on the command line have been processed. + +7.2 Multios +=========== + +If the user tries to open a file descriptor for writing more than once, +the shell opens the file descriptor as a pipe to a process that copies +its input to all the specified outputs, similar to `tee', provided the +MULTIOS option is set, as it is by default. Thus: + + + date >foo >bar + +writes the date to two files, named `foo' and `bar'. Note that a pipe +is an implicit redirection; thus + + + date >foo | cat + +writes the date to the file `foo', and also pipes it to cat. + +Note that the shell opens all the files to be used in the multio process +immediately, not at the point they are about to be written. + +Note also that redirections are always expanded in order. This happens +regardless of the setting of the MULTIOS option, but with the option in +effect there are additional consequences. For example, the meaning of +the expression >&1 will change after a previous redirection: + + + date >&1 >output + +In the case above, the >&1 refers to the standard output at the start +of the line; the result is similar to the tee command. However, +consider: + + + date >output >&1 + +As redirections are evaluated in order, when the >&1 is encountered the +standard output is set to the file output and another copy of the +output is therefore sent to that file. This is unlikely to be what is +intended. + +If the MULTIOS option is set, the word after a redirection operator is +also subjected to filename generation (globbing). Thus + + + : > * + +will truncate all files in the current directory, assuming there's at +least one. (Without the MULTIOS option, it would create an empty file +called `*'.) Similarly, you can do + + + echo exit 0 >> *.sh + +If the user tries to open a file descriptor for reading more than once, +the shell opens the file descriptor as a pipe to a process that copies +all the specified inputs to its output in the order specified, provided +the MULTIOS option is set. It should be noted that each file is opened +immediately, not at the point where it is about to be read: this +behaviour differs from cat, so if strictly standard behaviour is +needed, cat should be used instead. + +Thus + + + sort <foo <fubar + +or even + + + sort <f{oo,ubar} + +is equivalent to `cat foo fubar | sort'. + +Expansion of the redirection argument occurs at the point the +redirection is opened, at the point described above for the expansion +of the variable in >&$myfd. + +Note that a pipe is an implicit redirection; thus + + + cat bar | sort <foo + +is equivalent to `cat bar foo | sort' (note the order of the inputs). + +If the MULTIOS option is _un_set, each redirection replaces the +previous redirection for that file descriptor. However, all files +redirected to are actually opened, so + + + echo Hello > bar > baz + +when MULTIOS is unset will truncate `bar', and write `Hello' into `baz'. + +There is a problem when an output multio is attached to an external +program. A simple example shows this: + + + cat file >file1 >file2 + cat file1 file2 + +Here, it is possible that the second `cat' will not display the full +contents of file1 and file2 (i.e. the original contents of file +repeated twice). + +The reason for this is that the multios are spawned after the cat +process is forked from the parent shell, so the parent shell does not +wait for the multios to finish writing data. This means the command as +shown can exit before file1 and file2 are completely written. As a +workaround, it is possible to run the cat process as part of a job in +the current shell: + + + { cat file } >file >file2 + +Here, the {...} job will pause to wait for both files to be written. + + + +7.3 Redirections with no command +================================ + +When a simple command consists of one or more redirection operators and +zero or more parameter assignments, but no command name, zsh can behave +in several ways. + +If the parameter NULLCMD is not set or the option CSH_NULLCMD is set, +an error is caused. This is the `csh' behavior and CSH_NULLCMD is set +by default when emulating `csh'. + +If the option SH_NULLCMD is set, the builtin `:' is inserted as a +command with the given redirections. This is the default when emulating +`sh' or `ksh'. + +Otherwise, if the parameter NULLCMD is set, its value will be used as a +command with the given redirections. If both NULLCMD and READNULLCMD +are set, then the value of the latter will be used instead of that of +the former when the redirection is an input. The default for NULLCMD +is `cat' and for READNULLCMD is `more'. Thus + + + < file + +shows the contents of file on standard output, with paging if that is a +terminal. NULLCMD and READNULLCMD may refer to shell functions. + + + + +File: zsh.info, Node: Command Execution, Next: Functions, Prev: Redirection, Up: Top + +8 Command Execution +******************* + +If a command name contains no slashes, the shell attempts to locate it. +If there exists a shell function by that name, the function is invoked +as described in *Note Functions::. If there exists a shell builtin by +that name, the builtin is invoked. + +Otherwise, the shell searches each element of $path for a directory +containing an executable file by that name. If the search is +unsuccessful, the shell prints an error message and returns a nonzero +exit status. + +If execution fails because the file is not in executable format, and +the file is not a directory, it is assumed to be a shell script. +/bin/sh is spawned to execute it. If the program is a file beginning +with `#!', the remainder of the first line specifies an interpreter for +the program. The shell will execute the specified interpreter on +operating systems that do not handle this executable format in the +kernel. + +If no external command is found but a function command_not_found_handler +exists the shell executes this function with all command line +arguments. The return status of the function becomes the status of the +command. If the function wishes to mimic the behaviour of the shell +when the command is not found, it should print the message `command not +found: CMD' to standard error and return status 127. Note that the +handler is executed in a subshell forked to execute an external +command, hence changes to directories, shell parameters, etc. have no +effect on the main shell. + + + + +File: zsh.info, Node: Functions, Next: Jobs & Signals, Prev: Command Execution, Up: Top + +9 Functions +*********** + +Shell functions are defined with the function reserved word or the +special syntax `FUNCNAME ()'. Shell functions are read in and stored +internally. Alias names are resolved when the function is read. +Functions are executed like commands with the arguments passed as +positional parameters. (See *Note Command Execution::.) + +Functions execute in the same process as the caller and share all files +and present working directory with the caller. A trap on EXIT set +inside a function is executed after the function completes in the +environment of the caller. + +The return builtin is used to return from function calls. + +Function identifiers can be listed with the functions builtin. Functions +can be undefined with the unfunction builtin. + +9.1 Autoloading Functions +========================= + + + +A function can be marked as _undefined_ using the autoload builtin (or +`functions -u' or `typeset -fu'). Such a function has no body. When +the function is first executed, the shell searches for its definition +using the elements of the fpath variable. Thus to define functions for +autoloading, a typical sequence is: + + + fpath=(~/myfuncs $fpath) + autoload myfunc1 myfunc2 ... + +The usual alias expansion during reading will be suppressed if the +autoload builtin or its equivalent is given the option -U. This is +recommended for the use of functions supplied with the zsh distribution. Note +that for functions precompiled with the zcompile builtin command the +flag -U must be provided when the .zwc file is created, as the +corresponding information is compiled into the latter. + +For each ELEMENT in fpath, the shell looks for three possible files, +the newest of which is used to load the definition for the function: + + +ELEMENT.zwc + A file created with the zcompile builtin command, which is + expected to contain the definitions for all functions in the + directory named ELEMENT. The file is treated in the same manner + as a directory containing files for functions and is searched for + the definition of the function. If the definition is not found, + the search for a definition proceeds with the other two + possibilities described below. + + If ELEMENT already includes a .zwc extension (i.e. the extension + was explicitly given by the user), ELEMENT is searched for the + definition of the function without comparing its age to that of + other files; in fact, there does not need to be any directory + named ELEMENT without the suffix. Thus including an element such + as `/usr/local/funcs.zwc' in fpath will speed up the search for + functions, with the disadvantage that functions included must be + explicitly recompiled by hand before the shell notices any changes. + +ELEMENT/FUNCTION.zwc + A file created with zcompile, which is expected to contain the + definition for FUNCTION. It may include other function definitions + as well, but those are neither loaded nor executed; a file found + in this way is searched _only_ for the definition of FUNCTION. + +ELEMENT/FUNCTION + A file of zsh command text, taken to be the definition for + FUNCTION. + + +In summary, the order of searching is, first, in the _parents of_ +directories in fpath for the newer of either a compiled directory or a +directory in fpath; second, if more than one of these contains a +definition for the function that is sought, the leftmost in the fpath +is chosen; and third, within a directory, the newer of either a compiled +function or an ordinary function definition is used. + +If the KSH_AUTOLOAD option is set, or the file contains only a simple +definition of the function, the file's contents will be executed. This +will normally define the function in question, but may also perform +initialization, which is executed in the context of the function +execution, and may therefore define local parameters. It is an error +if the function is not defined by loading the file. + +Otherwise, the function body (with no surrounding `FUNCNAME() {...}') +is taken to be the complete contents of the file. This form allows the +file to be used directly as an executable shell script. If processing +of the file results in the function being re-defined, the function +itself is not re-executed. To force the shell to perform +initialization and then call the function defined, the file should +contain initialization code (which will be executed then discarded) in +addition to a complete function definition (which will be retained for +subsequent calls to the function), and a call to the shell function, +including any arguments, at the end. + +For example, suppose the autoload file func contains + + + func() { print This is func; } + print func is initialized + +then `func; func' with KSH_AUTOLOAD set will produce both messages on +the first call, but only the message `This is func' on the second and +subsequent calls. Without KSH_AUTOLOAD set, it will produce the +initialization message on the first call, and the other message on the +second and subsequent calls. + +It is also possible to create a function that is not marked as +autoloaded, but which loads its own definition by searching fpath, by +using `autoload -X' within a shell function. For example, the +following are equivalent: + + + myfunc() { + autoload -X + } + myfunc args... + +and + + + unfunction myfunc # if myfunc was defined + autoload myfunc + myfunc args... + +In fact, the functions command outputs `builtin autoload -X' as the +body of an autoloaded function. This is done so that + + + eval "$(functions)" + +produces a reasonable result. A true autoloaded function can be +identified by the presence of the comment `# undefined' in the body, +because all comments are discarded from defined functions. + +To load the definition of an autoloaded function myfunc without +executing myfunc, use: + + + autoload +X myfunc + + +9.2 Anonymous Functions +======================= + + + +If no name is given for a function, it is `anonymous' and is handled +specially. Either form of function definition may be used: a `()' with +no preceding name, or a `function' with an immediately following open +brace. The function is executed immediately at the point of definition +and is not stored for future use. The function name is set to `(anon)'. + +Arguments to the function may be specified as words following the +closing brace defining the function, hence if there are none no +arguments (other than $0) are set. This is a difference from the way +other functions are parsed: normal function definitions may be followed +by certain keywords such as `else' or `fi', which will be treated as +arguments to anonymous functions, so that a newline or semicolon is +needed to force keyword interpretation. + +Note also that the argument list of any enclosing script or function is +hidden (as would be the case for any other function called at this +point). + +Redirections may be applied to the anonymous function in the same +manner as to a current-shell structure enclosed in braces. The main +use of anonymous functions is to provide a scope for local variables. +This is particularly convenient in start-up files as these do not +provide their own local variable scope. + +For example, + + + variable=outside + function { + local variable=inside + print "I am $variable with arguments $*" + } this and that + print "I am $variable" + +outputs the following: + + + I am inside with arguments this and that + I am outside + +Note that function definitions with arguments that expand to nothing, +for example `name=; function $name { ... }', are not treated as +anonymous functions. Instead, they are treated as normal function +definitions where the definition is silently discarded. + + + +9.3 Special Functions +===================== + +Certain functions, if defined, have special meaning to the shell. + + + +9.3.1 Hook Functions +-------------------- + + + +For the functions below, it is possible to define an array that has the +same name as the function with `_functions' appended. Any element in +such an array is taken as the name of a function to execute; it is +executed in the same context and with the same arguments as the basic +function. For example, if $chpwd_functions is an array containing the +values `mychpwd', `chpwd_save_dirstack', then the shell attempts to +execute the functions `chpwd', `mychpwd' and `chpwd_save_dirstack', in +that order. Any function that does not exist is silently ignored. A +function found by this mechanism is referred to elsewhere as a `hook +function'. An error in any function causes subsequent functions not to +be run. Note further that an error in a precmd hook causes an +immediately following periodic function not to run (though it may run +at the next opportunity). + + +chpwd + Executed whenever the current working directory is changed. + +periodic + If the parameter PERIOD is set, this function is executed every + $PERIOD seconds, just before a prompt. Note that if multiple + functions are defined using the array periodic_functions only one + period is applied to the complete set of functions, and the + scheduled time is not reset if the list of functions is altered. + Hence the set of functions is always called together. + +precmd + Executed before each prompt. Note that precommand functions are + not re-executed simply because the command line is redrawn, as + happens, for example, when a notification about an exiting job is + displayed. + +preexec + Executed just after a command has been read and is about to be + executed. If the history mechanism is active (regardless of + whether the line was discarded from the history buffer), the + string that the user typed is passed as the first argument, + otherwise it is an empty string. The actual command that will be + executed (including expanded aliases) is passed in two different + forms: the second argument is a single-line, size-limited version + of the command (with things like function bodies elided); the + third argument contains the full text that is being executed. + +zshaddhistory + Executed when a history line has been read interactively, but + before it is executed. The sole argument is the complete history + line (so that any terminating newline will still be present). + + If any of the hook functions returns status 1 (or any non-zero + value other than 2, though this is not guaranteed for future + versions of the shell) the history line will not be saved, + although it lingers in the history until the next line is + executed, allowing you to reuse or edit it immediately. + + If any of the hook functions returns status 2 the history line + will be saved on the internal history list, but not written to the + history file. In case of a conflict, the first non-zero status + value is taken. + + A hook function may call `fc -p ...' to switch the history context + so that the history is saved in a different file from the that in + the global HISTFILE parameter. This is handled specially: the + history context is automatically restored after the processing of + the history line is finished. + + The following example function works with one of the options + INC_APPEND_HISTORY or SHARE_HISTORY set, in order that the line is + written out immediately after the history entry is added. It first + adds the history line to the normal history with the newline + stripped, which is usually the correct behaviour. Then it + switches the history context so that the line will be written to a + history file in the current directory. + + + zshaddhistory() { + print -sr -- ${1%%$'\n'} + fc -p .zsh_local_history + } + +zshexit + Executed at the point where the main shell is about to exit + normally. This is not called by exiting subshells, nor when the + exec precommand modifier is used before an external command. + Also, unlike TRAPEXIT, it is not called when functions exit. + + + +9.3.2 Trap Functions +-------------------- + +The functions below are treated specially but do not have corresponding +hook arrays. + + +TRAPNAL + If defined and non-null, this function will be executed whenever + the shell catches a signal SIGNAL, where NAL is a signal name as + specified for the kill builtin. The signal number will be passed + as the first parameter to the function. + + If a function of this form is defined and null, the shell and + processes spawned by it will ignore SIGNAL. + + The return status from the function is handled specially. If it is + zero, the signal is assumed to have been handled, and execution + continues normally. Otherwise, the shell will behave as + interrupted except that the return status of the trap is retained. + + Programs terminated by uncaught signals typically return the + status 128 plus the signal number. Hence the following causes the + handler for SIGINT to print a message, then mimic the usual effect + of the signal. + + + TRAPINT() { + print "Caught SIGINT, aborting." + return $(( 128 + $1 )) + } + + The functions TRAPZERR, TRAPDEBUG and TRAPEXIT are never executed + inside other traps. + +TRAPDEBUG + If the option DEBUG_BEFORE_CMD is set (as it is by default), + executed before each command; otherwise executed after each + command. See the description of the trap builtin in *Note Shell + Builtin Commands:: for details of additional features provided in + debug traps. + +TRAPEXIT + Executed when the shell exits, or when the current function exits + if defined inside a function. The value of $? at the start of + execution is the exit status of the shell or the return status of + the function exiting. + +TRAPZERR + Executed whenever a command has a non-zero exit status. However, + the function is not executed if the command occurred in a sublist + followed by `&&' or `||'; only the final command in a sublist of + this type causes the trap to be executed. The function TRAPERR + acts the same as TRAPZERR on systems where there is no SIGERR + (this is the usual case). + + +The functions beginning `TRAP' may alternatively be defined with the +trap builtin: this may be preferable for some uses. Setting a trap +with one form removes any trap of the other form for the same signal; +removing a trap in either form removes all traps for the same signal. +The forms + + + TRAPNAL() { + # code + } + +('function traps') and + + + trap ' + # code + ' NAL + +('list traps') are equivalent in most ways, the exceptions being the +following: + + + * Function traps have all the properties of normal functions, + appearing in the list of functions and being called with their own + function context rather than the context where the trap was + triggered. + + * The return status from function traps is special, whereas a return + from a list trap causes the surrounding context to return with the + given status. + + * Function traps are not reset within subshells, in accordance with + zsh behaviour; list traps are reset, in accordance with POSIX + behaviour. + + +File: zsh.info, Node: Jobs & Signals, Next: Arithmetic Evaluation, Prev: Functions, Up: Top + +10 Jobs & Signals +***************** + + + +10.1 Jobs +========= + +If the MONITOR option is set, an interactive shell associates a _job_ +with each pipeline. It keeps a table of current jobs, printed by the +jobs command, and assigns them small integer numbers. When a job is +started asynchronously with `&', the shell prints a line to standard +error which looks like: + + + [1] 1234 + +indicating that the job which was started asynchronously was job number +1 and had one (top-level) process, whose process ID was 1234. + +If a job is started with `&|' or `&!', then that job is immediately +disowned. After startup, it does not have a place in the job table, +and is not subject to the job control features described here. + +If you are running a job and wish to do something else you may hit the +key ^Z (control-Z) which sends a TSTP signal to the current job: this +key may be redefined by the susp option of the external stty command. The +shell will then normally indicate that the job has been `suspended', +and print another prompt. You can then manipulate the state of this +job, putting it in the background with the bg command, or run some other +commands and then eventually bring the job back into the foreground with the +foreground command fg. A ^Z takes effect immediately and is like an +interrupt in that pending output and unread input are discarded when it +is typed. + +A job being run in the background will suspend if it tries to read from +the terminal. + +Note that if the job running in the foreground is a shell function, +then suspending it will have the effect of causing the shell to fork. +This is necessary to separate the function's state from that of the +parent shell performing the job control, so that the latter can return +to the command line prompt. As a result, even if fg is used to +continue the job the function will no longer be part of the parent +shell, and any variables set by the function will not be visible in the +parent shell. Thus the behaviour is different from the case where the +function was never suspended. Zsh is different from many other shells +in this regard. + +One additional side effect is that use of disown with a job created by +suspending shell code in this fashion is delayed: the job can only be +disowned once any process started from the parent shell has terminated. +At that point, the disowned job disappears silently from the job list. + +The same behaviour is found when the shell is executing code as the +right hand side of a pipeline or any complex shell construct such as +if, for, etc., in order that the entire block of code can be managed as +a single job. Background jobs are normally allowed to produce output, +but this can be disabled by giving the command `stty tostop'. If you +set this tty option, then background jobs will suspend when they try to +produce output like they do when they try to read input. + +When a command is suspended and continued later with the fg or wait +builtins, zsh restores tty modes that were in effect when it was +suspended. This (intentionally) does not apply if the command is +continued via `kill -CONT', nor when it is continued with bg. + +There are several ways to refer to jobs in the shell. A job can be +referred to by the process ID of any process of the job or by one of +the following: + + +%NUMBER + The job with the given number. + +%STRING + The last job whose command line begins with STRING. + +%?STRING + The last job whose command line contains STRING. + +%% + Current job. + +%+ + Equivalent to `%%'. + +%- + Previous job. + +The shell learns immediately whenever a process changes state. It +normally informs you whenever a job becomes blocked so that no further +progress is possible. If the NOTIFY option is not set, it waits until +just before it prints a prompt before it informs you. All such +notifications are sent directly to the terminal, not to the standard +output or standard error. + +When the monitor mode is on, each background job that completes +triggers any trap set for CHLD. + +When you try to leave the shell while jobs are running or suspended, +you will be warned that `You have suspended (running) jobs'. You may +use the jobs command to see what they are. If you do this or +immediately try to exit again, the shell will not warn you a second +time; the suspended jobs will be terminated, and the running jobs will +be sent a SIGHUP signal, if the HUP option is set. + +To avoid having the shell terminate the running jobs, either use the +`nohup' command (see man page nohup(1)) or the disown builtin. + +10.2 Signals +============ + +The INT and QUIT signals for an invoked command are ignored if the +command is followed by `&' and the MONITOR option is not active. The +shell itself always ignores the QUIT signal. Otherwise, signals have +the values inherited by the shell from its parent (but see the TRAPNAL +special functions in *Note Functions::). + +Certain jobs are run asynchronously by the shell other than those +explicitly put into the background; even in cases where the shell would +usually wait for such jobs, an explicit exit command or exit due to the +option ERR_EXIT will cause the shell to exit without waiting. Examples +of such asynchronous jobs are process substitution, see *Note Process +Substitution::, and the handler processes for multios, see the section +Multios in *Note Redirection::. + + +File: zsh.info, Node: Arithmetic Evaluation, Next: Conditional Expressions, Prev: Jobs & Signals, Up: Top + +11 Arithmetic Evaluation +************************ + +The shell can perform integer and floating point arithmetic, either +using the builtin let, or via a substitution of the form $((...)). For +integers, the shell is usually compiled to use 8-byte precision where +this is available, otherwise precision is 4 bytes. This can be tested, +for example, by giving the command `print - $(( 12345678901 ))'; if the +number appears unchanged, the precision is at least 8 bytes. Floating +point arithmetic always uses the `double' type with whatever +corresponding precision is provided by the compiler and the library. + +The let builtin command takes arithmetic expressions as arguments; each +is evaluated separately. Since many of the arithmetic operators, as +well as spaces, require quoting, an alternative form is provided: for +any command which begins with a `((', all the characters until a +matching `))' are treated as a quoted expression and arithmetic +expansion performed as for an argument of let. More precisely, +`((...))' is equivalent to `let "..."'. The return status is 0 if the +arithmetic value of the expression is non-zero, 1 if it is zero, and 2 +if an error occurred. + +For example, the following statement + + + (( val = 2 + 1 )) + +is equivalent to + + + let "val = 2 + 1" + +both assigning the value 3 to the shell variable val and returning a +zero status. + +Integers can be in bases other than 10. A leading `0x' or `0X' denotes +hexadecimal and a leading `0b' or `0B' binary. Integers may also be of +the form `BASE#N', where BASE is a decimal number between two and +thirty-six representing the arithmetic base and N is a number in that +base (for example, `16#ff' is 255 in hexadecimal). The BASE# may also +be omitted, in which case base 10 is used. For backwards compatibility +the form `[BASE]N' is also accepted. + +An integer expression or a base given in the form `BASE#N' may contain +underscores (`_') after the leading digit for visual guidance; these +are ignored in computation. Examples are 1_000_000 or 0xffff_ffff +which are equivalent to 1000000 and 0xffffffff respectively. + +It is also possible to specify a base to be used for output in the form +`[#BASE]', for example `[#16]'. This is used when outputting +arithmetical substitutions or when assigning to scalar parameters, but +an explicitly defined integer or floating point parameter will not be +affected. If an integer variable is implicitly defined by an +arithmetic expression, any base specified in this way will be set as the +variable's output arithmetic base as if the option `-i BASE' to the +typeset builtin had been used. The expression has no precedence and if +it occurs more than once in a mathematical expression, the last +encountered is used. For clarity it is recommended that it appear at +the beginning of an expression. As an example: + + + typeset -i 16 y + print $(( [#8] x = 32, y = 32 )) + print $x $y + +outputs first `8#40', the rightmost value in the given output base, and +then `8#40 16#20', because y has been explicitly declared to have +output base 16, while x (assuming it does not already exist) is +implicitly typed by the arithmetic evaluation, where it acquires the +output base 8. + +The BASE may be replaced or followed by an underscore, which may itself +be followed by a positive integer (if it is missing the value 3 is +used). This indicates that underscores should be inserted into the +output string, grouping the number for visual clarity. The following +integer specifies the number of digits to group together. For example: + + + setopt cbases + print $(( [#16_4] 65536 ** 2 )) + +outputs `0x1_0000_0000'. + +The feature can be used with floating point numbers, in which case the +base must be omitted; grouping is away from the decimal point. For +example, + + + zmodload zsh/mathfunc + print $(( [#_] sqrt(1e7) )) + +outputs `3_162.277_660_168_379_5' (the number of decimal places shown +may vary). + +If the C_BASES option is set, hexadecimal numbers are output in the +standard C format, for example `0xFF' instead of the usual `16#FF'. If +the option OCTAL_ZEROES is also set (it is not by default), octal +numbers will be treated similarly and hence appear as `077' instead of +`8#77'. This option has no effect on the output of bases other than +hexadecimal and octal, and these formats are always understood on input. + +When an output base is specified using the `[#BASE]' syntax, an +appropriate base prefix will be output if necessary, so that the value +output is valid syntax for input. If the # is doubled, for example +`[##16]', then no base prefix is output. + +Floating point constants are recognized by the presence of a decimal +point or an exponent. The decimal point may be the first character of +the constant, but the exponent character e or E may not, as it will be +taken for a parameter name. All numeric parts (before and after the +decimal point and in the exponent) may contain underscores after the +leading digit for visual guidance; these are ignored in computation. + +An arithmetic expression uses nearly the same syntax and associativity +of expressions as in C. + +In the native mode of operation, the following operators are supported +(listed in decreasing order of precedence): + + ++ - ! ~ ++ - + unary plus/minus, logical NOT, complement, {pre,post}{in,de}crement + +<< >> + bitwise shift left, right + +& + bitwise AND + +^ + bitwise XOR + +| + bitwise OR + +** + exponentiation + +* / % + multiplication, division, modulus (remainder) + ++ - + addition, subtraction + +< > <= >= + comparison + +== != + equality and inequality + +&& + logical AND + +|| ^^ + logical OR, XOR + +? : + ternary operator + += += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **= + assignment + +, + comma operator + +The operators `&&', `||', `&&=', and `||=' are short-circuiting, and +only one of the latter two expressions in a ternary operator is +evaluated. Note the precedence of the bitwise AND, OR, and XOR +operators. + +With the option C_PRECEDENCES the precedences (but no other properties) +of the operators are altered to be the same as those in most other +languages that support the relevant operators: + + ++ - ! ~ ++ - + unary plus/minus, logical NOT, complement, {pre,post}{in,de}crement + +** + exponentiation + +* / % + multiplication, division, modulus (remainder) + ++ - + addition, subtraction + +<< >> + bitwise shift left, right + +< > <= >= + comparison + +== != + equality and inequality + +& + bitwise AND + +^ + bitwise XOR + +| + bitwise OR + +&& + logical AND + +^^ + logical XOR + +|| + logical OR + +? : + ternary operator + += += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **= + assignment + +, + comma operator + +Note the precedence of exponentiation in both cases is below that of +unary operators, hence `-3**2' evaluates as `9', not `-9'. Use +parentheses where necessary: `-(3**2)'. This is for compatibility with +other shells. + +Mathematical functions can be called with the syntax `FUNC(ARGS)', +where the function decides if the ARGS is used as a string or a +comma-separated list of arithmetic expressions. The shell currently +defines no mathematical functions by default, but the module +zsh/mathfunc may be loaded with the zmodload builtin to provide +standard floating point mathematical functions. + +An expression of the form `##X' where X is any character sequence such +as `a', `^A', or `\M-\C-x' gives the value of this character and an +expression of the form `#NAME' gives the value of the first character +of the contents of the parameter NAME. Character values are according +to the character set used in the current locale; for multibyte +character handling the option MULTIBYTE must be set. Note that this +form is different from `$#NAME', a standard parameter substitution +which gives the length of the parameter NAME. `#\' is accepted instead +of `##', but its use is deprecated. + +Named parameters and subscripted arrays can be referenced by name +within an arithmetic expression without using the parameter expansion +syntax. For example, + + + ((val2 = val1 * 2)) + +assigns twice the value of $val1 to the parameter named val2. + +An internal integer representation of a named parameter can be +specified with the integer builtin. Arithmetic evaluation is performed +on the value of each assignment to a named parameter declared integer +in this manner. Assigning a floating point number to an integer +results in rounding towards zero. + +Likewise, floating point numbers can be declared with the float +builtin; there are two types, differing only in their output format, as +described for the typeset builtin. The output format can be bypassed +by using arithmetic substitution instead of the parameter substitution, +i.e. `${FLOAT}' uses the defined format, but `$((FLOAT))' uses a +generic floating point format. + +Promotion of integer to floating point values is performed where +necessary. In addition, if any operator which requires an integer +(`&', `|', `^', `<<', `>>' and their equivalents with assignment) is +given a floating point argument, it will be silently rounded towards +zero except for `~' which rounds down. + +Users should beware that, in common with many other programming +languages but not software designed for calculation, the evaluation of +an expression in zsh is taken a term at a time and promotion of integers +to floating point does not occur in terms only containing integers. A +typical result of this is that a division such as 6/8 is truncated, in +this being rounded towards 0. The FORCE_FLOAT shell option can be used +in scripts or functions where floating point evaluation is required +throughout. + +Scalar variables can hold integer or floating point values at different +times; there is no memory of the numeric type in this case. + +If a variable is first assigned in a numeric context without previously +being declared, it will be implicitly typed as integer or float and +retain that type either until the type is explicitly changed or until +the end of the scope. This can have unforeseen consequences. For +example, in the loop + + + for (( f = 0; f < 1; f += 0.1 )); do + # use $f + done + +if f has not already been declared, the first assignment will cause it +to be created as an integer, and consequently the operation `f += 0.1' +will always cause the result to be truncated to zero, so that the loop +will fail. A simple fix would be to turn the initialization into `f = +0.0'. It is therefore best to declare numeric variables with explicit +types. + + +File: zsh.info, Node: Conditional Expressions, Next: Prompt Expansion, Prev: Arithmetic Evaluation, Up: Top + +12 Conditional Expressions +************************** + +A _conditional expression_ is used with the [[ compound command to test +attributes of files and to compare strings. Each expression can be +constructed from one or more of the following unary or binary +expressions: + + +-a FILE + true if FILE exists. + +-b FILE + true if FILE exists and is a block special file. + +-c FILE + true if FILE exists and is a character special file. + +-d FILE + true if FILE exists and is a directory. + +-e FILE + true if FILE exists. + +-f FILE + true if FILE exists and is a regular file. + +-g FILE + true if FILE exists and has its setgid bit set. + +-h FILE + true if FILE exists and is a symbolic link. + +-k FILE + true if FILE exists and has its sticky bit set. + +-n STRING + true if length of STRING is non-zero. + +-o OPTION + true if option named OPTION is on. OPTION may be a single + character, in which case it is a single letter option name. (See + *Note Specifying Options::.) + + When no option named OPTION exists, and the POSIX_BUILTINS option + hasn't been set, return 3 with a warning. If that option is set, + return 1 with no warning. + +-p FILE + true if FILE exists and is a FIFO special file (named pipe). + +-r FILE + true if FILE exists and is readable by current process. + +-s FILE + true if FILE exists and has size greater than zero. + +-t FD + true if file descriptor number FD is open and associated with a + terminal device. (note: FD is not optional) + +-u FILE + true if FILE exists and has its setuid bit set. + +-v VARNAME + true if shell variable VARNAME is set. + +-w FILE + true if FILE exists and is writable by current process. + +-x FILE + true if FILE exists and is executable by current process. If FILE + exists and is a directory, then the current process has permission + to search in the directory. + +-z STRING + true if length of STRING is zero. + +-L FILE + true if FILE exists and is a symbolic link. + +-O FILE + true if FILE exists and is owned by the effective user ID of this + process. + +-G FILE + true if FILE exists and its group matches the effective group ID + of this process. + +-S FILE + true if FILE exists and is a socket. + +-N FILE + true if FILE exists and its access time is not newer than its + modification time. + +FILE1 -nt FILE2 + true if FILE1 exists and is newer than FILE2. + +FILE1 -ot FILE2 + true if FILE1 exists and is older than FILE2. + +FILE1 -ef FILE2 + true if FILE1 and FILE2 exist and refer to the same file. + +STRING = PATTERN +STRING == PATTERN + true if STRING matches PATTERN. The two forms are exactly + equivalent. The `=' form is the traditional shell syntax (and + hence the only one generally used with the test and [ builtins); + the `==' form provides compatibility with other sorts of computer + language. + +STRING != PATTERN + true if STRING does not match PATTERN. + +STRING =~ REGEXP + true if STRING matches the regular expression REGEXP. If the + option RE_MATCH_PCRE is set REGEXP is tested as a PCRE regular + expression using the zsh/pcre module, else it is tested as a POSIX + extended regular expression using the zsh/regex module. Upon + successful match, some variables will be updated; no variables are + changed if the matching fails. + + If the option BASH_REMATCH is not set the scalar parameter MATCH + is set to the substring that matched the pattern and the integer + parameters MBEGIN and MEND to the index of the start and end, + respectively, of the match in STRING, such that if STRING is + contained in variable var the expression `${var[$MBEGIN,$MEND]}' + is identical to `$MATCH'. The setting of the option KSH_ARRAYS is + respected. Likewise, the array match is set to the substrings + that matched parenthesised subexpressions and the arrays mbegin + and mend to the indices of the start and end positions, + respectively, of the substrings within STRING. The arrays are not + set if there were no parenthesised subexpressions. For example, + if the string `a short string' is matched against the regular + expression `s(...)t', then (assuming the option KSH_ARRAYS is not + set) MATCH, MBEGIN and MEND are `short', 3 and 7, respectively, + while match, mbegin and mend are single entry arrays containing + the strings `hor', `4' and `6', respectively. + + If the option BASH_REMATCH is set the array BASH_REMATCH is set to + the substring that matched the pattern followed by the substrings + that matched parenthesised subexpressions within the pattern. + +STRING1 < STRING2 + true if STRING1 comes before STRING2 based on ASCII value of their + characters. + +STRING1 > STRING2 + true if STRING1 comes after STRING2 based on ASCII value of their + characters. + +EXP1 -eq EXP2 + true if EXP1 is numerically equal to EXP2. Note that for purely + numeric comparisons use of the ((...)) builtin described in *Note + Arithmetic Evaluation:: is more convenient than conditional + expressions. + +EXP1 -ne EXP2 + true if EXP1 is numerically not equal to EXP2. + +EXP1 -lt EXP2 + true if EXP1 is numerically less than EXP2. + +EXP1 -gt EXP2 + true if EXP1 is numerically greater than EXP2. + +EXP1 -le EXP2 + true if EXP1 is numerically less than or equal to EXP2. + +EXP1 -ge EXP2 + true if EXP1 is numerically greater than or equal to EXP2. + +( EXP ) + true if EXP is true. + +! EXP + true if EXP is false. + +EXP1 && EXP2 + true if EXP1 and EXP2 are both true. + +EXP1 || EXP2 + true if either EXP1 or EXP2 is true. + + +For compatibility, if there is a single argument that is not +syntactically significant, typically a variable, the condition is +treated as a test for whether the expression expands as a string of +non-zero length. In other words, [[ $var ]] is the same as [[ -n $var +]]. It is recommended that the second, explicit, form be used where +possible. + +Normal shell expansion is performed on the FILE, STRING and PATTERN +arguments, but the result of each expansion is constrained to be a +single word, similar to the effect of double quotes. + +Filename generation is not performed on any form of argument to +conditions. However, it can be forced in any case where normal shell +expansion is valid and when the option EXTENDED_GLOB is in effect by +using an explicit glob qualifier of the form (#q) at the end of the +string. A normal glob qualifier expression may appear between the `q' +and the closing parenthesis; if none appears the expression has no +effect beyond causing filename generation. The results of filename +generation are joined together to form a single word, as with the +results of other forms of expansion. + +This special use of filename generation is only available with the [[ +syntax. If the condition occurs within the [ or test builtin commands +then globbing occurs instead as part of normal command line expansion +before the condition is evaluated. In this case it may generate +multiple words which are likely to confuse the syntax of the test +command. + +For example, + + + [[ -n file*(#qN) ]] + +produces status zero if and only if there is at least one file in the +current directory beginning with the string `file'. The globbing +qualifier N ensures that the expression is empty if there is no +matching file. + +Pattern metacharacters are active for the PATTERN arguments; the +patterns are the same as those used for filename generation, see *Note +Filename Generation::, but there is no special behaviour of `/' nor +initial dots, and no glob qualifiers are allowed. + +In each of the above expressions, if FILE is of the form `/dev/fd/N', +where N is an integer, then the test applied to the open file whose +descriptor number is N, even if the underlying system does not support +the /dev/fd directory. + +In the forms which do numeric comparison, the expressions EXP undergo +arithmetic expansion as if they were enclosed in $((...)). + +For example, the following: + + + [[ ( -f foo || -f bar ) && $report = y* ]] && print File exists. + +tests if either file foo or file bar exists, and if so, if the value of +the parameter report begins with `y'; if the complete condition is +true, the message `File exists.' is printed. + + +File: zsh.info, Node: Prompt Expansion, Next: Expansion, Prev: Conditional Expressions, Up: Top + +13 Prompt Expansion +******************* + + + +13.1 Expansion of Prompt Sequences +================================== + +Prompt sequences undergo a special form of expansion. This type of +expansion is also available using the -P option to the print builtin. + +If the PROMPT_SUBST option is set, the prompt string is first subjected +to _parameter expansion_, _command substitution_ and _arithmetic +expansion_. See *Note Expansion::. + +Certain escape sequences may be recognised in the prompt string. + +If the PROMPT_BANG option is set, a `!' in the prompt is replaced by +the current history event number. A literal `!' may then be +represented as `!!'. + +If the PROMPT_PERCENT option is set, certain escape sequences that +start with `%' are expanded. Many escapes are followed by a single +character, although some of these take an optional integer argument that +should appear between the `%' and the next character of the sequence. +More complicated escape sequences are available to provide conditional +expansion. + + + +13.2 Simple Prompt Escapes +========================== + + + +13.2.1 Special characters +------------------------- + + +%% + A `%'. + +%) + A `)'. + + + +13.2.2 Login information +------------------------ + + +%l + The line (tty) the user is logged in on, without `/dev/' prefix. + If the name starts with `/dev/tty', that prefix is stripped. + +%M + The full machine hostname. + +%m + The hostname up to the first `.'. An integer may follow the `%' + to specify how many components of the hostname are desired. With + a negative integer, trailing components of the hostname are shown. + +%n + $USERNAME. + +%y + The line (tty) the user is logged in on, without `/dev/' prefix. + This does not treat `/dev/tty' names specially. + + + +13.2.3 Shell state +------------------ + + +%# + A `#' if the shell is running with privileges, a `%' if not. + Equivalent to `%(!.#.%%)'. The definition of `privileged', for + these purposes, is that either the effective user ID is zero, or, + if POSIX.1e capabilities are supported, that at least one + capability is raised in either the Effective or Inheritable + capability vectors. + +%? + The return status of the last command executed just before the + prompt. + +%_ + The status of the parser, i.e. the shell constructs (like `if' and + `for') that have been started on the command line. If given an + integer number that many strings will be printed; zero or negative + or no integer means print as many as there are. This is most + useful in prompts PS2 for continuation lines and PS4 for debugging + with the XTRACE option; in the latter case it will also work + non-interactively. + +%^ + The status of the parser in reverse. This is the same as `%_' + other than the order of strings. It is often used in RPS2. + +%d +%/ + Current working directory. If an integer follows the `%', it + specifies a number of trailing components of the current working + directory to show; zero means the whole path. A negative integer + specifies leading components, i.e. %-1d specifies the first + component. + +%~ + As %d and %/, but if the current working directory starts with + $HOME, that part is replaced by a `~'. Furthermore, if it has a + named directory as its prefix, that part is replaced by a `~' + followed by the name of the directory, but only if the result is + shorter than the full path; *Note Filename Expansion::. + +%e + Evaluation depth of the current sourced file, shell function, or + eval. This is incremented or decremented every time the value of + %N is set or reverted to a previous value, respectively. This is + most useful for debugging as part of $PS4. + +%h +%! + Current history event number. + +%i + The line number currently being executed in the script, sourced + file, or shell function given by %N. This is most useful for + debugging as part of $PS4. + +%I + The line number currently being executed in the file %x. This is + similar to %i, but the line number is always a line number in the + file where the code was defined, even if the code is a shell + function. + +%j + The number of jobs. + +%L + The current value of $SHLVL. + +%N + The name of the script, sourced file, or shell function that zsh is + currently executing, whichever was started most recently. If + there is none, this is equivalent to the parameter $0. An integer + may follow the `%' to specify a number of trailing path components + to show; zero means the full path. A negative integer specifies + leading components. + +%x + The name of the file containing the source code currently being + executed. This behaves as %N except that function and eval command + names are not shown, instead the file where they were defined. + +%c +%. +%C + Trailing component of the current working directory. An integer + may follow the `%' to get more than one component. Unless `%C' is + used, tilde contraction is performed first. These are deprecated + as %c and %C are equivalent to %1~ and %1/, respectively, while + explicit positive integers have the same effect as for the latter + two sequences. + + + +13.2.4 Date and time +-------------------- + + +%D + The date in YY-MM-DD format. + +%T + Current time of day, in 24-hour format. + +%t +%@ + Current time of day, in 12-hour, am/pm format. + +%* + Current time of day in 24-hour format, with seconds. + +%w + The date in DAY-DD format. + +%W + The date in MM/DD/YY format. + +%D{STRING} + STRING is formatted using the strftime function. See man page + strftime(3) for more details. Various zsh extensions provide + numbers with no leading zero or space if the number is a single + digit: + + + %f + a day of the month + + %K + the hour of the day on the 24-hour clock + + %L + the hour of the day on the 12-hour clock + + In addition, if the system supports the POSIX gettimeofday system + call, %. provides decimal fractions of a second since the epoch + with leading zeroes. By default three decimal places are + provided, but a number of digits up to 9 may be given following + the %; hence %6. outputs microseconds, and %9. outputs + nanoseconds. (The latter requires a nanosecond-precision + clock_gettime; systems lacking this will return a value multiplied + by the appropriate power of 10.) A typical example of this is the + format `%D{%H:%M:%S.%.}'. + + The GNU extension %N is handled as a synonym for %9.. + + Additionally, the GNU extension that a `-' between the % and the + format character causes a leading zero or space to be stripped is + handled directly by the shell for the format characters d, f, H, + k, l, m, M, S and y; any other format characters are provided to + the system's strftime(3) with any leading `-' present, so the + handling is system dependent. Further GNU (or other) extensions + are also passed to strftime(3) and may work if the system supports + them. + + + +13.2.5 Visual effects +--------------------- + + +%B (%b) + Start (stop) boldface mode. + +%E + Clear to end of line. + +%U (%u) + Start (stop) underline mode. + +%S (%s) + Start (stop) standout mode. + +%F (%f) + Start (stop) using a different foreground colour, if supported by + the terminal. The colour may be specified two ways: either as a + numeric argument, as normal, or by a sequence in braces following + the %F, for example %F{red}. In the latter case the values + allowed are as described for the fg zle_highlight attribute; *Note + Character Highlighting::. This means that numeric colours are + allowed in the second format also. + +%K (%k) + Start (stop) using a different bacKground colour. The syntax is + identical to that for %F and %f. + +%{...%} + Include a string as a literal escape sequence. The string within + the braces should not change the cursor position. Brace pairs can + nest. + + A positive numeric argument between the % and the { is treated as + described for %G below. + +%G + Within a %{...%} sequence, include a `glitch': that is, assume + that a single character width will be output. This is useful when + outputting characters that otherwise cannot be correctly handled + by the shell, such as the alternate character set on some + terminals. The characters in question can be included within a + %{...%} sequence together with the appropriate number of %G + sequences to indicate the correct width. An integer between the + `%' and `G' indicates a character width other than one. Hence + %{SEQ%2G%} outputs SEQ and assumes it takes up the width of two + standard characters. + + Multiple uses of %G accumulate in the obvious fashion; the position + of the %G is unimportant. Negative integers are not handled. + + Note that when prompt truncation is in use it is advisable to + divide up output into single characters within each %{...%} group + so that the correct truncation point can be found. + + + +13.3 Conditional Substrings in Prompts +====================================== + + +%v + The value of the first element of the psvar array parameter. + Following the `%' with an integer gives that element of the array. + Negative integers count from the end of the array. + +%(X.TRUE-TEXT.FALSE-TEXT) + Specifies a ternary expression. The character following the X is + arbitrary; the same character is used to separate the text for the + `true' result from that for the `false' result. This separator + may not appear in the TRUE-TEXT, except as part of a %-escape + sequence. A `)' may appear in the FALSE-TEXT as `%)'. TRUE-TEXT + and FALSE-TEXT may both contain arbitrarily-nested escape + sequences, including further ternary expressions. + + The left parenthesis may be preceded or followed by a positive + integer N, which defaults to zero. A negative integer will be + multiplied by -1, except as noted below for `l'. The test + character X may be any of the following: + + + ! + True if the shell is running with privileges. + + # + True if the effective uid of the current process is N. + + ? + True if the exit status of the last command was N. + + _ + True if at least N shell constructs were started. + + C + / + True if the current absolute path has at least N elements + relative to the root directory, hence / is counted as 0 + elements. + + c + . + ~ + True if the current path, with prefix replacement, has at + least N elements relative to the root directory, hence / is + counted as 0 elements. + + D + True if the month is equal to N (January = 0). + + d + True if the day of the month is equal to N. + + e + True if the evaluation depth is at least N. + + g + True if the effective gid of the current process is N. + + j + True if the number of jobs is at least N. + + L + True if the SHLVL parameter is at least N. + + l + True if at least N characters have already been printed on + the current line. When N is negative, true if at least + abs(N) characters remain before the opposite margin (thus the + left margin for RPROMPT). + + S + True if the SECONDS parameter is at least N. + + T + True if the time in hours is equal to N. + + t + True if the time in minutes is equal to N. + + v + True if the array psvar has at least N elements. + + V + True if element N of the array psvar is set and non-empty. + + w + True if the day of the week is equal to N (Sunday = 0). + +%<STRING< +%>STRING> +%[XSTRING] + Specifies truncation behaviour for the remainder of the prompt + string. The third, deprecated, form is equivalent to `%XSTRINGX', + i.e. X may be `<' or `>'. The STRING will be displayed in place + of the truncated portion of any string; note this does not undergo + prompt expansion. + + The numeric argument, which in the third form may appear + immediately after the `[', specifies the maximum permitted length + of the various strings that can be displayed in the prompt. In + the first two forms, this numeric argument may be negative, in + which case the truncation length is determined by subtracting the + absolute value of the numeric argument from the number of + character positions remaining on the current prompt line. If this + results in a zero or negative length, a length of 1 is used. In + other words, a negative argument arranges that after truncation at + least N characters remain before the right margin (left margin for + RPROMPT). + + The forms with `<' truncate at the left of the string, and the + forms with `>' truncate at the right of the string. For example, + if the current directory is `/home/pike', the prompt `%8<..<%/' + will expand to `..e/pike'. In this string, the terminating + character (`<', `>' or `]'), or in fact any character, may be + quoted by a preceding `\'; note when using print -P, however, that + this must be doubled as the string is also subject to standard + print processing, in addition to any backslashes removed by a + double quoted string: the worst case is therefore `print -P + "%<\\\\<<..."'. + + If the STRING is longer than the specified truncation length, it + will appear in full, completely replacing the truncated string. + + The part of the prompt string to be truncated runs to the end of + the string, or to the end of the next enclosing group of the `%(' + construct, or to the next truncation encountered at the same + grouping level (i.e. truncations inside a `%(' are separate), which + ever comes first. In particular, a truncation with argument zero + (e.g., `%<<') marks the end of the range of the string to be + truncated while turning off truncation from there on. For example, + the prompt `%10<...<%~%<<%# ' will print a truncated + representation of the current directory, followed by a `%' or `#', + followed by a space. Without the `%<<', those two characters + would be included in the string to be truncated. Note that + `%-0<<' is not equivalent to `%<<' but specifies that the prompt + is truncated at the right margin. + + Truncation applies only within each individual line of the prompt, + as delimited by embedded newlines (if any). If the total length + of any line of the prompt after truncation is greater than the + terminal width, or if the part to be truncated contains embedded + newlines, truncation behavior is undefined and may change in a + future version of the shell. Use `%-N(l.TRUE-TEXT.FALSE-TEXT)' to + remove parts of the prompt when the available space is less than N. + + + +File: zsh.info, Node: Expansion, Next: Parameters, Prev: Prompt Expansion, Up: Top + +14 Expansion +************ + +The following types of expansions are performed in the indicated order +in five steps: + + +_History Expansion_ + This is performed only in interactive shells. + +_Alias Expansion_ + Aliases are expanded immediately before the command line is parsed + as explained in *Note Aliasing::. + +_Process Substitution_ +_Parameter Expansion_ +_Command Substitution_ +_Arithmetic Expansion_ +_Brace Expansion_ + These five are performed in left-to-right fashion. On each + argument, any of the five steps that are needed are performed one + after the other. Hence, for example, all the parts of parameter + expansion are completed before command substitution is started. + After these expansions, all unquoted occurrences of the characters + `\',`'' and `"' are removed. + +_Filename Expansion_ + If the SH_FILE_EXPANSION option is set, the order of expansion is + modified for compatibility with `sh' and `ksh'. In that case + _filename expansion_ is performed immediately after _alias + expansion_, preceding the set of five expansions mentioned above. + +_Filename Generation_ + This expansion, commonly referred to as `globbing', is always done + last. + + +The following sections explain the types of expansion in detail. + + + +* Menu: + +* History Expansion:: +* Process Substitution:: +* Parameter Expansion:: +* Command Substitution:: +* Arithmetic Expansion:: +* Brace Expansion:: +* Filename Expansion:: +* Filename Generation:: + + +File: zsh.info, Node: History Expansion, Next: Process Substitution, Up: Expansion + +14.1 History Expansion +====================== + +History expansion allows you to use words from previous command lines +in the command line you are typing. This simplifies spelling +corrections and the repetition of complicated commands or arguments. + +Immediately before execution, each command is saved in the history list, +the size of which is controlled by the HISTSIZE parameter. The one +most recent command is always retained in any case. Each saved command +in the history list is called a history _event_ and is assigned a +number, beginning with 1 (one) when the shell starts up. The history +number that you may see in your prompt (see *Note Prompt Expansion::) +is the number that is to be assigned to the _next_ command. + + + +* Menu: + +* Overview:: +* Event Designators:: +* Word Designators:: +* Modifiers:: + + +File: zsh.info, Node: Overview, Next: Event Designators, Up: History Expansion + +14.1.1 Overview +--------------- + +A history expansion begins with the first character of the histchars +parameter, which is `!' by default, and may occur anywhere on the +command line, including inside double quotes (but not inside single +quotes '...' or C-style quotes $'...' nor when escaped with a +backslash). + +The first character is followed by an optional event designator (*Note +Event Designators::) and then an optional word designator (*Note Word +Designators::); if neither of these designators is present, no history +expansion occurs. + +Input lines containing history expansions are echoed after being +expanded, but before any other expansions take place and before the +command is executed. It is this expanded form that is recorded as the +history event for later references. + +History expansions do not nest. + +By default, a history reference with no event designator refers to the +same event as any preceding history reference on that command line; if +it is the only history reference in a command, it refers to the previous +command. However, if the option CSH_JUNKIE_HISTORY is set, then every +history reference with no event specification _always_ refers to the +previous command. + +For example, `!' is the event designator for the previous command, so +`!!:1' always refers to the first word of the previous command, and +`!!$' always refers to the last word of the previous command. With +CSH_JUNKIE_HISTORY set, then `!:1' and `!$' function in the same manner +as `!!:1' and `!!$', respectively. Conversely, if CSH_JUNKIE_HISTORY +is unset, then `!:1' and `!$' refer to the first and last words, +respectively, of the same event referenced by the nearest other history +reference preceding them on the current command line, or to the +previous command if there is no preceding reference. + +The character sequence `^FOO^BAR' (where `^' is actually the second +character of the histchars parameter) repeats the last command, +replacing the string FOO with BAR. More precisely, the sequence +`^FOO^BAR^' is synonymous with `!!:s^FOO^BAR^', hence other modifiers +(see *Note Modifiers::) may follow the final `^'. In particular, +`^FOO^BAR^:G' performs a global substitution. + +If the shell encounters the character sequence `!"' in the input, the +history mechanism is temporarily disabled until the current list (see +*Note Shell Grammar::) is fully parsed. The `!"' is removed from the +input, and any subsequent `!' characters have no special significance. + +A less convenient but more comprehensible form of command history +support is provided by the fc builtin. + + +File: zsh.info, Node: Event Designators, Next: Word Designators, Prev: Overview, Up: History Expansion + +14.1.2 Event Designators +------------------------ + +An event designator is a reference to a command-line entry in the +history list. In the list below, remember that the initial `!' in each +item may be changed to another character by setting the histchars +parameter. + + +! + Start a history expansion, except when followed by a blank, + newline, `=' or `('. If followed immediately by a word designator + (*Note Word Designators::), this forms a history reference with no + event designator (*Note Overview::). + +!! + Refer to the previous command. By itself, this expansion repeats + the previous command. + +!N + Refer to command-line N. + +!-N + Refer to the current command-line minus N. + +!STR + Refer to the most recent command starting with STR. + +!?STR[?] + Refer to the most recent command containing STR. The trailing `?' + is necessary if this reference is to be followed by a modifier or + followed by any text that is not to be considered part of STR. + +!# + Refer to the current command line typed in so far. The line is + treated as if it were complete up to and including the word before + the one with the `!#' reference. + +!{...} + Insulate a history reference from adjacent characters (if + necessary). + + + +File: zsh.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Expansion + +14.1.3 Word Designators +----------------------- + +A word designator indicates which word or words of a given command line +are to be included in a history reference. A `:' usually separates the +event specification from the word designator. It may be omitted only +if the word designator begins with a `^', `$', `*', `-' or `%'. Word +designators include: + + +0 + The first input word (command). + +N + The Nth argument. + +^ + The first argument. That is, 1. + +$ + The last argument. + +% + The word matched by (the most recent) ?STR search. + +X-Y + A range of words; X defaults to 0. + +* + All the arguments, or a null value if there are none. + +X* + Abbreviates `X-$'. + +X- + Like `X*' but omitting word $. + +Note that a `%' word designator works only when used in one of `!%', +`!:%' or `!?STR?:%', and only when used after a !? expansion (possibly +in an earlier command). Anything else results in an error, although +the error may not be the most obvious one. + + +File: zsh.info, Node: Modifiers, Prev: Word Designators, Up: History Expansion + +14.1.4 Modifiers +---------------- + +After the optional word designator, you can add a sequence of one or +more of the following modifiers, each preceded by a `:'. These +modifiers also work on the result of _filename generation_ and +_parameter expansion_, except where noted. + + +a + Turn a file name into an absolute path: prepends the current + directory, if necessary; remove `.' path segments; and remove `..' + path segments and the segments that immediately precede them. + + This transformation is agnostic about what is in the filesystem, + i.e. is on the logical, not the physical directory. It takes + place in the same manner as when changing directories when neither + of the options CHASE_DOTS or CHASE_LINKS is set. For example, + `/before/here/../after' is always transformed to `/before/after', + regardless of whether `/before/here' exists or what kind of object + (dir, file, symlink, etc.) it is. + +A + Turn a file name into an absolute path as the `a' modifier does, + and _then_ pass the result through the realpath(3) library + function to resolve symbolic links. + + Note: on systems that do not have a realpath(3) library function, + symbolic links are not resolved, so on those systems `a' and `A' + are equivalent. + + Note: foo:A and realpath(foo) are different on some inputs. For + realpath(foo) semantics, see the `P` modifier. + +c + Resolve a command name into an absolute path by searching the + command path given by the PATH variable. This does not work for + commands containing directory parts. Note also that this does not + usually work as a glob qualifier unless a file of the same name is + found in the current directory. + +e + Remove all but the part of the filename extension following the + `.'; see the definition of the filename extension in the + description of the r modifier below. Note that according to that + definition the result will be empty if the string ends with a `.'. + +h [ DIGITS ] + Remove a trailing pathname component, shortening the path by one + directory level: this is the `head' of the pathname. This works + like `dirname'. If the h is followed immediately (with no spaces + or other separator) by any number of decimal digits, and the value + of the resulting number is non-zero, that number of leading + components is preserved instead of the final component being + removed. In an absolute path the leading `/' is the first + component, so, for example, if var=/my/path/to/something, then + ${var:h3} substitutes /my/path. Consecutive `/'s are treated the + same as a single `/'. In parameter substitution, digits may only + be used if the expression is in braces, so for example the short + form substitution $var:h2 is treated as ${var:h}2, not as + ${var:h2}. No restriction applies to the use of digits in history + substitution or globbing qualifiers. If more components are + requested than are present, the entire path is substituted (so + this does not trigger a `failed modifier' error in history + expansion). + +l + Convert the words to all lowercase. + +p + Print the new command but do not execute it. Only works with + history expansion. + +P + Turn a file name into an absolute path, like realpath(3). The + resulting path will be absolute, have neither `.' nor `..' + components, and refer to the same directory entry as the input + filename. + + Unlike realpath(3), non-existent trailing components are permitted + and preserved. + +q + Quote the substituted words, escaping further substitutions. Works + with history expansion and parameter expansion, though for + parameters it is only useful if the resulting text is to be + re-evaluated such as by eval. + +Q + Remove one level of quotes from the substituted words. + +r + Remove a filename extension leaving the root name. Strings with no + filename extension are not altered. A filename extension is a `.' + followed by any number of characters (including zero) that are + neither `.' nor `/' and that continue to the end of the string. + For example, the extension of `foo.orig.c' is `.c', and + `dir.c/foo' has no extension. + +s/L/R[/] + Substitute R for L as described below. The substitution is done + only for the first string that matches L. For arrays and for + filename generation, this applies to each word of the expanded + text. See below for further notes on substitutions. + + The forms `gs/L/R' and `s/L/R/:G' perform global substitution, + i.e. substitute every occurrence of R for L. Note that the g or + :G must appear in exactly the position shown. + + See further notes on this form of substitution below. + +& + Repeat the previous s substitution. Like s, may be preceded + immediately by a g. In parameter expansion the & must appear + inside braces, and in filename generation it must be quoted with a + backslash. + +t [ DIGITS ] + Remove all leading pathname components, leaving the final + component (tail). This works like `basename'. Any trailing + slashes are first removed. Decimal digits are handled as + described above for (h), but in this case that number of trailing + components is preserved instead of the default 1; 0 is treated the + same as 1. + +u + Convert the words to all uppercase. + +x + Like q, but break into words at whitespace. Does not work with + parameter expansion. + + +The s/L/R/ substitution works as follows. By default the left-hand +side of substitutions are not patterns, but character strings. Any +character can be used as the delimiter in place of `/'. A backslash +quotes the delimiter character. The character `&', in the +right-hand-side R, is replaced by the text from the left-hand-side L. +The `&' can be quoted with a backslash. A null L uses the previous +string either from the previous L or from the contextual scan string S +from `!?S'. You can omit the rightmost delimiter if a newline +immediately follows R; the rightmost `?' in a context scan can +similarly be omitted. Note the same record of the last L and R is +maintained across all forms of expansion. + +Note that if a `&' is used within glob qualifiers an extra backslash is +needed as a & is a special character in this case. + +Also note that the order of expansions affects the interpretation of L +and R. When used in a history expansion, which occurs before any other +expansions, L and R are treated as literal strings (except as explained +for HIST_SUBST_PATTERN below). When used in parameter expansion, the +replacement of R into the parameter's value is done first, and then any +additional process, parameter, command, arithmetic, or brace references +are applied, which may evaluate those substitutions and expansions more +than once if L appears more than once in the starting value. When used +in a glob qualifier, any substitutions or expansions are performed once +at the time the qualifier is parsed, even before the `:s' expression +itself is divided into L and R sides. + +If the option HIST_SUBST_PATTERN is set, L is treated as a pattern of +the usual form described in *Note Filename Generation::. This can be +used in all the places where modifiers are available; note, however, +that in globbing qualifiers parameter substitution has already taken +place, so parameters in the replacement string should be quoted to +ensure they are replaced at the correct time. Note also that +complicated patterns used in globbing qualifiers may need the extended +glob qualifier notation (#q:s/.../.../) in order for the shell to +recognize the expression as a glob qualifier. Further, note that bad +patterns in the substitution are not subject to the NO_BAD_PATTERN +option so will cause an error. + +When HIST_SUBST_PATTERN is set, L may start with a # to indicate that +the pattern must match at the start of the string to be substituted, +and a % may appear at the start or after an # to indicate that the +pattern must match at the end of the string to be substituted. The % +or # may be quoted with two backslashes. + +For example, the following piece of filename generation code with the +EXTENDED_GLOB option: + + + print -r -- *.c(#q:s/#%(#b)s(*).c/'S${match[1]}.C'/) + +takes the expansion of *.c and applies the glob qualifiers in the +(#q...) expression, which consists of a substitution modifier anchored +to the start and end of each word (#%). This turns on backreferences +((#b)), so that the parenthesised subexpression is available in the +replacement string as ${match[1]}. The replacement string is quoted so +that the parameter is not substituted before the start of filename +generation. + +The following f, F, w and W modifiers work only with parameter +expansion and filename generation. They are listed here to provide a +single point of reference for all modifiers. + + +f + Repeats the immediately (without a colon) following modifier until + the resulting word doesn't change any more. + +F:EXPR: + Like f, but repeats only N times if the expression EXPR evaluates + to N. Any character can be used instead of the `:'; if `(', `[', + or `{' is used as the opening delimiter, the closing delimiter + should be ')', `]', or `}', respectively. + +w + Makes the immediately following modifier work on each word in the + string. + +W:SEP: + Like w but words are considered to be the parts of the string that + are separated by SEP. Any character can be used instead of the + `:'; opening parentheses are handled specially, see above. + + + +File: zsh.info, Node: Process Substitution, Next: Parameter Expansion, Prev: History Expansion, Up: Expansion + +14.2 Process Substitution +========================= + +Each part of a command argument that takes the form `<(LIST)', +`>(LIST)' or `=(LIST)' is subject to process substitution. The +expression may be preceded or followed by other strings except that, to +prevent clashes with commonly occurring strings and patterns, the last +form must occur at the start of a command argument, and the forms are +only expanded when first parsing command or assignment arguments. +Process substitutions may be used following redirection operators; in +this case, the substitution must appear with no trailing string. + +Note that `<<(LIST)' is not a special syntax; it is equivalent to `< +<(LIST)', redirecting standard input from the result of process +substitution. Hence all the following documentation applies. The +second form (with the space) is recommended for clarity. + +In the case of the < or > forms, the shell runs the commands in LIST as +a subprocess of the job executing the shell command line. If the +system supports the /dev/fd mechanism, the command argument is the name +of the device file corresponding to a file descriptor; otherwise, if +the system supports named pipes (FIFOs), the command argument will be a +named pipe. If the form with > is selected then writing on this +special file will provide input for LIST. If < is used, then the file +passed as an argument will be connected to the output of the LIST +process. For example, + + + paste <(cut -f1 FILE1) <(cut -f3 FILE2) | + tee >(PROCESS1) >(PROCESS2) >/dev/null + +cuts fields 1 and 3 from the files FILE1 and FILE2 respectively, pastes +the results together, and sends it to the processes PROCESS1 and +PROCESS2. + +If =(...) is used instead of <(...), then the file passed as an +argument will be the name of a temporary file containing the output of +the LIST process. This may be used instead of the < form for a program +that expects to lseek (see man page lseek(2)) on the input file. + +There is an optimisation for substitutions of the form =(<<<ARG), where +ARG is a single-word argument to the here-string redirection <<<. This +form produces a file name containing the value of ARG after any +substitutions have been performed. This is handled entirely within the +current shell. This is effectively the reverse of the special form +$(<ARG) which treats ARG as a file name and replaces it with the file's +contents. + +The = form is useful as both the /dev/fd and the named pipe +implementation of <(...) have drawbacks. In the former case, some +programmes may automatically close the file descriptor in question +before examining the file on the command line, particularly if this is +necessary for security reasons such as when the programme is running +setuid. In the second case, if the programme does not actually open +the file, the subshell attempting to read from or write to the pipe +will (in a typical implementation, different operating systems may have +different behaviour) block for ever and have to be killed explicitly. +In both cases, the shell actually supplies the information using a +pipe, so that programmes that expect to lseek (see man page lseek(2)) +on the file will not work. + +Also note that the previous example can be more compactly and +efficiently written (provided the MULTIOS option is set) as: + + + paste <(cut -f1 FILE1) <(cut -f3 FILE2) > >(PROCESS1) > >(PROCESS2) + +The shell uses pipes instead of FIFOs to implement the latter two +process substitutions in the above example. + +There is an additional problem with >(PROCESS); when this is attached +to an external command, the parent shell does not wait for PROCESS to +finish and hence an immediately following command cannot rely on the +results being complete. The problem and solution are the same as +described in the section _MULTIOS_ in *Note Redirection::. Hence in a +simplified version of the example above: + + + paste <(cut -f1 FILE1) <(cut -f3 FILE2) > >(PROCESS) + +(note that no MULTIOS are involved), PROCESS will be run asynchronously +as far as the parent shell is concerned. The workaround is: + + + { paste <(cut -f1 FILE1) <(cut -f3 FILE2) } > >(PROCESS) + +The extra processes here are spawned from the parent shell which will +wait for their completion. + +Another problem arises any time a job with a substitution that requires +a temporary file is disowned by the shell, including the case where +`&!' or `&|' appears at the end of a command containing a substitution. +In that case the temporary file will not be cleaned up as the shell no +longer has any memory of the job. A workaround is to use a subshell, +for example, + + + (mycmd =(myoutput)) &! + +as the forked subshell will wait for the command to finish then remove +the temporary file. + +A general workaround to ensure a process substitution endures for an +appropriate length of time is to pass it as a parameter to an anonymous +shell function (a piece of shell code that is run immediately with +function scope). For example, this code: + + + () { + print File $1: + cat $1 + } =(print This be the verse) + +outputs something resembling the following + + + File /tmp/zsh6nU0kS: + This be the verse + +The temporary file created by the process substitution will be deleted +when the function exits. + + + + +File: zsh.info, Node: Parameter Expansion, Next: Command Substitution, Prev: Process Substitution, Up: Expansion + +14.3 Parameter Expansion +======================== + +The character `$' is used to introduce parameter expansions. See *Note +Parameters:: for a description of parameters, including arrays, +associative arrays, and subscript notation to access individual array +elements. + +Note in particular the fact that words of unquoted parameters are not +automatically split on whitespace unless the option SH_WORD_SPLIT is +set; see references to this option below for more details. This is an +important difference from other shells. However, as in other shells, +null words are elided from unquoted parameters' expansions. + +With default options, after the assignments: + + + array=("first word" "" "third word") + scalar="only word" + +then $array substitutes two words, `first word' and `third word', and +$scalar substitutes a single word `only word'. Note that second +element of array was elided. Scalar parameters can be elided too if +their value is null (empty). To avoid elision, use quoting as follows: +"$scalar" for scalars and "${array[@]}" or "${(@)array}" for arrays. +(The last two forms are equivalent.) + +Parameter expansions can involve _flags_, as in `${(@kv)aliases}', and +other operators, such as `${PREFIX:-"/usr/local"}'. Parameter +expansions can also be nested. These topics will be introduced below. +The full rules are complicated and are noted at the end. + +In the expansions discussed below that require a pattern, the form of +the pattern is the same as that used for filename generation; see *Note +Filename Generation::. Note that these patterns, along with the +replacement text of any substitutions, are themselves subject to +parameter expansion, command substitution, and arithmetic expansion. +In addition to the following operations, the colon modifiers described +in *Note Modifiers:: in *Note History Expansion:: can be applied: for +example, ${i:s/foo/bar/} performs string substitution on the expansion +of parameter $i. + +In the following descriptions, `WORD' refers to a single word +substituted on the command line, not necessarily a space delimited word. + + +${NAME} + The value, if any, of the parameter NAME is substituted. The + braces are required if the expansion is to be followed by a + letter, digit, or underscore that is not to be interpreted as part + of NAME. In addition, more complicated forms of substitution + usually require the braces to be present; exceptions, which only + apply if the option KSH_ARRAYS is not set, are a single subscript + or any colon modifiers appearing after the name, or any of the + characters `^', `=', `~', `#' or `+' appearing before the name, + all of which work with or without braces. + + If NAME is an array parameter, and the KSH_ARRAYS option is not + set, then the value of each element of NAME is substituted, one + element per word. Otherwise, the expansion results in one word + only; with KSH_ARRAYS, this is the first element of an array. No + field splitting is done on the result unless the SH_WORD_SPLIT + option is set. See also the flags = and s:STRING:. + +${+NAME} + If NAME is the name of a set parameter `1' is substituted, + otherwise `0' is substituted. + +${NAME-WORD} +${NAME:-WORD} + If NAME is set, or in the second form is non-null, then substitute + its value; otherwise substitute WORD. In the second form NAME may + be omitted, in which case WORD is always substituted. + +${NAME+WORD} +${NAME:+WORD} + If NAME is set, or in the second form is non-null, then substitute + WORD; otherwise substitute nothing. + +${NAME=WORD} +${NAME:=WORD} +${NAME::=WORD} + In the first form, if NAME is unset then set it to WORD; in the + second form, if NAME is unset or null then set it to WORD; and in + the third form, unconditionally set NAME to WORD. In all forms, + the value of the parameter is then substituted. + +${NAME?WORD} +${NAME:?WORD} + In the first form, if NAME is set, or in the second form if NAME + is both set and non-null, then substitute its value; otherwise, + print WORD and exit from the shell. Interactive shells instead + return to the prompt. If WORD is omitted, then a standard message + is printed. + + +In any of the above expressions that test a variable and substitute an +alternate WORD, note that you can use standard shell quoting in the +WORD value to selectively override the splitting done by the +SH_WORD_SPLIT option and the = flag, but not splitting by the s:STRING: +flag. + +In the following expressions, when NAME is an array and the +substitution is not quoted, or if the `(@)' flag or the NAME[@] syntax +is used, matching and replacement is performed on each array element +separately. + + +${NAME#PATTERN} +${NAME##PATTERN} + If the PATTERN matches the beginning of the value of NAME, then + substitute the value of NAME with the matched portion deleted; + otherwise, just substitute the value of NAME. In the first form, + the smallest matching pattern is preferred; in the second form, + the largest matching pattern is preferred. + +${NAME%PATTERN} +${NAME%%PATTERN} + If the PATTERN matches the end of the value of NAME, then + substitute the value of NAME with the matched portion deleted; + otherwise, just substitute the value of NAME. In the first form, + the smallest matching pattern is preferred; in the second form, + the largest matching pattern is preferred. + +${NAME:#PATTERN} + If the PATTERN matches the value of NAME, then substitute the + empty string; otherwise, just substitute the value of NAME. If + NAME is an array the matching array elements are removed (use the + `(M)' flag to remove the non-matched elements). + +${NAME:|ARRAYNAME} + If ARRAYNAME is the name (N.B., not contents) of an array + variable, then any elements contained in ARRAYNAME are removed + from the substitution of NAME. If the substitution is scalar, + either because NAME is a scalar variable or the expression is + quoted, the elements of ARRAYNAME are instead tested against the + entire expression. + +${NAME:*ARRAYNAME} + Similar to the preceding substitution, but in the opposite sense, + so that entries present in both the original substitution and as + elements of ARRAYNAME are retained and others removed. + +${NAME:^ARRAYNAME} +${NAME:^^ARRAYNAME} + Zips two arrays, such that the output array is twice as long as the + shortest (longest for `:^^') of name and arrayname, with the + elements alternatingly being picked from them. For `:^', if one of + the input arrays is longer, the output will stop when the end of + the shorter array is reached. Thus, + + + a=(1 2 3 4); b=(a b); print ${a:^b} + + will output `1 a 2 b'. For `:^^', then the input is repeated + until all of the longer array has been used up and the above will + output `1 a 2 b 3 a 4 b'. + + Either or both inputs may be a scalar, they will be treated as an + array of length 1 with the scalar as the only element. If either + array is empty, the other array is output with no extra elements + inserted. + + Currently the following code will output `a b' and `1' as two + separate elements, which can be unexpected. The second print + provides a workaround which should continue to work if this is + changed. + + + a=(a b); b=(1 2); print -l "${a:^b}"; print -l "${${a:^b}}" + +${NAME:OFFSET} +${NAME:OFFSET:LENGTH} + This syntax gives effects similar to parameter subscripting in the + form $NAME[START,END], but is compatible with other shells; note + that both OFFSET and LENGTH are interpreted differently from the + components of a subscript. + + If OFFSET is non-negative, then if the variable NAME is a scalar + substitute the contents starting OFFSET characters from the first + character of the string, and if NAME is an array substitute + elements starting OFFSET elements from the first element. If + LENGTH is given, substitute that many characters or elements, + otherwise the entire rest of the scalar or array. + + A positive OFFSET is always treated as the offset of a character or + element in NAME from the first character or element of the array + (this is different from native zsh subscript notation). Hence 0 + refers to the first character or element regardless of the setting + of the option KSH_ARRAYS. + + A negative offset counts backwards from the end of the scalar or + array, so that -1 corresponds to the last character or element, + and so on. + + When positive, LENGTH counts from the OFFSET position toward the + end of the scalar or array. When negative, LENGTH counts back + from the end. If this results in a position smaller than OFFSET, + a diagnostic is printed and nothing is substituted. + + The option MULTIBYTE is obeyed, i.e. the offset and length count + multibyte characters where appropriate. + + OFFSET and LENGTH undergo the same set of shell substitutions as + for scalar assignment; in addition, they are then subject to + arithmetic evaluation. Hence, for example + + + print ${foo:3} + print ${foo: 1 + 2} + print ${foo:$(( 1 + 2))} + print ${foo:$(echo 1 + 2)} + + all have the same effect, extracting the string starting at the + fourth character of $foo if the substitution would otherwise + return a scalar, or the array starting at the fourth element if + $foo would return an array. Note that with the option KSH_ARRAYS + $foo always returns a scalar (regardless of the use of the offset + syntax) and a form such as ${foo[*]:3} is required to extract + elements of an array named foo. + + If OFFSET is negative, the - may not appear immediately after the + : as this indicates the ${NAME:-WORD} form of substitution. + Instead, a space may be inserted before the -. Furthermore, + neither OFFSET nor LENGTH may begin with an alphabetic character + or & as these are used to indicate history-style modifiers. To + substitute a value from a variable, the recommended approach is to + precede it with a $ as this signifies the intention (parameter + substitution can easily be rendered unreadable); however, as + arithmetic substitution is performed, the expression ${var: offs} + does work, retrieving the offset from $offs. + + For further compatibility with other shells there is a special case + for array offset 0. This usually accesses the first element of + the array. However, if the substitution refers to the positional + parameter array, e.g. $@ or $*, then offset 0 instead refers to + $0, offset 1 refers to $1, and so on. In other words, the + positional parameter array is effectively extended by prepending + $0. Hence ${*:0:1} substitutes $0 and ${*:1:1} substitutes $1. + +${NAME/PATTERN/REPL} +${NAME//PATTERN/REPL} +${NAME:/PATTERN/REPL} + Replace the longest possible match of PATTERN in the expansion of + parameter NAME by string REPL. The first form replaces just the + first occurrence, the second form all occurrences, and the third + form replaces only if PATTERN matches the entire string. Both + PATTERN and REPL are subject to double-quoted substitution, so + that expressions like ${name/$opat/$npat} will work, but obey the + usual rule that pattern characters in $opat are not treated + specially unless either the option GLOB_SUBST is set, or $opat is + instead substituted as ${~opat}. + + The PATTERN may begin with a `#', in which case the PATTERN must + match at the start of the string, or `%', in which case it must + match at the end of the string, or `#%' in which case the PATTERN + must match the entire string. The REPL may be an empty string, in + which case the final `/' may also be omitted. To quote the final + `/' in other cases it should be preceded by a single backslash; + this is not necessary if the `/' occurs inside a substituted + parameter. Note also that the `#', `%' and `#% are not active if + they occur inside a substituted parameter, even at the start. + + If, after quoting rules apply, ${NAME} expands to an array, the + replacements act on each element individually. Note also the + effect of the I and S parameter expansion flags below; however, + the flags M, R, B, E and N are not useful. + + For example, + + + foo="twinkle twinkle little star" sub="t*e" rep="spy" + print ${foo//${~sub}/$rep} + print ${(S)foo//${~sub}/$rep} + + Here, the `~' ensures that the text of $sub is treated as a + pattern rather than a plain string. In the first case, the longest + match for t*e is substituted and the result is `spy star', while + in the second case, the shortest matches are taken and the result + is `spy spy lispy star'. + +${#SPEC} + If SPEC is one of the above substitutions, substitute the length + in characters of the result instead of the result itself. If SPEC + is an array expression, substitute the number of elements of the + result. This has the side-effect that joining is skipped even in + quoted forms, which may affect other sub-expressions in SPEC. + Note that `^', `=', and `~', below, must appear to the left of `#' + when these forms are combined. + + If the option POSIX_IDENTIFIERS is not set, and SPEC is a simple + name, then the braces are optional; this is true even for special + parameters so e.g. $#- and $#* take the length of the string $- + and the array $* respectively. If POSIX_IDENTIFIERS is set, then + braces are required for the # to be treated in this fashion. + +${^SPEC} + Turn on the RC_EXPAND_PARAM option for the evaluation of SPEC; if + the `^' is doubled, turn it off. When this option is set, array + expansions of the form FOO${XX}BAR, where the parameter XX is set + to (A B C), are substituted with `FOOABAR FOOBBAR FOOCBAR' instead + of the default `FOOA B CBAR'. Note that an empty array will + therefore cause all arguments to be removed. + + Internally, each such expansion is converted into the equivalent + list for brace expansion. E.g., ${^var} becomes + {$var[1],$var[2],...}, and is processed as described in *Note + Brace Expansion:: below: note, however, the expansion happens + immediately, with any explicit brace expansion happening later. + If word splitting is also in effect the $var[N] may themselves be + split into different list elements. + +${=SPEC} + Perform word splitting using the rules for SH_WORD_SPLIT during the + evaluation of SPEC, but regardless of whether the parameter + appears in double quotes; if the `=' is doubled, turn it off. This + forces parameter expansions to be split into separate words before + substitution, using IFS as a delimiter. This is done by default + in most other shells. + + Note that splitting is applied to WORD in the assignment forms of + SPEC _before_ the assignment to NAME is performed. This affects + the result of array assignments with the A flag. + +${~SPEC} + Turn on the GLOB_SUBST option for the evaluation of SPEC; if the + `~' is doubled, turn it off. When this option is set, the string + resulting from the expansion will be interpreted as a pattern + anywhere that is possible, such as in filename expansion and + filename generation and pattern-matching contexts like the right + hand side of the `=' and `!=' operators in conditions. + + In nested substitutions, note that the effect of the ~ applies to + the result of the current level of substitution. A surrounding + pattern operation on the result may cancel it. Hence, for + example, if the parameter foo is set to *, ${~foo//\*/*.c} is + substituted by the pattern *.c, which may be expanded by filename + generation, but ${${~foo}//\*/*.c} substitutes to the string *.c, + which will not be further expanded. + + +If a ${...} type parameter expression or a $(...) type command +substitution is used in place of NAME above, it is expanded first and +the result is used as if it were the value of NAME. Thus it is +possible to perform nested operations: ${${foo#head}%tail} substitutes +the value of $foo with both `head' and `tail' deleted. The form with +$(...) is often useful in combination with the flags described next; +see the examples below. Each NAME or nested ${...} in a parameter +expansion may also be followed by a subscript expression as described in +*Note Array Parameters::. + +Note that double quotes may appear around nested expressions, in which +case only the part inside is treated as quoted; for example, +${(f)"$(foo)"} quotes the result of $(foo), but the flag `(f)' (see +below) is applied using the rules for unquoted expansions. Note +further that quotes are themselves nested in this context; for example, +in "${(@f)"$(foo)"}", there are two sets of quotes, one surrounding the +whole expression, the other (redundant) surrounding the $(foo) as +before. + + + +14.3.1 Parameter Expansion Flags +-------------------------------- + +If the opening brace is directly followed by an opening parenthesis, +the string up to the matching closing parenthesis will be taken as a +list of flags. In cases where repeating a flag is meaningful, the +repetitions need not be consecutive; for example, `(q%q%q)' means the +same thing as the more readable `(%%qqq)'. The following flags are +supported: + + +# + Evaluate the resulting words as numeric expressions and output the + characters corresponding to the resulting integer. Note that this + form is entirely distinct from use of the # without parentheses. + + If the MULTIBYTE option is set and the number is greater than 127 + (i.e. not an ASCII character) it is treated as a Unicode character. + +% + Expand all % escapes in the resulting words in the same way as in + prompts (see *Note Prompt Expansion::). If this flag is given + twice, full prompt expansion is done on the resulting words, + depending on the setting of the PROMPT_PERCENT, PROMPT_SUBST and + PROMPT_BANG options. + +@ + In double quotes, array elements are put into separate words. + E.g., `"${(@)foo}"' is equivalent to `"${foo[@]}"' and + `"${(@)foo[1,2]}"' is the same as `"$foo[1]" "$foo[2]"'. This is + distinct from _field splitting_ by the f, s or z flags, which + still applies within each array element. + +A + Convert the substitution into an array expression, even if it + otherwise would be scalar. This has lower precedence than + subscripting, so one level of nested expansion is required in + order that subscripts apply to array elements. Thus + ${${(A)NAME}[1]} yields the full value of NAME when NAME is scalar. + + This assigns an array parameter with `${...=...}', `${...:=...}' + or `${...::=...}'. If this flag is repeated (as in `AA'), assigns + an associative array parameter. Assignment is made before sorting + or padding; if field splitting is active, the WORD part is split + before assignment. The NAME part may be a subscripted range for + ordinary arrays; when assigning an associative array, the WORD + part _must_ be converted to an array, for example by using + `${(AA)=NAME=...}' to activate field splitting. + + Surrounding context such as additional nesting or use of the value + in a scalar assignment may cause the array to be joined back into + a single string again. + +a + Sort in array index order; when combined with `O' sort in reverse + array index order. Note that `a' is therefore equivalent to the + default but `Oa' is useful for obtaining an array's elements in + reverse order. + +b + Quote with backslashes only characters that are special to pattern + matching. This is useful when the contents of the variable are to + be tested using GLOB_SUBST, including the ${~...} switch. + + Quoting using one of the q family of flags does not work for this + purpose since quotes are not stripped from non-pattern characters + by GLOB_SUBST. In other words, + + + pattern=${(q)str} + [[ $str = ${~pattern} ]] + + works if $str is `a*b' but not if it is `a b', whereas + + + pattern=${(b)str} + [[ $str = ${~pattern} ]] + + is always true for any possible value of $str. + +c + With ${#NAME}, count the total number of characters in an array, + as if the elements were concatenated with spaces between them. + This is not a true join of the array, so other expressions used + with this flag may have an effect on the elements of the array + before it is counted. + +C + Capitalize the resulting words. `Words' in this case refers to + sequences of alphanumeric characters separated by + non-alphanumerics, _not_ to words that result from field splitting. + +D + Assume the string or array elements contain directories and attempt + to substitute the leading part of these by names. The remainder of + the path (the whole of it if the leading part was not substituted) + is then quoted so that the whole string can be used as a shell + argument. This is the reverse of `~' substitution: see *Note + Filename Expansion::. + +e + Perform single word shell expansions, namely _parameter expansion_, + _command substitution_ and _arithmetic expansion_, on the result. + Such expansions can be nested but too deep recursion may have + unpredictable effects. + +f + Split the result of the expansion at newlines. This is a shorthand + for `ps:\n:'. + +F + Join the words of arrays together using newline as a separator. + This is a shorthand for `pj:\n:'. + +g:OPTS: + Process escape sequences like the echo builtin when no options are + given (g::). With the o option, octal escapes don't take a leading + zero. With the c option, sequences like `^X' are also processed. + With the e option, processes `\M-t' and similar sequences like the + print builtin. With both of the o and e options, behaves like the + print builtin except that in none of these modes is `\c' + interpreted. + +i + Sort case-insensitively. May be combined with `n' or `O'. + +k + If NAME refers to an associative array, substitute the _keys_ + (element names) rather than the values of the elements. Used with + subscripts (including ordinary arrays), force indices or keys to be + substituted even if the subscript form refers to values. However, + this flag may not be combined with subscript ranges. With the + KSH_ARRAYS option a subscript `[*]' or `[@]' is needed to operate + on the whole array, as usual. + +L + Convert all letters in the result to lower case. + +n + Sort decimal integers numerically; if the first differing + characters of two test strings are not digits, sorting is lexical. + Integers with more initial zeroes are sorted before those with + fewer or none. Hence the array `foo1 foo02 foo2 foo3 foo20 foo23' + is sorted into the order shown. May be combined with `i' or `O'. + +o + Sort the resulting words in ascending order; if this appears on its + own the sorting is lexical and case-sensitive (unless the locale + renders it case-insensitive). Sorting in ascending order is the + default for other forms of sorting, so this is ignored if combined + with `a', `i' or `n'. + +O + Sort the resulting words in descending order; `O' without `a', `i' + or `n' sorts in reverse lexical order. May be combined with `a', + `i' or `n' to reverse the order of sorting. + +P + This forces the value of the parameter NAME to be interpreted as a + further parameter name, whose value will be used where appropriate. + Note that flags set with one of the typeset family of commands (in + particular case transformations) are not applied to the value of + NAME used in this fashion. + + If used with a nested parameter or command substitution, the + result of that will be taken as a parameter name in the same way. + For example, if you have `foo=bar' and `bar=baz', the strings + ${(P)foo}, ${(P)${foo}}, and ${(P)$(echo bar)} will be expanded to + `baz'. + + Likewise, if the reference is itself nested, the expression with + the flag is treated as if it were directly replaced by the + parameter name. It is an error if this nested substitution + produces an array with more than one word. For example, if + `name=assoc' where the parameter assoc is an associative array, + then `${${(P)name}[elt]}' refers to the element of the associative + subscripted `elt'. + +q + Quote characters that are special to the shell in the resulting + words with backslashes; unprintable or invalid characters are + quoted using the $'\NNN' form, with separate quotes for each octet. + + If this flag is given twice, the resulting words are quoted in + single quotes and if it is given three times, the words are quoted + in double quotes; in these forms no special handling of + unprintable or invalid characters is attempted. If the flag is + given four times, the words are quoted in single quotes preceded + by a $. Note that in all three of these forms quoting is done + unconditionally, even if this does not change the way the + resulting string would be interpreted by the shell. + + If a q- is given (only a single q may appear), a minimal form of + single quoting is used that only quotes the string if needed to + protect special characters. Typically this form gives the most + readable output. + + If a q+ is given, an extended form of minimal quoting is used that + causes unprintable characters to be rendered using $'...'. This + quoting is similar to that used by the output of values by the + typeset family of commands. + +Q + Remove one level of quotes from the resulting words. + +t + Use a string describing the type of the parameter where the value + of the parameter would usually appear. This string consists of + keywords separated by hyphens (`-'). The first keyword in the + string describes the main type, it can be one of `scalar', + `array', `integer', `float' or `association'. The other keywords + describe the type in more detail: + + + local + for local parameters + + left + for left justified parameters + + right_blanks + for right justified parameters with leading blanks + + right_zeros + for right justified parameters with leading zeros + + lower + for parameters whose value is converted to all lower case + when it is expanded + + upper + for parameters whose value is converted to all upper case + when it is expanded + + readonly + for readonly parameters + + tag + for tagged parameters + + export + for exported parameters + + unique + for arrays which keep only the first occurrence of duplicated + values + + hide + for parameters with the `hide' flag + + hideval + for parameters with the `hideval' flag + + special + for special parameters defined by the shell + + +u + Expand only the first occurrence of each unique word. + +U + Convert all letters in the result to upper case. + +v + Used with k, substitute (as two consecutive words) both the key + and the value of each associative array element. Used with + subscripts, force values to be substituted even if the subscript + form refers to indices or keys. + +V + Make any special characters in the resulting words visible. + +w + With ${#NAME}, count words in arrays or strings; the s flag may be + used to set a word delimiter. + +W + Similar to w with the difference that empty words between repeated + delimiters are also counted. + +X + With this flag, parsing errors occurring with the Q, e and # flags + or the pattern matching forms such as `${NAME#PATTERN}' are + reported. Without the flag, errors are silently ignored. + +z + Split the result of the expansion into words using shell parsing to + find the words, i.e. taking into account any quoting in the value. + Comments are not treated specially but as ordinary strings, similar + to interactive shells with the INTERACTIVE_COMMENTS option unset + (however, see the Z flag below for related options) + + Note that this is done very late, even later than the `(s)' flag. + So to access single words in the result use nested expansions as + in `${${(z)foo}[2]}'. Likewise, to remove the quotes in the + resulting words use `${(Q)${(z)foo}}'. + +0 + Split the result of the expansion on null bytes. This is a + shorthand for `ps:\0:'. + + +The following flags (except p) are followed by one or more arguments as +shown. Any character, or the matching pairs `(...)', `{...}', `[...]', +or `<...>', may be used in place of a colon as delimiters, but note +that when a flag takes more than one argument, a matched pair of +delimiters must surround each argument. + + +p + Recognize the same escape sequences as the print builtin in string + arguments to any of the flags described below that follow this + argument. + + Alternatively, with this option string arguments may be in the form + $VAR in which case the value of the variable is substituted. Note + this form is strict; the string argument does not undergo general + parameter expansion. + + For example, + + + sep=: + val=a:b:c + print ${(ps.$sep.)val} + + splits the variable on a :. + +~ + Strings inserted into the expansion by any of the flags below are + to be treated as patterns. This applies to the string arguments + of flags that follow ~ within the same set of parentheses. + Compare with ~ outside parentheses, which forces the entire + substituted string to be treated as a pattern. Hence, for example, + + + [[ "?" = ${(~j.|.)array} ]] + + treats `|' as a pattern and succeeds if and only if $array + contains the string `?' as an element. The ~ may be repeated to + toggle the behaviour; its effect only lasts to the end of the + parenthesised group. + +j:STRING: + Join the words of arrays together using STRING as a separator. Note + that this occurs before field splitting by the s:STRING: flag or + the SH_WORD_SPLIT option. + +l:EXPR::STRING1::STRING2: + Pad the resulting words on the left. Each word will be truncated + if required and placed in a field EXPR characters wide. + + The arguments :STRING1: and :STRING2: are optional; neither, the + first, or both may be given. Note that the same pairs of + delimiters must be used for each of the three arguments. The + space to the left will be filled with STRING1 (concatenated as + often as needed) or spaces if STRING1 is not given. If both + STRING1 and STRING2 are given, STRING2 is inserted once directly + to the left of each word, truncated if necessary, before STRING1 + is used to produce any remaining padding. + + If either of STRING1 or STRING2 is present but empty, i.e. there + are two delimiters together at that point, the first character of + $IFS is used instead. + + If the MULTIBYTE option is in effect, the flag m may also be + given, in which case widths will be used for the calculation of + padding; otherwise individual multibyte characters are treated as + occupying one unit of width. + + If the MULTIBYTE option is not in effect, each byte in the string + is treated as occupying one unit of width. + + Control characters are always assumed to be one unit wide; this + allows the mechanism to be used for generating repetitions of + control characters. + +m + Only useful together with one of the flags l or r or with the # + length operator when the MULTIBYTE option is in effect. Use the + character width reported by the system in calculating how much of + the string it occupies or the overall length of the string. Most + printable characters have a width of one unit, however certain + Asian character sets and certain special effects use wider + characters; combining characters have zero width. Non-printable + characters are arbitrarily counted as zero width; how they would + actually be displayed will vary. + + If the m is repeated, the character either counts zero (if it has + zero width), else one. For printable character strings this has + the effect of counting the number of glyphs (visibly separate + characters), except for the case where combining characters + themselves have non-zero width (true in certain alphabets). + +r:EXPR::STRING1::STRING2: + As l, but pad the words on the right and insert STRING2 + immediately to the right of the string to be padded. + + Left and right padding may be used together. In this case the + strategy is to apply left padding to the first half width of each + of the resulting words, and right padding to the second half. If + the string to be padded has odd width the extra padding is applied + on the left. + +s:STRING: + Force field splitting at the separator STRING. Note that a STRING + of two or more characters means that all of them must match in + sequence; this differs from the treatment of two or more + characters in the IFS parameter. See also the = flag and the + SH_WORD_SPLIT option. An empty string may also be given in which + case every character will be a separate element. + + For historical reasons, the usual behaviour that empty array + elements are retained inside double quotes is disabled for arrays + generated by splitting; hence the following: + + + line="one::three" + print -l "${(s.:.)line}" + + produces two lines of output for one and three and elides the + empty field. To override this behaviour, supply the `(@)' flag as + well, i.e. "${(@s.:.)line}". + +Z:OPTS: + As z but takes a combination of option letters between a following + pair of delimiter characters. With no options the effect is + identical to z. (Z+c+) causes comments to be parsed as a string + and retained; any field in the resulting array beginning with an + unquoted comment character is a comment. (Z+C+) causes comments + to be parsed and removed. The rule for comments is standard: + anything between a word starting with the third character of + $HISTCHARS, default #, up to the next newline is a comment. + (Z+n+) causes unquoted newlines to be treated as ordinary + whitespace, else they are treated as if they are shell code + delimiters and converted to semicolons. Options are combined + within the same set of delimiters, e.g. (Z+Cn+). + +_:FLAGS: + The underscore (_) flag is reserved for future use. As of this + revision of zsh, there are no valid FLAGS; anything following an + underscore, other than an empty pair of delimiters, is treated as + an error, and the flag itself has no effect. + + +The following flags are meaningful with the ${...#...} or ${...%...} +forms. The S and I flags may also be used with the ${.../...} forms. + + +S + With # or ##, search for the match that starts closest to the + start of the string (a `substring match'). Of all matches at a + particular position, # selects the shortest and ## the longest: + + + % str="aXbXc" + % echo ${(S)str#X*} + abXc + % echo ${(S)str##X*} + a + % + + With % or %%, search for the match that starts closest to the end + of the string: + + + % str="aXbXc" + % echo ${(S)str%X*} + aXbc + % echo ${(S)str%%X*} + aXb + % + + (Note that % and %% don't search for the match that ends closest + to the end of the string, as one might expect.) + + With substitution via ${.../...} or ${...//...}, specifies + non-greedy matching, i.e. that the shortest instead of the longest + match should be replaced: + + + % str="abab" + % echo ${str/*b/_} + _ + % echo ${(S)str/*b/_} + _ab + % + +I:EXPR: + Search the EXPRth match (where EXPR evaluates to a number). This + only applies when searching for substrings, either with the S + flag, or with ${.../...} (only the EXPRth match is substituted) or + ${...//...} (all matches from the EXPRth on are substituted). The + default is to take the first match. + + The EXPRth match is counted such that there is either one or zero + matches from each starting position in the string, although for + global substitution matches overlapping previous replacements are + ignored. With the ${...%...} and ${...%%...} forms, the starting + position for the match moves backwards from the end as the index + increases, while with the other forms it moves forward from the + start. + + Hence with the string + which switch is the right switch for Ipswich? + substitutions of the form ${(SI:N:)string#w*ch} as N increases + from 1 will match and remove `which', `witch', `witch' and `wich'; + the form using `##' will match and remove `which switch is the + right switch for Ipswich', `witch is the right switch for + Ipswich', `witch for Ipswich' and `wich'. The form using `%' will + remove the same matches as for `#', but in reverse order, and the + form using `%%' will remove the same matches as for `##' in reverse + order. + +B + Include the index of the beginning of the match in the result. + +E + Include the index one character past the end of the match in the + result (note this is inconsistent with other uses of parameter + index). + +M + Include the matched portion in the result. + +N + Include the length of the match in the result. + +R + Include the unmatched portion in the result (the _R_est). + + + +14.3.2 Rules +------------ + +Here is a summary of the rules for substitution; this assumes that +braces are present around the substitution, i.e. ${...}. Some +particular examples are given below. Note that the Zsh Development +Group accepts _no responsibility_ for any brain damage which may occur +during the reading of the following rules. + + +1. _Nested substitution_ + If multiple nested ${...} forms are present, substitution is + performed from the inside outwards. At each level, the + substitution takes account of whether the current value is a + scalar or an array, whether the whole substitution is in double + quotes, and what flags are supplied to the current level of + substitution, just as if the nested substitution were the + outermost. The flags are not propagated up to enclosing + substitutions; the nested substitution will return either a scalar + or an array as determined by the flags, possibly adjusted for + quoting. All the following steps take place where applicable at + all levels of substitution. + + Note that, unless the `(P)' flag is present, the flags and any + subscripts apply directly to the value of the nested substitution; + for example, the expansion ${${foo}} behaves exactly the same as + ${foo}. When the `(P)' flag is present in a nested substitution, + the other substitution rules are applied to the value _before_ it + is interpreted as a name, so ${${(P)foo}} may differ from + ${(P)foo}. + + At each nested level of substitution, the substituted words + undergo all forms of single-word substitution (i.e. not filename + generation), including command substitution, arithmetic expansion + and filename expansion (i.e. leading ~ and =). Thus, for example, + ${${:-=cat}:h} expands to the directory where the cat program + resides. (Explanation: the internal substitution has no parameter + but a default value =cat, which is expanded by filename expansion + to a full path; the outer substitution then applies the modifier + :h and takes the directory part of the path.) + +2. _Internal parameter flags_ + Any parameter flags set by one of the typeset family of commands, + in particular the -L, -R, -Z, -u and -l options for padding and + capitalization, are applied directly to the parameter value. Note + these flags are options to the command, e.g. `typeset -Z'; they + are not the same as the flags used within parameter substitutions. + + At the outermost level of substitution, the `(P)' flag (rule 4.) + ignores these transformations and uses the unmodified value of the + parameter as the name to be replaced. This is usually the desired + behavior because padding may make the value syntactically illegal + as a parameter name, but if capitalization changes are desired, + use the ${${(P)foo}} form (rule 25.). + +3. _Parameter subscripting_ + If the value is a raw parameter reference with a subscript, such as + ${VAR[3]}, the effect of subscripting is applied directly to the + parameter. Subscripts are evaluated left to right; subsequent + subscripts apply to the scalar or array value yielded by the + previous subscript. Thus if var is an array, ${var[1][2]} is the + second character of the first word, but ${var[2,4][2]} is the + entire third word (the second word of the range of words two + through four of the original array). Any number of subscripts may + appear. Flags such as `(k)' and `(v)' which alter the result of + subscripting are applied. + +4. _Parameter name replacement_ + At the outermost level of nesting only, the `(P)' flag is applied. + This treats the value so far as a parameter name (which may + include a subscript expression) and replaces that with the + corresponding value. This replacement occurs later if the `(P)' + flag appears in a nested substitution. + + If the value so far names a parameter that has internal flags + (rule 2.), those internal flags are applied to the new value after + replacement. + +5. _Double-quoted joining_ + If the value after this process is an array, and the substitution + appears in double quotes, and neither an `(@)' flag nor a `#' + length operator is present at the current level, then words of the + value are joined with the first character of the parameter $IFS, + by default a space, between each word (single word arrays are not + modified). If the `(j)' flag is present, that is used for joining + instead of $IFS. + +6. _Nested subscripting_ + Any remaining subscripts (i.e. of a nested substitution) are + evaluated at this point, based on whether the value is an array or + a scalar. As with 3., multiple subscripts can appear. Note that + ${foo[2,4][2]} is thus equivalent to ${${foo[2,4]}[2]} and also to + "${${(@)foo[2,4]}[2]}" (the nested substitution returns an array in + both cases), but not to "${${foo[2,4]}[2]}" (the nested + substitution returns a scalar because of the quotes). + +7. _Modifiers_ + Any modifiers, as specified by a trailing `#', `%', `/' (possibly + doubled) or by a set of modifiers of the form `:...' (see *Note + Modifiers:: in *Note History Expansion::), are applied to the words + of the value at this level. + +8. _Character evaluation_ + Any `(#)' flag is applied, evaluating the result so far numerically + as a character. + +9. _Length_ + Any initial `#' modifier, i.e. in the form ${#VAR}, is used to + evaluate the length of the expression so far. + +10. _Forced joining_ + If the `(j)' flag is present, or no `(j)' flag is present but the + string is to be split as given by rule 11., and joining did not + take place at rule 5., any words in the value are joined together + using the given string or the first character of $IFS if none. + Note that the `(F)' flag implicitly supplies a string for joining + in this manner. + +11. _Simple word splitting_ + If one of the `(s)' or `(f)' flags are present, or the `=' + specifier was present (e.g. ${=VAR}), the word is split on + occurrences of the specified string, or (for = with neither of the + two flags present) any of the characters in $IFS. + + If no `(s)', `(f)' or `=' was given, but the word is not quoted + and the option SH_WORD_SPLIT is set, the word is split on + occurrences of any of the characters in $IFS. Note this step, too, + takes place at all levels of a nested substitution. + +12. _Case modification_ + Any case modification from one of the flags `(L)', `(U)' or `(C)' + is applied. + +13. _Escape sequence replacement_ + First any replacements from the `(g)' flag are performed, then any + prompt-style formatting from the `(%)' family of flags is applied. + +14. _Quote application_ + Any quoting or unquoting using `(q)' and `(Q)' and related flags + is applied. + +15. _Directory naming_ + Any directory name substitution using `(D)' flag is applied. + +16. _Visibility enhancement_ + Any modifications to make characters visible using the `(V)' flag + are applied. + +17. _Lexical word splitting_ + If the '(z)' flag or one of the forms of the '(Z)' flag is + present, the word is split as if it were a shell command line, so + that quotation marks and other metacharacters are used to decide + what constitutes a word. Note this form of splitting is entirely + distinct from that described by rule 11.: it does not use $IFS, and + does not cause forced joining. + +18. _Uniqueness_ + If the result is an array and the `(u)' flag was present, duplicate + elements are removed from the array. + +19. _Ordering_ + If the result is still an array and one of the `(o)' or `(O)' flags + was present, the array is reordered. + +20. RC_EXPAND_PARAM + At this point the decision is made whether any resulting array + elements are to be combined element by element with surrounding + text, as given by either the RC_EXPAND_PARAM option or the `^' + flag. + +21. _Re-evaluation_ + Any `(e)' flag is applied to the value, forcing it to be + re-examined for new parameter substitutions, but also for command + and arithmetic substitutions. + +22. _Padding_ + Any padding of the value by the `(l.FILL.)' or `(r.FILL.)' flags + is applied. + +23. _Semantic joining_ + In contexts where expansion semantics requires a single word to + result, all words are rejoined with the first character of IFS + between. So in `${(P)${(f)lines}}' the value of ${lines} is split + at newlines, but then must be joined again before the `(P)' flag + can be applied. + + If a single word is not required, this rule is skipped. + +24. _Empty argument removal_ + If the substitution does not appear in double quotes, any resulting + zero-length argument, whether from a scalar or an element of an + array, is elided from the list of arguments inserted into the + command line. + + Strictly speaking, the removal happens later as the same happens + with other forms of substitution; the point to note here is simply + that it occurs after any of the above parameter operations. + +25. _Nested parameter name replacement_ + If the `(P)' flag is present and rule 4. has not applied, the + value so far is treated as a parameter name (which may include a + subscript expression) and replaced with the corresponding value, + with internal flags (rule 2.) applied to the new value. + + + +14.3.3 Examples +--------------- + +The flag f is useful to split a double-quoted substitution line by +line. For example, ${(f)"$(<FILE)"} substitutes the contents of FILE +divided so that each line is an element of the resulting array. +Compare this with the effect of $(<FILE) alone, which divides the file +up by words, or the same inside double quotes, which makes the entire +content of the file a single string. + +The following illustrates the rules for nested parameter expansions. +Suppose that $foo contains the array (bar baz): + + +"${(@)${foo}[1]}" + This produces the result b. First, the inner substitution + "${foo}", which has no array (@) flag, produces a single word + result "bar baz". The outer substitution "${(@)...[1]}" detects + that this is a scalar, so that (despite the `(@)' flag) the + subscript picks the first character. + +"${${(@)foo}[1]}" + This produces the result `bar'. In this case, the inner + substitution "${(@)foo}" produces the array `(bar baz)'. The outer + substitution "${...[1]}" detects that this is an array and picks + the first word. This is similar to the simple case "${foo[1]}". + + +As an example of the rules for word splitting and joining, suppose $foo +contains the array `(ax1 bx1)'. Then + + +${(s/x/)foo} + produces the words `a', `1 b' and `1'. + +${(j/x/s/x/)foo} + produces `a', `1', `b' and `1'. + +${(s/x/)foo%%1*} + produces `a' and ` b' (note the extra space). As substitution + occurs before either joining or splitting, the operation first + generates the modified array (ax bx), which is joined to give "ax + bx", and then split to give `a', ` b' and `'. The final empty + string will then be elided, as it is not in double quotes. + + + + +File: zsh.info, Node: Command Substitution, Next: Arithmetic Expansion, Prev: Parameter Expansion, Up: Expansion + +14.4 Command Substitution +========================= + +A command enclosed in parentheses preceded by a dollar sign, like +`$(...)', or quoted with grave accents, like ``...`', is replaced with +its standard output, with any trailing newlines deleted. If the +substitution is not enclosed in double quotes, the output is broken +into words using the IFS parameter. + +The substitution `$(cat FOO)' may be replaced by the faster `$(<FOO)'. +In this case FOO undergoes single word shell expansions (_parameter +expansion_, _command substitution_ and _arithmetic expansion_), but not +filename generation. + +If the option GLOB_SUBST is set, the result of any unquoted command +substitution, including the special form just mentioned, is eligible for +filename generation. + + + + +File: zsh.info, Node: Arithmetic Expansion, Next: Brace Expansion, Prev: Command Substitution, Up: Expansion + +14.5 Arithmetic Expansion +========================= + +A string of the form `$[EXP]' or `$((EXP))' is substituted with the +value of the arithmetic expression EXP. EXP is subjected to _parameter +expansion_, _command substitution_ and _arithmetic expansion_ before it +is evaluated. See *Note Arithmetic Evaluation::. + + +File: zsh.info, Node: Brace Expansion, Next: Filename Expansion, Prev: Arithmetic Expansion, Up: Expansion + +14.6 Brace Expansion +==================== + +A string of the form `FOO{XX,YY,ZZ}BAR' is expanded to the individual +words `FOOXXBAR', `FOOYYBAR' and `FOOZZBAR'. Left-to-right order is +preserved. This construct may be nested. Commas may be quoted in +order to include them literally in a word. + +An expression of the form `{N1..N2}', where N1 and N2 are integers, is +expanded to every number between N1 and N2 inclusive. If either number +begins with a zero, all the resulting numbers will be padded with +leading zeroes to that minimum width, but for negative numbers the - +character is also included in the width. If the numbers are in +decreasing order the resulting sequence will also be in decreasing +order. + +An expression of the form `{N1..N2..N3}', where N1, N2, and N3 are +integers, is expanded as above, but only every N3th number starting +from N1 is output. If N3 is negative the numbers are output in reverse +order, this is slightly different from simply swapping N1 and N2 in the +case that the step N3 doesn't evenly divide the range. Zero padding +can be specified in any of the three numbers, specifying it in the +third can be useful to pad for example `{-99..100..01}' which is not +possible to specify by putting a 0 on either of the first two numbers +(i.e. pad to two characters). + +An expression of the form `{C1..C2}', where C1 and C2 are single +characters (which may be multibyte characters), is expanded to every +character in the range from C1 to C2 in whatever character sequence is +used internally. For characters with code points below 128 this is US +ASCII (this is the only case most users will need). If any intervening +character is not printable, appropriate quotation is used to render it +printable. If the character sequence is reversed, the output is in +reverse order, e.g. `{d..a}' is substituted as `d c b a'. + +If a brace expression matches none of the above forms, it is left +unchanged, unless the option BRACE_CCL (an abbreviation for `brace +character class') is set. In that case, it is expanded to a list of +the individual characters between the braces sorted into the order of +the characters in the ASCII character set (multibyte characters are not +currently handled). The syntax is similar to a [...] expression in +filename generation: `-' is treated specially to denote a range of +characters, but `^' or `!' as the first character is treated normally. +For example, `{abcdef0-9}' expands to 16 words 0 1 2 3 4 5 6 7 8 9 a b +c d e f. + +Note that brace expansion is not part of filename generation +(globbing); an expression such as */{foo,bar} is split into two +separate words */foo and */bar before filename generation takes place. +In particular, note that this is liable to produce a `no match' error if +_either_ of the two expressions does not match; this is to be contrasted +with */(foo|bar), which is treated as a single pattern but otherwise +has similar effects. + +To combine brace expansion with array expansion, see the ${^SPEC} form +described in *Note Parameter Expansion:: above. + + + + +File: zsh.info, Node: Filename Expansion, Next: Filename Generation, Prev: Brace Expansion, Up: Expansion + +14.7 Filename Expansion +======================= + +Each word is checked to see if it begins with an unquoted `~'. If it +does, then the word up to a `/', or the end of the word if there is no +`/', is checked to see if it can be substituted in one of the ways +described here. If so, then the `~' and the checked portion are +replaced with the appropriate substitute value. + +A `~' by itself is replaced by the value of $HOME. A `~' followed by a +`+' or a `-' is replaced by current or previous working directory, +respectively. + +A `~' followed by a number is replaced by the directory at that +position in the directory stack. `~0' is equivalent to `~+', and `~1' +is the top of the stack. `~+' followed by a number is replaced by the +directory at that position in the directory stack. `~+0' is equivalent +to `~+', and `~+1' is the top of the stack. `~-' followed by a number +is replaced by the directory that many positions from the bottom of the +stack. `~-0' is the bottom of the stack. The PUSHD_MINUS option +exchanges the effects of `~+' and `~-' where they are followed by a +number. + + + +14.7.1 Dynamic named directories +-------------------------------- + + + +If the function zsh_directory_name exists, or the shell variable +zsh_directory_name_functions exists and contains an array of function +names, then the functions are used to implement dynamic directory +naming. The functions are tried in order until one returns status +zero, so it is important that functions test whether they can handle +the case in question and return an appropriate status. + +A `~' followed by a string NAMSTR in unquoted square brackets is +treated specially as a dynamic directory name. Note that the first +unquoted closing square bracket always terminates NAMSTR. The shell +function is passed two arguments: the string n (for name) and NAMSTR. +It should either set the array reply to a single element which is the +directory corresponding to the name and return status zero (executing +an assignment as the last statement is usually sufficient), or it +should return status non-zero. In the former case the element of reply +is used as the directory; in the latter case the substitution is deemed +to have failed. If all functions fail and the option NOMATCH is set, +an error results. + +The functions defined as above are also used to see if a directory can +be turned into a name, for example when printing the directory stack or +when expanding %~ in prompts. In this case each function is passed two +arguments: the string d (for directory) and the candidate for dynamic +naming. The function should either return non-zero status, if the +directory cannot be named by the function, or it should set the array +reply to consist of two elements: the first is the dynamic name for the +directory (as would appear within `~[...]'), and the second is the +prefix length of the directory to be replaced. For example, if the +trial directory is /home/myname/src/zsh and the dynamic name for +/home/myname/src (which has 16 characters) is s, then the function sets + + + reply=(s 16) + +The directory name so returned is compared with possible static names +for parts of the directory path, as described below; it is used if the +prefix length matched (16 in the example) is longer than that matched +by any static name. + +It is not a requirement that a function implements both n and d calls; +for example, it might be appropriate for certain dynamic forms of +expansion not to be contracted to names. In that case any call with +the first argument d should cause a non-zero status to be returned. + +The completion system calls `zsh_directory_name c' followed by +equivalent calls to elements of the array zsh_directory_name_functions, +if it exists, in order to complete dynamic names for directories. The +code for this should be as for any other completion function as +described in *Note Completion System::. + +As a working example, here is a function that expands any dynamic names +beginning with the string p: to directories below /home/pws/perforce. +In this simple case a static name for the directory would be just as +effective. + + + zsh_directory_name() { + emulate -L zsh + setopt extendedglob + local -a match mbegin mend + if [[ $1 = d ]]; then + # turn the directory into a name + if [[ $2 = (#b)(/home/pws/perforce/)([^/]##)* ]]; then + typeset -ga reply + reply=(p:$match[2] $(( ${#match[1]} + ${#match[2]} )) ) + else + return 1 + fi + elif [[ $1 = n ]]; then + # turn the name into a directory + [[ $2 != (#b)p:(?*) ]] && return 1 + typeset -ga reply + reply=(/home/pws/perforce/$match[1]) + elif [[ $1 = c ]]; then + # complete names + local expl + local -a dirs + dirs=(/home/pws/perforce/*(/:t)) + dirs=(p:${^dirs}) + _wanted dynamic-dirs expl 'dynamic directory' compadd -S\] -a dirs + return + else + return 1 + fi + return 0 + } + + +14.7.2 Static named directories +------------------------------- + +A `~' followed by anything not already covered consisting of any number +of alphanumeric characters or underscore (`_'), hyphen (`-'), or dot +(`.') is looked up as a named directory, and replaced by the value of +that named directory if found. Named directories are typically home +directories for users on the system. They may also be defined if the +text after the `~' is the name of a string shell parameter whose value +begins with a `/'. Note that trailing slashes will be removed from the +path to the directory (though the original parameter is not modified). + +It is also possible to define directory names using the -d option to the +hash builtin. + +When the shell prints a path (e.g. when expanding %~ in prompts or when +printing the directory stack), the path is checked to see if it has a +named directory as its prefix. If so, then the prefix portion is +replaced with a `~' followed by the name of the directory. The shorter +of the two ways of referring to the directory is used, i.e. either the +directory name or the full path; the name is used if they are the same +length. The parameters $PWD and $OLDPWD are never abbreviated in this +fashion. + + + +14.7.3 `=' expansion +-------------------- + +If a word begins with an unquoted `=' and the EQUALS option is set, the +remainder of the word is taken as the name of a command. If a command +exists by that name, the word is replaced by the full pathname of the +command. + + + +14.7.4 Notes +------------ + +Filename expansion is performed on the right hand side of a parameter +assignment, including those appearing after commands of the typeset +family. In this case, the right hand side will be treated as a +colon-separated list in the manner of the PATH parameter, so that a `~' +or an `=' following a `:' is eligible for expansion. All such +behaviour can be disabled by quoting the `~', the `=', or the whole +expression (but not simply the colon); the EQUALS option is also +respected. + +If the option MAGIC_EQUAL_SUBST is set, any unquoted shell argument in +the form `IDENTIFIER=EXPRESSION' becomes eligible for file expansion as +described in the previous paragraph. Quoting the first `=' also +inhibits this. + + + + +File: zsh.info, Node: Filename Generation, Prev: Filename Expansion, Up: Expansion + +14.8 Filename Generation +======================== + +If a word contains an unquoted instance of one of the characters `*', +`(', `|', `<', `[', or `?', it is regarded as a pattern for filename +generation, unless the GLOB option is unset. If the EXTENDED_GLOB +option is set, the `^' and `#' characters also denote a pattern; +otherwise they are not treated specially by the shell. + +The word is replaced with a list of sorted filenames that match the +pattern. If no matching pattern is found, the shell gives an error +message, unless the NULL_GLOB option is set, in which case the word is +deleted; or unless the NOMATCH option is unset, in which case the word +is left unchanged. + +In filename generation, the character `/' must be matched explicitly; +also, a `.' must be matched explicitly at the beginning of a pattern or +after a `/', unless the GLOB_DOTS option is set. No filename +generation pattern matches the files `.' or `..'. In other instances +of pattern matching, the `/' and `.' are not treated specially. + +14.8.1 Glob Operators +--------------------- + + +* + Matches any string, including the null string. + +? + Matches any character. + +[...] + Matches any of the enclosed characters. Ranges of characters can + be specified by separating two characters by a `-'. A `-' or `]' + may be matched by including it as the first character in the list. There + are also several named classes of characters, in the form + `[:NAME:]' with the following meanings. The first set use the + macros provided by the operating system to test for the given + character combinations, including any modifications due to local + language settings, see man page ctype(3): + + + [:alnum:] + The character is alphanumeric + + [:alpha:] + The character is alphabetic + + [:ascii:] + The character is 7-bit, i.e. is a single-byte character + without the top bit set. + + [:blank:] + The character is a blank character + + [:cntrl:] + The character is a control character + + [:digit:] + The character is a decimal digit + + [:graph:] + The character is a printable character other than whitespace + + [:lower:] + The character is a lowercase letter + + [:print:] + The character is printable + + [:punct:] + The character is printable but neither alphanumeric nor + whitespace + + [:space:] + The character is whitespace + + [:upper:] + The character is an uppercase letter + + [:xdigit:] + The character is a hexadecimal digit + + + Another set of named classes is handled internally by the shell and + is not sensitive to the locale: + + + [:IDENT:] + The character is allowed to form part of a shell identifier, + such as a parameter name + + [:IFS:] + The character is used as an input field separator, i.e. is + contained in the IFS parameter + + [:IFSSPACE:] + The character is an IFS white space character; see the + documentation for IFS in *Note Parameters Used By The Shell::. + + [:INCOMPLETE:] + Matches a byte that starts an incomplete multibyte character. + Note that there may be a sequence of more than one bytes that + taken together form the prefix of a multibyte character. To + test for a potentially incomplete byte sequence, use the + pattern `[[:INCOMPLETE:]]*'. This will never match a + sequence starting with a valid multibyte character. + + [:INVALID:] + Matches a byte that does not start a valid multibyte + character. Note this may be a continuation byte of an + incomplete multibyte character as any part of a multibyte + string consisting of invalid and incomplete multibyte + characters is treated as single bytes. + + [:WORD:] + The character is treated as part of a word; this test is + sensitive to the value of the WORDCHARS parameter + + + Note that the square brackets are additional to those enclosing + the whole set of characters, so to test for a single alphanumeric + character you need `[[:alnum:]]'. Named character sets can be + used alongside other types, e.g. `[[:alpha:]0-9]'. + +[^...] +[!...] + Like [...], except that it matches any character which is not in + the given set. + +<[X]-[Y]> + Matches any number in the range X to Y, inclusive. Either of the + numbers may be omitted to make the range open-ended; hence `<->' + matches any number. To match individual digits, the [...] form is + more efficient. + + Be careful when using other wildcards adjacent to patterns of this + form; for example, <0-9>* will actually match any number + whatsoever at the start of the string, since the `<0-9>' will + match the first digit, and the `*' will match any others. This is + a trap for the unwary, but is in fact an inevitable consequence of + the rule that the longest possible match always succeeds. + Expressions such as `<0-9>[^[:digit:]]*' can be used instead. + +(...) + Matches the enclosed pattern. This is used for grouping. If the + KSH_GLOB option is set, then a `@', `*', `+', `?' or `!' + immediately preceding the `(' is treated specially, as detailed + below. The option SH_GLOB prevents bare parentheses from being + used in this way, though the KSH_GLOB option is still available. + + Note that grouping cannot extend over multiple directories: it is + an error to have a `/' within a group (this only applies for + patterns used in filename generation). There is one exception: a + group of the form (PAT/)# appearing as a complete path segment can + match a sequence of directories. For example, foo/(a*/)#bar + matches foo/bar, foo/any/bar, foo/any/anyother/bar, and so on. + +X|Y + Matches either X or Y. This operator has lower precedence than + any other. The `|' character must be within parentheses, to avoid + interpretation as a pipeline. The alternatives are tried in order + from left to right. + +^X + (Requires EXTENDED_GLOB to be set.) Matches anything except the + pattern X. This has a higher precedence than `/', so `^foo/bar' + will search directories in `.' except `./foo' for a file named + `bar'. + +X~Y + (Requires EXTENDED_GLOB to be set.) Match anything that matches + the pattern X but does not match Y. This has lower precedence + than any operator except `|', so `*/*~foo/bar' will search for all + files in all directories in `.' and then exclude `foo/bar' if + there was such a match. Multiple patterns can be excluded by + `FOO~BAR~BAZ'. In the exclusion pattern (Y), `/' and `.' are not + treated specially the way they usually are in globbing. + +X# + (Requires EXTENDED_GLOB to be set.) Matches zero or more + occurrences of the pattern X. This operator has high precedence; + `12#' is equivalent to `1(2#)', rather than `(12)#'. It is an + error for an unquoted `#' to follow something which cannot be + repeated; this includes an empty string, a pattern already + followed by `##', or parentheses when part of a KSH_GLOB pattern + (for example, `!(FOO)#' is invalid and must be replaced by + `*(!(FOO))'). + +X## + (Requires EXTENDED_GLOB to be set.) Matches one or more + occurrences of the pattern X. This operator has high precedence; + `12##' is equivalent to `1(2##)', rather than `(12)##'. No more + than two active `#' characters may appear together. (Note the + potential clash with glob qualifiers in the form `1(2##)' which + should therefore be avoided.) + + +14.8.2 ksh-like Glob Operators +------------------------------ + +If the KSH_GLOB option is set, the effects of parentheses can be +modified by a preceding `@', `*', `+', `?' or `!'. This character need +not be unquoted to have special effects, but the `(' must be. + + +@(...) + Match the pattern in the parentheses. (Like `(...)'.) + +*(...) + Match any number of occurrences. (Like `(...)#', except that + recursive directory searching is not supported.) + ++(...) + Match at least one occurrence. (Like `(...)##', except that + recursive directory searching is not supported.) + +?(...) + Match zero or one occurrence. (Like `(|...)'.) + +!(...) + Match anything but the expression in parentheses. (Like + `(^(...))'.) + + +14.8.3 Precedence +----------------- + +The precedence of the operators given above is (highest) `^', `/', `~', +`|' (lowest); the remaining operators are simply treated from left to +right as part of a string, with `#' and `##' applying to the shortest +possible preceding unit (i.e. a character, `?', `[...]', `<...>', or a +parenthesised expression). As mentioned above, a `/' used as a +directory separator may not appear inside parentheses, while a `|' must +do so; in patterns used in other contexts than filename generation (for +example, in case statements and tests within `[[...]]'), a `/' is not +special; and `/' is also not special after a `~' appearing outside +parentheses in a filename pattern. + +14.8.4 Globbing Flags +--------------------- + +There are various flags which affect any text to their right up to the +end of the enclosing group or to the end of the pattern; they require +the EXTENDED_GLOB option. All take the form (#X) where X may have one +of the following forms: + + +i + Case insensitive: upper or lower case characters in the pattern + match upper or lower case characters. + +l + Lower case characters in the pattern match upper or lower case + characters; upper case characters in the pattern still only match + upper case characters. + +I + Case sensitive: locally negates the effect of i or l from that + point on. + +b + Activate backreferences for parenthesised groups in the pattern; + this does not work in filename generation. When a pattern with a + set of active parentheses is matched, the strings matched by the + groups are stored in the array $match, the indices of the + beginning of the matched parentheses in the array $mbegin, and the + indices of the end in the array $mend, with the first element of + each array corresponding to the first parenthesised group, and so + on. These arrays are not otherwise special to the shell. The + indices use the same convention as does parameter substitution, so + that elements of $mend and $mbegin may be used in subscripts; the + KSH_ARRAYS option is respected. Sets of globbing flags are not + considered parenthesised groups; only the first nine active + parentheses can be referenced. + + For example, + + + foo="a_string_with_a_message" + if [[ $foo = (a|an)_(#b)(*) ]]; then + print ${foo[$mbegin[1],$mend[1]]} + fi + + prints `string_with_a_message'. Note that the first set of + parentheses is before the (#b) and does not create a backreference. + + Backreferences work with all forms of pattern matching other than + filename generation, but note that when performing matches on an + entire array, such as ${ARRAY#PATTERN}, or a global substitution, + such as ${PARAM//PAT/REPL}, only the data for the last match + remains available. In the case of global replacements this may + still be useful. See the example for the m flag below. + + The numbering of backreferences strictly follows the order of the + opening parentheses from left to right in the pattern string, + although sets of parentheses may be nested. There are special + rules for parentheses followed by `#' or `##'. Only the last + match of the parenthesis is remembered: for example, in `[[ abab = + (#b)([ab])# ]]', only the final `b' is stored in match[1]. Thus + extra parentheses may be necessary to match the complete segment: + for example, use `X((ab|cd)#)Y' to match a whole string of either + `ab' or `cd' between `X' and `Y', using the value of $match[1] + rather than $match[2]. + + If the match fails none of the parameters is altered, so in some + cases it may be necessary to initialise them beforehand. If some + of the backreferences fail to match -- which happens if they are + in an alternate branch which fails to match, or if they are + followed by # and matched zero times -- then the matched string is + set to the empty string, and the start and end indices are set to + -1. + + Pattern matching with backreferences is slightly slower than + without. + +B + Deactivate backreferences, negating the effect of the b flag from + that point on. + +cN,M + The flag (#cN,M) can be used anywhere that the # or ## operators + can be used except in the expressions `(*/)#' and `(*/)##' in + filename generation, where `/' has special meaning; it cannot be + combined with other globbing flags and a bad pattern error occurs + if it is misplaced. It is equivalent to the form {N,M} in regular + expressions. The previous character or group is required to match + between N and M times, inclusive. The form (#cN) requires exactly + N matches; (#c,M) is equivalent to specifying N as 0; (#cN,) + specifies that there is no maximum limit on the number of matches. + +m + Set references to the match data for the entire string matched; + this is similar to backreferencing and does not work in filename + generation. The flag must be in effect at the end of the pattern, + i.e. not local to a group. The parameters $MATCH, $MBEGIN and + $MEND will be set to the string matched and to the indices of the + beginning and end of the string, respectively. This is most + useful in parameter substitutions, as otherwise the string matched + is obvious. + + For example, + + + arr=(veldt jynx grimps waqf zho buck) + print ${arr//(#m)[aeiou]/${(U)MATCH}} + + forces all the matches (i.e. all vowels) into uppercase, printing + `vEldt jynx grImps wAqf zhO bUck'. + + Unlike backreferences, there is no speed penalty for using match + references, other than the extra substitutions required for the + replacement strings in cases such as the example shown. + +M + Deactivate the m flag, hence no references to match data will be + created. + +aNUM + Approximate matching: NUM errors are allowed in the string matched + by the pattern. The rules for this are described in the next + subsection. + +s, e + Unlike the other flags, these have only a local effect, and each + must appear on its own: `(#s)' and `(#e)' are the only valid + forms. The `(#s)' flag succeeds only at the start of the test + string, and the `(#e)' flag succeeds only at the end of the test + string; they correspond to `^' and `$' in standard regular + expressions. They are useful for matching path segments in + patterns other than those in filename generation (where path + segments are in any case treated separately). For example, + `*((#s)|/)test((#e)|/)*' matches a path segment `test' in any of + the following strings: test, test/at/start, at/end/test, + in/test/middle. + + Another use is in parameter substitution; for example + `${array/(#s)A*Z(#e)}' will remove only elements of an array which + match the complete pattern `A*Z'. There are other ways of + performing many operations of this type, however the combination + of the substitution operations `/' and `//' with the `(#s)' and + `(#e)' flags provides a single simple and memorable method. + + Note that assertions of the form `(^(#s))' also work, i.e. match + anywhere except at the start of the string, although this actually + means `anything except a zero-length portion at the start of the + string'; you need to use `(""~(#s))' to match a zero-length + portion of the string not at the start. + +q + A `q' and everything up to the closing parenthesis of the globbing + flags are ignored by the pattern matching code. This is intended + to support the use of glob qualifiers, see below. The result is + that the pattern `(#b)(*).c(#q.)' can be used both for globbing + and for matching against a string. In the former case, the + `(#q.)' will be treated as a glob qualifier and the `(#b)' will + not be useful, while in the latter case the `(#b)' is useful for + backreferences and the `(#q.)' will be ignored. Note that colon + modifiers in the glob qualifiers are also not applied in ordinary + pattern matching. + +u + Respect the current locale in determining the presence of multibyte + characters in a pattern, provided the shell was compiled with + MULTIBYTE_SUPPORT. This overrides the MULTIBYTE option; the + default behaviour is taken from the option. Compare U. + (Mnemonic: typically multibyte characters are from Unicode in the + UTF-8 encoding, although any extension of ASCII supported by the + system library may be used.) + +U + All characters are considered to be a single byte long. The + opposite of u. This overrides the MULTIBYTE option. + + +For example, the test string fooxx can be matched by the pattern +(#i)FOOXX, but not by (#l)FOOXX, (#i)FOO(#I)XX or ((#i)FOOX)X. The +string (#ia2)readme specifies case-insensitive matching of readme with +up to two errors. + +When using the ksh syntax for grouping both KSH_GLOB and EXTENDED_GLOB +must be set and the left parenthesis should be preceded by @. Note +also that the flags do not affect letters inside [...] groups, in other +words (#i)[a-z] still matches only lowercase letters. Finally, note +that when examining whole paths case-insensitively every directory must +be searched for all files which match, so that a pattern of the form +(#i)/foo/bar/... is potentially slow. + + + +14.8.5 Approximate Matching +--------------------------- + +When matching approximately, the shell keeps a count of the errors +found, which cannot exceed the number specified in the (#aNUM) flags. +Four types of error are recognised: + + +1. + Different characters, as in fooxbar and fooybar. + +2. + Transposition of characters, as in banana and abnana. + +3. + A character missing in the target string, as with the pattern road + and target string rod. + +4. + An extra character appearing in the target string, as with stove + and strove. + + +Thus, the pattern (#a3)abcd matches dcba, with the errors occurring by +using the first rule twice and the second once, grouping the string as +[d][cb][a] and [a][bc][d]. + +Non-literal parts of the pattern must match exactly, including +characters in character ranges: hence (#a1)??? matches strings of +length four, by applying rule 4 to an empty part of the pattern, but not +strings of length two, since all the ? must match. Other characters +which must match exactly are initial dots in filenames (unless the +GLOB_DOTS option is set), and all slashes in filenames, so that a/bc is +two errors from ab/c (the slash cannot be transposed with another +character). Similarly, errors are counted separately for +non-contiguous strings in the pattern, so that (ab|cd)ef is two errors +from aebf. + +When using exclusion via the ~ operator, approximate matching is +treated entirely separately for the excluded part and must be activated +separately. Thus, (#a1)README~READ_ME matches READ.ME but not READ_ME, +as the trailing READ_ME is matched without approximation. However, +(#a1)README~(#a1)READ_ME does not match any pattern of the form READ?ME +as all such forms are now excluded. + +Apart from exclusions, there is only one overall error count; however, +the maximum errors allowed may be altered locally, and this can be +delimited by grouping. For example, (#a1)cat((#a0)dog)fox allows one +error in total, which may not occur in the dog section, and the pattern +(#a1)cat(#a0)dog(#a1)fox is equivalent. Note that the point at which +an error is first found is the crucial one for establishing whether to +use approximation; for example, (#a1)abc(#a0)xyz will not match +abcdxyz, because the error occurs at the `x', where approximation is +turned off. + +Entire path segments may be matched approximately, so that +`(#a1)/foo/d/is/available/at/the/bar' allows one error in any path +segment. This is much less efficient than without the (#a1), however, +since every directory in the path must be scanned for a possible +approximate match. It is best to place the (#a1) after any path +segments which are known to be correct. + + + +14.8.6 Recursive Globbing +------------------------- + +A pathname component of the form `(FOO/)#' matches a path consisting of +zero or more directories matching the pattern FOO. + +As a shorthand, `**/' is equivalent to `(*/)#'; note that this +therefore matches files in the current directory as well as +subdirectories. Thus: + + + ls -ld -- (*/)#bar + +or + + + ls -ld -- **/bar + +does a recursive directory search for files named `bar' (potentially +including the file `bar' in the current directory). This form does not +follow symbolic links; the alternative form `***/' does, but is +otherwise identical. Neither of these can be combined with other forms +of globbing within the same path segment; in that case, the `*' +operators revert to their usual effect. + +Even shorter forms are available when the option GLOB_STAR_SHORT is +set. In that case if no / immediately follows a ** or *** they are +treated as if both a / plus a further * are present. Hence: + + + setopt GLOBSTARSHORT + ls -ld -- **.c + +is equivalent to + + + ls -ld -- **/*.c + +14.8.7 Glob Qualifiers +---------------------- + +Patterns used for filename generation may end in a list of qualifiers +enclosed in parentheses. The qualifiers specify which filenames that +otherwise match the given pattern will be inserted in the argument list. + +If the option BARE_GLOB_QUAL is set, then a trailing set of parentheses +containing no `|' or `(' characters (or `~' if it is special) is taken +as a set of glob qualifiers. A glob subexpression that would normally +be taken as glob qualifiers, for example `(^x)', can be forced to be +treated as part of the glob pattern by doubling the parentheses, in +this case producing `((^x))'. + +If the option EXTENDED_GLOB is set, a different syntax for glob +qualifiers is available, namely `(#qX)' where X is any of the same glob +qualifiers used in the other format. The qualifiers must still appear +at the end of the pattern. However, with this syntax multiple glob +qualifiers may be chained together. They are treated as a logical AND +of the individual sets of flags. Also, as the syntax is unambiguous, +the expression will be treated as glob qualifiers just as long any +parentheses contained within it are balanced; appearance of `|', `(' or +`~' does not negate the effect. Note that qualifiers will be +recognised in this form even if a bare glob qualifier exists at the end +of the pattern, for example `*(#q*)(.)' will recognise executable +regular files if both options are set; however, mixed syntax should +probably be avoided for the sake of clarity. Note that within +conditions using the `[[' form the presence of a parenthesised +expression (#q...) at the end of a string indicates that globbing +should be performed; the expression may include glob qualifiers, but it +is also valid if it is simply (#q). This does not apply to the right +hand side of pattern match operators as the syntax already has special +significance. + +A qualifier may be any one of the following: + + +/ + directories + +F + `full' (i.e. non-empty) directories. Note that the opposite sense + (^F) expands to empty directories and all non-directories. Use + (/^F) for empty directories. + +. + plain files + +@ + symbolic links + += + sockets + +p + named pipes (FIFOs) + +* + executable plain files (0100 or 0010 or 0001) + +% + device files (character or block special) + +%b + block special files + +%c + character special files + +r + owner-readable files (0400) + +w + owner-writable files (0200) + +x + owner-executable files (0100) + +A + group-readable files (0040) + +I + group-writable files (0020) + +E + group-executable files (0010) + +R + world-readable files (0004) + +W + world-writable files (0002) + +X + world-executable files (0001) + +s + setuid files (04000) + +S + setgid files (02000) + +t + files with the sticky bit (01000) + +fSPEC + files with access rights matching SPEC. This SPEC may be a octal + number optionally preceded by a `=', a `+', or a `-'. If none of + these characters is given, the behavior is the same as for `='. + The octal number describes the mode bits to be expected, if + combined with a `=', the value given must match the file-modes + exactly, with a `+', at least the bits in the given number must be + set in the file-modes, and with a `-', the bits in the number must + not be set. Giving a `?' instead of a octal digit anywhere in the + number ensures that the corresponding bits in the file-modes are + not checked, this is only useful in combination with `='. + + If the qualifier `f' is followed by any other character anything + up to the next matching character (`[', `{', and `<' match `]', + `}', and `>' respectively, any other character matches itself) is + taken as a list of comma-separated SUB-SPECs. Each SUB-SPEC may be + either an octal number as described above or a list of any of the + characters `u', `g', `o', and `a', followed by a `=', a `+', or a + `-', followed by a list of any of the characters `r', `w', `x', + `s', and `t', or an octal digit. The first list of characters + specify which access rights are to be checked. If a `u' is given, + those for the owner of the file are used, if a `g' is given, those + of the group are checked, a `o' means to test those of other + users, and the `a' says to test all three groups. The `=', `+', + and `-' again says how the modes are to be checked and have the + same meaning as described for the first form above. The second + list of characters finally says which access rights are to be + expected: `r' for read access, `w' for write access, `x' for the + right to execute the file (or to search a directory), `s' for the + setuid and setgid bits, and `t' for the sticky bit. + + Thus, `*(f70?)' gives the files for which the owner has read, + write, and execute permission, and for which other group members + have no rights, independent of the permissions for other users. + The pattern `*(f-100)' gives all files for which the owner does + not have execute permission, and `*(f:gu+w,o-rx:)' gives the files + for which the owner and the other members of the group have at + least write permission, and for which other users don't have read + or execute permission. + +eSTRING ++CMD + The STRING will be executed as shell code. The filename will be + included in the list if and only if the code returns a zero status + (usually the status of the last command). + + In the first form, the first character after the `e' will be used + as a separator and anything up to the next matching separator will + be taken as the STRING; `[', `{', and `<' match `]', `}', and + `>', respectively, while any other character matches itself. Note + that expansions must be quoted in the STRING to prevent them from + being expanded before globbing is done. STRING is then executed + as shell code. The string globqual is appended to the array + zsh_eval_context the duration of execution. + + During the execution of STRING the filename currently being tested + is available in the parameter REPLY; the parameter may be altered + to a string to be inserted into the list instead of the original + filename. In addition, the parameter reply may be set to an array + or a string, which overrides the value of REPLY. If set to an + array, the latter is inserted into the command line word by word. + + For example, suppose a directory contains a single file `lonely'. + Then the expression `*(e:'reply=(${REPLY}{1,2})':)' will cause the + words `lonely1' and `lonely2' to be inserted into the command + line. Note the quoting of STRING. + + The form +CMD has the same effect, but no delimiters appear around + CMD. Instead, CMD is taken as the longest sequence of characters + following the + that are alphanumeric or underscore. Typically + CMD will be the name of a shell function that contains the + appropriate test. For example, + + + nt() { [[ $REPLY -nt $NTREF ]] } + NTREF=reffile + ls -ld -- *(+nt) + + lists all files in the directory that have been modified more + recently than reffile. + +dDEV + files on the device DEV + +l[-|+]CT + files having a link count less than CT (-), greater than CT (+), + or equal to CT + +U + files owned by the effective user ID + +G + files owned by the effective group ID + +uID + files owned by user ID ID if that is a number. Otherwise, ID + specifies a user name: the character after the `u' will be taken + as a separator and the string between it and the next matching + separator will be taken as a user name. The starting separators + `[', `{', and `<' match the final separators `]', `}', and `>', + respectively; any other character matches itself. The selected + files are those owned by this user. For example, `u:foo:' or + `u[foo]' selects files owned by user `foo'. + +gID + like uID but with group IDs or names + +a[Mwhms][-|+]N + files accessed exactly N days ago. Files accessed within the last + N days are selected using a negative value for N (-N). Files + accessed more than N days ago are selected by a positive N value + (+N). Optional unit specifiers `M', `w', `h', `m' or `s' (e.g. + `ah5') cause the check to be performed with months (of 30 days), + weeks, hours, minutes or seconds instead of days, respectively. + An explicit `d' for days is also allowed. + + Any fractional part of the difference between the access time and + the current part in the appropriate units is ignored in the + comparison. For instance, `echo *(ah-5)' would echo files + accessed within the last five hours, while `echo *(ah+5)' would + echo files accessed at least six hours ago, as times strictly + between five and six hours are treated as five hours. + +m[Mwhms][-|+]N + like the file access qualifier, except that it uses the file + modification time. + +c[Mwhms][-|+]N + like the file access qualifier, except that it uses the file inode + change time. + +L[+|-]N + files less than N bytes (-), more than N bytes (+), or exactly N + bytes in length. + + If this flag is directly followed by a _size specifier_ `k' (`K'), + `m' (`M'), or `p' (`P') (e.g. `Lk-50') the check is performed with + kilobytes, megabytes, or blocks (of 512 bytes) instead. (On some + systems additional specifiers are available for gigabytes, `g' or + `G', and terabytes, `t' or `T'.) If a size specifier is used a + file is regarded as "exactly" the size if the file size rounded up + to the next unit is equal to the test size. Hence `*(Lm1)' + matches files from 1 byte up to 1 Megabyte inclusive. Note also + that the set of files "less than" the test size only includes + files that would not match the equality test; hence `*(Lm-1)' only + matches files of zero size. + +^ + negates all qualifiers following it + +- + toggles between making the qualifiers work on symbolic links (the + default) and the files they point to + +M + sets the MARK_DIRS option for the current pattern + +T + appends a trailing qualifier mark to the filenames, analogous to + the LIST_TYPES option, for the current pattern (overrides M) + +N + sets the NULL_GLOB option for the current pattern + +D + sets the GLOB_DOTS option for the current pattern + +n + sets the NUMERIC_GLOB_SORT option for the current pattern + +YN + enables short-circuit mode: the pattern will expand to at most N + filenames. If more than N matches exist, only the first N matches + in directory traversal order will be considered. + + Implies oN when no oC qualifier is used. + +oC + specifies how the names of the files should be sorted. If C is n + they are sorted by name; if it is L they are sorted depending on + the size (length) of the files; if l they are sorted by the number + of links; if a, m, or c they are sorted by the time of the last + access, modification, or inode change respectively; if d, files in + subdirectories appear before those in the current directory at + each level of the search -- this is best combined with other + criteria, for example `odon' to sort on names for files within the + same directory; if N, no sorting is performed. Note that a, m, + and c compare the age against the current time, hence the first + name in the list is the youngest file. Also note that the + modifiers ^ and - are used, so `*(^-oL)' gives a list of all files + sorted by file size in descending order, following any symbolic + links. Unless oN is used, multiple order specifiers may occur to + resolve ties. + + The default sorting is n (by name) unless the Y glob qualifier is + used, in which case it is N (unsorted). + + oe and o+ are special cases; they are each followed by shell code, + delimited as for the e glob qualifier and the + glob qualifier + respectively (see above). The code is executed for each matched + file with the parameter REPLY set to the name of the file on entry + and globsort appended to zsh_eval_context. The code should modify + the parameter REPLY in some fashion. On return, the value of the + parameter is used instead of the file name as the string on which + to sort. Unlike other sort operators, oe and o+ may be repeated, + but note that the maximum number of sort operators of any kind + that may appear in any glob expression is 12. + +OC + like `o', but sorts in descending order; i.e. `*(^oc)' is the same + as `*(Oc)' and `*(^Oc)' is the same as `*(oc)'; `Od' puts files in + the current directory before those in subdirectories at each level + of the search. + +[BEG[,END]] + specifies which of the matched filenames should be included in the + returned list. The syntax is the same as for array subscripts. BEG + and the optional END may be mathematical expressions. As in + parameter subscripting they may be negative to make them count + from the last match backward. E.g.: `*(-OL[1,3])' gives a list of + the names of the three largest files. + +PSTRING + The STRING will be prepended to each glob match as a separate + word. STRING is delimited in the same way as arguments to the e + glob qualifier described above. The qualifier can be repeated; + the words are prepended separately so that the resulting command + line contains the words in the same order they were given in the + list of glob qualifiers. + + A typical use for this is to prepend an option before all + occurrences of a file name; for example, the pattern `*(P:-f:)' + produces the command line arguments `-f FILE1 -f FILE2 ...' + + If the modifier ^ is active, then STRING will be appended instead + of prepended. Prepending and appending is done independently so + both can be used on the same glob expression; for example by + writing `*(P:foo:^P:bar:^P:baz:)' which produces the command line + arguments `foo baz FILE1 bar ...' + + +More than one of these lists can be combined, separated by commas. The +whole list matches if at least one of the sublists matches (they are +`or'ed, the qualifiers in the sublists are `and'ed). Some qualifiers, +however, affect all matches generated, independent of the sublist in +which they are given. These are the qualifiers `M', `T', `N', `D', +`n', `o', `O' and the subscripts given in brackets (`[...]'). + +If a `:' appears in a qualifier list, the remainder of the expression in +parenthesis is interpreted as a modifier (see *Note Modifiers:: in +*Note History Expansion::). Each modifier must be introduced by a +separate `:'. Note also that the result after modification does not +have to be an existing file. The name of any existing file can be +followed by a modifier of the form `(:...)' even if no actual filename +generation is performed, although note that the presence of the +parentheses causes the entire expression to be subjected to any global +pattern matching options such as NULL_GLOB. Thus: + + + ls -ld -- *(-/) + +lists all directories and symbolic links that point to directories, and + + + ls -ld -- *(-@) + +lists all broken symbolic links, and + + + ls -ld -- *(%W) + +lists all world-writable device files in the current directory, and + + + ls -ld -- *(W,X) + +lists all files in the current directory that are world-writable or +world-executable, and + + + print -rC1 /tmp/foo*(u0^@:t) + +outputs the basename of all root-owned files beginning with the string +`foo' in /tmp, ignoring symlinks, and + + + ls -ld -- *.*~(lex|parse).[ch](^D^l1) + +lists all files having a link count of one whose names contain a dot +(but not those starting with a dot, since GLOB_DOTS is explicitly +switched off) except for lex.c, lex.h, parse.c and parse.h. + + + print -rC1 b*.pro(#q:s/pro/shmo/)(#q.:s/builtin/shmiltin/) + +demonstrates how colon modifiers and other qualifiers may be chained +together. The ordinary qualifier `.' is applied first, then the colon +modifiers in order from left to right. So if EXTENDED_GLOB is set and +the base pattern matches the regular file builtin.pro, the shell will +print `shmiltin.shmo'. + + +File: zsh.info, Node: Parameters, Next: Options, Prev: Expansion, Up: Top + +15 Parameters +************* + + + +15.1 Description +================ + +A parameter has a name, a value, and a number of attributes. A name +may be any sequence of alphanumeric characters and underscores, or the +single characters `*', `@', `#', `?', `-', `$', or `!'. A parameter +whose name begins with an alphanumeric or underscore is also referred +to as a _variable_. + +The attributes of a parameter determine the _type_ of its value, often +referred to as the parameter type or variable type, and also control +other processing that may be applied to the value when it is referenced. +The value type may be a _scalar_ (a string, an integer, or a floating +point number), an array (indexed numerically), or an _associative_ +array (an unordered set of name-value pairs, indexed by name, also +referred to as a _hash_). + +Named scalar parameters may have the _exported_, -x, attribute, to copy +them into the process environment, which is then passed from the shell +to any new processes that it starts. Exported parameters are called +_environment variables_. The shell also _imports_ environment variables +at startup time and automatically marks the corresponding parameters as +exported. Some environment variables are not imported for reasons of +security or because they would interfere with the correct operation of +other shell features. + +Parameters may also be _special_, that is, they have a predetermined +meaning to the shell. Special parameters cannot have their type changed +or their readonly attribute turned off, and if a special parameter is +unset, then later recreated, the special properties will be retained. + +To declare the type of a parameter, or to assign a string or numeric +value to a scalar parameter, use the typeset builtin. + +The value of a scalar parameter may also be assigned by writing: + + NAME=VALUE + +In scalar assignment, VALUE is expanded as a single string, in which +the elements of arrays are joined together; filename expansion is not +performed unless the option GLOB_ASSIGN is set. + +When the integer attribute, -i, or a floating point attribute, -E or +-F, is set for NAME, the VALUE is subject to arithmetic evaluation. +Furthermore, by replacing `=' with `+=', a parameter can be incremented +or appended to. See *Note Array Parameters:: and *Note Arithmetic +Evaluation:: for additional forms of assignment. + +Note that assignment may implicitly change the attributes of a +parameter. For example, assigning a number to a variable in arithmetic +evaluation may change its type to integer or float, and with +GLOB_ASSIGN assigning a pattern to a variable may change its type to an +array. + +To reference the value of a parameter, write `$NAME' or `${NAME}'. See +*Note Parameter Expansion:: for complete details. That section also +explains the effect of the difference between scalar and array +assignment on parameter expansion. + +* Menu: + +* Array Parameters:: +* Positional Parameters:: +* Local Parameters:: +* Parameters Set By The Shell:: +* Parameters Used By The Shell:: + + +File: zsh.info, Node: Array Parameters, Next: Positional Parameters, Up: Parameters + +15.2 Array Parameters +===================== + +To assign an array value, write one of: + + set -A NAME VALUE ... + + NAME=(VALUE ...) + + NAME=([KEY]=VALUE ...) + +If no parameter NAME exists, an ordinary array parameter is created. +If the parameter NAME exists and is a scalar, it is replaced by a new +array. + +In the third form, KEY is an expression that will be evaluated in +arithmetic context (in its simplest form, an integer) that gives the +index of the element to be assigned with VALUE. In this form any +elements not explicitly mentioned that come before the largest index to +which a value is assigned are assigned an empty string. The indices +may be in any order. Note that this syntax is strict: [ and ]= must +not be quoted, and KEY may not consist of the unquoted string ]=, but +is otherwise treated as a simple string. The enhanced forms of +subscript expression that may be used when directly subscripting a +variable name, described in the section Array Subscripts below, are not +available. + +The syntaxes with and without the explicit key may be mixed. An +implicit KEY is deduced by incrementing the index from the previously +assigned element. Note that it is not treated as an error if latter +assignments in this form overwrite earlier assignments. + +For example, assuming the option KSH_ARRAYS is not set, the following: + + + array=(one [3]=three four) + +causes the array variable array to contain four elements one, an empty +string, three and four, in that order. + +In the forms where only VALUE is specified, full command line expansion +is performed. + +In the [KEY]=VALUE form, both KEY and VALUE undergo all forms of +expansion allowed for single word shell expansions (this does not +include filename generation); these are as performed by the parameter +expansion flag (e) as described in *Note Parameter Expansion::. Nested +parentheses may surround VALUE and are included as part of the value, +which is joined into a plain string; this differs from ksh which allows +the values themselves to be arrays. A future version of zsh may +support that. To cause the brackets to be interpreted as a character +class for filename generation, and therefore to treat the resulting list +of files as a set of values, quote the equal sign using any form of +quoting. Example: + + NAME=([a-z]'='*) + +To append to an array without changing the existing values, use one of +the following: + + NAME+=(VALUE ...) + + NAME+=([KEY]=VALUE ...) + +In the second form KEY may specify an existing index as well as an +index off the end of the old array; any existing value is overwritten by +VALUE. Also, it is possible to use [KEY]+=VALUE to append to the +existing value at that index. + +Within the parentheses on the right hand side of either form of the +assignment, newlines and semicolons are treated the same as white space, +separating individual VALUEs. Any consecutive sequence of such +characters has the same effect. + +Ordinary array parameters may also be explicitly declared with: + + typeset -a NAME + +Associative arrays _must_ be declared before assignment, by using: + + typeset -A NAME + +When NAME refers to an associative array, the list in an assignment is +interpreted as alternating keys and values: + + set -A NAME KEY VALUE ... + + NAME=(KEY VALUE ...) + + NAME=([KEY]=VALUE ...) + +Note that only one of the two syntaxes above may be used in any given +assignment; the forms may not be mixed. This is unlike the case of +numerically indexed arrays. + +Every KEY must have a VALUE in this case. Note that this assigns to +the entire array, deleting any elements that do not appear in the list. +The append syntax may also be used with an associative array: + + NAME+=(KEY VALUE ...) + + NAME+=([KEY]=VALUE ...) + +This adds a new key/value pair if the key is not already present, and +replaces the value for the existing key if it is. In the second form +it is also possible to use [KEY]+=VALUE to append to the existing value +at that key. Expansion is performed identically to the corresponding +forms for normal arrays, as described above. + +To create an empty array (including associative arrays), use one of: + + set -A NAME + + NAME=() + + +15.2.1 Array Subscripts +----------------------- + +Individual elements of an array may be selected using a subscript. A +subscript of the form `[EXP]' selects the single element EXP, where EXP +is an arithmetic expression which will be subject to arithmetic +expansion as if it were surrounded by `$((...))'. The elements are +numbered beginning with 1, unless the KSH_ARRAYS option is set in which +case they are numbered from zero. + +Subscripts may be used inside braces used to delimit a parameter name, +thus `${foo[2]}' is equivalent to `$foo[2]'. If the KSH_ARRAYS option +is set, the braced form is the only one that works, as bracketed +expressions otherwise are not treated as subscripts. + +If the KSH_ARRAYS option is not set, then by default accesses to an +array element with a subscript that evaluates to zero return an empty +string, while an attempt to write such an element is treated as an +error. For backward compatibility the KSH_ZERO_SUBSCRIPT option can be +set to cause subscript values 0 and 1 to be equivalent; see the +description of the option in *Note Description of Options::. + +The same subscripting syntax is used for associative arrays, except that +no arithmetic expansion is applied to EXP. However, the parsing rules +for arithmetic expressions still apply, which affects the way that +certain special characters must be protected from interpretation. See +_Subscript Parsing_ below for details. + +A subscript of the form `[*]' or `[@]' evaluates to all elements of an +array; there is no difference between the two except when they appear +within double quotes. `"$foo[*]"' evaluates to `"$foo[1] $foo[2] +..."', whereas `"$foo[@]"' evaluates to `"$foo[1]" "$foo[2]" ...'. For +associative arrays, `[*]' or `[@]' evaluate to all the values, in no +particular order. Note that this does not substitute the keys; see the +documentation for the `k' flag under *Note Parameter Expansion:: for +complete details. When an array parameter is referenced as `$NAME' +(with no subscript) it evaluates to `$NAME[*]', unless the KSH_ARRAYS +option is set in which case it evaluates to `${NAME[0]}' (for an +associative array, this means the value of the key `0', which may not +exist even if there are values for other keys). + +A subscript of the form `[EXP1,EXP2]' selects all elements in the range +EXP1 to EXP2, inclusive. (Associative arrays are unordered, and so do +not support ranges.) If one of the subscripts evaluates to a negative +number, say -N, then the Nth element from the end of the array is used. +Thus `$foo[-3]' is the third element from the end of the array foo, and +`$foo[1,-1]' is the same as `$foo[*]'. + +Subscripting may also be performed on non-array values, in which case +the subscripts specify a substring to be extracted. For example, if +FOO is set to `foobar', then `echo $FOO[2,5]' prints `ooba'. Note that +some forms of subscripting described below perform pattern matching, +and in that case the substring extends from the start of the match of +the first subscript to the end of the match of the second subscript. +For example, + + + string="abcdefghijklm" + print ${string[(r)d?,(r)h?]} + +prints `defghi'. This is an obvious generalisation of the rule for +single-character matches. For a single subscript, only a single +character is referenced (not the range of characters covered by the +match). + +Note that in substring operations the second subscript is handled +differently by the r and R subscript flags: the former takes the +shortest match as the length and the latter the longest match. Hence +in the former case a * at the end is redundant while in the latter case +it matches the whole remainder of the string. This does not affect the +result of the single subscript case as here the length of the match is +irrelevant. + + + +15.2.2 Array Element Assignment +------------------------------- + +A subscript may be used on the left side of an assignment like so: + + NAME[EXP]=VALUE + +In this form of assignment the element or range specified by EXP is +replaced by the expression on the right side. An array (but not an +associative array) may be created by assignment to a range or element. +Arrays do not nest, so assigning a parenthesized list of values to an +element or range changes the number of elements in the array, shifting +the other elements to accommodate the new values. (This is not +supported for associative arrays.) + +This syntax also works as an argument to the typeset command: + + typeset "NAME[EXP]"=VALUE + +The VALUE may _not_ be a parenthesized list in this case; only +single-element assignments may be made with typeset. Note that quotes +are necessary in this case to prevent the brackets from being +interpreted as filename generation operators. The noglob precommand +modifier could be used instead. + +To delete an element of an ordinary array, assign `()' to that element. +To delete an element of an associative array, use the unset command: + + unset "NAME[EXP]" + + +15.2.3 Subscript Flags +---------------------- + +If the opening bracket, or the comma in a range, in any subscript +expression is directly followed by an opening parenthesis, the string up +to the matching closing one is considered to be a list of flags, as in +`NAME[(FLAGS)EXP]'. + +The flags s, n and b take an argument; the delimiter is shown below as +`:', but any character, or the matching pairs `(...)', `{...}', +`[...]', or `<...>', may be used, but note that `<...>' can only be +used if the subscript is inside a double quoted expression or a +parameter substitution enclosed in braces as otherwise the expression is +interpreted as a redirection. + +The flags currently understood are: + + +w + If the parameter subscripted is a scalar then this flag makes + subscripting work on words instead of characters. The default word + separator is whitespace. When combined with the i or I flag, the + effect is to produce the index of the first character of the + first/last word which matches the given pattern; note that a failed + match in this case always yields 0. + +s:STRING: + This gives the STRING that separates words (for use with the w + flag). The delimiter character : is arbitrary; see above. + +p + Recognize the same escape sequences as the print builtin in the + string argument of a subsequent `s' flag. + +f + If the parameter subscripted is a scalar then this flag makes + subscripting work on lines instead of characters, i.e. with + elements separated by newlines. This is a shorthand for `pws:\n:'. + +r + Reverse subscripting: if this flag is given, the EXP is taken as a + pattern and the result is the first matching array element, + substring or word (if the parameter is an array, if it is a + scalar, or if it is a scalar and the `w' flag is given, + respectively). The subscript used is the number of the matching + element, so that pairs of subscripts such as `$foo[(r)??,3]' and + `$foo[(r)??,(r)f*]' are possible if the parameter is not an + associative array. If the parameter is an associative array, only + the value part of each pair is compared to the pattern, and the + result is that value. + + If a search through an ordinary array failed, the search sets the + subscript to one past the end of the array, and hence + ${array[(r)PATTERN]} will substitute the empty string. Thus the + success of a search can be tested by using the (i) flag, for + example (assuming the option KSH_ARRAYS is not in effect): + + + [[ ${array[(i)pattern]} -le ${#array} ]] + + If KSH_ARRAYS is in effect, the -le should be replaced by -lt. + +R + Like `r', but gives the last match. For associative arrays, gives + all possible matches. May be used for assigning to ordinary array + elements, but not for assigning to associative arrays. On + failure, for normal arrays this has the effect of returning the + element corresponding to subscript 0; this is empty unless one of + the options KSH_ARRAYS or KSH_ZERO_SUBSCRIPT is in effect. + + Note that in subscripts with both `r' and `R' pattern characters + are active even if they were substituted for a parameter + (regardless of the setting of GLOB_SUBST which controls this + feature in normal pattern matching). The flag `e' can be added to + inhibit pattern matching. As this flag does not inhibit other + forms of substitution, care is still required; using a parameter + to hold the key has the desired effect: + + + key2='original key' + print ${array[(Re)$key2]} + +i + Like `r', but gives the index of the match instead; this may not be + combined with a second argument. On the left side of an + assignment, behaves like `r'. For associative arrays, the key + part of each pair is compared to the pattern, and the first + matching key found is the result. On failure substitutes the + length of the array plus one, as discussed under the description + of `r', or the empty string for an associative array. + +I + Like `i', but gives the index of the last match, or all possible + matching keys in an associative array. On failure substitutes 0, + or the empty string for an associative array. This flag is best + when testing for values or keys that do not exist. + +k + If used in a subscript on an associative array, this flag causes + the keys to be interpreted as patterns, and returns the value for + the first key found where EXP is matched by the key. Note this + could be any such key as no ordering of associative arrays is + defined. This flag does not work on the left side of an + assignment to an associative array element. If used on another + type of parameter, this behaves like `r'. + +K + On an associative array this is like `k' but returns all values + where EXP is matched by the keys. On other types of parameters + this has the same effect as `R'. + +n:EXPR: + If combined with `r', `R', `i' or `I', makes them give the Nth or + Nth last match (if EXPR evaluates to N). This flag is ignored + when the array is associative. The delimiter character : is + arbitrary; see above. + +b:EXPR: + If combined with `r', `R', `i' or `I', makes them begin at the Nth + or Nth last element, word, or character (if EXPR evaluates to N). + This flag is ignored when the array is associative. The delimiter + character : is arbitrary; see above. + +e + This flag causes any pattern matching that would be performed on + the subscript to use plain string matching instead. Hence + `${array[(re)*]}' matches only the array element whose value is *. + Note that other forms of substitution such as parameter + substitution are not inhibited. + + This flag can also be used to force * or @ to be interpreted as a + single key rather than as a reference to all values. It may be + used for either purpose on the left side of an assignment. + + +See _Parameter Expansion Flags_ (*Note Parameter Expansion::) for +additional ways to manipulate the results of array subscripting. + + + +15.2.4 Subscript Parsing +------------------------ + +This discussion applies mainly to associative array key strings and to +patterns used for reverse subscripting (the `r', `R', `i', etc. flags), +but it may also affect parameter substitutions that appear as part of +an arithmetic expression in an ordinary subscript. + +To avoid subscript parsing limitations in assignments to associative +array elements, use the append syntax: + + + aa+=('key with "*strange*" characters' 'value string') + +The basic rule to remember when writing a subscript expression is that +all text between the opening `[' and the closing `]' is interpreted _as +if_ it were in double quotes (*Note Quoting::). However, unlike double +quotes which normally cannot nest, subscript expressions may appear +inside double-quoted strings or inside other subscript expressions (or +both!), so the rules have two important differences. + +The first difference is that brackets (`[' and `]') must appear as +balanced pairs in a subscript expression unless they are preceded by a +backslash (`\'). Therefore, within a subscript expression (and unlike +true double-quoting) the sequence `\[' becomes `[', and similarly `\]' +becomes `]'. This applies even in cases where a backslash is not +normally required; for example, the pattern `[^[]' (to match any +character other than an open bracket) should be written `[^\[]' in a +reverse-subscript pattern. However, note that `\[^\[\]' and even +`\[^[]' mean the _same_ thing, because backslashes are always stripped +when they appear before brackets! + +The same rule applies to parentheses (`(' and `)') and braces (`{' and +`}'): they must appear either in balanced pairs or preceded by a +backslash, and backslashes that protect parentheses or braces are +removed during parsing. This is because parameter expansions may be +surrounded by balanced braces, and subscript flags are introduced by +balanced parentheses. + +The second difference is that a double-quote (`"') may appear as part +of a subscript expression without being preceded by a backslash, and +therefore that the two characters `\"' remain as two characters in the +subscript (in true double-quoting, `\"' becomes `"'). However, because +of the standard shell quoting rules, any double-quotes that appear must +occur in balanced pairs unless preceded by a backslash. This makes it +more difficult to write a subscript expression that contains an odd +number of double-quote characters, but the reason for this difference is +so that when a subscript expression appears inside true double-quotes, +one can still write `\"' (rather than `\\\"') for `"'. + +To use an odd number of double quotes as a key in an assignment, use the +typeset builtin and an enclosing pair of double quotes; to refer to the +value of that key, again use double quotes: + + + typeset -A aa + typeset "aa[one\"two\"three\"quotes]"=QQQ + print "$aa[one\"two\"three\"quotes]" + +It is important to note that the quoting rules do not change when a +parameter expansion with a subscript is nested inside another subscript +expression. That is, it is not necessary to use additional backslashes +within the inner subscript expression; they are removed only once, from +the innermost subscript outwards. Parameters are also expanded from the +innermost subscript first, as each expansion is encountered left to +right in the outer expression. + +A further complication arises from a way in which subscript parsing is +_not_ different from double quote parsing. As in true double-quoting, +the sequences `\*', and `\@' remain as two characters when they appear +in a subscript expression. To use a literal `*' or `@' as an +associative array key, the `e' flag must be used: + + + typeset -A aa + aa[(e)*]=star + print $aa[(e)*] + +A last detail must be considered when reverse subscripting is performed. +Parameters appearing in the subscript expression are first expanded and +then the complete expression is interpreted as a pattern. This has two +effects: first, parameters behave as if GLOB_SUBST were on (and it +cannot be turned off); second, backslashes are interpreted twice, once +when parsing the array subscript and again when parsing the pattern. +In a reverse subscript, it's necessary to use _four_ backslashes to +cause a single backslash to match literally in the pattern. For +complex patterns, it is often easiest to assign the desired pattern to +a parameter and then refer to that parameter in the subscript, because +then the backslashes, brackets, parentheses, etc., are seen only when +the complete expression is converted to a pattern. To match the value +of a parameter literally in a reverse subscript, rather than as a +pattern, use `${(q)NAME}' (*Note Parameter Expansion::) to quote the +expanded value. + +Note that the `k' and `K' flags are reverse subscripting for an +ordinary array, but are _not_ reverse subscripting for an associative +array! (For an associative array, the keys in the array itself are +interpreted as patterns by those flags; the subscript is a plain string +in that case.) + +One final note, not directly related to subscripting: the numeric names +of positional parameters (*Note Positional Parameters::) are parsed +specially, so for example `$2foo' is equivalent to `${2}foo'. +Therefore, to use subscript syntax to extract a substring from a +positional parameter, the expansion must be surrounded by braces; for +example, `${2[3,5]}' evaluates to the third through fifth characters of +the second positional parameter, but `$2[3,5]' is the entire second +parameter concatenated with the filename generation pattern `[3,5]'. + + + + +File: zsh.info, Node: Positional Parameters, Next: Local Parameters, Prev: Array Parameters, Up: Parameters + +15.3 Positional Parameters +========================== + +The positional parameters provide access to the command-line arguments +of a shell function, shell script, or the shell itself; see *Note +Invocation::, and also *Note Functions::. The parameter N, where N is +a number, is the Nth positional parameter. The parameter `$0' is a +special case, see *Note Parameters Set By The Shell::. + +The parameters *, @ and argv are arrays containing all the positional +parameters; thus `$argv[N]', etc., is equivalent to simply `$N'. Note +that the options KSH_ARRAYS or KSH_ZERO_SUBSCRIPT apply to these arrays +as well, so with either of those options set, `${argv[0]}' is +equivalent to `$1' and so on. + +Positional parameters may be changed after the shell or function starts +by using the set builtin, by assigning to the argv array, or by direct +assignment of the form `N=VALUE' where N is the number of the +positional parameter to be changed. This also creates (with empty +values) any of the positions from 1 to N that do not already have +values. Note that, because the positional parameters form an array, an +array assignment of the form `N=(VALUE ...)' is allowed, and has the +effect of shifting all the values at positions greater than N by as +many positions as necessary to accommodate the new values. + + + + +File: zsh.info, Node: Local Parameters, Next: Parameters Set By The Shell, Prev: Positional Parameters, Up: Parameters + +15.4 Local Parameters +===================== + +Shell function executions delimit scopes for shell parameters. +(Parameters are dynamically scoped.) The typeset builtin, and its +alternative forms declare, integer, local and readonly (but not +export), can be used to declare a parameter as being local to the +innermost scope. + +When a parameter is read or assigned to, the innermost existing +parameter of that name is used. (That is, the local parameter hides +any less-local parameter.) However, assigning to a non-existent +parameter, or declaring a new parameter with export, causes it to be +created in the _outer_most scope. + +Local parameters disappear when their scope ends. unset can be used to +delete a parameter while it is still in scope; any outer parameter of +the same name remains hidden. + +Special parameters may also be made local; they retain their special +attributes unless either the existing or the newly-created parameter +has the -h (hide) attribute. This may have unexpected effects: there +is no default value, so if there is no assignment at the point the +variable is made local, it will be set to an empty value (or zero in +the case of integers). The following: + + + typeset PATH=/new/directory:$PATH + +is valid for temporarily allowing the shell or programmes called from +it to find the programs in /new/directory inside a function. + +Note that the restriction in older versions of zsh that local parameters +were never exported has been removed. + + + + +File: zsh.info, Node: Parameters Set By The Shell, Next: Parameters Used By The Shell, Prev: Local Parameters, Up: Parameters + +15.5 Parameters Set By The Shell +================================ + +In the parameter lists that follow, the mark `<S>' indicates that the +parameter is special. `<Z>' indicates that the parameter does not exist +when the shell initializes in sh or ksh emulation mode. + +The following parameters are automatically set by the shell: + + +! <S> + The process ID of the last command started in the background with + &, put into the background with the bg builtin, or spawned with + coproc. + +# <S> + The number of positional parameters in decimal. Note that some + confusion may occur with the syntax $#PARAM which substitutes the + length of PARAM. Use ${#} to resolve ambiguities. In particular, + the sequence `$#-...' in an arithmetic expression is interpreted as + the length of the parameter -, q.v. + +ARGC <S> <Z> + Same as #. + +$ <S> + The process ID of this shell. Note that this indicates the + original shell started by invoking zsh; all processes forked from + the shells without executing a new program, such as subshells + started by (...), substitute the same value. + +- <S> + Flags supplied to the shell on invocation or by the set or setopt + commands. + +* <S> + An array containing the positional parameters. + +argv <S> <Z> + Same as *. Assigning to argv changes the local positional + parameters, but argv is _not_ itself a local parameter. Deleting + argv with unset in any function deletes it everywhere, although + only the innermost positional parameter array is deleted (so * and + @ in other scopes are not affected). + +@ <S> + Same as argv[@], even when argv is not set. + +? <S> + The exit status returned by the last command. + +0 <S> + The name used to invoke the current shell, or as set by the -c + command line option upon invocation. If the FUNCTION_ARGZERO + option is set, $0 is set upon entry to a shell function to the + name of the function, and upon entry to a sourced script to the + name of the script, and reset to its previous value when the + function or script returns. + +status <S> <Z> + Same as ?. + +pipestatus <S> <Z> + An array containing the exit statuses returned by all commands in + the last pipeline. + +_ <S> + The last argument of the previous command. Also, this parameter + is set in the environment of every command executed to the full + pathname of the command. + +CPUTYPE + The machine type (microprocessor class or machine model), as + determined at run time. + +EGID <S> + The effective group ID of the shell process. If you have + sufficient privileges, you may change the effective group ID of + the shell process by assigning to this parameter. Also (assuming + sufficient privileges), you may start a single command with a + different effective group ID by `(EGID=GID; command)' + + If this is made local, it is not implicitly set to 0, but may be + explicitly set locally. + +EUID <S> + The effective user ID of the shell process. If you have sufficient + privileges, you may change the effective user ID of the shell + process by assigning to this parameter. Also (assuming sufficient + privileges), you may start a single command with a different + effective user ID by `(EUID=UID; command)' + + If this is made local, it is not implicitly set to 0, but may be + explicitly set locally. + +ERRNO <S> + The value of errno (see man page errno(3)) as set by the most + recently failed system call. This value is system dependent and + is intended for debugging purposes. It is also useful with the + zsh/system module which allows the number to be turned into a name + or message. + +FUNCNEST <S> + Integer. If greater than or equal to zero, the maximum nesting + depth of shell functions. When it is exceeded, an error is raised + at the point where a function is called. The default value is + determined when the shell is configured, but is typically 500. + Increasing the value increases the danger of a runaway function + recursion causing the shell to crash. Setting a negative value + turns off the check. + +GID <S> + The real group ID of the shell process. If you have sufficient + privileges, you may change the group ID of the shell process by + assigning to this parameter. Also (assuming sufficient + privileges), you may start a single command under a different + group ID by `(GID=GID; command)' + + If this is made local, it is not implicitly set to 0, but may be + explicitly set locally. + +HISTCMD + The current history event number in an interactive shell, in other + words the event number for the command that caused $HISTCMD to be + read. If the current history event modifies the history, HISTCMD + changes to the new maximum history event number. + +HOST + The current hostname. + +LINENO <S> + The line number of the current line within the current script, + sourced file, or shell function being executed, whichever was + started most recently. Note that in the case of shell functions + the line number refers to the function as it appeared in the + original definition, not necessarily as displayed by the functions + builtin. + +LOGNAME + If the corresponding variable is not set in the environment of the + shell, it is initialized to the login name corresponding to the + current login session. This parameter is exported by default but + this can be disabled using the typeset builtin. The value is set + to the string returned by the man page getlogin(3) system call if + that is available. + +MACHTYPE + The machine type (microprocessor class or machine model), as + determined at compile time. + +OLDPWD + The previous working directory. This is set when the shell + initializes and whenever the directory changes. + +OPTARG <S> + The value of the last option argument processed by the getopts + command. + +OPTIND <S> + The index of the last option argument processed by the getopts + command. + +OSTYPE + The operating system, as determined at compile time. + +PPID <S> + The process ID of the parent of the shell. As for $$, the value + indicates the parent of the original shell and does not change in + subshells. + +PWD + The present working directory. This is set when the shell + initializes and whenever the directory changes. + +RANDOM <S> + A pseudo-random integer from 0 to 32767, newly generated each time + this parameter is referenced. The random number generator can be + seeded by assigning a numeric value to RANDOM. + + The values of RANDOM form an intentionally-repeatable pseudo-random + sequence; subshells that reference RANDOM will result in identical + pseudo-random values unless the value of RANDOM is referenced or + seeded in the parent shell in between subshell invocations. + +SECONDS <S> + The number of seconds since shell invocation. If this parameter + is assigned a value, then the value returned upon reference will + be the value that was assigned plus the number of seconds since + the assignment. + + Unlike other special parameters, the type of the SECONDS parameter + can be changed using the typeset command. Only integer and one of + the floating point types are allowed. For example, `typeset -F + SECONDS' causes the value to be reported as a floating point + number. The value is available to microsecond accuracy, although + the shell may show more or fewer digits depending on the use of + typeset. See the documentation for the builtin typeset in *Note + Shell Builtin Commands:: for more details. + +SHLVL <S> + Incremented by one each time a new shell is started. + +signals + An array containing the names of the signals. Note that with the + standard zsh numbering of array indices, where the first element + has index 1, the signals are offset by 1 from the signal number + used by the operating system. For example, on typical Unix-like + systems HUP is signal number 1, but is referred to as $signals[2]. + This is because of EXIT at position 1 in the array, which is used + internally by zsh but is not known to the operating system. + +TRY_BLOCK_ERROR <S> + In an always block, indicates whether the preceding list of code + caused an error. The value is 1 to indicate an error, 0 otherwise. + It may be reset, clearing the error condition. See *Note Complex + Commands:: + +TRY_BLOCK_INTERRUPT <S> + This variable works in a similar way to TRY_BLOCK_ERROR, but + represents the status of an interrupt from the signal SIGINT, which + typically comes from the keyboard when the user types ^C. If set + to 0, any such interrupt will be reset; otherwise, the interrupt is + propagated after the always block. + + Note that it is possible that an interrupt arrives during the + execution of the always block; this interrupt is also propagated. + +TTY + The name of the tty associated with the shell, if any. + +TTYIDLE <S> + The idle time of the tty associated with the shell in seconds or + -1 if there is no such tty. + +UID <S> + The real user ID of the shell process. If you have sufficient + privileges, you may change the user ID of the shell by assigning + to this parameter. Also (assuming sufficient privileges), you may + start a single command under a different user ID by `(UID=UID; + command)' + + If this is made local, it is not implicitly set to 0, but may be + explicitly set locally. + +USERNAME <S> + The username corresponding to the real user ID of the shell + process. If you have sufficient privileges, you may change the + username (and also the user ID and group ID) of the shell by + assigning to this parameter. Also (assuming sufficient + privileges), you may start a single command under a different + username (and user ID and group ID) by `(USERNAME=USERNAME; + command)' + +VENDOR + The vendor, as determined at compile time. + +zsh_eval_context <S> <Z> (ZSH_EVAL_CONTEXT <S>) + An array (colon-separated list) indicating the context of shell + code that is being run. Each time a piece of shell code that is + stored within the shell is executed a string is temporarily + appended to the array to indicate the type of operation that is + being performed. Read in order the array gives an indication of + the stack of operations being performed with the most immediate + context last. + + Note that the variable does not give information on syntactic + context such as pipelines or subshells. Use $ZSH_SUBSHELL to + detect subshells. + + The context is one of the following: + cmdarg + Code specified by the -c option to the command line that + invoked the shell. + + cmdsubst + Command substitution using the `...` or $(...) construct. + + equalsubst + File substitution using the =(...) construct. + + eval + Code executed by the eval builtin. + + evalautofunc + Code executed with the KSH_AUTOLOAD mechanism in order to + define an autoloaded function. + + fc + Code from the shell history executed by the -e option to the + fc builtin. + + file + Lines of code being read directly from a file, for example by + the source builtin. + + filecode + Lines of code being read from a .zwc file instead of directly + from the source file. + + globqual + Code executed by the e or + glob qualifier. + + globsort + Code executed to order files by the o glob qualifier. + + insubst + File substitution using the <(...) construct. + + loadautofunc + Code read directly from a file to define an autoloaded + function. + + outsubst + File substitution using the >(...) construct. + + sched + Code executed by the sched builtin. + + shfunc + A shell function. + + stty + Code passed to stty by the STTY environment variable. + Normally this is passed directly to the system's stty command, + so this value is unlikely to be seen in practice. + + style + Code executed as part of a style retrieved by the zstyle + builtin from the zsh/zutil module. + + toplevel + The highest execution level of a script or interactive shell. + + trap + Code executed as a trap defined by the trap builtin. Traps + defined as functions have the context shfunc. As traps are + asynchronous they may have a different hierarchy from other + code. + + zpty + Code executed by the zpty builtin from the zsh/zpty module. + + zregexparse-guard + Code executed as a guard by the zregexparse command from the + zsh/zutil module. + + zregexparse-action + Code executed as an action by the zregexparse command from the + zsh/zutil module. + + +ZSH_ARGZERO + If zsh was invoked to run a script, this is the name of the script. + Otherwise, it is the name used to invoke the current shell. This + is the same as the value of $0 when the POSIX_ARGZERO option is + set, but is always available. + +ZSH_EXECUTION_STRING + If the shell was started with the option -c, this contains the + argument passed to the option. Otherwise it is not set. + +ZSH_NAME + Expands to the basename of the command used to invoke this instance + of zsh. + +ZSH_PATCHLEVEL + The output of `git describe -tags -long' for the zsh repository + used to build the shell. This is most useful in order to keep + track of versions of the shell during development between releases; + hence most users should not use it and should instead rely on + $ZSH_VERSION. + +zsh_scheduled_events + See *Note The zsh/sched Module::. + +ZSH_SCRIPT + If zsh was invoked to run a script, this is the name of the script, + otherwise it is unset. + +ZSH_SUBSHELL + Readonly integer. Initially zero, incremented each time the shell + forks to create a subshell for executing code. Hence `(print + $ZSH_SUBSHELL)' and `print $(print $ZSH_SUBSHELL)' output 1, while + `( (print $ZSH_SUBSHELL) )' outputs 2. + +ZSH_VERSION + The version number of the release of zsh. + + |