diff options
121 files changed, 102989 insertions, 146 deletions
diff --git a/Doc/Zsh/manmodmenu.yo b/Doc/Zsh/manmodmenu.yo new file mode 100644 index 000000000..e91a5ce3d --- /dev/null +++ b/Doc/Zsh/manmodmenu.yo @@ -0,0 +1,37 @@ +menu(The zsh/attr Module) +menu(The zsh/cap Module) +menu(The zsh/clone Module) +menu(The zsh/compctl Module) +menu(The zsh/complete Module) +menu(The zsh/complist Module) +menu(The zsh/computil Module) +menu(The zsh/curses Module) +menu(The zsh/datetime Module) +menu(The zsh/db/gdbm Module) +menu(The zsh/deltochar Module) +menu(The zsh/example Module) +menu(The zsh/files Module) +menu(The zsh/langinfo Module) +menu(The zsh/mapfile Module) +menu(The zsh/mathfunc Module) +menu(The zsh/nearcolor Module) +menu(The zsh/newuser Module) +menu(The zsh/parameter Module) +menu(The zsh/pcre Module) +menu(The zsh/param/private Module) +menu(The zsh/regex Module) +menu(The zsh/sched Module) +menu(The zsh/net/socket Module) +menu(The zsh/stat Module) +menu(The zsh/system Module) +menu(The zsh/net/tcp Module) +menu(The zsh/termcap Module) +menu(The zsh/terminfo Module) +menu(The zsh/watch Module) +menu(The zsh/zftp Module) +menu(The zsh/zle Module) +menu(The zsh/zleparameter Module) +menu(The zsh/zprof Module) +menu(The zsh/zpty Module) +menu(The zsh/zselect Module) +menu(The zsh/zutil Module) diff --git a/Doc/Zsh/modlist.yo b/Doc/Zsh/modlist.yo new file mode 100644 index 000000000..d066879a9 --- /dev/null +++ b/Doc/Zsh/modlist.yo @@ -0,0 +1,227 @@ +startitem() +item(tt(zsh/attr))( +Builtins for manipulating extended attributes (xattr). +) +item(tt(zsh/cap))( +Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege) sets. +) +item(tt(zsh/clone))( +A builtin that can clone a running shell onto another terminal. +) +item(tt(zsh/compctl))( +The tt(compctl) builtin for controlling completion. +) +item(tt(zsh/complete))( +The basic completion code. +) +item(tt(zsh/complist))( +Completion listing extensions. +) +item(tt(zsh/computil))( +A module with utility builtins needed for the shell function based +completion system. +) +item(tt(zsh/curses))( +curses windowing commands +) +item(tt(zsh/datetime))( +Some date/time commands and parameters. +) +item(tt(zsh/db/gdbm))( +Builtins for managing associative array parameters tied to GDBM databases. +) +item(tt(zsh/deltochar))( +A ZLE function duplicating EMACS' tt(zap-to-char). +) +item(tt(zsh/example))( +An example of how to write a module. +) +item(tt(zsh/files))( +Some basic file manipulation commands as builtins. +) +item(tt(zsh/langinfo))( +Interface to locale information. +) +item(tt(zsh/mapfile))( +Access to external files via a special associative array. +) +item(tt(zsh/mathfunc))( +Standard scientific functions for use in mathematical evaluations. +) +item(tt(zsh/nearcolor))( +Map colours to the nearest colour in the available palette. +) +item(tt(zsh/newuser))( +Arrange for files for new users to be installed. +) +item(tt(zsh/parameter))( +Access to internal hash tables via special associative arrays. +) +item(tt(zsh/pcre))( +Interface to the PCRE library. +) +item(tt(zsh/param/private))( +Builtins for managing private-scoped parameters in function context. +) +item(tt(zsh/regex))( +Interface to the POSIX regex library. +) +item(tt(zsh/sched))( +A builtin that provides a timed execution facility within the shell. +) +item(tt(zsh/net/socket))( +Manipulation of Unix domain sockets +) +item(tt(zsh/stat))( +A builtin command interface to the tt(stat) system call. +) +item(tt(zsh/system))( +A builtin interface to various low-level system features. +) +item(tt(zsh/net/tcp))( +Manipulation of TCP sockets +) +item(tt(zsh/termcap))( +Interface to the termcap database. +) +item(tt(zsh/terminfo))( +Interface to the terminfo database. +) +item(tt(zsh/watch))( +Reporting of login and logout events. +) +item(tt(zsh/zftp))( +A builtin FTP client. +) +item(tt(zsh/zle))( +The Zsh Line Editor, including the tt(bindkey) and tt(vared) builtins. +) +item(tt(zsh/zleparameter))( +Access to internals of the Zsh Line Editor via parameters. +) +item(tt(zsh/zprof))( +A module allowing profiling for shell functions. +) +item(tt(zsh/zpty))( +A builtin for starting a command in a pseudo-terminal. +) +item(tt(zsh/zselect))( +Block and return when file descriptors are ready. +) +item(tt(zsh/zutil))( +Some utility builtins, e.g. the one for supporting configuration via +styles. +) +enditem() +includefile(Zsh/modmenu.yo) +texinode(The zsh/attr Module)(The zsh/cap Module)()(Zsh Modules) +sect(The zsh/attr Module) +includefile(Zsh/mod_attr.yo) +texinode(The zsh/cap Module)(The zsh/clone Module)(The zsh/attr Module)(Zsh Modules) +sect(The zsh/cap Module) +includefile(Zsh/mod_cap.yo) +texinode(The zsh/clone Module)(The zsh/compctl Module)(The zsh/cap Module)(Zsh Modules) +sect(The zsh/clone Module) +includefile(Zsh/mod_clone.yo) +texinode(The zsh/compctl Module)(The zsh/complete Module)(The zsh/clone Module)(Zsh Modules) +sect(The zsh/compctl Module) +includefile(Zsh/mod_compctl.yo) +texinode(The zsh/complete Module)(The zsh/complist Module)(The zsh/compctl Module)(Zsh Modules) +sect(The zsh/complete Module) +includefile(Zsh/mod_complete.yo) +texinode(The zsh/complist Module)(The zsh/computil Module)(The zsh/complete Module)(Zsh Modules) +sect(The zsh/complist Module) +includefile(Zsh/mod_complist.yo) +texinode(The zsh/computil Module)(The zsh/curses Module)(The zsh/complist Module)(Zsh Modules) +sect(The zsh/computil Module) +includefile(Zsh/mod_computil.yo) +texinode(The zsh/curses Module)(The zsh/datetime Module)(The zsh/computil Module)(Zsh Modules) +sect(The zsh/curses Module) +includefile(Zsh/mod_curses.yo) +texinode(The zsh/datetime Module)(The zsh/db/gdbm Module)(The zsh/curses Module)(Zsh Modules) +sect(The zsh/datetime Module) +includefile(Zsh/mod_datetime.yo) +texinode(The zsh/db/gdbm Module)(The zsh/deltochar Module)(The zsh/datetime Module)(Zsh Modules) +sect(The zsh/db/gdbm Module) +includefile(Zsh/mod_db_gdbm.yo) +texinode(The zsh/deltochar Module)(The zsh/example Module)(The zsh/db/gdbm Module)(Zsh Modules) +sect(The zsh/deltochar Module) +includefile(Zsh/mod_deltochar.yo) +texinode(The zsh/example Module)(The zsh/files Module)(The zsh/deltochar Module)(Zsh Modules) +sect(The zsh/example Module) +includefile(Zsh/mod_example.yo) +texinode(The zsh/files Module)(The zsh/langinfo Module)(The zsh/example Module)(Zsh Modules) +sect(The zsh/files Module) +includefile(Zsh/mod_files.yo) +texinode(The zsh/langinfo Module)(The zsh/mapfile Module)(The zsh/files Module)(Zsh Modules) +sect(The zsh/langinfo Module) +includefile(Zsh/mod_langinfo.yo) +texinode(The zsh/mapfile Module)(The zsh/mathfunc Module)(The zsh/langinfo Module)(Zsh Modules) +sect(The zsh/mapfile Module) +includefile(Zsh/mod_mapfile.yo) +texinode(The zsh/mathfunc Module)(The zsh/nearcolor Module)(The zsh/mapfile Module)(Zsh Modules) +sect(The zsh/mathfunc Module) +includefile(Zsh/mod_mathfunc.yo) +texinode(The zsh/nearcolor Module)(The zsh/newuser Module)(The zsh/mathfunc Module)(Zsh Modules) +sect(The zsh/nearcolor Module) +includefile(Zsh/mod_nearcolor.yo) +texinode(The zsh/newuser Module)(The zsh/parameter Module)(The zsh/nearcolor Module)(Zsh Modules) +sect(The zsh/newuser Module) +includefile(Zsh/mod_newuser.yo) +texinode(The zsh/parameter Module)(The zsh/pcre Module)(The zsh/newuser Module)(Zsh Modules) +sect(The zsh/parameter Module) +includefile(Zsh/mod_parameter.yo) +texinode(The zsh/pcre Module)(The zsh/param/private Module)(The zsh/parameter Module)(Zsh Modules) +sect(The zsh/pcre Module) +includefile(Zsh/mod_pcre.yo) +texinode(The zsh/param/private Module)(The zsh/regex Module)(The zsh/pcre Module)(Zsh Modules) +sect(The zsh/param/private Module) +includefile(Zsh/mod_private.yo) +texinode(The zsh/regex Module)(The zsh/sched Module)(The zsh/param/private Module)(Zsh Modules) +sect(The zsh/regex Module) +includefile(Zsh/mod_regex.yo) +texinode(The zsh/sched Module)(The zsh/net/socket Module)(The zsh/regex Module)(Zsh Modules) +sect(The zsh/sched Module) +includefile(Zsh/mod_sched.yo) +texinode(The zsh/net/socket Module)(The zsh/stat Module)(The zsh/sched Module)(Zsh Modules) +sect(The zsh/net/socket Module) +includefile(Zsh/mod_socket.yo) +texinode(The zsh/stat Module)(The zsh/system Module)(The zsh/net/socket Module)(Zsh Modules) +sect(The zsh/stat Module) +includefile(Zsh/mod_stat.yo) +texinode(The zsh/system Module)(The zsh/net/tcp Module)(The zsh/stat Module)(Zsh Modules) +sect(The zsh/system Module) +includefile(Zsh/mod_system.yo) +texinode(The zsh/net/tcp Module)(The zsh/termcap Module)(The zsh/system Module)(Zsh Modules) +sect(The zsh/net/tcp Module) +includefile(Zsh/mod_tcp.yo) +texinode(The zsh/termcap Module)(The zsh/terminfo Module)(The zsh/net/tcp Module)(Zsh Modules) +sect(The zsh/termcap Module) +includefile(Zsh/mod_termcap.yo) +texinode(The zsh/terminfo Module)(The zsh/watch Module)(The zsh/termcap Module)(Zsh Modules) +sect(The zsh/terminfo Module) +includefile(Zsh/mod_terminfo.yo) +texinode(The zsh/watch Module)(The zsh/zftp Module)(The zsh/terminfo Module)(Zsh Modules) +sect(The zsh/watch Module) +includefile(Zsh/mod_watch.yo) +texinode(The zsh/zftp Module)(The zsh/zle Module)(The zsh/watch Module)(Zsh Modules) +sect(The zsh/zftp Module) +includefile(Zsh/mod_zftp.yo) +texinode(The zsh/zle Module)(The zsh/zleparameter Module)(The zsh/zftp Module)(Zsh Modules) +sect(The zsh/zle Module) +includefile(Zsh/mod_zle.yo) +texinode(The zsh/zleparameter Module)(The zsh/zprof Module)(The zsh/zle Module)(Zsh Modules) +sect(The zsh/zleparameter Module) +includefile(Zsh/mod_zleparameter.yo) +texinode(The zsh/zprof Module)(The zsh/zpty Module)(The zsh/zleparameter Module)(Zsh Modules) +sect(The zsh/zprof Module) +includefile(Zsh/mod_zprof.yo) +texinode(The zsh/zpty Module)(The zsh/zselect Module)(The zsh/zprof Module)(Zsh Modules) +sect(The zsh/zpty Module) +includefile(Zsh/mod_zpty.yo) +texinode(The zsh/zselect Module)(The zsh/zutil Module)(The zsh/zpty Module)(Zsh Modules) +sect(The zsh/zselect Module) +includefile(Zsh/mod_zselect.yo) +texinode(The zsh/zutil Module)()(The zsh/zselect Module)(Zsh Modules) +sect(The zsh/zutil Module) +includefile(Zsh/mod_zutil.yo) diff --git a/Doc/Zsh/modmenu.yo b/Doc/Zsh/modmenu.yo new file mode 100644 index 000000000..c922390a4 --- /dev/null +++ b/Doc/Zsh/modmenu.yo @@ -0,0 +1,39 @@ +startmenu() +menu(The zsh/attr Module) +menu(The zsh/cap Module) +menu(The zsh/clone Module) +menu(The zsh/compctl Module) +menu(The zsh/complete Module) +menu(The zsh/complist Module) +menu(The zsh/computil Module) +menu(The zsh/curses Module) +menu(The zsh/datetime Module) +menu(The zsh/db/gdbm Module) +menu(The zsh/deltochar Module) +menu(The zsh/example Module) +menu(The zsh/files Module) +menu(The zsh/langinfo Module) +menu(The zsh/mapfile Module) +menu(The zsh/mathfunc Module) +menu(The zsh/nearcolor Module) +menu(The zsh/newuser Module) +menu(The zsh/parameter Module) +menu(The zsh/pcre Module) +menu(The zsh/param/private Module) +menu(The zsh/regex Module) +menu(The zsh/sched Module) +menu(The zsh/net/socket Module) +menu(The zsh/stat Module) +menu(The zsh/system Module) +menu(The zsh/net/tcp Module) +menu(The zsh/termcap Module) +menu(The zsh/terminfo Module) +menu(The zsh/watch Module) +menu(The zsh/zftp Module) +menu(The zsh/zle Module) +menu(The zsh/zleparameter Module) +menu(The zsh/zprof Module) +menu(The zsh/zpty Module) +menu(The zsh/zselect Module) +menu(The zsh/zutil Module) +endmenu() diff --git a/Doc/help.txt b/Doc/help.txt new file mode 100644 index 000000000..c59000ef2 --- /dev/null +++ b/Doc/help.txt @@ -0,0 +1,17 @@ +exit bye +cd chdir +typeset declare +typeset float +fc history +typeset integer +typeset local +exit logout +print pushln +fc r +typeset readonly +hash rehash +whence type +unhash unalias +unhash unfunction +whence where +whence which diff --git a/Doc/help/alias b/Doc/help/alias new file mode 100644 index 000000000..a746af240 --- /dev/null +++ b/Doc/help/alias @@ -0,0 +1,48 @@ +alias [ {+|-}gmrsL ] [ name[=value] ... ] + For each name with a corresponding value, define an alias with + that value. A trailing space in value causes the next word to + be checked for alias expansion. If the -g flag is present, de- + fine a global alias; global aliases are expanded even if they do + not occur in command position: + + % perldoc --help 2>&1 | grep 'built-in functions' + -f Search Perl built-in functions + % alias -g HG='--help 2>&1 | grep' + % perldoc HG 'built-in functions' + -f Search Perl built-in functions + + If the -s flag is present, define a suffix alias: if the command + word on a command line is in the form `text.name', where text is + any non-empty string, it is replaced by the text `value + text.name'. Note that name is treated as a literal string, not + a pattern. A trailing space in value is not special in this + case. For example, + + alias -s ps='gv --' + + will cause the command `*.ps' to be expanded to `gv -- *.ps'. + As alias expansion is carried out earlier than globbing, the + `*.ps' will then be expanded. Suffix aliases constitute a dif- + ferent name space from other aliases (so in the above example it + is still possible to create an alias for the command ps) and the + two sets are never listed together. + + For each name with no value, print the value of name, if any. + With no arguments, print all currently defined aliases other + than suffix aliases. If the -m flag is given the arguments are + taken as patterns (they should be quoted to preserve them from + being interpreted as glob patterns), and the aliases matching + these patterns are printed. When printing aliases and one of + the -g, -r or -s flags is present, restrict the printing to + global, regular or suffix aliases, respectively; a regular alias + is one which is neither a global nor a suffix alias. Using `+' + instead of `-', or ending the option list with a single `+', + prevents the values of the aliases from being printed. + + If the -L flag is present, then print each alias in a manner + suitable for putting in a startup script. The exit status is + nonzero if a name (with no value) is given for which no alias + has been defined. + + For more on aliases, include common problems, see the section + ALIASING in zshmisc(1). diff --git a/Doc/help/autoload b/Doc/help/autoload new file mode 100644 index 000000000..bc3a0294b --- /dev/null +++ b/Doc/help/autoload @@ -0,0 +1,83 @@ +autoload [ {+|-}RTUXdkmrtWz ] [ -w ] [ name ... ] + See the section `Autoloading Functions' in zshmisc(1) for full + details. The fpath parameter will be searched to find the func- + tion definition when the function is first referenced. + + If name consists of an absolute path, the function is defined to + load from the file given (searching as usual for dump files in + the given location). The name of the function is the basename + (non-directory part) of the file. It is normally an error if + the function is not found in the given location; however, if the + option -d is given, searching for the function defaults to + $fpath. If a function is loaded by absolute path, any functions + loaded from it that are marked for autoload without an absolute + path have the load path of the parent function temporarily + prepended to $fpath. + + If the option -r or -R is given, the function is searched for + immediately and the location is recorded internally for use when + the function is executed; a relative path is expanded using the + value of $PWD. This protects against a change to $fpath after + the call to autoload. With -r, if the function is not found, it + is silently left unresolved until execution; with -R, an error + message is printed and command processing aborted immediately + the search fails, i.e. at the autoload command rather than at + function execution.. + + The flag -X may be used only inside a shell function. It causes + the calling function to be marked for autoloading and then imme- + diately loaded and executed, with the current array of posi- + tional parameters as arguments. This replaces the previous def- + inition of the function. If no function definition is found, an + error is printed and the function remains undefined and marked + for autoloading. If an argument is given, it is used as a di- + rectory (i.e. it does not include the name of the function) in + which the function is to be found; this may be combined with the + -d option to allow the function search to default to $fpath if + it is not in the given location. + + The flag +X attempts to load each name as an autoloaded func- + tion, but does not execute it. The exit status is zero (suc- + cess) if the function was not previously defined and a defini- + tion for it was found. This does not replace any existing defi- + nition of the function. The exit status is nonzero (failure) if + the function was already defined or when no definition was + found. In the latter case the function remains undefined and + marked for autoloading. If ksh-style autoloading is enabled, + the function created will contain the contents of the file plus + a call to the function itself appended to it, thus giving normal + ksh autoloading behaviour on the first call to the function. If + the -m flag is also given each name is treated as a pattern and + all functions already marked for autoload that match the pattern + are loaded. + + With the -t flag, turn on execution tracing; with -T, turn on + execution tracing only for the current function, turning it off + on entry to any called functions that do not also have tracing + enabled. + + With the -U flag, alias expansion is suppressed when the func- + tion is loaded. + + With the -w flag, the names are taken as names of files compiled + with the zcompile builtin, and all functions defined in them are + marked for autoloading. + + The flags -z and -k mark the function to be autoloaded using the + zsh or ksh style, as if the option KSH_AUTOLOAD were unset or + were set, respectively. The flags override the setting of the + option at the time the function is loaded. + + Note that the autoload command makes no attempt to ensure the + shell options set during the loading or execution of the file + have any particular value. For this, the emulate command can be + used: + + emulate zsh -c 'autoload -Uz func' + + arranges that when func is loaded the shell is in native zsh em- + ulation, and this emulation is also applied when func is run. + + Some of the functions of autoload are also provided by functions + -u or functions -U, but autoload is a more comprehensive inter- + face. diff --git a/Doc/help/bg b/Doc/help/bg new file mode 100644 index 000000000..fb5e5c527 --- /dev/null +++ b/Doc/help/bg @@ -0,0 +1,4 @@ +bg [ job ... ] +job ... & + Put each specified job in the background, or the current job if + none is specified. diff --git a/Doc/help/bindkey b/Doc/help/bindkey new file mode 100644 index 000000000..ceb9aaed2 --- /dev/null +++ b/Doc/help/bindkey @@ -0,0 +1,2 @@ +bindkey + See the section `Zle Builtins' in zshzle(1). diff --git a/Doc/help/break b/Doc/help/break new file mode 100644 index 000000000..63c0bf650 --- /dev/null +++ b/Doc/help/break @@ -0,0 +1,4 @@ +break [ n ] + Exit from an enclosing for, while, until, select or repeat loop. + If an arithmetic expression n is specified, then break n levels + instead of just one. diff --git a/Doc/help/builtin b/Doc/help/builtin new file mode 100644 index 000000000..60842df2e --- /dev/null +++ b/Doc/help/builtin @@ -0,0 +1,2 @@ +builtin name [ args ... ] + Executes the builtin name, with the given args. diff --git a/Doc/help/cap b/Doc/help/cap new file mode 100644 index 000000000..fe60b5bbb --- /dev/null +++ b/Doc/help/cap @@ -0,0 +1 @@ +cap See the section `The zsh/cap Module' in zshmodules(1). diff --git a/Doc/help/cd b/Doc/help/cd new file mode 100644 index 000000000..34c6ad936 --- /dev/null +++ b/Doc/help/cd @@ -0,0 +1,54 @@ +cd [ -qsLP ] [ arg ] +cd [ -qsLP ] old new +cd [ -qsLP ] {+|-}n + Change the current directory. In the first form, change the + current directory to arg, or to the value of $HOME if arg is not + specified. If arg is `-', change to the previous directory. + + Otherwise, if arg begins with a slash, attempt to change to the + directory given by arg. + + If arg does not begin with a slash, the behaviour depends on + whether the current directory `.' occurs in the list of directo- + ries contained in the shell parameter cdpath. If it does not, + first attempt to change to the directory arg under the current + directory, and if that fails but cdpath is set and contains at + least one element attempt to change to the directory arg under + each component of cdpath in turn until successful. If `.' oc- + curs in cdpath, then cdpath is searched strictly in order so + that `.' is only tried at the appropriate point. + + The order of testing cdpath is modified if the option POSIX_CD + is set, as described in the documentation for the option. + + If no directory is found, the option CDABLE_VARS is set, and a + parameter named arg exists whose value begins with a slash, + treat its value as the directory. In that case, the parameter + is added to the named directory hash table. + + The second form of cd substitutes the string new for the string + old in the name of the current directory, and tries to change to + this new directory. + + The third form of cd extracts an entry from the directory stack, + and changes to that directory. An argument of the form `+n' + identifies a stack entry by counting from the left of the list + shown by the dirs command, starting with zero. An argument of + the form `-n' counts from the right. If the PUSHD_MINUS option + is set, the meanings of `+' and `-' in this context are swapped. + If the POSIX_CD option is set, this form of cd is not recognised + and will be interpreted as the first form. + + If the -q (quiet) option is specified, the hook function chpwd + and the functions in the array chpwd_functions are not called. + This is useful for calls to cd that do not change the environ- + ment seen by an interactive user. + + If the -s option is specified, cd refuses to change the current + directory if the given pathname contains symlinks. If the -P + option is given or the CHASE_LINKS option is set, symbolic links + are resolved to their true values. If the -L option is given + symbolic links are retained in the directory (and not resolved) + regardless of the state of the CHASE_LINKS option. + +chdir Same as cd. diff --git a/Doc/help/clone b/Doc/help/clone new file mode 100644 index 000000000..a2f618b53 --- /dev/null +++ b/Doc/help/clone @@ -0,0 +1 @@ +clone See the section `The zsh/clone Module' in zshmodules(1). diff --git a/Doc/help/colon b/Doc/help/colon new file mode 100644 index 000000000..5f0c340eb --- /dev/null +++ b/Doc/help/colon @@ -0,0 +1,4 @@ +: [ arg ... ] + This command does nothing, although normal argument expansions + is performed which may have effects on shell parameters. A zero + exit status is returned. diff --git a/Doc/help/command b/Doc/help/command new file mode 100644 index 000000000..f81b08eaa --- /dev/null +++ b/Doc/help/command @@ -0,0 +1,10 @@ +command [ -pvV ] simple command + The simple command argument is taken as an external command in- + stead of a function or builtin and is executed. 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. + + See also the section `Precommand Modifiers' in zshmisc(1). diff --git a/Doc/help/comparguments b/Doc/help/comparguments new file mode 100644 index 000000000..10a2c0d01 --- /dev/null +++ b/Doc/help/comparguments @@ -0,0 +1,2 @@ +comparguments + See the section `The zsh/computil Module' in zshmodules(1). diff --git a/Doc/help/compcall b/Doc/help/compcall new file mode 100644 index 000000000..b483147ae --- /dev/null +++ b/Doc/help/compcall @@ -0,0 +1,2 @@ +compcall + See the section `The zsh/compctl Module' in zshmodules(1). diff --git a/Doc/help/compctl b/Doc/help/compctl new file mode 100644 index 000000000..281736816 --- /dev/null +++ b/Doc/help/compctl @@ -0,0 +1,2 @@ +compctl + See the section `The zsh/compctl Module' in zshmodules(1). diff --git a/Doc/help/compdescribe b/Doc/help/compdescribe new file mode 100644 index 000000000..0a81aa92b --- /dev/null +++ b/Doc/help/compdescribe @@ -0,0 +1,2 @@ +compdescribe + See the section `The zsh/computil Module' in zshmodules(1). diff --git a/Doc/help/compfiles b/Doc/help/compfiles new file mode 100644 index 000000000..14436f5dd --- /dev/null +++ b/Doc/help/compfiles @@ -0,0 +1,2 @@ +compfiles + See the section `The zsh/computil Module' in zshmodules(1). diff --git a/Doc/help/compgroups b/Doc/help/compgroups new file mode 100644 index 000000000..5126b18ce --- /dev/null +++ b/Doc/help/compgroups @@ -0,0 +1,2 @@ +compgroups + See the section `The zsh/computil Module' in zshmodules(1). diff --git a/Doc/help/compquote b/Doc/help/compquote new file mode 100644 index 000000000..bde5916c9 --- /dev/null +++ b/Doc/help/compquote @@ -0,0 +1,2 @@ +compquote + See the section `The zsh/computil Module' in zshmodules(1). diff --git a/Doc/help/comptags b/Doc/help/comptags new file mode 100644 index 000000000..a7ef796f8 --- /dev/null +++ b/Doc/help/comptags @@ -0,0 +1,2 @@ +comptags + See the section `The zsh/computil Module' in zshmodules(1). diff --git a/Doc/help/comptry b/Doc/help/comptry new file mode 100644 index 000000000..08ca4c151 --- /dev/null +++ b/Doc/help/comptry @@ -0,0 +1,2 @@ +comptry + See the section `The zsh/computil Module' in zshmodules(1). diff --git a/Doc/help/compvalues b/Doc/help/compvalues new file mode 100644 index 000000000..0d85bafd3 --- /dev/null +++ b/Doc/help/compvalues @@ -0,0 +1,2 @@ +compvalues + See the section `The zsh/computil Module' in zshmodules(1). diff --git a/Doc/help/continue b/Doc/help/continue new file mode 100644 index 000000000..ac0cadfa6 --- /dev/null +++ b/Doc/help/continue @@ -0,0 +1,5 @@ +continue [ n ] + Resume the next iteration of the enclosing for, while, until, + select or repeat loop. If an arithmetic expression n is speci- + fied, break out of n-1 loops and resume at the nth enclosing + loop. diff --git a/Doc/help/dirs b/Doc/help/dirs new file mode 100644 index 000000000..c2c8e0311 --- /dev/null +++ b/Doc/help/dirs @@ -0,0 +1,17 @@ +dirs [ -c ] [ arg ... ] +dirs [ -lpv ] + With no arguments, print the contents of the directory stack. + Directories are added to this stack with the pushd command, and + removed with the cd or popd commands. If arguments are speci- + fied, load them onto the directory stack, replacing anything + that was there, and push the current directory onto the stack. + + -c clear the directory stack. + + -l print directory names in full instead of using of using ~ + expressions (see Dynamic and Static named directories in + zshexpn(1)). + + -p print directory entries one per line. + + -v number the directories in the stack when printing. diff --git a/Doc/help/disable b/Doc/help/disable new file mode 100644 index 000000000..3d2e4a4f7 --- /dev/null +++ b/Doc/help/disable @@ -0,0 +1,85 @@ +disable [ -afmprs ] name ... + Temporarily disable the named hash table elements or patterns. + The default is to disable builtin commands. This allows you to + use an external command with the same name as a builtin command. + The -a option causes disable to act on regular or global + aliases. The -s option causes disable to act on suffix aliases. + The -f option causes disable to act on shell functions. The -r + options causes disable to act on reserved words. Without argu- + ments all disabled hash table elements from the corresponding + hash table are printed. With the -m flag the arguments are + taken as patterns (which should be quoted to prevent them from + undergoing filename expansion), and all hash table elements from + the corresponding hash table matching these patterns are dis- + abled. Disabled objects can be enabled with the enable command. + + With the option -p, name ... refer to elements of the shell's + pattern syntax as described in the section `Filename Genera- + tion'. Certain elements can be disabled separately, as given + below. + + Note that patterns not allowed by the current settings for the + options EXTENDED_GLOB, KSH_GLOB and SH_GLOB are never enabled, + regardless of the setting here. For example, if EXTENDED_GLOB + is not active, the pattern ^ is ineffective even if `disable -p + "^"' has not been issued. The list below indicates any option + settings that restrict the use of the pattern. It should be + noted that setting SH_GLOB has a wider effect than merely dis- + abling patterns as certain expressions, in particular those in- + volving parentheses, are parsed differently. + + The following patterns may be disabled; all the strings need + quoting on the command line to prevent them from being inter- + preted immediately as patterns and the patterns are shown below + in single quotes as a reminder. + + '?' The pattern character ? wherever it occurs, including + when preceding a parenthesis with KSH_GLOB. + + '*' The pattern character * wherever it occurs, including re- + cursive globbing and when preceding a parenthesis with + KSH_GLOB. + + '[' Character classes. + + '<' (NO_SH_GLOB) + Numeric ranges. + + '|' (NO_SH_GLOB) + Alternation in grouped patterns, case statements, or + KSH_GLOB parenthesised expressions. + + '(' (NO_SH_GLOB) + Grouping using single parentheses. Disabling this does + not disable the use of parentheses for KSH_GLOB where + they are introduced by a special character, nor for glob + qualifiers (use `setopt NO_BARE_GLOB_QUAL' to disable + glob qualifiers that use parentheses only). + + '~' (EXTENDED_GLOB) + Exclusion in the form A~B. + + '^' (EXTENDED_GLOB) + Exclusion in the form A^B. + + '#' (EXTENDED_GLOB) + The pattern character # wherever it occurs, both for rep- + etition of a previous pattern and for indicating globbing + flags. + + '?(' (KSH_GLOB) + The grouping form ?(...). Note this is also disabled if + '?' is disabled. + + '*(' (KSH_GLOB) + The grouping form *(...). Note this is also disabled if + '*' is disabled. + + '+(' (KSH_GLOB) + The grouping form +(...). + + '!(' (KSH_GLOB) + The grouping form !(...). + + '@(' (KSH_GLOB) + The grouping form @(...). diff --git a/Doc/help/disown b/Doc/help/disown new file mode 100644 index 000000000..254d641e9 --- /dev/null +++ b/Doc/help/disown @@ -0,0 +1,14 @@ +disown [ job ... ] +job ... &| +job ... &! + Remove the specified jobs from the job table; the shell will no + longer report their status, and will not complain if you try to + exit an interactive shell with them running or stopped. If no + job is specified, disown the current job. + + If the jobs are currently stopped and the AUTO_CONTINUE option + is not set, a warning is printed containing information about + how to make them running after they have been disowned. If one + of the latter two forms is used, the jobs will automatically be + made running, independent of the setting of the AUTO_CONTINUE + option. diff --git a/Doc/help/dot b/Doc/help/dot new file mode 100644 index 000000000..2d969a509 --- /dev/null +++ b/Doc/help/dot @@ -0,0 +1,22 @@ +. file [ arg ... ] + Read commands from file and execute them in the current shell + environment. + + If file does not contain a slash, or if PATH_DIRS is set, the + shell looks in the components of $path to find the directory + containing file. Files in the current directory are not read + unless `.' appears somewhere in $path. If a file named + `file.zwc' is found, is newer than file, and is the compiled + form (created with the zcompile builtin) of file, then commands + are read from that file instead of file. + + If any arguments arg are given, they become the positional pa- + rameters; the old positional parameters are restored when the + file is done executing. However, if no arguments are given, the + positional parameters remain those of the calling context, and + no restoring is done. + + If file was not found the return status is 127; if file was + found but contained a syntax error the return status is 126; + else the return status is the exit status of the last command + executed. diff --git a/Doc/help/echo b/Doc/help/echo new file mode 100644 index 000000000..24299d6f6 --- /dev/null +++ b/Doc/help/echo @@ -0,0 +1,33 @@ +echo [ -neE ] [ arg ... ] + Write each arg on the standard output, with a space separating + each one. If the -n flag is not present, print a newline at the + end. echo recognizes the following escape sequences: + + \a bell character + \b backspace + \c suppress subsequent characters and final newline + \e escape + \f form feed + \n linefeed (newline) + \r carriage return + \t horizontal tab + \v vertical tab + \\ backslash + \0NNN character code in octal + \xNN character code in hexadecimal + \uNNNN unicode character code in hexadecimal + \UNNNNNNNN + unicode character code in hexadecimal + + The -E flag, or the BSD_ECHO option, can be used to disable + these escape sequences. In the latter case, -e flag can be used + to enable them. + + Note that for standards compliance a double dash does not termi- + nate option processing; instead, it is printed directly. How- + ever, a single dash does terminate option processing, so the + first dash, possibly following options, is not printed, but ev- + erything following it is printed as an argument. The single + dash behaviour is different from other shells. For a more por- + table way of printing text, see printf, and for a more control- + lable way of printing text within zsh, see print. diff --git a/Doc/help/echotc b/Doc/help/echotc new file mode 100644 index 000000000..36f630f39 --- /dev/null +++ b/Doc/help/echotc @@ -0,0 +1 @@ +echotc See the section `The zsh/termcap Module' in zshmodules(1). diff --git a/Doc/help/echoti b/Doc/help/echoti new file mode 100644 index 000000000..042a8397b --- /dev/null +++ b/Doc/help/echoti @@ -0,0 +1 @@ +echoti See the section `The zsh/terminfo Module' in zshmodules(1). diff --git a/Doc/help/emulate b/Doc/help/emulate new file mode 100644 index 000000000..7bf402183 --- /dev/null +++ b/Doc/help/emulate @@ -0,0 +1,108 @@ +emulate [ -lLR ] [ {zsh|sh|ksh|csh} [ flags ... ] ] + Without any argument print current emulation mode. + + With single argument set up zsh options to emulate the specified + shell as much as possible. csh will never be fully emulated. + If the argument is not one of the shells listed above, zsh will + be used as a default; more precisely, the tests performed on the + argument are the same as those used to determine the emulation + at startup based on the shell name, see the section COMPATIBIL- + ITY in zsh(1) . In addition to setting shell options, the com- + mand also restores the pristine state of pattern enables, as if + all patterns had been enabled using enable -p. + + If the emulate command occurs inside a function that has been + marked for execution tracing with functions -t then the xtrace + option will be turned on regardless of emulation mode or other + options. Note that code executed inside the function by the ., + source, or eval commands is not considered to be running di- + rectly from the function, hence does not provoke this behaviour. + + If the -R switch is given, all settable options are reset to + their default value corresponding to the specified emulation + mode, except for certain options describing the interactive en- + vironment; otherwise, only those options likely to cause porta- + bility problems in scripts and functions are altered. If the -L + switch is given, the options LOCAL_OPTIONS, LOCAL_PATTERNS and + LOCAL_TRAPS will be set as well, causing the effects of the emu- + late command and any setopt, disable -p or enable -p, and trap + commands to be local to the immediately surrounding shell func- + tion, if any; normally these options are turned off in all emu- + lation modes except ksh. The -L switch is mutually exclusive + with the use of -c in flags. + + If there is a single argument and the -l switch is given, the + options that would be set or unset (the latter indicated with + the prefix `no') are listed. -l can be combined with -L or -R + and the list will be modified in the appropriate way. Note the + list does not depend on the current setting of options, i.e. it + includes all options that may in principle change, not just + those that would actually change. + + The flags may be any of the invocation-time flags described in + the section INVOCATION in zsh(1), except that `-o EMACS' and `-o + VI' may not be used. Flags such as `+r'/`+o RESTRICTED' may be + prohibited in some circumstances. + + If -c arg appears in flags, arg is evaluated while the requested + emulation is temporarily in effect. In this case the emulation + mode and all options are restored to their previous values be- + fore emulate returns. The -R switch may precede the name of the + shell to emulate; note this has a meaning distinct from includ- + ing -R in flags. + + Use of -c enables `sticky' emulation mode for functions defined + within the evaluated expression: the emulation mode is associ- + ated thereafter with the function so that whenever the function + is executed the emulation (respecting the -R switch, if present) + and all options are set (and pattern disables cleared) before + entry to the function, and the state is restored after exit. If + the function is called when the sticky emulation is already in + effect, either within an `emulate shell -c' expression or within + another function with the same sticky emulation, entry and exit + from the function do not cause options to be altered (except due + to standard processing such as the LOCAL_OPTIONS option). This + also applies to functions marked for autoload within the sticky + emulation; the appropriate set of options will be applied at the + point the function is loaded as well as when it is run. + + For example: + + emulate sh -c 'fni() { setopt cshnullglob; } + fno() { fni; }' + fno + + The two functions fni and fno are defined with sticky sh emula- + tion. fno is then executed, causing options associated with em- + ulations to be set to their values in sh. fno then calls fni; + because fni is also marked for sticky sh emulation, no option + changes take place on entry to or exit from it. Hence the op- + tion cshnullglob, turned off by sh emulation, will be turned on + within fni and remain on return to fno. On exit from fno, the + emulation mode and all options will be restored to the state + they were in before entry to the temporary emulation. + + The documentation above is typically sufficient for the intended + purpose of executing code designed for other shells in a suit- + able environment. More detailed rules follow. + 1. The sticky emulation environment provided by `emulate + shell -c' is identical to that provided by entry to a + function marked for sticky emulation as a consequence of + being defined in such an environment. Hence, for exam- + ple, the sticky emulation is inherited by subfunctions + defined within functions with sticky emulation. + 2. No change of options takes place on entry to or exit from + functions that are not marked for sticky emulation, other + than those that would normally take place, even if those + functions are called within sticky emulation. + 3. No special handling is provided for functions marked for + autoload nor for functions present in wordcode created by + the zcompile command. + 4. The presence or absence of the -R switch to emulate cor- + responds to different sticky emulation modes, so for ex- + ample `emulate sh -c', `emulate -R sh -c' and `emulate + csh -c' are treated as three distinct sticky emulations. + 5. Difference in shell options supplied in addition to the + basic emulation also mean the sticky emulations are dif- + ferent, so for example `emulate zsh -c' and `emulate zsh + -o cbases -c' are treated as distinct sticky emulations. diff --git a/Doc/help/enable b/Doc/help/enable new file mode 100644 index 000000000..ecf1329c3 --- /dev/null +++ b/Doc/help/enable @@ -0,0 +1,20 @@ +enable [ -afmprs ] name ... + Enable the named hash table elements, presumably disabled ear- + lier with disable. The default is to enable builtin commands. + The -a option causes enable to act on regular or global aliases. + The -s option causes enable to act on suffix aliases. The -f + option causes enable to act on shell functions. The -r option + causes enable to act on reserved words. Without arguments all + enabled hash table elements from the corresponding hash table + are printed. With the -m flag the arguments are taken as pat- + terns (should be quoted) and all hash table elements from the + corresponding hash table matching these patterns are enabled. + Enabled objects can be disabled with the disable builtin com- + mand. + + enable -p reenables patterns disabled with disable -p. Note + that it does not override globbing options; for example, `enable + -p "~"' does not cause the pattern character ~ to be active un- + less the EXTENDED_GLOB option is also set. To enable all possi- + ble patterns (so that they may be individually disabled with + disable -p), use `setopt EXTENDED_GLOB KSH_GLOB NO_SH_GLOB'. diff --git a/Doc/help/eval b/Doc/help/eval new file mode 100644 index 000000000..3c04cf307 --- /dev/null +++ b/Doc/help/eval @@ -0,0 +1,6 @@ +eval [ arg ... ] + Read the arguments as input to the shell and execute the result- + ing command(s) in the current shell process. The return status + is the same as if the commands had been executed directly by the + shell; if there are no args or they contain no commands (i.e. + are an empty string or whitespace) the return status is zero. diff --git a/Doc/help/exec b/Doc/help/exec new file mode 100644 index 000000000..baaddc642 --- /dev/null +++ b/Doc/help/exec @@ -0,0 +1,18 @@ +exec [ -cl ] [ -a argv0 ] [ command [ arg ... ] ] + Replace the current shell with command rather than forking. If + command is a shell builtin command or a shell function, the + shell executes it, and exits when the command is complete. + + With -c clear the environment; with -l prepend - to the argv[0] + string of the command executed (to simulate a login shell); with + -a argv0 set the argv[0] string of the command executed. See + the section `Precommand Modifiers' in zshmisc(1). + + If the option POSIX_BUILTINS is set, command is never inter- + preted as a shell builtin command or shell function. This means + further precommand modifiers such as builtin and noglob are also + not interpreted within the shell. Hence command is always found + by searching the command path. + + If command is omitted but any redirections are specified, then + the redirections will take effect in the current shell. diff --git a/Doc/help/exit b/Doc/help/exit new file mode 100644 index 000000000..04b5d6815 --- /dev/null +++ b/Doc/help/exit @@ -0,0 +1,13 @@ +exit [ n ] + Exit the shell with the exit status specified by an arithmetic + expression n; if none is specified, use the exit status from the + last command executed. An EOF condition will also cause the + shell to exit, unless the IGNORE_EOF option is set. + + See notes at the end of the section JOBS in zshmisc(1) for some + possibly unexpected interactions of the exit command with jobs. + +bye Same as exit. + +logout [ n ] + Same as exit, except that it only works in a login shell. diff --git a/Doc/help/export b/Doc/help/export new file mode 100644 index 000000000..88ec7fe1d --- /dev/null +++ b/Doc/help/export @@ -0,0 +1,5 @@ +export [ name[=value] ... ] + The specified names are marked for automatic export to the envi- + ronment of subsequently executed commands. Equivalent to type- + set -gx. If a parameter specified does not already exist, it is + created in the global scope. diff --git a/Doc/help/false b/Doc/help/false new file mode 100644 index 000000000..29e752045 --- /dev/null +++ b/Doc/help/false @@ -0,0 +1,2 @@ +false [ arg ... ] + Do nothing and return an exit status of 1. diff --git a/Doc/help/fc b/Doc/help/fc new file mode 100644 index 000000000..5a4b149e2 --- /dev/null +++ b/Doc/help/fc @@ -0,0 +1,113 @@ +fc [ -e ename ] [ -s ] [ -LI ] [ -m match ] [ old=new ... ] [ first [ +last ] ] +fc -l [ -LI ] [ -nrdfEiD ] [ -t timefmt ] [ -m match ] + [ old=new ... ] [ first [ last ] ] +fc -p [ -a ] [ filename [ histsize [ savehistsize ] ] ] +fc -P +fc -ARWI [ filename ] + The fc command controls the interactive history mechanism. Note + that reading and writing of history options is only performed if + the shell is interactive. Usually this is detected automati- + cally, but it can be forced by setting the interactive option + when starting the shell. + + The first two forms of this command select a range of events + from first to last from the history list. The arguments first + and last may be specified as a number or as a string. A nega- + tive number is used as an offset to the current history event + number. A string specifies the most recent event beginning with + the given string. All substitutions old=new, if any, are then + performed on the text of the events. + + The range of events selected by numbers can be narrowed further + by the following flags. + -I restricts to only internal events (not from $HISTFILE) + -L restricts to only local events (not from other shells, + see SHARE_HISTORY in zshoptions(1) -- note that $HISTFILE + is considered local when read at startup) + -m takes the first argument as a pattern (which should be + quoted) and only the history events matching this pattern + are considered + + If first is not specified, it will be set to -1 (the most recent + event), or to -16 if the -l flag is given. If last is not spec- + ified, it will be set to first, or to -1 if the -l flag is + given. However, if the current event has added entries to the + history with `print -s' or `fc -R', then the default last for -l + includes all new history entries since the current event began. + + When the -l flag is given, the resulting events are listed on + standard output. Otherwise the editor program specified by -e + ename is invoked on a file containing these history events. If + -e is not given, the value of the parameter FCEDIT is used; if + that is not set the value of the parameter EDITOR is used; if + that is not set a builtin default, usually `vi' is used. If + ename is `-', no editor is invoked. When editing is complete, + the edited command is executed. + + The flag `-s' is equivalent to `-e -'. The flag -r reverses the + order of the events and the flag -n suppresses event numbers + when listing. + + Also when listing, + -d prints timestamps for each event + -f prints full time-date stamps in the US `MM/DD/YY hh:mm' + format + -E prints full time-date stamps in the European `dd.mm.yyyy + hh:mm' format + -i prints full time-date stamps in ISO8601 `yyyy-mm-dd + hh:mm' format + -t fmt prints time and date stamps in the given format; fmt is + formatted with the strftime function with the zsh exten- + sions described for the %D{string} prompt format in the + section EXPANSION OF PROMPT SEQUENCES in zshmisc(1). The + resulting formatted string must be no more than 256 char- + acters or will not be printed + -D prints elapsed times; may be combined with one of the op- + tions above + + `fc -p' pushes the current history list onto a stack and + switches to a new history list. If the -a option is also speci- + fied, this history list will be automatically popped when the + current function scope is exited, which is a much better solu- + tion than creating a trap function to call `fc -P' manually. If + no arguments are specified, the history list is left empty, + $HISTFILE is unset, and $HISTSIZE & $SAVEHIST are set to their + default values. If one argument is given, $HISTFILE is set to + that filename, $HISTSIZE & $SAVEHIST are left unchanged, and the + history file is read in (if it exists) to initialize the new + list. If a second argument is specified, $HISTSIZE & $SAVEHIST + are instead set to the single specified numeric value. Finally, + if a third argument is specified, $SAVEHIST is set to a separate + value from $HISTSIZE. You are free to change these environment + values for the new history list however you desire in order to + manipulate the new history list. + + `fc -P' pops the history list back to an older list saved by `fc + -p'. The current list is saved to its $HISTFILE before it is + destroyed (assuming that $HISTFILE and $SAVEHIST are set appro- + priately, of course). The values of $HISTFILE, $HISTSIZE, and + $SAVEHIST are restored to the values they had when `fc -p' was + called. Note that this restoration can conflict with making + these variables "local", so your best bet is to avoid local dec- + larations for these variables in functions that use `fc -p'. + The one other guaranteed-safe combination is declaring these + variables to be local at the top of your function and using the + automatic option (-a) with `fc -p'. Finally, note that it is + legal to manually pop a push marked for automatic popping if you + need to do so before the function exits. + + `fc -R' reads the history from the given file, `fc -W' writes + the history out to the given file, and `fc -A' appends the his- + tory out to the given file. If no filename is specified, the + $HISTFILE is assumed. If the -I option is added to -R, only + those events that are not already contained within the internal + history list are added. If the -I option is added to -A or -W, + only those events that are new since last incremental ap- + pend/write to the history file are appended/written. In any + case, the created file will have no more than $SAVEHIST entries. + +history + Same as fc -l. + +r Same as fc -e -. diff --git a/Doc/help/fg b/Doc/help/fg new file mode 100644 index 000000000..da8897332 --- /dev/null +++ b/Doc/help/fg @@ -0,0 +1,4 @@ +fg [ job ... ] +job ... + Bring each specified job in turn to the foreground. If no job + is specified, resume the current job. diff --git a/Doc/help/functions b/Doc/help/functions new file mode 100644 index 000000000..cadbd0350 --- /dev/null +++ b/Doc/help/functions @@ -0,0 +1,115 @@ +functions [ {+|-}UkmtTuWz ] [ -x num ] [ name ... ] +functions -c oldfn newfn +functions -M [-s] mathfn [ min [ max [ shellfn ] ] ] +functions -M [ -m pattern ... ] +functions +M [ -m ] mathfn ... + Equivalent to typeset -f, with the exception of the -c, -x, -M + and -W options. For functions -u and functions -U, see au- + toload, which provides additional options. + + The -x option indicates that any functions output will have each + leading tab for indentation, added by the shell to show syntac- + tic structure, expanded to the given number num of spaces. num + can also be 0 to suppress all indentation. + + The -W option turns on the option WARN_NESTED_VAR for the named + function or functions only. The option is turned off at the + start of nested functions (apart from anonoymous functions) un- + less the called function also has the -W attribute. + + The -c option causes oldfn to be copied to newfn. The copy is + efficiently handled internally by reference counting. If oldfn + was marked for autoload it is first loaded and if this fails the + copy fails. Either function may subsequently be redefined with- + out affecting the other. A typical idiom is that oldfn is the + name of a library shell function which is then redefined to call + newfn, thereby installing a modified version of the function. + + The -M and +M flags + + Use of the -M option may not be combined with any of the options + handled by typeset -f. + + functions -M mathfn defines mathfn as the name of a mathematical + function recognised in all forms of arithmetical expressions; + see the section `Arithmetic Evaluation' in zshmisc(1). By de- + fault mathfn may take any number of comma-separated arguments. + If min is given, it must have exactly min args; if min and max + are both given, it must have at least min and at most max args. + max may be -1 to indicate that there is no upper limit. + + By default the function is implemented by a shell function of + the same name; if shellfn is specified it gives the name of the + corresponding shell function while mathfn remains the name used + in arithmetical expressions. The name of the function in $0 is + mathfn (not shellfn as would usually be the case), provided the + option FUNCTION_ARGZERO is in effect. The positional parameters + in the shell function correspond to the arguments of the mathe- + matical function call. + + The result of the last arithmetical expression evaluated inside + the shell function gives the result of the mathematical func- + tion. This is not limited to arithmetic substitutions of the + form $((...)), but also includes arithmetical expressions evalu- + ated in any other way, including by the let builtin, by ((...)) + statements, and even by the return builtin and by array sub- + scripts. Therefore, care must be taken not to use syntactical + constructs that perform arithmetic evaluation after evaluating + what is to be the result of the function. For example: + + # WRONG + zmath_cube() { + (( $1 * $1 * $1 )) + return 0 + } + functions -M cube 1 1 zmath_cube + print $(( cube(3) )) + + This will print `0' because of the return. + + Commenting the return out would lead to a different problem: the + ((...)) statement would become the last statement in the func- + tion, so the return status ($?) of the function would be + non-zero (indicating failure) whenever the arithmetic result of + the function would happen to be zero (numerically): + + # WRONG + zmath_cube() { + (( $1 * $1 * $1 )) + } + functions -M cube 1 1 zmath_cube + print $(( cube(0) )) + + Instead, the true builtin can be used: + + # RIGHT + zmath_cube() { + (( $1 * $1 * $1 )) + true + } + functions -M cube 1 1 zmath_cube + print $(( cube(3) )) + + If the additional option -s is given to functions -M, the argu- + ment to the function is a single string: anything between the + opening and matching closing parenthesis is passed to the func- + tion as a single argument, even if it includes commas or white + space. The minimum and maximum argument specifiers must there- + fore be 1 if given. An empty argument list is passed as a + zero-length string. Thus, the following string function takes a + single argument, including the commas, and prints 11: + + stringfn() { (( $#1 )); true } + functions -Ms stringfn + print $(( stringfn(foo,bar,rod) )) + + functions -M with no arguments lists all such user-defined func- + tions in the same form as a definition. With the additional op- + tion -m and a list of arguments, all functions whose mathfn + matches one of the pattern arguments are listed. + + function +M removes the list of mathematical functions; with the + additional option -m the arguments are treated as patterns and + all functions whose mathfn matches the pattern are removed. + Note that the shell function implementing the behaviour is not + removed (regardless of whether its name coincides with mathfn). diff --git a/Doc/help/getcap b/Doc/help/getcap new file mode 100644 index 000000000..3e4a51b21 --- /dev/null +++ b/Doc/help/getcap @@ -0,0 +1 @@ +getcap See the section `The zsh/cap Module' in zshmodules(1). diff --git a/Doc/help/getln b/Doc/help/getln new file mode 100644 index 000000000..88c938138 --- /dev/null +++ b/Doc/help/getln @@ -0,0 +1,3 @@ +getln [ -AclneE ] name ... + Read the top value from the buffer stack and put it in the shell + parameter name. Equivalent to read -zr. diff --git a/Doc/help/getopts b/Doc/help/getopts new file mode 100644 index 000000000..bb89d2f2a --- /dev/null +++ b/Doc/help/getopts @@ -0,0 +1,31 @@ +getopts optstring name [ arg ... ] + Checks the args for legal options. If the args are omitted, use + the positional parameters. A valid option argument begins with + a `+' or a `-'. An argument not beginning with a `+' or a `-', + or the argument `--', ends the options. Note that a single `-' + is not considered a valid option argument. optstring contains + the letters that getopts recognizes. If a letter is followed by + a `:', that option requires an argument. The options can be + separated from the argument by blanks. + + Each time it is invoked, getopts places the option letter it + finds in the shell parameter name, prepended with a `+' when arg + begins with a `+'. The index of the next arg is stored in + OPTIND. The option argument, if any, is stored in OPTARG. + + The first option to be examined may be changed by explicitly as- + signing to OPTIND. OPTIND has an initial value of 1, and is + normally set to 1 upon entry to a shell function and restored + upon exit. (The POSIX_BUILTINS option disables this, and also + changes the way the value is calculated to match other shells.) + OPTARG is not reset and retains its value from the most recent + call to getopts. If either of OPTIND or OPTARG is explicitly + unset, it remains unset, and the index or option argument is not + stored. The option itself is still stored in name in this case. + + A leading `:' in optstring causes getopts to store the letter of + any invalid option in OPTARG, and to set name to `?' for an un- + known option and to `:' when a required argument is missing. + Otherwise, getopts sets name to `?' and prints an error message + when an option is invalid. The exit status is nonzero when + there are no more options. diff --git a/Doc/help/hash b/Doc/help/hash new file mode 100644 index 000000000..dcbc7fd1c --- /dev/null +++ b/Doc/help/hash @@ -0,0 +1,50 @@ +hash [ -Ldfmrv ] [ name[=value] ] ... + hash can be used to directly modify the contents of the command + hash table, and the named directory hash table. Normally one + would modify these tables by modifying one's PATH (for the com- + mand hash table) or by creating appropriate shell parameters + (for the named directory hash table). The choice of hash table + to work on is determined by the -d option; without the option + the command hash table is used, and with the option the named + directory hash table is used. + + A command name starting with a / is never hashed, whether by ex- + plicit use of the hash command or otherwise. Such a command is + always found by direct look up in the file system. + + Given no arguments, and neither the -r or -f options, the se- + lected hash table will be listed in full. + + The -r option causes the selected hash table to be emptied. It + will be subsequently rebuilt in the normal fashion. The -f op- + tion causes the selected hash table to be fully rebuilt immedi- + ately. For the command hash table this hashes all the absolute + directories in the PATH, and for the named directory hash table + this adds all users' home directories. These two options cannot + be used with any arguments. + + The -m option causes the arguments to be taken as patterns + (which should be quoted) and the elements of the hash table + matching those patterns are printed. This is the only way to + display a limited selection of hash table elements. + + For each name with a corresponding value, put `name' in the se- + lected hash table, associating it with the pathname `value'. In + the command hash table, this means that whenever `name' is used + as a command argument, the shell will try to execute the file + given by `value'. In the named directory hash table, this means + that `value' may be referred to as `~name'. + + For each name with no corresponding value, attempt to add name + to the hash table, checking what the appropriate value is in the + normal manner for that hash table. If an appropriate value + can't be found, then the hash table will be unchanged. + + The -v option causes hash table entries to be listed as they are + added by explicit specification. If has no effect if used with + -f. + + If the -L flag is present, then each hash table entry is printed + in the form of a call to hash. + +rehash Same as hash -r. diff --git a/Doc/help/jobs b/Doc/help/jobs new file mode 100644 index 000000000..56f4e34fd --- /dev/null +++ b/Doc/help/jobs @@ -0,0 +1,33 @@ +jobs [ -dlprs ] [ job ... ] +jobs -Z string + Lists information about each given job, or all jobs if job is + omitted. The -l flag lists process IDs, and the -p flag lists + process groups. If the -r flag is specified only running jobs + will be listed and if the -s flag is given only stopped jobs are + shown. If the -d flag is given, the directory from which the + job was started (which may not be the current directory of the + job) will also be shown. + + The -Z option replaces the shell's argument and environment + space with the given string, truncated if necessary to fit. + This will normally be visible in ps (ps(1)) listings. This fea- + ture is typically used by daemons, to indicate their state. + + Full job control is only available in the top-level interactive + shell, not in commands run in the left hand side of pipelines or + within the (...) construct. However, a snapshot of the job + state at that point is taken, so it is still possible to use the + jobs builtin, or any parameter providing job information. This + gives information about the state of jobs at the point the sub- + shell was created. If background processes are created within + the subshell, then instead information about those processes is + provided. + + For example, + + sleep 10 & # Job in background + ( # Shell forks + jobs # Shows information about "sleep 10 &" + sleep 5 & # Process in background (no job control) + jobs # Shows information about "sleep 5 &" + ) diff --git a/Doc/help/kill b/Doc/help/kill new file mode 100644 index 000000000..9112ffefe --- /dev/null +++ b/Doc/help/kill @@ -0,0 +1,24 @@ +kill [ -s signal_name | -n signal_number | -sig ] job ... +kill -l [ sig ... ] + Sends either SIGTERM or the specified signal to the given jobs + or processes. Signals are given by number or by names, with or + without the `SIG' prefix. If the signal being sent is not + `KILL' or `CONT', then the job will be sent a `CONT' signal if + it is stopped. The argument job can be the process ID of a job + not in the job list. In the second form, kill -l, if sig is not + specified the signal names are listed. Otherwise, for each sig + that is a name, the corresponding signal number is listed. For + each sig that is a signal number or a number representing the + exit status of a process which was terminated or stopped by a + signal the name of the signal is printed. + + On some systems, alternative signal names are allowed for a few + signals. Typical examples are SIGCHLD and SIGCLD or SIGPOLL and + SIGIO, assuming they correspond to the same signal number. kill + -l will only list the preferred form, however kill -l alt will + show if the alternative form corresponds to a signal number. + For example, under Linux kill -l IO and kill -l POLL both output + 29, hence kill -IO and kill -POLL have the same effect. + + Many systems will allow process IDs to be negative to kill a + process group or zero to kill the current process group. diff --git a/Doc/help/let b/Doc/help/let new file mode 100644 index 000000000..2119df55c --- /dev/null +++ b/Doc/help/let @@ -0,0 +1,6 @@ +let arg ... + Evaluate each arg as an arithmetic expression. See the section + `Arithmetic Evaluation' in zshmisc(1) for a description of + arithmetic expressions. The exit status is 0 if the value of + the last expression is nonzero, 1 if it is zero, and 2 if an er- + ror occurred. diff --git a/Doc/help/limit b/Doc/help/limit new file mode 100644 index 000000000..342df33da --- /dev/null +++ b/Doc/help/limit @@ -0,0 +1,91 @@ +limit [ -hs ] [ resource [ limit ] ] ... + Set or display resource limits. Unless the -s flag is given, + the limit applies only the children of the shell. If -s is + given without other arguments, the resource limits of the cur- + rent shell is set to the previously set resource limits of the + children. + + If limit is not specified, print the current limit placed on re- + source, otherwise set the limit to the specified value. If the + -h flag is given, use hard limits instead of soft limits. If no + resource is given, print all limits. + + When looping over multiple resources, the shell will abort imme- + diately if it detects a badly formed argument. However, if it + fails to set a limit for some other reason it will continue try- + ing to set the remaining limits. + + resource can be one of: + + addressspace + Maximum amount of address space used. + aiomemorylocked + Maximum amount of memory locked in RAM for AIO opera- + tions. + aiooperations + Maximum number of AIO operations. + cachedthreads + Maximum number of cached threads. + coredumpsize + Maximum size of a core dump. + cputime + Maximum CPU seconds per process. + datasize + Maximum data size (including stack) for each process. + descriptors + Maximum value for a file descriptor. + filesize + Largest single file allowed. + kqueues + Maximum number of kqueues allocated. + maxproc + Maximum number of processes. + maxpthreads + Maximum number of threads per process. + memorylocked + Maximum amount of memory locked in RAM. + memoryuse + Maximum resident set size. + msgqueue + Maximum number of bytes in POSIX message queues. + posixlocks + Maximum number of POSIX locks per user. + pseudoterminals + Maximum number of pseudo-terminals. + resident + Maximum resident set size. + sigpending + Maximum number of pending signals. + sockbufsize + Maximum size of all socket buffers. + stacksize + Maximum stack size for each process. + swapsize + Maximum amount of swap used. + vmemorysize + Maximum amount of virtual memory. + + Which of these resource limits are available depends on the sys- + tem. resource can be abbreviated to any unambiguous prefix. It + can also be an integer, which corresponds to the integer defined + for the resource by the operating system. + + If argument corresponds to a number which is out of the range of + the resources configured into the shell, the shell will try to + read or write the limit anyway, and will report an error if this + fails. As the shell does not store such resources internally, + an attempt to set the limit will fail unless the -s option is + present. + + limit is a number, with an optional scaling factor, as follows: + + nh hours + nk kilobytes (default) + nm megabytes or minutes + ng gigabytes + [mm:]ss + minutes and seconds + + The limit command is not made available by default when the + shell starts in a mode emulating another shell. It can be made + available with the command `zmodload -F zsh/rlimits b:limit'. diff --git a/Doc/help/noglob b/Doc/help/noglob new file mode 100644 index 000000000..7dfc94c6e --- /dev/null +++ b/Doc/help/noglob @@ -0,0 +1,2 @@ +noglob simple command + See the section `Precommand Modifiers' in zshmisc(1). diff --git a/Doc/help/popd b/Doc/help/popd new file mode 100644 index 000000000..d2fa4643b --- /dev/null +++ b/Doc/help/popd @@ -0,0 +1,14 @@ +popd [ -q ] [ {+|-}n ] + Remove an entry from the directory stack, and perform a cd to + the new top directory. With no argument, the current top entry + is removed. An argument of the form `+n' identifies a stack en- + try by counting from the left of the list shown by the dirs com- + mand, starting with zero. An argument of the form -n counts + from the right. If the PUSHD_MINUS option is set, the meanings + of `+' and `-' in this context are swapped. + + If the -q (quiet) option is specified, the hook function chpwd + and the functions in the array $chpwd_functions are not called, + and the new directory stack is not printed. This is useful for + calls to popd that do not change the environment seen by an in- + teractive user. diff --git a/Doc/help/print b/Doc/help/print new file mode 100644 index 000000000..3bf470e5d --- /dev/null +++ b/Doc/help/print @@ -0,0 +1,120 @@ +print [ -abcDilmnNoOpPrsSz ] [ -u n ] [ -f format ] [ -C cols ] + [ -v name ] [ -xX tabstop ] [ -R [ -en ]] [ arg ... ] + With the `-f' option the arguments are printed as described by + printf. With no flags or with the flag `-', the arguments are + printed on the standard output as described by echo, with the + following differences: the escape sequence `\M-x' (or `\Mx') + metafies the character x (sets the highest bit), `\C-x' (or + `\Cx') produces a control character (`\C-@' and `\C-?' give the + characters NULL and delete), a character code in octal is repre- + sented by `\NNN' (instead of `\0NNN'), and `\E' is a synonym for + `\e'. Finally, if not in an escape sequence, `\' escapes the + following character and is not printed. + + -a Print arguments with the column incrementing first. Only + useful with the -c and -C options. + + -b Recognize all the escape sequences defined for the bind- + key command, see the section `Zle Builtins' in zshzle(1). + + -c Print the arguments in columns. Unless -a is also given, + arguments are printed with the row incrementing first. + + -C cols + Print the arguments in cols columns. Unless -a is also + given, arguments are printed with the row incrementing + first. + + -D Treat the arguments as paths, replacing directory pre- + fixes with ~ expressions corresponding to directory + names, as appropriate. + + -i If given together with -o or -O, sorting is performed + case-independently. + + -l Print the arguments separated by newlines instead of spa- + ces. Note: if the list of arguments is empty, print -l + will still output one empty line. To print a possi- + bly-empty list of arguments one per line, use print -C1, + as in `print -rC1 -- "$list[@]"'. + + -m Take the first argument as a pattern (should be quoted), + and remove it from the argument list together with subse- + quent arguments that do not match this pattern. + + -n Do not add a newline to the output. + + -N Print the arguments separated and terminated by nulls. + Again, print -rNC1 -- "$list[@]" is a canonical way to + print an arbitrary list as null-delimited records. + + -o Print the arguments sorted in ascending order. + + -O Print the arguments sorted in descending order. + + -p Print the arguments to the input of the coprocess. + + -P Perform prompt expansion (see EXPANSION OF PROMPT SE- + QUENCES in zshmisc(1)). In combination with `-f', prompt + escape sequences are parsed only within interpolated ar- + guments, not within the format string. + + -r Ignore the escape conventions of echo. + + -R Emulate the BSD echo command, which does not process es- + cape sequences unless the -e flag is given. The -n flag + suppresses the trailing newline. Only the -e and -n + flags are recognized after -R; all other arguments and + options are printed. + + -s Place the results in the history list instead of on the + standard output. Each argument to the print command is + treated as a single word in the history, regardless of + its content. + + -S Place the results in the history list instead of on the + standard output. In this case only a single argument is + allowed; it will be split into words as if it were a full + shell command line. The effect is similar to reading the + line from a history file with the HIST_LEX_WORDS option + active. + + -u n Print the arguments to file descriptor n. + + -v name + Store the printed arguments as the value of the parameter + name. + + -x tab-stop + Expand leading tabs on each line of output in the printed + string assuming a tab stop every tab-stop characters. + This is appropriate for formatting code that may be in- + dented with tabs. Note that leading tabs of any argument + to print, not just the first, are expanded, even if print + is using spaces to separate arguments (the column count + is maintained across arguments but may be incorrect on + output owing to previous unexpanded tabs). + + The start of the output of each print command is assumed + to be aligned with a tab stop. Widths of multibyte char- + acters are handled if the option MULTIBYTE is in effect. + This option is ignored if other formatting options are in + effect, namely column alignment or printf style, or if + output is to a special location such as shell history or + the command line editor. + + -X tab-stop + This is similar to -x, except that all tabs in the + printed string are expanded. This is appropriate if tabs + in the arguments are being used to produce a table for- + mat. + + -z Push the arguments onto the editing buffer stack, sepa- + rated by spaces. + + If any of `-m', `-o' or `-O' are used in combination with `-f' + and there are no arguments (after the removal process in the + case of `-m') then nothing is printed. + +pushln [ arg ... ] + Equivalent to print -nz. diff --git a/Doc/help/printf b/Doc/help/printf new file mode 100644 index 000000000..e18ca3ea4 --- /dev/null +++ b/Doc/help/printf @@ -0,0 +1,35 @@ +printf [ -v name ] format [ arg ... ] + Print the arguments according to the format specification. For- + matting rules are the same as used in C. The same escape se- + quences as for echo are recognised in the format. All C conver- + sion specifications ending in one of csdiouxXeEfgGn are handled. + In addition to this, `%b' can be used instead of `%s' to cause + escape sequences in the argument to be recognised and `%q' can + be used to quote the argument in such a way that allows it to be + reused as shell input. With the numeric format specifiers, if + the corresponding argument starts with a quote character, the + numeric value of the following character is used as the number + to print; otherwise the argument is evaluated as an arithmetic + expression. See the section `Arithmetic Evaluation' in zsh- + misc(1) for a description of arithmetic expressions. With `%n', + the corresponding argument is taken as an identifier which is + created as an integer parameter. + + Normally, conversion specifications are applied to each argument + in order but they can explicitly specify the nth argument is to + be used by replacing `%' by `%n$' and `*' by `*n$'. It is rec- + ommended that you do not mix references of this explicit style + with the normal style and the handling of such mixed styles may + be subject to future change. + + If arguments remain unused after formatting, the format string + is reused until all arguments have been consumed. With the print + builtin, this can be suppressed by using the -r option. If more + arguments are required by the format than have been specified, + the behaviour is as if zero or an empty string had been speci- + fied as the argument. + + The -v option causes the output to be stored as the value of the + parameter name, instead of printed. If name is an array and the + format string is reused when consuming arguments then one array + element will be used for each use of the format string. diff --git a/Doc/help/pushd b/Doc/help/pushd new file mode 100644 index 000000000..7365532ae --- /dev/null +++ b/Doc/help/pushd @@ -0,0 +1,31 @@ +pushd [ -qsLP ] [ arg ] +pushd [ -qsLP ] old new +pushd [ -qsLP ] {+|-}n + Change the current directory, and push the old current directory + onto the directory stack. In the first form, change the current + directory to arg. If arg is not specified, change to the second + directory on the stack (that is, exchange the top two entries), + or change to $HOME if the PUSHD_TO_HOME option is set or if + there is only one entry on the stack. Otherwise, arg is inter- + preted as it would be by cd. The meaning of old and new in the + second form is also the same as for cd. + + The third form of pushd changes directory by rotating the direc- + tory list. An argument of the form `+n' identifies a stack en- + try by counting from the left of the list shown by the dirs com- + mand, starting with zero. An argument of the form `-n' counts + from the right. If the PUSHD_MINUS option is set, the meanings + of `+' and `-' in this context are swapped. + + If the -q (quiet) option is specified, the hook function chpwd + and the functions in the array $chpwd_functions are not called, + and the new directory stack is not printed. This is useful for + calls to pushd that do not change the environment seen by an in- + teractive user. + + If the option -q is not specified and the shell option + PUSHD_SILENT is not set, the directory stack will be printed af- + ter a pushd is performed. + + The options -s, -L and -P have the same meanings as for the cd + builtin. diff --git a/Doc/help/pwd b/Doc/help/pwd new file mode 100644 index 000000000..282b4dbc5 --- /dev/null +++ b/Doc/help/pwd @@ -0,0 +1,5 @@ +pwd [ -rLP ] + Print the absolute pathname of the current working directory. + If the -r or the -P flag is specified, or the CHASE_LINKS option + is set and the -L flag is not given, the printed path will not + contain symbolic links. diff --git a/Doc/help/read b/Doc/help/read new file mode 100644 index 000000000..ac14407ea --- /dev/null +++ b/Doc/help/read @@ -0,0 +1,113 @@ +read [ -rszpqAclneE ] [ -t [ num ] ] [ -k [ num ] ] [ -d delim ] + [ -u n ] [ [name][?prompt] ] [ name ... ] + Read one line and break it into fields using the characters in + $IFS as separators, except as noted below. The first field is + assigned to the first name, the second field to the second name, + etc., with leftover fields assigned to the last name. If name + is omitted then REPLY is used for scalars and reply for arrays. + + -r Raw mode: a `\' at the end of a line does not signify + line continuation and backslashes in the line don't quote + the following character and are not removed. + + -s Don't echo back characters if reading from the terminal. + + -q Read only one character from the terminal and set name to + `y' if this character was `y' or `Y' and to `n' other- + wise. With this flag set the return status is zero only + if the character was `y' or `Y'. This option may be used + with a timeout (see -t); if the read times out, or en- + counters end of file, status 2 is returned. Input is + read from the terminal unless one of -u or -p is present. + This option may also be used within zle widgets. + + -k [ num ] + Read only one (or num) characters. All are assigned to + the first name, without word splitting. This flag is ig- + nored when -q is present. Input is read from the termi- + nal unless one of -u or -p is present. This option may + also be used within zle widgets. + + Note that despite the mnemonic `key' this option does + read full characters, which may consist of multiple bytes + if the option MULTIBYTE is set. + + -z Read one entry from the editor buffer stack and assign it + to the first name, without word splitting. Text is + pushed onto the stack with `print -z' or with push-line + from the line editor (see zshzle(1)). This flag is ig- + nored when the -k or -q flags are present. + + -e + -E The input read is printed (echoed) to the standard out- + put. If the -e flag is used, no input is assigned to the + parameters. + + -A The first name is taken as the name of an array and all + words are assigned to it. + + -c + -l These flags are allowed only if called inside a function + used for completion (specified with the -K flag to com- + pctl). If the -c flag is given, the words of the current + command are read. If the -l flag is given, the whole line + is assigned as a scalar. If both flags are present, -l + is used and -c is ignored. + + -n Together with -c, the number of the word the cursor is on + is read. With -l, the index of the character the cursor + is on is read. Note that the command name is word number + 1, not word 0, and that when the cursor is at the end of + the line, its character index is the length of the line + plus one. + + -u n Input is read from file descriptor n. + + -p Input is read from the coprocess. + + -d delim + Input is terminated by the first character of delim in- + stead of by newline. + + -t [ num ] + Test if input is available before attempting to read. If + num is present, it must begin with a digit and will be + evaluated to give a number of seconds, which may be a + floating point number; in this case the read times out if + input is not available within this time. If num is not + present, it is taken to be zero, so that read returns im- + mediately if no input is available. If no input is + available, return status 1 and do not set any variables. + + This option is not available when reading from the editor + buffer with -z, when called from within completion with + -c or -l, with -q which clears the input queue before + reading, or within zle where other mechanisms should be + used to test for input. + + Note that read does not attempt to alter the input pro- + cessing mode. The default mode is canonical input, in + which an entire line is read at a time, so usually `read + -t' will not read anything until an entire line has been + typed. However, when reading from the terminal with -k + input is processed one key at a time; in this case, only + availability of the first character is tested, so that + e.g. `read -t -k 2' can still block on the second charac- + ter. Use two instances of `read -t -k' if this is not + what is wanted. + + If the first argument contains a `?', the remainder of this word + is used as a prompt on standard error when the shell is interac- + tive. + + The value (exit status) of read is 1 when an end-of-file is en- + countered, or when -c or -l is present and the command is not + called from a compctl function, or as described for -q. Other- + wise the value is 0. + + The behavior of some combinations of the -k, -p, -q, -u and -z + flags is undefined. Presently -q cancels all the others, -p + cancels -u, -k cancels -z, and otherwise -z cancels both -p and + -u. + + The -c or -l flags cancel any and all of -kpquz. diff --git a/Doc/help/return b/Doc/help/return new file mode 100644 index 000000000..61a32d48a --- /dev/null +++ b/Doc/help/return @@ -0,0 +1,21 @@ +return [ n ] + Causes a shell function or `.' script to return to the invoking + script with the return status specified by an arithmetic expres- + sion n. For example, the following prints `42': + + () { integer foo=40; return "foo + 2" } + echo $? + + If n is omitted, the return status is that of the last command + executed. + + If return was executed from a trap in a TRAPNAL function, the + effect is different for zero and non-zero return status. With + zero status (or after an implicit return at the end of the + trap), the shell will return to whatever it was previously pro- + cessing; with a non-zero status, the shell will behave as inter- + rupted except that the return status of the trap is retained. + Note that the numeric value of the signal which caused the trap + is passed as the first argument, so the statement `return + "128+$1"' will return the same status as if the signal had not + been trapped. diff --git a/Doc/help/sched b/Doc/help/sched new file mode 100644 index 000000000..a85eb8d97 --- /dev/null +++ b/Doc/help/sched @@ -0,0 +1 @@ +sched See the section `The zsh/sched Module' in zshmodules(1). diff --git a/Doc/help/set b/Doc/help/set new file mode 100644 index 000000000..9a0196f01 --- /dev/null +++ b/Doc/help/set @@ -0,0 +1,46 @@ +set [ {+|-}options | {+|-}o [ option_name ] ] ... [ {+|-}A [ name ] ] + [ arg ... ] + Set the options for the shell and/or set the positional parame- + ters, or declare and set an array. If the -s option is given, + it causes the specified arguments to be sorted before assigning + them to the positional parameters (or to the array name if -A is + used). With +s sort arguments in descending order. For the + meaning of the other flags, see zshoptions(1). Flags may be + specified by name using the -o option. If no option name is sup- + plied with -o, the current option states are printed: see the + description of setopt below for more information on the format. + With +o they are printed in a form that can be used as input to + the shell. + + If the -A flag is specified, name is set to an array containing + the given args; if no name is specified, all arrays are printed + together with their values. + + If +A is used and name is an array, the given arguments will re- + place the initial elements of that array; if no name is speci- + fied, all arrays are printed without their values. + + The behaviour of arguments after -A name or +A name depends on + whether the option KSH_ARRAYS is set. If it is not set, all ar- + guments following name are treated as values for the array, re- + gardless of their form. If the option is set, normal option + processing continues at that point; only regular arguments are + treated as values for the array. This means that + + set -A array -x -- foo + + sets array to `-x -- foo' if KSH_ARRAYS is not set, but sets the + array to foo and turns on the option `-x' if it is set. + + If the -A flag is not present, but there are arguments beyond + the options, the positional parameters are set. If the option + list (if any) is terminated by `--', and there are no further + arguments, the positional parameters will be unset. + + If no arguments and no `--' are given, then the names and values + of all parameters are printed on the standard output. If the + only argument is `+', the names of all parameters are printed. + + For historical reasons, `set -' is treated as `set +xv' and `set + - args' as `set +xv -- args' when in any other emulation mode + than zsh's native mode. diff --git a/Doc/help/setcap b/Doc/help/setcap new file mode 100644 index 000000000..0646a7043 --- /dev/null +++ b/Doc/help/setcap @@ -0,0 +1 @@ +setcap See the section `The zsh/cap Module' in zshmodules(1). diff --git a/Doc/help/setopt b/Doc/help/setopt new file mode 100644 index 000000000..4478a1ed2 --- /dev/null +++ b/Doc/help/setopt @@ -0,0 +1,27 @@ +setopt [ {+|-}options | {+|-}o option_name ] [ -m ] [ name ... ] + Set the options for the shell. All options specified either + with flags or by name are set. + + If no arguments are supplied, the names of all options currently + set are printed. The form is chosen so as to minimize the dif- + ferences from the default options for the current emulation (the + default emulation being native zsh, shown as <Z> in zshop- + tions(1)). Options that are on by default for the emulation are + shown with the prefix no only if they are off, while other op- + tions are shown without the prefix no and only if they are on. + In addition to options changed from the default state by the + user, any options activated automatically by the shell (for ex- + ample, SHIN_STDIN or INTERACTIVE) will be shown in the list. + The format is further modified by the option KSH_OPTION_PRINT, + however the rationale for choosing options with or without the + no prefix remains the same in this case. + + If the -m flag is given the arguments are taken as patterns + (which should be quoted to protect them from filename expan- + sion), and all options with names matching these patterns are + set. + + Note that a bad option name does not cause execution of subse- + quent shell code to be aborted; this is behaviour is different + from that of `set -o'. This is because set is regarded as a + special builtin by the POSIX standard, but setopt is not. diff --git a/Doc/help/shift b/Doc/help/shift new file mode 100644 index 000000000..3bb236707 --- /dev/null +++ b/Doc/help/shift @@ -0,0 +1,8 @@ +shift [ -p ] [ n ] [ name ... ] + The positional parameters ${n+1} ... are renamed to $1 ..., + where n is an arithmetic expression that defaults to 1. If any + names are given then the arrays with these names are shifted in- + stead of the positional parameters. + + If the option -p is given arguments are instead removed (popped) + from the end rather than the start of the array. diff --git a/Doc/help/source b/Doc/help/source new file mode 100644 index 000000000..b321b1c65 --- /dev/null +++ b/Doc/help/source @@ -0,0 +1,4 @@ +source file [ arg ... ] + Same as `.', except that the current directory is always + searched and is always searched first, before directories in + $path. diff --git a/Doc/help/stat b/Doc/help/stat new file mode 100644 index 000000000..f18d9e7f0 --- /dev/null +++ b/Doc/help/stat @@ -0,0 +1 @@ +stat See the section `The zsh/stat Module' in zshmodules(1). diff --git a/Doc/help/suspend b/Doc/help/suspend new file mode 100644 index 000000000..f247380c4 --- /dev/null +++ b/Doc/help/suspend @@ -0,0 +1,4 @@ +suspend [ -f ] + Suspend the execution of the shell (send it a SIGTSTP) until it + receives a SIGCONT. Unless the -f option is given, this will + refuse to suspend a login shell. diff --git a/Doc/help/test b/Doc/help/test new file mode 100644 index 000000000..4b8d48e78 --- /dev/null +++ b/Doc/help/test @@ -0,0 +1,20 @@ +test [ arg ... ] +[ [ arg ... ] ] + Like the system version of test. Added for compatibility; use + conditional expressions instead (see the section `Conditional + Expressions'). The main differences between the conditional ex- + pression syntax and the test and [ builtins are: these commands + are not handled syntactically, so for example an empty variable + expansion may cause an argument to be omitted; syntax errors + cause status 2 to be returned instead of a shell error; and + arithmetic operators expect integer arguments rather than arith- + metic expressions. + + The command attempts to implement POSIX and its extensions where + these are specified. Unfortunately there are intrinsic ambigui- + ties in the syntax; in particular there is no distinction be- + tween test operators and strings that resemble them. The stan- + dard attempts to resolve these for small numbers of arguments + (up to four); for five or more arguments compatibility cannot be + relied on. Users are urged wherever possible to use the `[[' + test syntax which does not have these ambiguities. diff --git a/Doc/help/times b/Doc/help/times new file mode 100644 index 000000000..3126d95cf --- /dev/null +++ b/Doc/help/times @@ -0,0 +1,2 @@ +times Print the accumulated user and system times for the shell and + for processes run from the shell. diff --git a/Doc/help/trap b/Doc/help/trap new file mode 100644 index 000000000..e8de30f4a --- /dev/null +++ b/Doc/help/trap @@ -0,0 +1,72 @@ +trap [ arg ] [ sig ... ] + arg is a series of commands (usually quoted to protect it from + immediate evaluation by the shell) to be read and executed when + the shell receives any of the signals specified by one or more + sig args. Each sig can be given as a number, or as the name of + a signal either with or without the string SIG in front (e.g. 1, + HUP, and SIGHUP are all the same signal). + + If arg is `-', then the specified signals are reset to their de- + faults, or, if no sig args are present, all traps are reset. + + If arg is an empty string, then the specified signals are ig- + nored by the shell (and by the commands it invokes). + + If arg is omitted but one or more sig args are provided (i.e. + the first argument is a valid signal number or name), the effect + is the same as if arg had been specified as `-'. + + The trap command with no arguments prints a list of commands as- + sociated with each signal. + + If sig is ZERR then arg will be executed after each command with + a nonzero exit status. ERR is an alias for ZERR on systems that + have no SIGERR signal (this is the usual case). + + If sig is DEBUG then arg will be executed before each command if + the option DEBUG_BEFORE_CMD is set (as it is by default), else + after each command. Here, a `command' is what is described as a + `sublist' in the shell grammar, see the section SIMPLE COMMANDS + & PIPELINES in zshmisc(1). If DEBUG_BEFORE_CMD is set various + additional features are available. First, it is possible to + skip the next command by setting the option ERR_EXIT; see the + description of the ERR_EXIT option in zshoptions(1). Also, the + shell parameter ZSH_DEBUG_CMD is set to the string corresponding + to the command to be executed following the trap. Note that + this string is reconstructed from the internal format and may + not be formatted the same way as the original text. The parame- + ter is unset after the trap is executed. + + If sig is 0 or EXIT and the trap statement is executed inside + the body of a function, then the command arg is executed after + the function completes. The value of $? at the start of execu- + tion is the exit status of the shell or the return status of the + function exiting. If sig is 0 or EXIT and the trap statement is + not executed inside the body of a function, then the command arg + is executed when the shell terminates; the trap runs before any + zshexit hook functions. + + ZERR, DEBUG, and EXIT traps are not executed inside other traps. + ZERR and DEBUG traps are kept within subshells, while other + traps are reset. + + Note that traps defined with the trap builtin are slightly dif- + ferent from those defined as `TRAPNAL () { ... }', as the latter + have their own function environment (line numbers, local vari- + ables, etc.) while the former use the environment of the command + in which they were called. For example, + + trap 'print $LINENO' DEBUG + + will print the line number of a command executed after it has + run, while + + TRAPDEBUG() { print $LINENO; } + + will always print the number zero. + + Alternative signal names are allowed as described under kill + above. Defining a trap under either name causes any trap under + an alternative name to be removed. However, it is recommended + that for consistency users stick exclusively to one name or an- + other. diff --git a/Doc/help/true b/Doc/help/true new file mode 100644 index 000000000..65e09dc36 --- /dev/null +++ b/Doc/help/true @@ -0,0 +1,2 @@ +true [ arg ... ] + Do nothing and return an exit status of 0. diff --git a/Doc/help/ttyctl b/Doc/help/ttyctl new file mode 100644 index 000000000..937fdf913 --- /dev/null +++ b/Doc/help/ttyctl @@ -0,0 +1,22 @@ +ttyctl [ -fu ] + The -f option freezes the tty (i.e. terminal or terminal emula- + tor), and -u unfreezes it. When the tty is frozen, no changes + made to the tty settings by external programs will be honored by + the shell, except for changes in the size of the screen; the + shell will simply reset the settings to their previous values as + soon as each command exits or is suspended. Thus, stty and sim- + ilar programs have no effect when the tty is frozen. Freezing + the tty does not cause the current state to be remembered: in- + stead, it causes future changes to the state to be blocked. + + Without options it reports whether the terminal is frozen or + not. + + Note that, regardless of whether the tty is frozen or not, the + shell needs to change the settings when the line editor starts, + so unfreezing the tty does not guarantee settings made on the + command line are preserved. Strings of commands run between + editing the command line will see a consistent tty state. See + also the shell variable STTY for a means of initialising the tty + before running external commands and/or freezing the tty around + a single command. diff --git a/Doc/help/typeset b/Doc/help/typeset new file mode 100644 index 000000000..852b39153 --- /dev/null +++ b/Doc/help/typeset @@ -0,0 +1,417 @@ +typeset [ {+|-}AHUaghlmrtux ] [ {+|-}EFLRZip [ n ] ] + [ + ] [ name[=value] ... ] +typeset -T [ {+|-}Uglrux ] [ {+|-}LRZp [ n ] ] + [ + | SCALAR[=value] array[=(value ...)] [ sep ] ] +typeset -f [ {+|-}TUkmtuz ] [ + ] [ name ... ] + Set or display attributes and values for shell parameters. + + Except as noted below for control flags that change the behav- + ior, a parameter is created for each name that does not already + refer to one. When inside a function, a new parameter is cre- + ated for every name (even those that already exist), and is un- + set again when the function completes. See `Local Parameters' + in zshparam(1). The same rules apply to special shell parame- + ters, which retain their special attributes when made local. + + For each name=value assignment, the parameter name is set to + value. If the assignment is omitted and name does not refer to + an existing parameter, a new parameter is intialized to empty + string, zero, or empty array (as appropriate), unless the shell + option TYPESET_TO_UNSET is set. When that option is set, the + parameter attributes are recorded but the parameter remains un- + set. + + If the shell option TYPESET_SILENT is not set, for each remain- + ing name that refers to a parameter that is already set, the + name and value of the parameter are printed in the form of an + assignment. Nothing is printed for newly-created parameters, or + when any attribute flags listed below are given along with the + name. Using `+' instead of minus to introduce an attribute + turns it off. + + If no name is present, the names and values of all parameters + are printed. In this case the attribute flags restrict the dis- + play to only those parameters that have the specified at- + tributes, and using `+' rather than `-' to introduce the flag + suppresses printing of the values of parameters when there is no + parameter name. + + All forms of the command handle scalar assignment. Array as- + signment is possible if any of the reserved words declare, ex- + port, float, integer, local, readonly or typeset is matched when + the line is parsed (N.B. not when it is executed). In this case + the arguments are parsed as assignments, except that the `+=' + syntax and the GLOB_ASSIGN option are not supported, and scalar + values after = are not split further into words, even if ex- + panded (regardless of the setting of the KSH_TYPESET option; + this option is obsolete). + + Examples of the differences between command and reserved word + parsing: + + # Reserved word parsing + typeset svar=$(echo one word) avar=(several words) + + The above creates a scalar parameter svar and an array parameter + avar as if the assignments had been + + svar="one word" + avar=(several words) + + On the other hand: + + # Normal builtin interface + builtin typeset svar=$(echo two words) + + The builtin keyword causes the above to use the standard builtin + interface to typeset in which argument parsing is performed in + the same way as for other commands. This example creates a + scalar svar containing the value two and another scalar parame- + ter words with no value. An array value in this case would ei- + ther cause an error or be treated as an obscure set of glob + qualifiers. + + Arbitrary arguments are allowed if they take the form of assign- + ments after command line expansion; however, these only perform + scalar assignment: + + var='svar=val' + typeset $var + + The above sets the scalar parameter svar to the value val. + Parentheses around the value within var would not cause array + assignment as they will be treated as ordinary characters when + $var is substituted. Any non-trivial expansion in the name part + of the assignment causes the argument to be treated in this + fashion: + + typeset {var1,var2,var3}=name + + The above syntax is valid, and has the expected effect of set- + ting the three parameters to the same value, but the command + line is parsed as a set of three normal command line arguments + to typeset after expansion. Hence it is not possible to assign + to multiple arrays by this means. + + Note that each interface to any of the commands may be disabled + separately. For example, `disable -r typeset' disables the re- + served word interface to typeset, exposing the builtin inter- + face, while `disable typeset' disables the builtin. Note that + disabling the reserved word interface for typeset may cause + problems with the output of `typeset -p', which assumes the re- + served word interface is available in order to restore array and + associative array values. + + Unlike parameter assignment statements, typeset's exit status on + an assignment that involves a command substitution does not re- + flect the exit status of the command substitution. Therefore, + to test for an error in a command substitution, separate the + declaration of the parameter from its initialization: + + # WRONG + typeset var1=$(exit 1) || echo "Trouble with var1" + + # RIGHT + typeset var1 && var1=$(exit 1) || echo "Trouble with var1" + + To initialize a parameter param to a command output and mark it + readonly, use typeset -r param or readonly param after the pa- + rameter assignment statement. + + If no attribute flags are given, and either no name arguments + are present or the flag +m is used, then each parameter name + printed is preceded by a list of the attributes of that parame- + ter (array, association, exported, float, integer, readonly, or + undefined for autoloaded parameters not yet loaded). If +m is + used with attribute flags, and all those flags are introduced + with +, the matching parameter names are printed but their val- + ues are not. + + The following control flags change the behavior of typeset: + + + If `+' appears by itself in a separate word as the last + option, then the names of all parameters (functions with + -f) are printed, but the values (function bodies) are + not. No name arguments may appear, and it is an error + for any other options to follow `+'. The effect of `+' + is as if all attribute flags which precede it were given + with a `+' prefix. For example, `typeset -U +' is equiv- + alent to `typeset +U' and displays the names of all ar- + rays having the uniqueness attribute, whereas `typeset -f + -U +' displays the names of all autoloadable functions. + If + is the only option, then type information (array, + readonly, etc.) is also printed for each parameter, in + the same manner as `typeset +m "*"'. + + -g The -g (global) means that any resulting parameter will + not be restricted to local scope. Note that this does + not necessarily mean that the parameter will be global, + as the flag will apply to any existing parameter (even if + unset) from an enclosing function. This flag does not + affect the parameter after creation, hence it has no ef- + fect when listing existing parameters, nor does the flag + +g have any effect except in combination with -m (see be- + low). + + -m If the -m flag is given the name arguments are taken as + patterns (use quoting to prevent these from being inter- + preted as file patterns). With no attribute flags, all + parameters (or functions with the -f flag) with matching + names are printed (the shell option TYPESET_SILENT is not + used in this case). + + If the +g flag is combined with -m, a new local parameter + is created for every matching parameter that is not al- + ready local. Otherwise -m applies all other flags or as- + signments to the existing parameters. + + Except when assignments are made with name=value, using + +m forces the matching parameters and their attributes to + be printed, even inside a function. Note that -m is ig- + nored if no patterns are given, so `typeset -m' displays + attributes but `typeset -a +m' does not. + + -p [ n ] + If the -p option is given, parameters and values are + printed in the form of a typeset command with an assign- + ment, regardless of other flags and options. Note that + the -H flag on parameters is respected; no value will be + shown for these parameters. + + -p may be followed by an optional integer argument. Cur- + rently only the value 1 is supported. In this case ar- + rays and associative arrays are printed with newlines be- + tween indented elements for readability. + + -T [ scalar[=value] array[=(value ...)] [ sep ] ] + This flag has a different meaning when used with -f; see + below. Otherwise the -T option requires zero, two, or + three arguments to be present. With no arguments, the + list of parameters created in this fashion is shown. + With two or three arguments, the first two are the name + of a scalar and of an array parameter (in that order) + that will be tied together in the manner of $PATH and + $path. The optional third argument is a single-character + separator which will be used to join the elements of the + array to form the scalar; if absent, a colon is used, as + with $PATH. Only the first character of the separator is + significant; any remaining characters are ignored. + Multibyte characters are not yet supported. + + Only one of the scalar and array parameters may be as- + signed an initial value (the restrictions on assignment + forms described above also apply). + + Both the scalar and the array may be manipulated as nor- + mal. If one is unset, the other will automatically be + unset too. There is no way of untying the variables + without unsetting them, nor of converting the type of one + of them with another typeset command; +T does not work, + assigning an array to scalar is an error, and assigning a + scalar to array sets it to be a single-element array. + + Note that both `typeset -xT ...' and `export -T ...' + work, but only the scalar will be marked for export. + Setting the value using the scalar version causes a split + on all separators (which cannot be quoted). It is possi- + ble to apply -T to two previously tied variables but with + a different separator character, in which case the vari- + ables remain joined as before but the separator is + changed. + + When an existing scalar is tied to a new array, the value + of the scalar is preserved but no attribute other than + export will be preserved. + + Attribute flags that transform the final value (-L, -R, -Z, -l, + -u) are only applied to the expanded value at the point of a pa- + rameter expansion expression using `$'. They are not applied + when a parameter is retrieved internally by the shell for any + purpose. + + The following attribute flags may be specified: + + -A The names refer to associative array parameters; see `Ar- + ray Parameters' in zshparam(1). + + -L [ n ] + Left justify and remove leading blanks from the value + when the parameter is expanded. If n is nonzero, it de- + fines the width of the field. If n is zero, the width is + determined by the width of the value of the first assign- + ment. In the case of numeric parameters, the length of + the complete value assigned to the parameter is used to + determine the width, not the value that would be output. + + The width is the count of characters, which may be multi- + byte characters if the MULTIBYTE option is in effect. + Note that the screen width of the character is not taken + into account; if this is required, use padding with pa- + rameter expansion flags ${(ml...)...} as described in + `Parameter Expansion Flags' in zshexpn(1). + + When the parameter is expanded, it is filled on the right + with blanks or truncated if necessary to fit the field. + Note truncation can lead to unexpected results with nu- + meric parameters. Leading zeros are removed if the -Z + flag is also set. + + -R [ n ] + Similar to -L, except that right justification is used; + when the parameter is expanded, the field is left filled + with blanks or truncated from the end. May not be com- + bined with the -Z flag. + + -U For arrays (but not for associative arrays), keep only + the first occurrence of each duplicated value. This may + also be set for tied parameters (see -T) or colon-sepa- + rated special parameters like PATH or FIGNORE, etc. Note + the flag takes effect on assignment, and the type of the + variable being assigned to is determinative; for vari- + ables with shared values it is therefore recommended to + set the flag for all interfaces, e.g. `typeset -U PATH + path'. + + This flag has a different meaning when used with -f; see + below. + + -Z [ n ] + Specially handled if set along with the -L flag. Other- + wise, similar to -R, except that leading zeros are used + for padding instead of blanks if the first non-blank + character is a digit. Numeric parameters are specially + handled: they are always eligible for padding with ze- + roes, and the zeroes are inserted at an appropriate place + in the output. + + -a The names refer to array parameters. An array parameter + may be created this way, but it may be assigned to in the + typeset statement only if the reserved word form of type- + set is enabled (as it is by default). When displaying, + both normal and associative arrays are shown. + + -f The names refer to functions rather than parameters. No + assignments can be made, and the only other valid flags + are -t, -T, -k, -u, -U and -z. The flag -t turns on exe- + cution tracing for this function; the flag -T does the + same, but turns off tracing for any named (not anonymous) + function called from the present one, unless that func- + tion also has the -t or -T flag. The -u and -U flags + cause the function to be marked for autoloading; -U also + causes alias expansion to be suppressed when the function + is loaded. See the description of the `autoload' builtin + for details. + + Note that the builtin functions provides the same basic + capabilities as typeset -f but gives access to a few ex- + tra options; autoload gives further additional options + for the case typeset -fu and typeset -fU. + + -h Hide: only useful for special parameters (those marked + `<S>' in the table in zshparam(1)), and for local parame- + ters with the same name as a special parameter, though + harmless for others. A special parameter with this at- + tribute will not retain its special effect when made lo- + cal. Thus after `typeset -h PATH', a function containing + `typeset PATH' will create an ordinary local parameter + without the usual behaviour of PATH. Alternatively, the + local parameter may itself be given this attribute; hence + inside a function `typeset -h PATH' creates an ordinary + local parameter and the special PATH parameter is not al- + tered in any way. It is also possible to create a local + parameter using `typeset +h special', where the local + copy of special will retain its special properties re- + gardless of having the -h attribute. Global special pa- + rameters loaded from shell modules (currently those in + zsh/mapfile and zsh/parameter) are automatically given + the -h attribute to avoid name clashes. + + -H Hide value: specifies that typeset will not display the + value of the parameter when listing parameters; the dis- + play for such parameters is always as if the `+' flag had + been given. Use of the parameter is in other respects + normal, and the option does not apply if the parameter is + specified by name, or by pattern with the -m option. + This is on by default for the parameters in the zsh/pa- + rameter and zsh/mapfile modules. Note, however, that un- + like the -h flag this is also useful for non-special pa- + rameters. + + -i [ n ] + Use an internal integer representation. If n is nonzero + it defines the output arithmetic base, otherwise it is + determined by the first assignment. Bases from 2 to 36 + inclusive are allowed. + + -E [ n ] + Use an internal double-precision floating point represen- + tation. On output the variable will be converted to sci- + entific notation. If n is nonzero it defines the number + of significant figures to display; the default is ten. + + -F [ n ] + Use an internal double-precision floating point represen- + tation. On output the variable will be converted to + fixed-point decimal notation. If n is nonzero it defines + the number of digits to display after the decimal point; + the default is ten. + + -l Convert the result to lower case whenever the parameter + is expanded. The value is not converted when assigned. + + -r The given names are marked readonly. Note that if name + is a special parameter, the readonly attribute can be + turned on, but cannot then be turned off. + + If the POSIX_BUILTINS option is set, the readonly attri- + bute is more restrictive: unset variables can be marked + readonly and cannot then be set; furthermore, the read- + only attribute cannot be removed from any variable. + + It is still possible to change other attributes of the + variable though, some of which like -U or -Z would affect + the value. More generally, the readonly attribute should + not be relied on as a security mechanism. + + Note that in zsh (like in pdksh but unlike most other + shells) it is still possible to create a local variable + of the same name as this is considered a different vari- + able (though this variable, too, can be marked readonly). + Special variables that have been made readonly retain + their value and readonly attribute when made local. + + -t Tags the named parameters. Tags have no special meaning + to the shell. This flag has a different meaning when + used with -f; see above. + + -u Convert the result to upper case whenever the parameter + is expanded. The value is not converted when assigned. + This flag has a different meaning when used with -f; see + above. + + -x Mark for automatic export to the environment of subse- + quently executed commands. If the option GLOBAL_EXPORT + is set, this implies the option -g, unless +g is also ex- + plicitly given; in other words the parameter is not made + local to the enclosing function. This is for compatibil- + ity with previous versions of zsh. + +declare + Same as typeset. + +float [ {+|-}Hghlprtux ] [ {+|-}EFLRZ [ n ] ] [ name[=value] ... ] + Equivalent to typeset -E, except that options irrelevant to + floating point numbers are not permitted. + +integer [ {+|-}Hghlprtux ] [ {+|-}LRZi [ n ] ] [ name[=value] ... ] + Equivalent to typeset -i, except that options irrelevant to in- + tegers are not permitted. + +local [ {+|-}AHUahlprtux ] [ {+|-}EFLRZi [ n ] ] [ name[=value] ... ] + Same as typeset, except that the options -g, and -f are not per- + mitted. In this case the -x option does not force the use of + -g, i.e. exported variables will be local to functions. + +readonly + Same as typeset -r. With the POSIX_BUILTINS option set, same as + typeset -gr. diff --git a/Doc/help/ulimit b/Doc/help/ulimit new file mode 100644 index 000000000..0463ca046 --- /dev/null +++ b/Doc/help/ulimit @@ -0,0 +1,59 @@ +ulimit [ -HSa ] [ { -bcdfiklmnpqrsTtvwx | -N resource } [ limit ] ... ] + Set or display resource limits of the shell and the processes + started by the shell. The value of limit can be a number in the + unit specified below or one of the values `unlimited', which re- + moves the limit on the resource, or `hard', which uses the cur- + rent value of the hard limit on the resource. + + By default, only soft limits are manipulated. If the -H flag is + given use hard limits instead of soft limits. If the -S flag is + given together with the -H flag set both hard and soft limits. + + If no options are used, the file size limit (-f) is assumed. + + If limit is omitted the current value of the specified resources + are printed. When more than one resource value is printed, the + limit name and unit is printed before each value. + + When looping over multiple resources, the shell will abort imme- + diately if it detects a badly formed argument. However, if it + fails to set a limit for some other reason it will continue try- + ing to set the remaining limits. + + Not all the following resources are supported on all systems. + Running ulimit -a will show which are supported. + + -a Lists all of the current resource limits. + -b Socket buffer size in bytes (N.B. not kilobytes) + -c 512-byte blocks on the size of core dumps. + -d Kilobytes on the size of the data segment. + -f 512-byte blocks on the size of files written. + -i The number of pending signals. + -k The number of kqueues allocated. + -l Kilobytes on the size of locked-in memory. + -m Kilobytes on the size of physical memory. + -n open file descriptors. + -p The number of pseudo-terminals. + -q Bytes in POSIX message queues. + -r Maximum real time priority. On some systems where this + is not available, such as NetBSD, this has the same ef- + fect as -T for compatibility with sh. + -s Kilobytes on the size of the stack. + -T The number of simultaneous threads available to the user. + -t CPU seconds to be used. + -u The number of processes available to the user. + -v Kilobytes on the size of virtual memory. On some systems + this refers to the limit called `address space'. + -w Kilobytes on the size of swapped out memory. + -x The number of locks on files. + + A resource may also be specified by integer in the form `-N re- + source', where resource corresponds to the integer defined for + the resource by the operating system. This may be used to set + the limits for resources known to the shell which do not corre- + spond to option letters. Such limits will be shown by number in + the output of `ulimit -a'. + + The number may alternatively be out of the range of limits com- + piled into the shell. The shell will try to read or write the + limit anyway, and will report an error if this fails. diff --git a/Doc/help/umask b/Doc/help/umask new file mode 100644 index 000000000..a27f722c8 --- /dev/null +++ b/Doc/help/umask @@ -0,0 +1,8 @@ +umask [ -S ] [ mask ] + The umask is set to mask. mask can be either an octal number or + a symbolic value as described in the chmod(1) man page. If mask + is omitted, the current value is printed. The -S option causes + the mask to be printed as a symbolic value. Otherwise, the mask + is printed as an octal number. Note that in the symbolic form + the permissions you specify are those which are to be allowed + (not denied) to the users specified. diff --git a/Doc/help/unhash b/Doc/help/unhash new file mode 100644 index 000000000..a94c55dd4 --- /dev/null +++ b/Doc/help/unhash @@ -0,0 +1,23 @@ +unhash [ -adfms ] name ... + Remove the element named name from an internal hash table. The + default is remove elements from the command hash table. The -a + option causes unhash to remove regular or global aliases; note + when removing a global aliases that the argument must be quoted + to prevent it from being expanded before being passed to the + command. The -s option causes unhash to remove suffix aliases. + The -f option causes unhash to remove shell functions. The -d + options causes unhash to remove named directories. If the -m + flag is given the arguments are taken as patterns (should be + quoted) and all elements of the corresponding hash table with + matching names will be removed. + +unalias [ -ams ] name ... + Removes aliases. This command works the same as unhash -a, ex- + cept that the -a option removes all regular or global aliases, + or with -s all suffix aliases: in this case no name arguments + may appear. The options -m (remove by pattern) and -s without + -a (remove listed suffix aliases) behave as for unhash -a. Note + that the meaning of -a is different between unalias and unhash. + +unfunction + Same as unhash -f. diff --git a/Doc/help/unlimit b/Doc/help/unlimit new file mode 100644 index 000000000..42d64480a --- /dev/null +++ b/Doc/help/unlimit @@ -0,0 +1,10 @@ +unlimit [ -hs ] resource ... + The resource limit for each resource is set to the hard limit. + If the -h flag is given and the shell has appropriate privi- + leges, the hard resource limit for each resource is removed. + The resources of the shell process are only changed if the -s + flag is given. + + The unlimit command is not made available by default when the + shell starts in a mode emulating another shell. It can be made + available with the command `zmodload -F zsh/rlimits b:unlimit'. diff --git a/Doc/help/unset b/Doc/help/unset new file mode 100644 index 000000000..a48687fd5 --- /dev/null +++ b/Doc/help/unset @@ -0,0 +1,20 @@ +unset [ -fmv ] name ... + Each named parameter is unset. Local parameters remain local + even if unset; they appear unset within scope, but the previous + value will still reappear when the scope ends. + + Individual elements of associative array parameters may be unset + by using subscript syntax on name, which should be quoted (or + the entire command prefixed with noglob) to protect the sub- + script from filename generation. + + If the -m flag is specified the arguments are taken as patterns + (should be quoted) and all parameters with matching names are + unset. Note that this cannot be used when unsetting associative + array elements, as the subscript will be treated as part of the + pattern. + + The -v flag specifies that name refers to parameters. This is + the default behaviour. + + unset -f is equivalent to unfunction. diff --git a/Doc/help/unsetopt b/Doc/help/unsetopt new file mode 100644 index 000000000..dd8654a2f --- /dev/null +++ b/Doc/help/unsetopt @@ -0,0 +1,8 @@ +unsetopt [ {+|-}options | {+|-}o option_name ] [ name ... ] + Unset the options for the shell. All options specified either + with flags or by name are unset. If no arguments are supplied, + the names of all options currently unset are printed. If the -m + flag is given the arguments are taken as patterns (which should + be quoted to preserve them from being interpreted as glob pat- + terns), and all options with names matching these patterns are + unset. diff --git a/Doc/help/vared b/Doc/help/vared new file mode 100644 index 000000000..f920ca75f --- /dev/null +++ b/Doc/help/vared @@ -0,0 +1 @@ +vared See the section `Zle Builtins' in zshzle(1). diff --git a/Doc/help/wait b/Doc/help/wait new file mode 100644 index 000000000..876a9669f --- /dev/null +++ b/Doc/help/wait @@ -0,0 +1,25 @@ +wait [ job ... ] + Wait for the specified jobs or processes. If job is not given + then all currently active child processes are waited for. Each + job can be either a job specification or the process ID of a job + in the job table. The exit status from this command is that of + the job waited for. If job represents an unknown job or process + ID, a warning is printed (unless the POSIX_BUILTINS option is + set) and the exit status is 127. + + It is possible to wait for recent processes (specified by + process ID, not by job) that were running in the background even + if the process has exited. Typically the process ID will be + recorded by capturing the value of the variable $! immediately + after the process has been started. There is a limit on the + number of process IDs remembered by the shell; this is given by + the value of the system configuration parameter CHILD_MAX. When + this limit is reached, older process IDs are discarded, least + recently started processes first. + + Note there is no protection against the process ID wrapping, + i.e. if the wait is not executed soon enough there is a chance + the process waited for is the wrong one. A conflict implies + both process IDs have been generated by the shell, as other pro- + cesses are not recorded, and that the user is potentially inter- + ested in both, so this problem is intrinsic to process IDs. diff --git a/Doc/help/whence b/Doc/help/whence new file mode 100644 index 000000000..5ef016295 --- /dev/null +++ b/Doc/help/whence @@ -0,0 +1,64 @@ +whence [ -vcwfpamsS ] [ -x num ] name ... + For each name, indicate how it would be interpreted if used as a + command name. + + If name is not an alias, built-in command, external command, + shell function, hashed command, or a reserved word, the exit + status shall be non-zero, and -- if -v, -c, or -w was passed -- + a message will be written to standard output. (This is differ- + ent from other shells that write that message to standard er- + ror.) + + whence is most useful when name is only the last path component + of a command, i.e. does not include a `/'; in particular, pat- + tern matching only succeeds if just the non-directory component + of the command is passed. + + -v Produce a more verbose report. + + -c Print the results in a csh-like format. This takes + precedence over -v. + + -w For each name, print `name: word' where word is one of + alias, builtin, command, function, hashed, reserved or + none, according as name corresponds to an alias, a + built-in command, an external command, a shell function, + a command defined with the hash builtin, a reserved word, + or is not recognised. This takes precedence over -v and + -c. + + -f Causes the contents of a shell function to be displayed, + which would otherwise not happen unless the -c flag were + used. + + -p Do a path search for name even if it is an alias, re- + served word, shell function or builtin. + + -a Do a search for all occurrences of name throughout the + command path. Normally only the first occurrence is + printed. + + -m The arguments are taken as patterns (pattern characters + should be quoted), and the information is displayed for + each command matching one of these patterns. + + -s If a pathname contains symlinks, print the symlink-free + pathname as well. + + -S As -s, but if the pathname had to be resolved by follow- + ing multiple symlinks, the intermediate steps are + printed, too. The symlink resolved at each step might be + anywhere in the path. + + -x num Expand tabs when outputting shell functions using the -c + option. This has the same effect as the -x option to the + functions builtin. + +type [ -wfpamsS ] name ... + Equivalent to whence -v. + +where [ -wpmsS ] [ -x num ] name ... + Equivalent to whence -ca. + +which [ -wpamsS ] [ -x num ] name ... + Equivalent to whence -c. diff --git a/Doc/help/zcompile b/Doc/help/zcompile new file mode 100644 index 000000000..f79597e7c --- /dev/null +++ b/Doc/help/zcompile @@ -0,0 +1,122 @@ +zcompile [ -U ] [ -z | -k ] [ -R | -M ] file [ name ... ] +zcompile -ca [ -m ] [ -R | -M ] file [ name ... ] +zcompile -t file [ name ... ] + This builtin command can be used to compile functions or + scripts, storing the compiled form in a file, and to examine + files containing the compiled form. This allows faster au- + toloading of functions and sourcing of scripts by avoiding pars- + ing of the text when the files are read. + + The first form (without the -c, -a or -t options) creates a com- + piled file. If only the file argument is given, the output file + has the name `file.zwc' and will be placed in the same directory + as the file. The shell will load the compiled file instead of + the normal function file when the function is autoloaded; see + the section `Autoloading Functions' in zshmisc(1) for a descrip- + tion of how autoloaded functions are searched. The extension + .zwc stands for `zsh word code'. + + If there is at least one name argument, all the named files are + compiled into the output file given as the first argument. If + file does not end in .zwc, this extension is automatically ap- + pended. Files containing multiple compiled functions are called + `digest' files, and are intended to be used as elements of the + FPATH/fpath special array. + + The second form, with the -c or -a options, writes the compiled + definitions for all the named functions into file. For -c, the + names must be functions currently defined in the shell, not + those marked for autoloading. Undefined functions that are + marked for autoloading may be written by using the -a option, in + which case the fpath is searched and the contents of the defini- + tion files for those functions, if found, are compiled into + file. If both -c and -a are given, names of both defined func- + tions and functions marked for autoloading may be given. In ei- + ther case, the functions in files written with the -c or -a op- + tion will be autoloaded as if the KSH_AUTOLOAD option were un- + set. + + The reason for handling loaded and not-yet-loaded functions with + different options is that some definition files for autoloading + define multiple functions, including the function with the same + name as the file, and, at the end, call that function. In such + cases the output of `zcompile -c' does not include the addi- + tional functions defined in the file, and any other initializa- + tion code in the file is lost. Using `zcompile -a' captures all + this extra information. + + If the -m option is combined with -c or -a, the names are used + as patterns and all functions whose names match one of these + patterns will be written. If no name is given, the definitions + of all functions currently defined or marked as autoloaded will + be written. + + Note the second form cannot be used for compiling functions that + include redirections as part of the definition rather than + within the body of the function; for example + + fn1() { { ... } >~/logfile } + + can be compiled but + + fn1() { ... } >~/logfile + + cannot. It is possible to use the first form of zcompile to + compile autoloadable functions that include the full function + definition instead of just the body of the function. + + The third form, with the -t option, examines an existing com- + piled file. Without further arguments, the names of the origi- + nal files compiled into it are listed. The first line of output + shows the version of the shell which compiled the file and how + the file will be used (i.e. by reading it directly or by mapping + it into memory). With arguments, nothing is output and the re- + turn status is set to zero if definitions for all names were + found in the compiled file, and non-zero if the definition for + at least one name was not found. + + Other options: + + -U Aliases are not expanded when compiling the named files. + + -R When the compiled file is read, its contents are copied + into the shell's memory, rather than memory-mapped (see + -M). This happens automatically on systems that do not + support memory mapping. + + When compiling scripts instead of autoloadable functions, + it is often desirable to use this option; otherwise the + whole file, including the code to define functions which + have already been defined, will remain mapped, conse- + quently wasting memory. + + -M The compiled file is mapped into the shell's memory when + read. This is done in such a way that multiple instances + of the shell running on the same host will share this + mapped file. If neither -R nor -M is given, the zcompile + builtin decides what to do based on the size of the com- + piled file. + + -k + -z These options are used when the compiled file contains + functions which are to be autoloaded. If -z is given, the + function will be autoloaded as if the KSH_AUTOLOAD option + is not set, even if it is set at the time the compiled + file is read, while if the -k is given, the function will + be loaded as if KSH_AUTOLOAD is set. These options also + take precedence over any -k or -z options specified to + the autoload builtin. If neither of these options is + given, the function will be loaded as determined by the + setting of the KSH_AUTOLOAD option at the time the com- + piled file is read. + + These options may also appear as many times as necessary + between the listed names to specify the loading style of + all following functions, up to the next -k or -z. + + The created file always contains two versions of the com- + piled format, one for big-endian machines and one for + small-endian machines. The upshot of this is that the + compiled file is machine independent and if it is read or + mapped, only one half of the file is actually used (and + mapped). diff --git a/Doc/help/zformat b/Doc/help/zformat new file mode 100644 index 000000000..f962636ea --- /dev/null +++ b/Doc/help/zformat @@ -0,0 +1,2 @@ +zformat + See the section `The zsh/zutil Module' in zshmodules(1). diff --git a/Doc/help/zftp b/Doc/help/zftp new file mode 100644 index 000000000..2c66b3a7b --- /dev/null +++ b/Doc/help/zftp @@ -0,0 +1 @@ +zftp See the section `The zsh/zftp Module' in zshmodules(1). diff --git a/Doc/help/zle b/Doc/help/zle new file mode 100644 index 000000000..d79eedefd --- /dev/null +++ b/Doc/help/zle @@ -0,0 +1 @@ +zle See the section `Zle Builtins' in zshzle(1). diff --git a/Doc/help/zmodload b/Doc/help/zmodload new file mode 100644 index 000000000..a19159d71 --- /dev/null +++ b/Doc/help/zmodload @@ -0,0 +1,308 @@ +zmodload [ -dL ] [ -s ] [ ... ] +zmodload -F [ -alLme -P param ] module [ [+-]feature ... ] +zmodload -e [ -A ] [ ... ] +zmodload [ -a [ -bcpf [ -I ] ] ] [ -iL ] ... +zmodload -u [ -abcdpf [ -I ] ] [ -iL ] ... +zmodload -A [ -L ] [ modalias[=module] ... ] +zmodload -R modalias ... + Performs operations relating to zsh's loadable modules. Loading + of modules while the shell is running (`dynamical loading') is + not available on all operating systems, or on all installations + on a particular operating system, although the zmodload command + itself is always available and can be used to manipulate modules + built into versions of the shell executable without dynamical + loading. + + Without arguments the names of all currently loaded binary mod- + ules are printed. The -L option causes this list to be in the + form of a series of zmodload commands. Forms with arguments + are: + + zmodload [ -is ] name ... + zmodload -u [ -i ] name ... + In the simplest case, zmodload loads a binary module. + The module must be in a file with a name consisting of + the specified name followed by a standard suffix, usually + `.so' (`.sl' on HPUX). If the module to be loaded is al- + ready loaded the duplicate module is ignored. If zmod- + load detects an inconsistency, such as an invalid module + name or circular dependency list, the current code block + is aborted. If it is available, the module is loaded if + necessary, while if it is not available, non-zero status + is silently returned. The option -i is accepted for com- + patibility but has no effect. + + The named module is searched for in the same way a com- + mand is, using $module_path instead of $path. However, + the path search is performed even when the module name + contains a `/', which it usually does. There is no way + to prevent the path search. + + If the module supports features (see below), zmodload + tries to enable all features when loading a module. If + the module was successfully loaded but not all features + could be enabled, zmodload returns status 2. + + If the option -s is given, no error is printed if the + module was not available (though other errors indicating + a problem with the module are printed). The return sta- + tus indicates if the module was loaded. This is appro- + priate if the caller considers the module optional. + + With -u, zmodload unloads modules. The same name must be + given that was given when the module was loaded, but it + is not necessary for the module to exist in the file sys- + tem. The -i option suppresses the error if the module is + already unloaded (or was never loaded). + + Each module has a boot and a cleanup function. The mod- + ule will not be loaded if its boot function fails. Simi- + larly a module can only be unloaded if its cleanup func- + tion runs successfully. + + zmodload -F [ -almLe -P param ] module [ [+-]feature ... ] + zmodload -F allows more selective control over the fea- + tures provided by modules. With no options apart from + -F, the module named module is loaded, if it was not al- + ready loaded, and the list of features is set to the re- + quired state. If no features are specified, the module + is loaded, if it was not already loaded, but the state of + features is unchanged. Each feature may be preceded by a + + to turn the feature on, or - to turn it off; the + is + assumed if neither character is present. Any feature not + explicitly mentioned is left in its current state; if the + module was not previously loaded this means any such fea- + tures will remain disabled. The return status is zero if + all features were set, 1 if the module failed to load, + and 2 if some features could not be set (for example, a + parameter couldn't be added because there was a different + parameter of the same name) but the module was loaded. + + The standard features are builtins, conditions, parame- + ters and math functions; these are indicated by the pre- + fix `b:', `c:' (`C:' for an infix condition), `p:' and + `f:', respectively, followed by the name that the corre- + sponding feature would have in the shell. For example, + `b:strftime' indicates a builtin named strftime and + p:EPOCHSECONDS indicates a parameter named EPOCHSECONDS. + The module may provide other (`abstract') features of its + own as indicated by its documentation; these have no pre- + fix. + + With -l or -L, features provided by the module are + listed. With -l alone, a list of features together with + their states is shown, one feature per line. With -L + alone, a zmodload -F command that would cause enabled + features of the module to be turned on is shown. With + -lL, a zmodload -F command that would cause all the fea- + tures to be set to their current state is shown. If one + of these combinations is given with the option -P param + then the parameter param is set to an array of features, + either features together with their state or (if -L alone + is given) enabled features. + + With the option -L the module name may be omitted; then a + list of all enabled features for all modules providing + features is printed in the form of zmodload -F commands. + If -l is also given, the state of both enabled and dis- + abled features is output in that form. + + A set of features may be provided together with -l or -L + and a module name; in that case only the state of those + features is considered. Each feature may be preceded by + + or - but the character has no effect. If no set of + features is provided, all features are considered. + + With -e, the command first tests that the module is + loaded; if it is not, status 1 is returned. If the mod- + ule is loaded, the list of features given as an argument + is examined. Any feature given with no prefix is simply + tested to see if the module provides it; any feature + given with a prefix + or - is tested to see if is pro- + vided and in the given state. If the tests on all fea- + tures in the list succeed, status 0 is returned, else + status 1. + + With -m, each entry in the given list of features is + taken as a pattern to be matched against the list of fea- + tures provided by the module. An initial + or - must be + given explicitly. This may not be combined with the -a + option as autoloads must be specified explicitly. + + With -a, the given list of features is marked for au- + toload from the specified module, which may not yet be + loaded. An optional + may appear before the feature + name. If the feature is prefixed with -, any existing + autoload is removed. The options -l and -L may be used + to list autoloads. Autoloading is specific to individual + features; when the module is loaded only the requested + feature is enabled. Autoload requests are preserved if + the module is subsequently unloaded until an explicit + `zmodload -Fa module -feature' is issued. It is not an + error to request an autoload for a feature of a module + that is already loaded. + + When the module is loaded each autoload is checked + against the features actually provided by the module; if + the feature is not provided the autoload request is + deleted. A warning message is output; if the module is + being loaded to provide a different feature, and that au- + toload is successful, there is no effect on the status of + the current command. If the module is already loaded at + the time when zmodload -Fa is run, an error message is + printed and status 1 returned. + + zmodload -Fa can be used with the -l, -L, -e and -P op- + tions for listing and testing the existence of autoload- + able features. In this case -l is ignored if -L is spec- + ified. zmodload -FaL with no module name lists autoloads + for all modules. + + Note that only standard features as described above can + be autoloaded; other features require the module to be + loaded before enabling. + + zmodload -d [ -L ] [ name ] + zmodload -d name dep ... + zmodload -ud name [ dep ... ] + The -d option can be used to specify module dependencies. + The modules named in the second and subsequent arguments + will be loaded before the module named in the first argu- + ment. + + With -d and one argument, all dependencies for that mod- + ule are listed. With -d and no arguments, all module de- + pendencies are listed. This listing is by default in a + Makefile-like format. The -L option changes this format + to a list of zmodload -d commands. + + If -d and -u are both used, dependencies are removed. If + only one argument is given, all dependencies for that + module are removed. + + zmodload -ab [ -L ] + zmodload -ab [ -i ] name [ builtin ... ] + zmodload -ub [ -i ] builtin ... + The -ab option defines autoloaded builtins. It defines + the specified builtins. When any of those builtins is + called, the module specified in the first argument is + loaded and all its features are enabled (for selective + control of features use `zmodload -F -a' as described + above). If only the name is given, one builtin is de- + fined, with the same name as the module. -i suppresses + the error if the builtin is already defined or au- + toloaded, but not if another builtin of the same name is + already defined. + + With -ab and no arguments, all autoloaded builtins are + listed, with the module name (if different) shown in + parentheses after the builtin name. The -L option + changes this format to a list of zmodload -a commands. + + If -b is used together with the -u option, it removes + builtins previously defined with -ab. This is only pos- + sible if the builtin is not yet loaded. -i suppresses + the error if the builtin is already removed (or never ex- + isted). + + Autoload requests are retained if the module is subse- + quently unloaded until an explicit `zmodload -ub builtin' + is issued. + + zmodload -ac [ -IL ] + zmodload -ac [ -iI ] name [ cond ... ] + zmodload -uc [ -iI ] cond ... + The -ac option is used to define autoloaded condition + codes. The cond strings give the names of the conditions + defined by the module. The optional -I option is used to + define infix condition names. Without this option prefix + condition names are defined. + + If given no condition names, all defined names are listed + (as a series of zmodload commands if the -L option is + given). + + The -uc option removes definitions for autoloaded condi- + tions. + + zmodload -ap [ -L ] + zmodload -ap [ -i ] name [ parameter ... ] + zmodload -up [ -i ] parameter ... + The -p option is like the -b and -c options, but makes + zmodload work on autoloaded parameters instead. + + zmodload -af [ -L ] + zmodload -af [ -i ] name [ function ... ] + zmodload -uf [ -i ] function ... + The -f option is like the -b, -p, and -c options, but + makes zmodload work on autoloaded math functions instead. + + zmodload -a [ -L ] + zmodload -a [ -i ] name [ builtin ... ] + zmodload -ua [ -i ] builtin ... + Equivalent to -ab and -ub. + + zmodload -e [ -A ] [ string ... ] + The -e option without arguments lists all loaded modules; + if the -A option is also given, module aliases corre- + sponding to loaded modules are also shown. If arguments + are provided, nothing is printed; the return status is + set to zero if all strings given as arguments are names + of loaded modules and to one if at least on string is not + the name of a loaded module. This can be used to test + for the availability of things implemented by modules. + In this case, any aliases are automatically resolved and + the -A flag is not used. + + zmodload -A [ -L ] [ modalias[=module] ... ] + For each argument, if both modalias and module are given, + define modalias to be an alias for the module module. If + the module modalias is ever subsequently requested, ei- + ther via a call to zmodload or implicitly, the shell will + attempt to load module instead. If module is not given, + show the definition of modalias. If no arguments are + given, list all defined module aliases. When listing, if + the -L flag was also given, list the definition as a + zmodload command to recreate the alias. + + The existence of aliases for modules is completely inde- + pendent of whether the name resolved is actually loaded + as a module: while the alias exists, loading and unload- + ing the module under any alias has exactly the same ef- + fect as using the resolved name, and does not affect the + connection between the alias and the resolved name which + can be removed either by zmodload -R or by redefining the + alias. Chains of aliases (i.e. where the first resolved + name is itself an alias) are valid so long as these are + not circular. As the aliases take the same format as + module names, they may include path separators: in this + case, there is no requirement for any part of the path + named to exist as the alias will be resolved first. For + example, `any/old/alias' is always a valid alias. + + Dependencies added to aliased modules are actually added + to the resolved module; these remain if the alias is re- + moved. It is valid to create an alias whose name is one + of the standard shell modules and which resolves to a + different module. However, if a module has dependencies, + it will not be possible to use the module name as an + alias as the module will already be marked as a loadable + module in its own right. + + Apart from the above, aliases can be used in the zmodload + command anywhere module names are required. However, + aliases will not be shown in lists of loaded modules with + a bare `zmodload'. + + zmodload -R modalias ... + For each modalias argument that was previously defined as + a module alias via zmodload -A, delete the alias. If any + was not defined, an error is caused and the remainder of + the line is ignored. + + Note that zsh makes no distinction between modules that were + linked into the shell and modules that are loaded dynamically. + In both cases this builtin command has to be used to make avail- + able the builtins and other things defined by modules (unless + the module is autoloaded on these definitions). This is true + even for systems that don't support dynamic loading of modules. diff --git a/Doc/help/zparseopts b/Doc/help/zparseopts new file mode 100644 index 000000000..82608a2c2 --- /dev/null +++ b/Doc/help/zparseopts @@ -0,0 +1,2 @@ +zparseopts + See the section `The zsh/zutil Module' in zshmodules(1). diff --git a/Doc/help/zprof b/Doc/help/zprof new file mode 100644 index 000000000..7885238c7 --- /dev/null +++ b/Doc/help/zprof @@ -0,0 +1 @@ +zprof See the section `The zsh/zprof Module' in zshmodules(1). diff --git a/Doc/help/zpty b/Doc/help/zpty new file mode 100644 index 000000000..1e169fd34 --- /dev/null +++ b/Doc/help/zpty @@ -0,0 +1 @@ +zpty See the section `The zsh/zpty Module' in zshmodules(1). diff --git a/Doc/help/zregexparse b/Doc/help/zregexparse new file mode 100644 index 000000000..717fb78ad --- /dev/null +++ b/Doc/help/zregexparse @@ -0,0 +1,2 @@ +zregexparse + See the section `The zsh/zutil Module' in zshmodules(1). diff --git a/Doc/help/zsocket b/Doc/help/zsocket new file mode 100644 index 000000000..6e6f81fb6 --- /dev/null +++ b/Doc/help/zsocket @@ -0,0 +1,2 @@ +zsocket + See the section `The zsh/net/socket Module' in zshmodules(1). diff --git a/Doc/help/zstyle b/Doc/help/zstyle new file mode 100644 index 000000000..654a4041d --- /dev/null +++ b/Doc/help/zstyle @@ -0,0 +1 @@ +zstyle See the section `The zsh/zutil Module' in zshmodules(1). diff --git a/Doc/help/ztcp b/Doc/help/ztcp new file mode 100644 index 000000000..9b9d62f61 --- /dev/null +++ b/Doc/help/ztcp @@ -0,0 +1 @@ +ztcp See the section `The zsh/net/tcp Module' in zshmodules(1). diff --git a/Doc/version.yo b/Doc/version.yo new file mode 100644 index 000000000..3ca873cfd --- /dev/null +++ b/Doc/version.yo @@ -0,0 +1,9 @@ +IFDEF(INCWSLEVEL)(INCWSLEVEL())(STARTDEF()) +def(version)(0)(5.8.1.3-test) +def(date)(0)(May 1, 2022) +def(zshenv)(0)(/etc/zshenv) +def(zprofile)(0)(/etc/zprofile) +def(zshrc)(0)(/etc/zshrc) +def(zlogin)(0)(/etc/zlogin) +def(zlogout)(0)(/etc/zlogout) +IFDEF(DECWSLEVEL)(DECWSLEVEL())(ENDDEF())\ diff --git a/Doc/zsh.1 b/Doc/zsh.1 new file mode 100644 index 000000000..b5a7a96c3 --- /dev/null +++ b/Doc/zsh.1 @@ -0,0 +1,529 @@ +.TH "ZSH" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zsh \- the Z shell +.\" Yodl file: Zsh/intro.yo +.SH "OVERVIEW" +Because zsh contains many features, the zsh manual has been split into +a number of sections: +.PP +.PD 0 +.TP +\fIzsh\fP Zsh overview (this section) +.TP +\fIzshroadmap\fP Informal introduction to the manual +.TP +\fIzshmisc\fP Anything not fitting into the other sections +.TP +\fIzshexpn\fP Zsh command and parameter expansion +.TP +\fIzshparam\fP Zsh parameters +.TP +\fIzshoptions\fP Zsh options +.TP +\fIzshbuiltins\fP Zsh built\-in functions +.TP +\fIzshzle\fP Zsh command line editing +.TP +\fIzshcompwid\fP Zsh completion widgets +.TP +\fIzshcompsys\fP Zsh completion system +.TP +\fIzshcompctl\fP Zsh completion control +.TP +\fIzshmodules\fP Zsh loadable modules +.TP +\fIzshcalsys\fP Zsh built\-in calendar functions +.TP +\fIzshtcpsys\fP Zsh built\-in TCP functions +.TP +\fIzshzftpsys\fP Zsh built\-in FTP client +.TP +\fIzshcontrib\fP Additional zsh functions and utilities +.TP +\fIzshall\fP Meta\-man page containing all of the above +.PD +.SH "DESCRIPTION" +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 \fBksh\fP but includes many enhancements\&. It +does not provide compatibility with POSIX or other shells in its +default operating mode: see +the section `Compatibility\&' below\&. +.PP +Zsh has command line editing, builtin spelling correction, programmable +command completion, shell functions (with autoloading), a history +mechanism, and a host of other features\&. +.\" Yodl file: Zsh/metafaq.yo +.SH "AUTHOR" +Zsh was originally written by Paul Falstad\&. Zsh is now maintained by +the members of the zsh\-workers mailing list \fB<zsh\-workers@zsh\&.org>\fP\&. +The development is currently coordinated by Peter Stephenson +\fB<pws@zsh\&.org>\fP\&. The coordinator can be contacted at +\fB<coordinator@zsh\&.org>\fP, but matters relating to the code should +generally go to the mailing list\&. +.SH "AVAILABILITY" +Zsh is available from the following HTTP and anonymous FTP site\&. +.PP +.nf +\fBftp://ftp\&.zsh\&.org/pub/\fP +\fBhttps://www\&.zsh\&.org/pub/\fP +.fi +.PP +The up\-to\-date source code is available via Git from Sourceforge\&. See +\fBhttps://sourceforge\&.net/projects/zsh/\fP for details\&. A summary of +instructions for the archive can be found at +\fBhttps://zsh\&.sourceforge\&.io/\fP\&. +.PP +.SH "MAILING LISTS" +Zsh has several mailing lists: +.PP +.PD 0 +.TP +.PD +\fB<zsh\-announce@zsh\&.org>\fP +Announcements about releases, major changes in the shell and the +monthly posting of the Zsh FAQ\&. (moderated) +.TP +\fB<zsh\-users@zsh\&.org>\fP +User discussions\&. +.TP +\fB<zsh\-workers@zsh\&.org>\fP +Hacking, development, bug reports and patches\&. +.TP +\fB<zsh\-security@zsh\&.org>\fP +Private mailing list (the general public cannot subscribe to it) for discussing +bug reports with security implications, i\&.e\&., potential vulnerabilities\&. +.RS +.PP +If you find a security problem in zsh itself, please mail this address\&. +.RE +.PP +To subscribe or unsubscribe, send mail +to the associated administrative address for the mailing list\&. +.PP +.PD 0 +.TP +\fB<zsh\-announce\-subscribe@zsh\&.org>\fP +.TP +\fB<zsh\-users\-subscribe@zsh\&.org>\fP +.TP +\fB<zsh\-workers\-subscribe@zsh\&.org>\fP +.PP +.TP +\fB<zsh\-announce\-unsubscribe@zsh\&.org>\fP +.TP +\fB<zsh\-users\-unsubscribe@zsh\&.org>\fP +.TP +\fB<zsh\-workers\-unsubscribe@zsh\&.org>\fP +.PD +.PP +YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED\&. +All submissions to \fBzsh\-announce\fP are automatically forwarded to +\fBzsh\-users\fP\&. All submissions to \fBzsh\-users\fP are automatically +forwarded to \fBzsh\-workers\fP\&. +.PP +If you have problems subscribing/unsubscribing to any of the mailing +lists, send mail to \fB<listmaster@zsh\&.org>\fP\&. +.PP +The mailing lists are archived; the archives can be accessed via the +administrative addresses listed above\&. There is also a hypertext +archive available at +\fBhttps://www\&.zsh\&.org/mla/\fP\&. +.SH "THE ZSH FAQ" +Zsh has a list of Frequently Asked Questions (FAQ), maintained by +Peter Stephenson \fB<pws@zsh\&.org>\fP\&. It is regularly posted to the +newsgroup \fBcomp\&.unix\&.shell\fP and the \fBzsh\-announce\fP mailing list\&. +The latest version can be found at any of the Zsh FTP sites, or at +\fBhttps://www\&.zsh\&.org/FAQ/\fP\&. The contact address for FAQ\-related matters +is \fB<faqmaster@zsh\&.org>\fP\&. +.SH "THE ZSH WEB PAGE" +Zsh has a web page which is located at \fBhttps://www\&.zsh\&.org/\fP\&. +The contact address for web\-related matters is \fB<webmaster@zsh\&.org>\fP\&. +.SH "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 +\fBhttps://zsh\&.sourceforge\&.io/Guide/\fP\&. At the time of writing, chapters +dealing with startup files and their contents and the new completion system +were essentially complete\&. +.\" Yodl file: Zsh/invoke.yo +.SH "INVOCATION" +The following flags are interpreted by the shell when invoked to determine +where the shell will read commands from: +.PP +.PD 0 +.TP +.PD +\fB\-c\fP +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 \fB$0\fP, rather than being used as a positional +parameter\&. +.TP +\fB\-i\fP +Force shell to be interactive\&. It is still possible to specify a +script to execute\&. +.TP +\fB\-s\fP +Force shell to read commands from the standard input\&. +If the \fB\-s\fP flag is not present and an argument is given, +the first argument is taken to be the pathname of a script to +execute\&. +.PP +If there are any remaining arguments after option processing, and neither +of the options \fB\-c\fP or \fB\-s\fP was supplied, the first argument is taken +as the file name of a script containing shell commands to be executed\&. If +the option \fBPATH_SCRIPT\fP is set, and the file name does not contain a +directory path (i\&.e\&. there is no `\fB/\fP\&' in the name), first the current +directory and then the command path given by the variable \fBPATH\fP are +searched for the script\&. If the option is not set or the file name +contains a `\fB/\fP\&' it is used directly\&. +.PP +After the first one or two arguments have been appropriated as described above, +the remaining arguments are assigned to the positional parameters\&. +.PP +For further options, which are common to invocation and the \fBset\fP +builtin, see +\fIzshoptions\fP(1)\&. +.PP +The long option `\fB\-\fP\fB\-emulate\fP\&' followed (in a separate word) by an +emulation mode may be passed to the shell\&. +The emulation modes are those described for the \fBemulate\fP builtin, +see +\fIzshbuiltins\fP(1)\&. +The `\fB\-\fP\fB\-emulate\fP\&' 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 \fBemulate\fP command within the shell: for +example, variables that conflict with POSIX usage such as \fBpath\fP are +not defined within the shell\&. +.PP +Options may be specified by name using the \fB\-o\fP option\&. \fB\-o\fP acts like +a single\-letter option, but takes a following string as the option name\&. +For example, +.PP +.RS +.nf +\fBzsh \-x \-o shwordsplit scr\fP +.fi +.RE +.PP +runs the script \fBscr\fP, setting the \fBXTRACE\fP option by the corresponding +letter `\fB\-x\fP\&' and the \fBSH_WORD_SPLIT\fP option by name\&. +Options may be turned \fIoff\fP by name by using \fB+o\fP instead of \fB\-o\fP\&. +\fB\-o\fP can be stacked up with preceding single\-letter options, so for example +`\fB\-xo shwordsplit\fP\&' or `\fB\-xoshwordsplit\fP' is equivalent to +`\fB\-x \-o shwordsplit\fP\&'\&. +.PP +Options may also be specified by name in GNU long option style, +`\fB\-\fP\fB\-\fP\fIoption\-name\fP\&'\&. When this is done, `\fB\-\fP' characters in the +option name are permitted: they are translated into `\fB_\fP\&', and thus ignored\&. +So, for example, `\fBzsh \-\fP\fB\-sh\-word\-split\fP\&' invokes zsh with the +\fBSH_WORD_SPLIT\fP option turned on\&. Like other option syntaxes, options can +be turned off by replacing the initial `\fB\-\fP\&' with a `\fB+\fP'; thus +`\fB+\-sh\-word\-split\fP\&' is equivalent to `\fB\-\fP\fB\-no\-sh\-word\-split\fP'\&. +Unlike other option syntaxes, GNU\-style long options cannot be stacked with +any other options, so for example `\fB\-x\-shwordsplit\fP\&' is an error, +rather than being treated like `\fB\-x \-\fP\fB\-shwordsplit\fP\&'\&. +.PP +The special GNU\-style option `\fB\-\fP\fB\-version\fP\&' is handled; it sends to +standard output the shell\&'s version information, then exits successfully\&. +`\fB\-\fP\fB\-help\fP\&' is also handled; it sends to standard output a list of +options that can be used when invoking the shell, then exits successfully\&. +.PP +Option processing may be finished, allowing following arguments that start with +`\fB\-\fP\&' or `\fB+\fP' to be treated as normal arguments, in two ways\&. +Firstly, a lone `\fB\-\fP\&' (or `\fB+\fP') as an argument by itself ends +option processing\&. Secondly, a special option `\fB\-\fP\fB\-\fP\&' (or +`\fB+\-\fP\&'), which may be specified on its own (which is the standard +POSIX usage) or may be stacked with preceding options (so `\fB\-x\-\fP\&' is +equivalent to `\fB\-x \-\fP\fB\-\fP\&')\&. Options are not permitted to be stacked +after `\fB\-\fP\fB\-\fP\&' (so `\fB\-x\-f\fP' is an error), but note the GNU\-style +option form discussed above, where `\fB\-\fP\fB\-shwordsplit\fP\&' is permitted +and does not end option processing\&. +.PP +Except when the \fBsh\fP/\fBksh\fP emulation single\-letter options are in effect, +the option `\fB\-b\fP\&' (or `\fB+b\fP') ends option processing\&. +`\fB\-b\fP\&' is like `\fB\-\fP\fB\-\fP', except that further single\-letter options +can be stacked after the `\fB\-b\fP\&' and will take effect as normal\&. +.PP +.PP +.\" Yodl file: Zsh/compat.yo +.SH "COMPATIBILITY" +Zsh tries to emulate \fBsh\fP or \fBksh\fP when it is invoked as +\fBsh\fP or \fBksh\fP respectively; more precisely, it looks at the first +letter of the name by which it was invoked, excluding any initial `\fBr\fP\&' +(assumed to stand for `restricted\&'), and if that is `\fBb\fP', `\fBs\fP' or `\fBk\fP' it +will emulate \fBsh\fP or \fBksh\fP\&. Furthermore, if invoked as \fBsu\fP (which +happens on certain systems when the shell is executed by the \fBsu\fP +command), the shell will try to find an alternative name from the \fBSHELL\fP +environment variable and perform emulation based on that\&. +.PP +In \fBsh\fP and \fBksh\fP compatibility modes the following +parameters are not special and not initialized by the shell: +\fBARGC\fP, +\fBargv\fP, +\fBcdpath\fP, +\fBfignore\fP, +\fBfpath\fP, +\fBHISTCHARS\fP, +\fBmailpath\fP, +\fBMANPATH\fP, +\fBmanpath\fP, +\fBpath\fP, +\fBprompt\fP, +\fBPROMPT\fP, +\fBPROMPT2\fP, +\fBPROMPT3\fP, +\fBPROMPT4\fP, +\fBpsvar\fP, +\fBstatus\fP\&. +.PP +The usual zsh startup/shutdown scripts are not executed\&. Login shells +source \fB/etc/profile\fP followed by \fB$HOME/\&.profile\fP\&. If the +\fBENV\fP environment variable is set on invocation, \fB$ENV\fP is sourced +after the profile scripts\&. The value of \fBENV\fP is subjected to +parameter expansion, command substitution, and arithmetic expansion +before being interpreted as a pathname\&. Note that the \fBPRIVILEGED\fP +option also affects the execution of startup files\&. +.PP +The following options are set if the shell is invoked as \fBsh\fP or +\fBksh\fP: +\fBNO_BAD_PATTERN\fP, +\fBNO_BANG_HIST\fP, +\fBNO_BG_NICE\fP, +\fBNO_EQUALS\fP, +\fBNO_FUNCTION_ARGZERO\fP, +\fBGLOB_SUBST\fP, +\fBNO_GLOBAL_EXPORT\fP, +\fBNO_HUP\fP, +\fBINTERACTIVE_COMMENTS\fP, +\fBKSH_ARRAYS\fP, +\fBNO_MULTIOS\fP, +\fBNO_NOMATCH\fP, +\fBNO_NOTIFY\fP, +\fBPOSIX_BUILTINS\fP, +\fBNO_PROMPT_PERCENT\fP, +\fBRM_STAR_SILENT\fP, +\fBSH_FILE_EXPANSION\fP, +\fBSH_GLOB\fP, +\fBSH_OPTION_LETTERS\fP, +\fBSH_WORD_SPLIT\fP\&. +Additionally the \fBBSD_ECHO\fP and \fBIGNORE_BRACES\fP +options are set if zsh is invoked as \fBsh\fP\&. +Also, the +\fBKSH_OPTION_PRINT\fP, +\fBLOCAL_OPTIONS\fP, +\fBPROMPT_BANG\fP, +\fBPROMPT_SUBST\fP +and +\fBSINGLE_LINE_ZLE\fP +options are set if zsh is invoked as \fBksh\fP\&. +.PP +Please note that, whilst reasonable efforts are taken to address +incompatibilities when they arise, zsh does not guarantee complete +emulation of other shells, nor POSIX compliance\&. For more information on +the differences between zsh and other shells, please refer to chapter 2 +of the shell FAQ, \fBhttps://www\&.zsh\&.org/FAQ/\fP\&. +.\" Yodl file: Zsh/restricted.yo +.SH "RESTRICTED SHELL" +When the basename of the command used to invoke zsh starts with the letter +`\fBr\fP\&' or the `\fB\-r\fP' command line option is supplied at invocation, the +shell becomes restricted\&. Emulation mode is determined after stripping the +letter `\fBr\fP\&' from the invocation name\&. The following are disabled in +restricted mode: +.PP +.PD 0 +.TP +.PD +\(bu +changing directories with the \fBcd\fP builtin +.TP +\(bu +changing or unsetting the \fBEGID\fP, \fBEUID\fP, \fBGID\fP, +\fBHISTFILE\fP, \fBHISTSIZE\fP, \fBIFS\fP, \fBLD_AOUT_LIBRARY_PATH\fP, +\fBLD_AOUT_PRELOAD\fP, \fBLD_LIBRARY_PATH\fP, \fBLD_PRELOAD\fP, +\fBMODULE_PATH\fP, \fBmodule_path\fP, \fBPATH\fP, \fBpath\fP, \fBSHELL\fP, +\fBUID\fP and \fBUSERNAME\fP parameters +.TP +\(bu +specifying command names containing \fB/\fP +.TP +\(bu +specifying command pathnames using \fBhash\fP +.TP +\(bu +redirecting output to files +.TP +\(bu +using the \fBexec\fP builtin command to replace the shell with another +command +.TP +\(bu +using \fBjobs \-Z\fP to overwrite the shell process\&' argument and +environment space +.TP +\(bu +using the \fBARGV0\fP parameter to override \fBargv[0]\fP for external +commands +.TP +\(bu +turning off restricted mode with \fBset +r\fP or \fBunsetopt +RESTRICTED\fP +.PP +These restrictions are enforced after processing the startup files\&. The +startup files should set up \fBPATH\fP 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\&. +.PP +Restricted mode can also be activated any time by setting the +\fBRESTRICTED\fP option\&. This immediately enables all the restrictions +described above even if the shell still has not processed all startup +files\&. +.PP +A shell \fIRestricted Mode\fP 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 \fIchroot jails\fP, \fIcontainers\fP and +\fIzones\fP\&. +.PP +A restricted shell is very difficult to implement safely\&. The feature +may be removed in a future version of zsh\&. +.PP +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 `\fBPATH\fP\&' variable, it does not prevent those +commands from running any other command\&. +.PP +As an example, if `\fBenv\fP\&' is among the list of \fIallowed\fP commands, +then it allows the user to run any command as `\fBenv\fP\&' is not a shell +builtin command and can run arbitrary executables\&. +.PP +So when implementing a restricted shell framework it is important to be +fully aware of what actions each of the \fIallowed\fP commands or features +(which may be regarded as \fImodules\fP) can perform\&. +.PP +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\&. +.PP +If a `\fBperl\fP\&', `\fBpython\fP', `\fBbash\fP', or other general purpose +interpreted script it treated as a restricted +command, the user can work around the restriction by +setting specially crafted `\fBPERL5LIB\fP\&', `\fBPYTHONPATH\fP', +`\fBBASHENV\fP\&' (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 `\fBGCONV_PATH\fP\&' +environment variable\&. Those are only a few examples\&. +.PP +Bear in mind that, contrary to some other shells, `\fBreadonly\fP\&' is not a +security feature in zsh as it can be undone and so cannot be used to +mitigate the above\&. +.PP +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 `\fBzsh/system\fP\&', `\fBzsh/mapfile\fP' and +`\fBzsh/files\fP\&', allow bypassing most of the restrictions\&. +.\" Yodl file: Zsh/files.yo +.SH "STARTUP/SHUTDOWN FILES" +Commands are first read from \fB/etc/zshenv\fP; this cannot be overridden\&. +Subsequent behaviour is modified by the \fBRCS\fP and +\fBGLOBAL_RCS\fP options; the former affects all startup files, while the +second only affects global startup files (those shown here with an +path starting with a \fB/\fP)\&. 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 \fB$ZDOTDIR\fP to +re\-enable \fBGLOBAL_RCS\fP\&. Both \fBRCS\fP and \fBGLOBAL_RCS\fP are set by +default\&. +.PP +Commands are then read from \fB$ZDOTDIR/\&.zshenv\fP\&. +If the shell is a login shell, commands +are read from \fB/etc/zprofile\fP and then \fB$ZDOTDIR/\&.zprofile\fP\&. +Then, if the shell is interactive, +commands are read from \fB/etc/zshrc\fP and then \fB$ZDOTDIR/\&.zshrc\fP\&. +Finally, if the shell is a login shell, \fB/etc/zlogin\fP and +\fB$ZDOTDIR/\&.zlogin\fP are read\&. +.PP +When a login shell exits, the files \fB$ZDOTDIR/\&.zlogout\fP and then +\fB/etc/zlogout\fP are read\&. This happens with either an explicit exit +via the \fBexit\fP or \fBlogout\fP commands, or an implicit exit by reading +end\-of\-file from the terminal\&. However, if the shell terminates due +to \fBexec\fP\&'ing another process, the logout files are not read\&. +These are also affected by the \fBRCS\fP and \fBGLOBAL_RCS\fP options\&. +Note also that the \fBRCS\fP option affects the saving of history files, +i\&.e\&. if \fBRCS\fP is unset when the shell exits, no history file will be +saved\&. +.PP +If \fBZDOTDIR\fP is unset, \fBHOME\fP is used instead\&. +Files listed above as being in \fB/etc\fP may be in another +directory, depending on the installation\&. +.PP +As \fB/etc/zshenv\fP 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 `\fBif [[ \-o rcs ]]; then \&.\&.\&.\fP\&' so that it will not +be executed when zsh is invoked with the `\fB\-f\fP\&' option\&. +.PP +Any of these files may be pre\-compiled with the \fBzcompile\fP builtin +command (see \fIzshbuiltins\fP(1))\&. If a compiled file exists (named for the original file plus the +\fB\&.zwc\fP extension) and it is newer than the original file, the compiled +file will be used instead\&. +.\" Yodl file: Zsh/filelist.yo +.SH "FILES" +.PD 0 +.TP +\fB$ZDOTDIR/\&.zshenv\fP +.TP +\fB$ZDOTDIR/\&.zprofile\fP +.TP +\fB$ZDOTDIR/\&.zshrc\fP +.TP +\fB$ZDOTDIR/\&.zlogin\fP +.TP +\fB$ZDOTDIR/\&.zlogout\fP +.TP +\fB${TMPPREFIX}*\fP (default is /tmp/zsh*) +.TP +\fB/etc/zshenv\fP +.TP +\fB/etc/zprofile\fP +.TP +\fB/etc/zshrc\fP +.TP +\fB/etc/zlogin\fP +.TP +\fB/etc/zlogout\fP (installation\-specific \- \fB/etc\fP is the default) +.PD +.\" Yodl file: Zsh/seealso.yo +.SH "SEE ALSO" +\fIsh\fP(1), +\fIcsh\fP(1), +\fItcsh\fP(1), +\fIrc\fP(1), +\fIbash\fP(1), +\fIksh\fP(1), +\fIzshall\fP(1), +\fIzshbuiltins\fP(1), +\fIzshcalsys\fP(1), +\fIzshcompwid\fP(1), +\fIzshcompsys\fP(1), +\fIzshcompctl\fP(1), +\fIzshcontrib\fP(1), +\fIzshexpn\fP(1), +\fIzshmisc\fP(1), +\fIzshmodules\fP(1), +\fIzshoptions\fP(1), +\fIzshparam\fP(1), +\fIzshroadmap\fP(1), +\fIzshtcpsys\fP(1), +\fIzshzftpsys\fP(1), +\fIzshzle\fP(1) +.PP +\fBIEEE Standard for information Technology \- +Portable Operating System Interface (POSIX) \- +Part 2: Shell and Utilities\fP, +IEEE Inc, 1993, ISBN 1\-55937\-255\-9\&. diff --git a/Doc/zsh.texi b/Doc/zsh.texi new file mode 100644 index 000000000..9796d4c81 --- /dev/null +++ b/Doc/zsh.texi @@ -0,0 +1,41309 @@ +\input texinfo.tex +@c %**start of header +@iftex +@setchapternewpage off +@end iftex +@setfilename zsh.info +@settitle zsh +@c %**end of header + +@ifinfo +@set dsq '@:' +@set dsbq `@:` +@end ifinfo +@iftex +@set dsq '{}' +@set dsbq `{}` +@end iftex +@ifinfo +@dircategory Utilities +@direntry +* ZSH: (zsh). The Z Shell Manual. +@end direntry +@end ifinfo + +@iftex +@finalout +@end iftex +@titlepage +@title The Z Shell Manual +@subtitle Version 5.8.1.3-test +@subtitle Updated May 1, 2022 +@author Original documentation by Paul Falstad +@page +This is a texinfo version of the documentation for the Z Shell, originally by +Paul Falstad. + +@noindent +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@noindent +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +@noindent +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end titlepage +@contents +@c Yodl file: Zsh/manual.yo +@ifnottex +@node Top, The Z Shell Manual, (dir), (dir) +@top The Z Shell Manual +@end ifnottex +@ifinfo +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. + +@noindent +@cindex version +Version 5.8.1.3-test, last updated May 1, 2022. +@end ifinfo + +@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:: + +@noindent +--- Indices --- + +@noindent +* Concept Index:: +* Variables Index:: +* Options Index:: +* Functions Index:: +* Editor Functions Index:: +* Style and Tag Index:: + +@noindent +--- The Detailed Node Listing --- + +@noindent +Introduction + +@noindent +* Author:: +* Availability:: +* Mailing Lists:: +* The Zsh FAQ:: +* The Zsh Web Page:: +* The Zsh Userguide:: +* See Also:: + +@noindent +Invocation + +@noindent +* Compatibility:: +* Restricted Shell:: + +@noindent +Shell Grammar + +@noindent +* Simple Commands & Pipelines:: +* Precommand Modifiers:: +* Complex Commands:: +* Alternate Forms For Complex Commands:: +* Reserved Words:: +* Comments:: +* Aliasing:: +* Quoting:: + +@noindent +Expansion + +@noindent +* History Expansion:: +* Process Substitution:: +* Parameter Expansion:: +* Command Substitution:: +* Arithmetic Expansion:: +* Brace Expansion:: +* Filename Expansion:: +* Filename Generation:: + +@noindent +Parameters + +@noindent +* Array Parameters:: +* Positional Parameters:: +* Local Parameters:: +* Parameters Set By The Shell:: +* Parameters Used By The Shell:: + +@noindent +Options + +@noindent +* Specifying Options:: +* Description of Options:: +* Option Aliases:: +* Single Letter Options:: + +@noindent +Zsh Line Editor + +@noindent +* Keymaps:: +* Zle Builtins:: +* Zle Widgets:: +* User-Defined Widgets:: +* Standard Widgets:: +* Character Highlighting:: + +@noindent +Completion Widgets + +@noindent +* Completion Special Parameters:: +* Completion Builtin Commands:: +* Completion Condition Codes:: +* Completion Matching Control:: +* Completion Widget Example:: + +@noindent +Completion System + +@noindent +* Initialization:: +* Completion System Configuration:: +* Control Functions:: +* Bindable Commands:: +* Completion Functions:: +* Completion Directories:: + +@noindent +Completion Using compctl + +@noindent +* Command Flags:: +* Option Flags:: +* Alternative Completion:: +* Extended Completion:: +* Example:: + +@noindent +Zsh Modules + +@noindent +@c Yodl file: Zsh/manmodmenu.yo +* 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/watch 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:: +@c (avoiding a yodl bug) + +@noindent +Calendar Function System + +@noindent +* Calendar File and Date Formats:: +* Calendar System User Functions:: +* Calendar Styles:: +* Calendar Utility Functions:: +* Calendar Bugs:: + +@noindent +TCP Function System + +@noindent +* TCP Functions:: +* TCP Parameters:: +* TCP Examples:: +* TCP Bugs:: + +@noindent +Zftp Function System + +@noindent +* Installation:: +* Zftp Functions:: +* Miscellaneous Features:: + +@noindent +User Contributions + +@noindent +* Utilities:: +* Recent Directories:: +* Other Directory Functions:: +* Version Control Information:: +* Prompt Themes:: +* ZLE Functions:: +* Exception Handling:: +* MIME Functions:: +* Mathematical Functions:: +* User Configuration Functions:: +* Other Functions:: + +@noindent +@end menu +@node The Z Shell Manual, Introduction, Top, Top + +@chapter The Z Shell Manual +@noindent +This document has been produced from the texinfo file @t{zsh.texi}, +included in the @t{Doc} sub-directory of the Zsh distribution. + +@section Producing documentation from zsh.texi +@noindent +The texinfo source may be converted into several formats: + +@noindent +@table @asis +@item The Info manual +The Info format allows searching for topics, commands, functions, etc. +from the many Indices. The command `@t{makeinfo zsh.texi}' is used to +produce the Info documentation. + +@item The printed manual +The command `@t{texi2dvi zsh.texi}' will output @t{zsh.dvi} which can +then be processed with @cite{dvips} and optionally @cite{gs} (Ghostscript) to +produce a nicely formatted printed manual. + +@item The HTML manual +An HTML version of this manual is available at the Zsh web site via: + +@noindent +@t{@uref{https://zsh.sourceforge.io/Doc/}}. + +@noindent +(The HTML version is produced with @cite{texi2html}, which may be obtained +from @t{@uref{http://www.nongnu.org/texi2html/}}. The command is +`@t{texi2html --output . --ifinfo --split=chapter --node-files zsh.texi}'. +If necessary, upgrade to version 1.78 of texi2html.) + +@end table + +@noindent +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 +@t{zsh-doc.tar.gz}. (See @ref{Availability} for a list of sites.) +@c (avoiding a yodl bug) +@c Yodl file: Zsh/intro.yo +@node Introduction, Roadmap, The Z Shell Manual, Top + +@chapter Introduction +@noindent +@cindex 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 @cite{ksh} but includes many enhancements. It +does not provide compatibility with POSIX or other shells in its +default operating mode: see +the section @ref{Compatibility}. + +@noindent +Zsh has command line editing, builtin spelling correction, programmable +command completion, shell functions (with autoloading), a history +mechanism, and a host of other features. +@c Yodl file: Zsh/metafaq.yo +@menu +* Author:: +* Availability:: +* Mailing Lists:: +* The Zsh FAQ:: +* The Zsh Web Page:: +* The Zsh Userguide:: +* See Also:: +@end menu +@node Author, Availability, , Introduction + +@section Author +@noindent +@cindex author +Zsh was originally written by Paul Falstad. Zsh is now maintained by +the members of the zsh-workers mailing list @t{<zsh-workers@@zsh.org>}. +The development is currently coordinated by Peter Stephenson +@t{<pws@@zsh.org>}. The coordinator can be contacted at +@t{<coordinator@@zsh.org>}, but matters relating to the code should +generally go to the mailing list. +@node Availability, Mailing Lists, Author, Introduction + +@section Availability +@noindent +Zsh is available from the following HTTP and anonymous FTP site. + +@noindent +@cindex FTP sites for zsh +@cindex acquiring zsh by FTP +@cindex availability of zsh +@t{@uref{ftp://ftp.zsh.org/pub/}}@* +@t{@uref{https://www.zsh.org/pub/}} + +@noindent +The up-to-date source code is available via Git from Sourceforge. See +@t{@uref{https://sourceforge.net/projects/zsh/}} for details. A summary of +instructions for the archive can be found at +@t{@uref{https://zsh.sourceforge.io/}}. + +@noindent +@node Mailing Lists, The Zsh FAQ, Availability, Introduction + +@section Mailing Lists +@noindent +@cindex mailing lists +Zsh has several mailing lists: + +@noindent +@table @asis +@item @t{<zsh-announce@@zsh.org>} +Announcements about releases, major changes in the shell and the +monthly posting of the Zsh FAQ. (moderated) + +@item @t{<zsh-users@@zsh.org>} +User discussions. + +@item @t{<zsh-workers@@zsh.org>} +Hacking, development, bug reports and patches. + +@item @t{<zsh-security@@zsh.org>} +Private mailing list (the general public cannot subscribe to it) for discussing +bug reports with security implications, i.e., potential vulnerabilities. + +@noindent +If you find a security problem in zsh itself, please mail this address. + +@end table + +@noindent +To subscribe or unsubscribe, send mail +to the associated administrative address for the mailing list. + +@noindent +@table @asis +@item @t{<zsh-announce-subscribe@@zsh.org>} +@item @t{<zsh-users-subscribe@@zsh.org>} +@item @t{<zsh-workers-subscribe@@zsh.org>} + +@noindent +@item @t{<zsh-announce-unsubscribe@@zsh.org>} +@item @t{<zsh-users-unsubscribe@@zsh.org>} +@item @t{<zsh-workers-unsubscribe@@zsh.org>} +@end table +@sp 1 + +@noindent +YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED. +All submissions to @cite{zsh-announce} are automatically forwarded to +@cite{zsh-users}. All submissions to @cite{zsh-users} are automatically +forwarded to @cite{zsh-workers}. + +@noindent +If you have problems subscribing/unsubscribing to any of the mailing +lists, send mail to @t{<listmaster@@zsh.org>}. + +@noindent +The mailing lists are archived; the archives can be accessed via the +administrative addresses listed above. There is also a hypertext +archive available at +@t{@uref{https://www.zsh.org/mla/}}. +@node The Zsh FAQ, The Zsh Web Page, Mailing Lists, Introduction + +@section The Zsh FAQ +@noindent +Zsh has a list of Frequently Asked Questions (FAQ), maintained by +Peter Stephenson @t{<pws@@zsh.org>}. It is regularly posted to the +newsgroup @cite{comp.unix.shell} and the @cite{zsh-announce} mailing list. +The latest version can be found at any of the Zsh FTP sites, or at +@t{@uref{https://www.zsh.org/FAQ/}}. The contact address for FAQ-related matters +is @t{<faqmaster@@zsh.org>}. +@node The Zsh Web Page, The Zsh Userguide, The Zsh FAQ, Introduction + +@section The Zsh Web Page +@noindent +Zsh has a web page which is located at @t{@uref{https://www.zsh.org/}}. +The contact address for web-related matters is @t{<webmaster@@zsh.org>}. +@node The Zsh Userguide, See Also, The Zsh Web Page, Introduction + +@section The Zsh Userguide +@noindent +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 +@t{@uref{https://zsh.sourceforge.io/Guide/}}. At the time of writing, chapters +dealing with startup files and their contents and the new completion system +were essentially complete. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/seealso.yo +@node See Also, , The Zsh Userguide, Introduction + +@section See Also +@noindent +sh(1), +csh(1), +tcsh(1), +rc(1), +bash(1), +ksh(1) + +@noindent +@cite{IEEE Standard for information Technology - +Portable Operating System Interface (POSIX) - +Part 2: Shell and Utilities}, +IEEE Inc, 1993, ISBN 1-55937-255-9. +@c (avoiding a yodl bug) +@c (avoiding a yodl bug) +@c Yodl file: Zsh/roadmap.yo +@node Roadmap, Invocation, Introduction, Top + +@chapter Roadmap +@noindent +@cindex 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. + +@noindent + +@section When the shell starts +@noindent + +@noindent +When it starts, the shell reads commands from various files. These can +be created or edited to customize the shell. See @ref{Files}. + +@noindent +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 @t{zsh/newuser} module. +The function is designed to be self-explanatory. You can run it by hand +with `@t{autoload -Uz zsh-newuser-install; zsh-newuser-install -f}'. +See also +@ref{User Configuration Functions}. + +@noindent + +@section Interactive Use +@noindent + +@noindent +Interaction with the shell uses the builtin Zsh Line Editor, ZLE. This is +described in detail in @ref{Zsh Line Editor}. + +@noindent +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 @t{bindkey -e}. + +@noindent +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) @t{HISTFILE}, +@t{HISTSIZE} and @t{SAVEHIST} in @ref{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. + +@noindent +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, +@t{@uref{https://www.zsh.org/FAQ/}}. Note in particular that for combining +characters to be handled the option @t{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 +@t{LANG} (to affect all aspects of the shell's operation) or +@t{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 +@t{ISO-8859-1} or @t{ISO-8859-15}. See the description of @t{LC_CTYPE} +in +@ref{Parameters}. + +@noindent + +@subsection Completion +@noindent + +@noindent +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 @t{~/.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. + +@noindent +Zsh has two completion systems, an old, so called @t{compctl} completion +(named after the builtin command that serves as its complete and only +user interface), and a new one, referred to as @t{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. + +@noindent +The completion system must be enabled explicitly when the shell starts. +For more information see +@ref{Completion System}. + +@noindent + +@subsection Extending the line editor +@noindent + +@noindent +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: + +@noindent +@table @asis +@item @t{insert-composed-char} +composing characters not found on the keyboard + +@item @t{match-words-by-style} +configuring what the line editor considers a word when moving or +deleting by word + +@item @t{history-beginning-search-backward-end}, etc. +alternative ways of searching the shell history + +@item @t{replace-string}, @t{replace-pattern} +functions for replacing strings or patterns globally in the command line + +@item @t{edit-command-line} +edit the command line with an external editor. + +@end table + +@noindent +See @ref{ZLE Functions} for descriptions of these. + +@noindent + +@section Options +@noindent + +@noindent +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 +@ref{Options}. + +@noindent + +@section Pattern Matching +@noindent + +@noindent +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 @ref{Filename Generation}. + +@noindent +Of particular interest are the following patterns that are not commonly +supported by other systems of pattern matching: + +@noindent +@table @asis +@item @t{**} +for matching over multiple directories + +@item @t{|} +for matching either of two alternatives + +@item @t{~}, @t{^} +the ability to exclude patterns from matching when the @t{EXTENDED_GLOB} +option is set + +@item @t{(}@var{...}@t{)} +glob qualifiers, included in parentheses at the end of the pattern, +which select files by type (such as directories) or attribute (such as +size). + +@end table + +@noindent + +@section General Comments on Syntax +@noindent + +@noindent +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 @ref{Shell Grammar}. + +@noindent +One commonly encountered difference is that variables substituted onto the +command line are not split into words. See the description of the shell option +@t{SH_WORD_SPLIT} in +@ref{Parameter Expansion}. +In zsh, you can either explicitly request the splitting (e.g. @t{$@{=foo@}}) +or use an array when you want a variable to expand to more than one word. See +@ref{Array Parameters}. + +@noindent + +@section Programming +@noindent + +@noindent +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 @ref{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. + +@noindent +A few general functions, other than those for the line editor described +above, are provided with the shell and are described in +@ref{User Contributions}. Features include: + +@noindent +@table @asis +@item @t{promptinit} +a prompt theme system for changing prompts easily, see @ref{Prompt Themes} + +@item @t{zsh-mime-setup} +a MIME-handling system which dispatches commands according to the suffix of +a file as done by graphical file managers + +@item @t{zcalc} +a calculator + +@item @t{zargs} +a version of @t{xargs} that makes the @t{find} command redundant + +@item @t{zmv} +a command for renaming files by means of shell patterns. + +@end table +@c (avoiding a yodl bug) +@c Yodl file: Zsh/invoke.yo +@node Invocation, Files, Roadmap, Top + +@chapter Invocation +@noindent +@cindex invocation + +@section Invocation +@noindent +@cindex shell options +@cindex options, shell +@cindex shell flags +@cindex flags, shell +The following flags are interpreted by the shell when invoked to determine +where the shell will read commands from: + +@noindent +@table @asis +@item @t{-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 @t{$0}, rather than being used as a positional +parameter. + +@item @t{-i} +Force shell to be interactive. It is still possible to specify a +script to execute. + +@item @t{-s} +Force shell to read commands from the standard input. +If the @t{-s} flag is not present and an argument is given, +the first argument is taken to be the pathname of a script to +execute. + +@end table + +@noindent +If there are any remaining arguments after option processing, and neither +of the options @t{-c} or @t{-s} was supplied, the first argument is taken +as the file name of a script containing shell commands to be executed. If +the option @t{PATH_SCRIPT} is set, and the file name does not contain a +directory path (i.e. there is no `@t{/}' in the name), first the current +directory and then the command path given by the variable @t{PATH} are +searched for the script. If the option is not set or the file name +contains a `@t{/}' it is used directly. + +@noindent +After the first one or two arguments have been appropriated as described above, +the remaining arguments are assigned to the positional parameters. + +@noindent +For further options, which are common to invocation and the @t{set} +builtin, see +@ref{Options}. + +@noindent +The long option `@t{-}@t{-emulate}' followed (in a separate word) by an +emulation mode may be passed to the shell. +The emulation modes are those described for the @t{emulate} builtin, +see +@ref{Shell Builtin Commands}. +The `@t{-}@t{-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 @t{emulate} command within the shell: for +example, variables that conflict with POSIX usage such as @t{path} are +not defined within the shell. + +@noindent +Options may be specified by name using the @t{-o} option. @t{-o} acts like +a single-letter option, but takes a following string as the option name. +For example, + +@noindent +@example +zsh -x -o shwordsplit scr +@end example + +@noindent +runs the script @t{scr}, setting the @t{XTRACE} option by the corresponding +letter `@t{-x}' and the @t{SH_WORD_SPLIT} option by name. +Options may be turned @emph{off} by name by using @t{+o} instead of @t{-o}. +@t{-o} can be stacked up with preceding single-letter options, so for example +`@t{-xo shwordsplit}' or `@t{-xoshwordsplit}' is equivalent to +`@t{-x -o shwordsplit}'. + +@noindent +@cindex long option +Options may also be specified by name in GNU long option style, +`@t{-}@t{-}@var{option-name}'. When this is done, `@t{-}' characters in the +option name are permitted: they are translated into `@t{_}', and thus ignored. +So, for example, `@t{zsh -}@t{-sh-word-split}' invokes zsh with the +@t{SH_WORD_SPLIT} option turned on. Like other option syntaxes, options can +be turned off by replacing the initial `@t{-}' with a `@t{+}'; thus +`@t{+-sh-word-split}' is equivalent to `@t{-}@t{-no-sh-word-split}'. +Unlike other option syntaxes, GNU-style long options cannot be stacked with +any other options, so for example `@t{-x-shwordsplit}' is an error, +rather than being treated like `@t{-x -}@t{-shwordsplit}'. + +@noindent +@cindex --version +@cindex --help +The special GNU-style option `@t{-}@t{-version}' is handled; it sends to +standard output the shell's version information, then exits successfully. +`@t{-}@t{-help}' is also handled; it sends to standard output a list of +options that can be used when invoking the shell, then exits successfully. + +@noindent +Option processing may be finished, allowing following arguments that start with +`@t{-}' or `@t{+}' to be treated as normal arguments, in two ways. +Firstly, a lone `@t{-}' (or `@t{+}') as an argument by itself ends +option processing. Secondly, a special option `@t{-}@t{-}' (or +`@t{+-}'), which may be specified on its own (which is the standard +POSIX usage) or may be stacked with preceding options (so `@t{-x-}' is +equivalent to `@t{-x -}@t{-}'). Options are not permitted to be stacked +after `@t{-}@t{-}' (so `@t{-x-f}' is an error), but note the GNU-style +option form discussed above, where `@t{-}@t{-shwordsplit}' is permitted +and does not end option processing. + +@noindent +Except when the @cite{sh}/@cite{ksh} emulation single-letter options are in effect, +the option `@t{-b}' (or `@t{+b}') ends option processing. +`@t{-b}' is like `@t{-}@t{-}', except that further single-letter options +can be stacked after the `@t{-b}' and will take effect as normal. + +@noindent +@menu +* Compatibility:: +* Restricted Shell:: +@end menu + +@noindent +@c Yodl file: Zsh/compat.yo +@node Compatibility, Restricted Shell, , Invocation + +@section Compatibility +@noindent +@cindex compatibility +@cindex sh compatibility +@cindex ksh compatibility +Zsh tries to emulate @cite{sh} or @cite{ksh} when it is invoked as +@t{sh} or @t{ksh} respectively; more precisely, it looks at the first +letter of the name by which it was invoked, excluding any initial `@t{r}' +(assumed to stand for `restricted'), and if that is `@t{b}', `@t{s}' or `@t{k}' it +will emulate @cite{sh} or @cite{ksh}. Furthermore, if invoked as @t{su} (which +happens on certain systems when the shell is executed by the @t{su} +command), the shell will try to find an alternative name from the @t{SHELL} +environment variable and perform emulation based on that. + +@noindent +In @cite{sh} and @cite{ksh} compatibility modes the following +parameters are not special and not initialized by the shell: +@t{ARGC}, +@t{argv}, +@t{cdpath}, +@t{fignore}, +@t{fpath}, +@t{HISTCHARS}, +@t{mailpath}, +@t{MANPATH}, +@t{manpath}, +@t{path}, +@t{prompt}, +@t{PROMPT}, +@t{PROMPT2}, +@t{PROMPT3}, +@t{PROMPT4}, +@t{psvar}, +@t{status}. + +@noindent +@vindex ENV, use of +The usual zsh startup/shutdown scripts are not executed. Login shells +source @t{/etc/profile} followed by @t{$HOME/.profile}. If the +@t{ENV} environment variable is set on invocation, @t{$ENV} is sourced +after the profile scripts. The value of @t{ENV} is subjected to +parameter expansion, command substitution, and arithmetic expansion +before being interpreted as a pathname. Note that the @t{PRIVILEGED} +option also affects the execution of startup files. + +@noindent +The following options are set if the shell is invoked as @t{sh} or +@t{ksh}: +@t{NO_BAD_PATTERN}, +@t{NO_BANG_HIST}, +@t{NO_BG_NICE}, +@t{NO_EQUALS}, +@t{NO_FUNCTION_ARGZERO}, +@t{GLOB_SUBST}, +@t{NO_GLOBAL_EXPORT}, +@t{NO_HUP}, +@t{INTERACTIVE_COMMENTS}, +@t{KSH_ARRAYS}, +@t{NO_MULTIOS}, +@t{NO_NOMATCH}, +@t{NO_NOTIFY}, +@t{POSIX_BUILTINS}, +@t{NO_PROMPT_PERCENT}, +@t{RM_STAR_SILENT}, +@t{SH_FILE_EXPANSION}, +@t{SH_GLOB}, +@t{SH_OPTION_LETTERS}, +@t{SH_WORD_SPLIT}. +Additionally the @t{BSD_ECHO} and @t{IGNORE_BRACES} +options are set if zsh is invoked as @t{sh}. +Also, the +@t{KSH_OPTION_PRINT}, +@t{LOCAL_OPTIONS}, +@t{PROMPT_BANG}, +@t{PROMPT_SUBST} +and +@t{SINGLE_LINE_ZLE} +options are set if zsh is invoked as @t{ksh}. + +@noindent +Please note that, whilst reasonable efforts are taken to address +incompatibilities when they arise, zsh does not guarantee complete +emulation of other shells, nor POSIX compliance. For more information on +the differences between zsh and other shells, please refer to chapter 2 +of the shell FAQ, @t{@uref{https://www.zsh.org/FAQ/}}. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/restricted.yo +@node Restricted Shell, , Compatibility, Invocation + +@section Restricted Shell +@noindent +@cindex restricted shell +@pindex RESTRICTED +When the basename of the command used to invoke zsh starts with the letter +`@t{r}' or the `@t{-r}' command line option is supplied at invocation, the +shell becomes restricted. Emulation mode is determined after stripping the +letter `@t{r}' from the invocation name. The following are disabled in +restricted mode: + +@noindent +@itemize @bullet + +@item +changing directories with the @t{cd} builtin +@item +changing or unsetting the @t{EGID}, @t{EUID}, @t{GID}, +@t{HISTFILE}, @t{HISTSIZE}, @t{IFS}, @t{LD_AOUT_LIBRARY_PATH}, +@t{LD_AOUT_PRELOAD}, @t{LD_LIBRARY_PATH}, @t{LD_PRELOAD}, +@t{MODULE_PATH}, @t{module_path}, @t{PATH}, @t{path}, @t{SHELL}, +@t{UID} and @t{USERNAME} parameters +@item +specifying command names containing @t{/} +@item +specifying command pathnames using @t{hash} +@item +redirecting output to files +@item +using the @t{exec} builtin command to replace the shell with another +command +@item +using @t{jobs -Z} to overwrite the shell process' argument and +environment space +@item +using the @t{ARGV0} parameter to override @t{argv[0]} for external +commands +@item +turning off restricted mode with @t{set +r} or @t{unsetopt +RESTRICTED} +@end itemize + +@noindent +These restrictions are enforced after processing the startup files. The +startup files should set up @t{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. + +@noindent +Restricted mode can also be activated any time by setting the +@t{RESTRICTED} option. This immediately enables all the restrictions +described above even if the shell still has not processed all startup +files. + +@noindent +A shell @emph{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 @emph{chroot jails}, @emph{containers} and +@emph{zones}. + +@noindent +A restricted shell is very difficult to implement safely. The feature +may be removed in a future version of zsh. + +@noindent +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 `@t{PATH}' variable, it does not prevent those +commands from running any other command. + +@noindent +As an example, if `@t{env}' is among the list of @emph{allowed} commands, +then it allows the user to run any command as `@t{env}' is not a shell +builtin command and can run arbitrary executables. + +@noindent +So when implementing a restricted shell framework it is important to be +fully aware of what actions each of the @emph{allowed} commands or features +(which may be regarded as @emph{modules}) can perform. + +@noindent +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. + +@noindent +If a `@t{perl}', `@t{python}', `@t{bash}', or other general purpose +interpreted script it treated as a restricted +command, the user can work around the restriction by +setting specially crafted `@t{PERL5LIB}', `@t{PYTHONPATH}', +`@t{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 `@t{GCONV_PATH}' +environment variable. Those are only a few examples. + +@noindent +Bear in mind that, contrary to some other shells, `@t{readonly}' is not a +security feature in zsh as it can be undone and so cannot be used to +mitigate the above. + +@noindent +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 `@t{zsh/system}', `@t{zsh/mapfile}' and +`@t{zsh/files}', allow bypassing most of the restrictions. +@c (avoiding a yodl bug) +@c (avoiding a yodl bug) +@c Yodl file: Zsh/files.yo +@node Files, Shell Grammar, Invocation, Top + +@chapter Files +@noindent + +@section Startup/Shutdown Files +@noindent +@cindex files, startup +@cindex startup files +@cindex files, shutdown +@cindex shutdown files +@pindex RCS, use of +@pindex GLOBAL_RCS, use of +@pindex NO_RCS, use of +@pindex NO_GLOBAL_RCS, use of +@vindex ZDOTDIR, use of +@cindex zshenv +Commands are first read from @t{/etc/zshenv}; this cannot be overridden. +Subsequent behaviour is modified by the @t{RCS} and +@t{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 @t{/}). 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 @t{$ZDOTDIR} to +re-enable @t{GLOBAL_RCS}. Both @t{RCS} and @t{GLOBAL_RCS} are set by +default. + +@noindent +Commands are then read from @t{$ZDOTDIR/.zshenv}. +@pindex LOGIN, use of +@cindex zprofile +If the shell is a login shell, commands +are read from @t{/etc/zprofile} and then @t{$ZDOTDIR/.zprofile}. +@cindex zshrc +Then, if the shell is interactive, +commands are read from @t{/etc/zshrc} and then @t{$ZDOTDIR/.zshrc}. +@cindex zlogin +Finally, if the shell is a login shell, @t{/etc/zlogin} and +@t{$ZDOTDIR/.zlogin} are read. + +@noindent +@cindex zlogout +When a login shell exits, the files @t{$ZDOTDIR/.zlogout} and then +@t{/etc/zlogout} are read. This happens with either an explicit exit +via the @t{exit} or @t{logout} commands, or an implicit exit by reading +end-of-file from the terminal. However, if the shell terminates due +to @t{exec}'ing another process, the logout files are not read. +These are also affected by the @t{RCS} and @t{GLOBAL_RCS} options. +Note also that the @t{RCS} option affects the saving of history files, +i.e. if @t{RCS} is unset when the shell exits, no history file will be +saved. + +@noindent +@vindex HOME, use of +If @t{ZDOTDIR} is unset, @t{HOME} is used instead. +Files listed above as being in @t{/etc} may be in another +directory, depending on the installation. + +@noindent +As @t{/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 `@t{if [[ -o rcs ]]; then ...}' so that it will not +be executed when zsh is invoked with the `@t{-f}' option. +@c Yodl file: Zsh/filelist.yo + +@section Files +@noindent +@cindex files used +@table @asis +@item @t{$ZDOTDIR/.zshenv} +@item @t{$ZDOTDIR/.zprofile} +@item @t{$ZDOTDIR/.zshrc} +@item @t{$ZDOTDIR/.zlogin} +@item @t{$ZDOTDIR/.zlogout} +@item @t{$@{TMPPREFIX@}*} (default is /tmp/zsh*) +@item @t{/etc/zshenv} +@item @t{/etc/zprofile} +@item @t{/etc/zshrc} +@item @t{/etc/zlogin} +@item @t{/etc/zlogout} (installation-specific - @t{/etc} is the default) +@end table +@sp 1 +@c (avoiding a yodl bug) + +@noindent +Any of these files may be pre-compiled with the @t{zcompile} builtin +command (@ref{Shell Builtin Commands}). If a compiled file exists (named for the original file plus the +@t{.zwc} extension) and it is newer than the original file, the compiled +file will be used instead. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/grammar.yo +@node Shell Grammar, Redirection, Files, Top + +@chapter Shell Grammar +@noindent +@cindex shell grammar +@cindex grammar, shell +@menu +* Simple Commands & Pipelines:: +* Precommand Modifiers:: +* Complex Commands:: +* Alternate Forms For Complex Commands:: +* Reserved Words:: +* Errors:: +* Comments:: +* Aliasing:: +* Quoting:: +@end menu +@node Simple Commands & Pipelines, Precommand Modifiers, , Shell Grammar + +@section Simple Commands & Pipelines +@noindent +@cindex simple commands +@cindex commands, simple +A @emph{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 +@ref{Parameters}. + +@noindent +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, + +@noindent +@example +echo foo +@end example + +@noindent +is a simple command with arguments. + +@noindent +@cindex pipeline +A @emph{pipeline} is either a simple command, or a sequence of two or more +simple commands where each command is separated from the next by `@t{|}' +or `@t{|&}'. Where commands are separated by `@t{|}', the standard +output of the first command is connected to the +standard input of the next. `@t{|&}' is shorthand for `@t{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 +`@t{!}' in which case the value is the logical inverse of the value of the +last command. +For example, + +@noindent +@example +echo foo | sed 's/foo/bar/' +@end example + +@noindent +is a pipeline, where the output (`@t{foo}' plus a newline) of the first +command will be passed to the input of the second. + +@noindent +@findex coproc +@cindex coprocess +If a pipeline is preceded by `@t{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 `@t{>&p}' +and `@t{<&p}' redirection operators or with `@t{print -p}' and `@t{read -p}'. +A pipeline cannot be preceded by both `@t{coproc}' and `@t{!}'. +If job control is active, the coprocess can be treated in other than input +and output as an ordinary background job. + +@noindent +@cindex sublist +A @emph{sublist} is either a single pipeline, or a sequence of two or more +pipelines separated by `@t{&&}' or `@t{||}'. If two pipelines are separated +by `@t{&&}', the second pipeline is executed only if the first succeeds +(returns a zero status). If two pipelines are separated by `@t{||}', 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, + +@noindent +@example +dmesg | grep panic && print yes +@end example + +@noindent +is a sublist consisting of two pipelines, the second just a simple command +which will be executed if and only if the @t{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 @t{print} (almost certainly zero). + +@noindent +@cindex list +A @emph{list} is a sequence of zero or more sublists, in which each sublist +is terminated by `@t{;}', `@t{&}', `@t{&|}', `@t{&!}', 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 `@t{(}...@t{)}' +or `@t{@{}...@t{@}}'. When a +sublist is terminated by `@t{;}' or newline, the shell waits for it to +finish before executing the next sublist. If a sublist is terminated +by a `@t{&}', `@t{&|}', or `@t{&!}', +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. + +@noindent +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. +@node Precommand Modifiers, Complex Commands, Simple Commands & Pipelines, Shell Grammar + +@section Precommand Modifiers +@noindent +@cindex precommand modifiers +@cindex modifiers, precommand +A simple command may be preceded by a @emph{precommand modifier}, +which will alter how the command is interpreted. These modifiers are +shell builtin commands with the exception of @t{nocorrect} which is +a reserved word. + +@noindent +@table @asis +@findex - +@item @t{-} +The command is executed with a `@t{-}' prepended to its +@t{argv[0]} string. + +@findex builtin +@item @t{builtin} +The command word is taken to be the name of a builtin command, +rather than a shell function or external command. + +@findex command +@item @t{command} [ @t{-pvV} ] +The command word is taken to be the name of an external command, +rather than a shell function or builtin. If the @t{POSIX_BUILTINS} option +is set, builtins will also be executed but certain special properties +of them are suppressed. The @t{-p} flag causes a default path to be +searched instead of that in @t{$path}. With the @t{-v} flag, @t{command} +is similar to @t{whence} and with @t{-V}, it is equivalent to @t{whence +-v}. + +@findex exec +@item @t{exec} [ @t{-cl} ] [ @t{-a} @var{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 @t{TRAPEXIT}, nor does it +source @t{zlogout} files. +The options are provided for compatibility with other shells. + +@noindent +The @t{-c} option clears the environment. + +@noindent +The @t{-l} option is equivalent to the @t{-} precommand modifier, to +treat the replacement command as a login shell; the command is executed +with a @t{-} prepended to its @t{argv[0]} string. This flag has no effect +if used together with the @t{-a} option. + +@noindent +The @t{-a} option is used to specify explicitly the @t{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 @t{ARGV0} environment variable. + +@findex nocorrect +@item @t{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. + +@findex noglob +@item @t{noglob} +Filename generation (globbing) is not performed on any of +the words. + +@end table +@node Complex Commands, Alternate Forms For Complex Commands, Precommand Modifiers, Shell Grammar + +@section Complex Commands +@noindent +@cindex complex commands +@cindex commands, complex +A @emph{complex command} in zsh is one of the following: + +@noindent +@table @asis +@findex if +@cindex if construct +@item @t{if} @var{list} @t{then} @var{list} [ @t{elif} @var{list} @t{then} @var{list} ] ... [ @t{else} @var{list} ] @t{fi} +The @t{if} @var{list} is executed, and if it returns a zero exit status, +the @t{then} @var{list} is executed. +Otherwise, the @t{elif} @var{list} is executed and if its status is zero, +the @t{then} @var{list} is executed. +If each @t{elif} @var{list} returns nonzero status, the @t{else} @var{list} +is executed. + +@findex for +@cindex for loops +@cindex loops, for +@item @t{for} @var{name} ... [ @t{in} @var{word} ... ] @var{term} @t{do} @var{list} @t{done} +Expand the list of @var{word}s, and set the parameter +@var{name} to each of them in turn, executing @var{list} +each time. If the `@t{in} @var{word}' is omitted, +use the positional parameters instead of the @var{word}s. + +@noindent +The @var{term} consists of one or more newline or @t{;} +which terminate the @var{word}s, and are optional when the +`@t{in} @var{word}' is omitted. + +@noindent +More than one parameter @var{name} can appear before the list of +@var{word}s. If @var{N} @var{name}s are given, then on each execution of the +loop the next @var{N} @var{word}s are assigned to the corresponding +parameters. If there are more @var{name}s than remaining @var{word}s, the +remaining parameters are each set to the empty string. Execution of the +loop ends when there is no remaining @var{word} to assign to the first +@var{name}. It is only possible for @t{in} to appear as the first @var{name} +in the list, else it will be treated as marking the end of the list. + +@item @t{for ((} [@var{expr1}] @t{;} [@var{expr2}] @t{;} [@var{expr3}] @t{)) do} @var{list} @t{done} +The arithmetic expression @var{expr1} is evaluated first (see +@ref{Arithmetic Evaluation}). The arithmetic expression +@var{expr2} is repeatedly evaluated until it evaluates to zero and +when non-zero, @var{list} is executed and the arithmetic expression +@var{expr3} evaluated. If any expression is omitted, then it behaves +as if it evaluated to 1. + +@findex while +@cindex while loops +@cindex loops, while +@item @t{while} @var{list} @t{do} @var{list} @t{done} +Execute the @t{do} @var{list} as long as the @t{while} @var{list} +returns a zero exit status. + +@findex until +@cindex until loops +@cindex loops, until +@item @t{until} @var{list} @t{do} @var{list} @t{done} +Execute the @t{do} @var{list} as long as @t{until} @var{list} +returns a nonzero exit status. + +@findex repeat +@cindex repeat loops +@cindex loops, repeat +@item @t{repeat} @var{word} @t{do} @var{list} @t{done} +@var{word} is expanded and treated as an arithmetic expression, +which must evaluate to a number @var{n}. +@var{list} is then executed @var{n} times. + +@noindent +The @t{repeat} syntax is disabled by default when the +shell starts in a mode emulating another shell. It can be enabled +with the command `@t{enable -r repeat}' + +@findex case +@cindex case selection +@cindex selection, case +@item @t{case} @var{word} @t{in} [ [@t{(}] @var{pattern} [ @t{|} @var{pattern} ] ... @t{)} @var{list} (@t{;;}|@t{;&}|@t{;|}) ] ... @t{esac} +Execute the @var{list} associated with the first @var{pattern} +that matches @var{word}, if any. The form of the patterns +is the same as that used for filename generation. See +@ref{Filename Generation}. + +@noindent +Note further that, unless the @t{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 @t{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). + +@noindent +If the @var{list} that is executed is terminated with @t{;&} rather than +@t{;;}, the following list is also executed. The rule for +the terminator of the following list @t{;;}, @t{;&} or @t{;|} is +applied unless the @t{esac} is reached. + +@noindent +If the @var{list} that is executed is terminated with @t{;|} the +shell continues to scan the @var{pattern}s looking for the next match, +executing the corresponding @var{list}, and applying the rule for +the corresponding terminator @t{;;}, @t{;&} or @t{;|}. +Note that @var{word} is not re-expanded; all applicable @var{pattern}s +are tested with the same @var{word}. + +@findex select +@cindex user selection +@cindex selection, user +@item @t{select} @var{name} [ @t{in} @var{word} ... @var{term} ] @t{do} @var{list} @t{done} +where @var{term} is one or more newline or @t{;} to terminate the @var{word}s. +@vindex REPLY, use of +Print the set of @var{word}s, each preceded by a number. +If the @t{in} @var{word} is omitted, use the positional parameters. +The @t{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 @var{word}s, then the parameter @var{name} +is set to the @var{word} corresponding to this number. +If this line is empty, the selection list is printed again. +Otherwise, the value of the parameter @var{name} is set to null. +The contents of the line read from standard input is saved +in the parameter @t{REPLY}. @var{list} is executed +for each selection until a break or end-of-file is encountered. + +@cindex subshell +@item @t{(} @var{list} @t{)} +Execute @var{list} in a subshell. Traps set by the @t{trap} builtin +are reset to their default values while executing @var{list}; an +exception is that ignored signals will continue to be ignored +if the option @t{POSIXTRAPS} is set. + +@item @t{@{} @var{list} @t{@}} +Execute @var{list}. + +@findex always +@cindex always blocks +@cindex try blocks +@item @t{@{} @var{try-list} @t{@} always @{} @var{always-list} @t{@}} +First execute @var{try-list}. Regardless of errors, or @t{break} or +@t{continue} commands encountered within @var{try-list}, +execute @var{always-list}. Execution then continues from the +result of the execution of @var{try-list}; in other words, any error, +or @t{break} or @t{continue} command is treated in the +normal way, as if @var{always-list} were not present. The two +chunks of code are referred to as the `try block' and the `always block'. + +@noindent +Optional newlines or semicolons may appear after the @t{always}; +note, however, that they may @emph{not} appear between the preceding +closing brace and the @t{always}. + +@noindent +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 @var{always-list} to be executed. For example, +an erroneously constructed @t{if} block in @var{try-list} would cause the +shell to abort during parsing, so that @var{always-list} would not be +executed, while an erroneous substitution such as @t{$@{*foo*@}} would +cause a run-time error, after which @var{always-list} would be executed. + +@noindent +An error condition can be tested and reset with the special integer +variable @t{TRY_BLOCK_ERROR}. Outside an @var{always-list} the value is +irrelevant, but it is initialised to @t{-1}. Inside @var{always-list}, the +value is 1 if an error occurred in the @var{try-list}, else 0. If +@t{TRY_BLOCK_ERROR} is set to 0 during the @var{always-list}, the error +condition caused by the @var{try-list} is reset, and shell execution +continues normally after the end of @var{always-list}. Altering the value +during the @var{try-list} is not useful (unless this forms part of an +enclosing @t{always} block). + +@noindent +Regardless of @t{TRY_BLOCK_ERROR}, after the end of @var{always-list} the +normal shell status @t{$?} is the value returned from @var{try-list}. +This will be non-zero if there was an error, even if @t{TRY_BLOCK_ERROR} +was set to zero. + +@noindent +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. + +@noindent +@example +@{ + # 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. +@end example + +@noindent +When a @t{try} block occurs outside of any function, +a @t{return} or a @t{exit} encountered in @var{try-list} does @emph{not} cause +the execution of @var{always-list}. Instead, the shell exits immediately +after any @t{EXIT} trap has been executed. +Otherwise, a @t{return} command encountered in @var{try-list} will cause the +execution of @var{always-list}, just like @t{break} and @t{continue}. + +@noindent + + +@findex function +@item @t{function} [ @t{-T} ] @var{word} ... [ @t{()} ] [ @var{term} ] @t{@{} @var{list} @t{@}} +@itemx @var{word} ... @t{()} [ @var{term} ] @t{@{} @var{list} @t{@}} +@itemx @var{word} ... @t{()} [ @var{term} ] @var{command} +where @var{term} is one or more newline or @t{;}. +Define a function which is referenced by any one of @var{word}. +Normally, only one @var{word} is provided; multiple @var{word}s +are usually only useful for setting traps. +The body of the function is the @var{list} between +the @t{@{} and @t{@}}. See @ref{Functions}. + +@noindent +The options of @t{function} have the following meanings: + +@noindent +@table @asis +@item -T +Enable tracing for this function, as though with @t{functions -T}. See the +documentation of the @t{-f} option to the @t{typeset} builtin, in +@ref{Shell Builtin Commands}. + +@end table + +@noindent +If the option @t{SH_GLOB} is set for compatibility with other shells, then +whitespace may appear between the left and right parentheses when +there is a single @var{word}; otherwise, the parentheses will be treated as +forming a globbing pattern in that case. + +@noindent +In any of the forms above, a redirection may appear outside the +function body, for example + +@noindent +@example +func() @{ ... @} 2>&1 +@end example + +@noindent +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. + +@cindex timing +@findex time +@item @t{time} [ @var{pipeline} ] +The @var{pipeline} is executed, and timing statistics are +reported on the standard error in the form specified +by the @t{TIMEFMT} parameter. +If @var{pipeline} is omitted, print statistics about the +shell process and its children. + +@cindex conditional expression +@findex [[ +@item @t{[[} @var{exp} @t{]]} +Evaluates the conditional expression @var{exp} +and return a zero exit status if it is true. +See @ref{Conditional Expressions} +for a description of @var{exp}. + +@end table +@node Alternate Forms For Complex Commands, Reserved Words, Complex Commands, Shell Grammar + +@section Alternate Forms For Complex Commands +@noindent +@cindex alternate forms for complex commands +@cindex commands, alternate forms for complex +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. + +@noindent +The short versions below only work if @var{sublist} is of the form `@t{@{} +@var{list} @t{@}}' or if the @t{SHORT_LOOPS} option is set. For the @t{if}, +@t{while} and @t{until} commands, in both these cases the test part of the +loop must also be suitably delimited, such as by `@t{[[} @var{...} @t{]]}' or +`@t{((} @var{...} @t{))}', +else the end of the test will not be recognized. For the +@t{for}, @t{repeat}, @t{case} and @t{select} commands no such special form +for the arguments is necessary, but the other condition (the special form +of @var{sublist} or use of the @t{SHORT_LOOPS} option) still applies. +The @t{SHORT_REPEAT} option is available to enable the short version only +for the @t{repeat} command. + +@noindent +@table @asis +@item @t{if} @var{list} @t{@{} @var{list} @t{@}} [ @t{elif} @var{list} @t{@{} @var{list} @t{@}} ] ... [ @t{else @{} @var{list} @t{@}} ] +An alternate form of @t{if}. The rules mean that + +@noindent +@example +if [[ -o ignorebraces ]] @{ + print yes +@} +@end example + +@noindent +works, but + +@noindent +@example +if true @{ # Does not work! + print yes +@} +@end example + +@noindent +does @emph{not}, since the test is not suitably delimited. + +@item @t{if} @var{list} @var{sublist} +A short form of the alternate @t{if}. The same limitations on the form of +@var{list} apply as for the previous form. + +@item @t{for} @var{name} ... @t{(} @var{word} ... @t{)} @var{sublist} +A short form of @t{for}. + +@item @t{for} @var{name} ... [ @t{in} @var{word} ... ] @var{term} @var{sublist} +where @var{term} is at least one newline or @t{;}. +Another short form of @t{for}. + +@item @t{for ((} [@var{expr1}] @t{;} [@var{expr2}] @t{;} [@var{expr3}] @t{))} @var{sublist} +A short form of the arithmetic @t{for} command. + +@findex foreach +@item @t{foreach} @var{name} ... @t{(} @var{word} ... @t{)} @var{list} @t{end} +Another form of @t{for}. + +@item @t{while} @var{list} @t{@{} @var{list} @t{@}} +An alternative form of @t{while}. Note the limitations on the form of +@var{list} mentioned above. + +@item @t{until} @var{list} @t{@{} @var{list} @t{@}} +An alternative form of @t{until}. Note the limitations on the form of +@var{list} mentioned above. + +@item @t{repeat} @var{word} @var{sublist} +This is a short form of @t{repeat}. + +@item @t{case} @var{word} @t{@{} [ [@t{(}] @var{pattern} [ @t{|} @var{pattern} ] ... @t{)} @var{list} (@t{;;}|@t{;&}|@t{;|}) ] ... @t{@}} +An alternative form of @t{case}. + +@item @t{select} @var{name} [ @t{in} @var{word} ... @var{term} ] @var{sublist} +where @var{term} is at least one newline or @t{;}. +A short form of @t{select}. + +@item @t{function} @var{word} ... [ @t{()} ] [ @var{term} ] @var{sublist} +This is a short form of @t{function}. + +@end table +@node Reserved Words, Errors, Alternate Forms For Complex Commands, Shell Grammar + +@section Reserved Words +@noindent +@cindex reserved words +@findex disable, use of +The following words are recognized as reserved words when used as the first +word of a command unless quoted or disabled using @t{disable -r}: + +@noindent +@t{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} + +@noindent +Additionally, `@t{@}}' is recognized in any position if neither the +@t{IGNORE_BRACES} option nor the @t{IGNORE_CLOSE_BRACES} option is set. +@node Errors, Comments, Reserved Words, Shell Grammar + +@section Errors +@noindent +@cindex errors, handling of +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 @t{CONTINUE_ON_ERROR}. + +@noindent +Fatal errors found in non-interactive shells include: + +@noindent +@itemize @bullet + +@item +Failure to parse shell options passed when invoking the shell +@item +Failure to change options with the @t{set} builtin +@item +Parse errors of all sorts, including failures to parse +mathematical expressions +@item +Failures to set or modify variable behaviour with @t{typeset}, +@t{local}, @t{declare}, @t{export}, @t{integer}, @t{float} +@item +Execution of incorrectly positioned loop control structures +(@t{continue}, @t{break}) +@item +Attempts to use regular expression with no regular expression +module available +@item +Disallowed operations when the @t{RESTRICTED} options is set +@item +Failure to create a pipe needed for a pipeline +@item +Failure to create a multio +@item +Failure to autoload a module needed for a declared shell feature +@item +Errors creating command or process substitutions +@item +Syntax errors in glob qualifiers +@item +File generation errors where not caught by the option @t{BAD_PATTERN} +@item +All bad patterns used for matching within case statements +@item +File generation failures where not caused by @t{NO_MATCH} or +similar options +@item +All file generation errors where the pattern was used to create a +multio +@item +Memory errors where detected by the shell +@item +Invalid subscripts to shell variables +@item +Attempts to assign read-only variables +@item +Logical errors with variables such as assignment to the wrong type +@item +Use of invalid variable names +@item +Errors in variable substitution syntax +@item +Failure to convert characters in @t{$'}...@t{'} expressions +@end itemize + +@noindent +If the @t{POSIX_BUILTINS} option is set, more errors associated with +shell builtin commands are treated as fatal, as specified by the POSIX +standard. + +@noindent +@node Comments, Aliasing, Errors, Shell Grammar + +@section Comments +@noindent +@cindex comments +@pindex INTERACTIVE_COMMENTS, use of +@vindex histchars, use of +In non-interactive shells, or in interactive shells with the +@t{INTERACTIVE_COMMENTS} option set, a word beginning +with the third character of the @t{histchars} parameter +(`@t{#}' by default) causes that word and all the following +characters up to a newline to be ignored. +@node Aliasing, Quoting, Comments, Shell Grammar + +@section Aliasing +@noindent +@cindex aliasing +Every eligible @emph{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. + +@noindent +It is an error for the function name, @var{word}, in the sh-compatible function +definition syntax `@var{word} @t{()} ...' to be a word that resulted +from alias expansion, unless the @t{ALIAS_FUNC_DEF} option is set. + +@noindent +@findex alias, use of +@cindex aliases, global +An alias is defined using the @t{alias} builtin; global aliases +may be defined using the @t{-g} option to that builtin. + +@noindent +A @emph{word} is defined as: + +@noindent +@itemize @bullet + +@item +Any plain string or glob pattern +@item +Any quoted string, using any quoting method (note that the quotes +must be part of the alias definition for this to be eligible) +@item +Any parameter reference or command substitution +@item +Any series of the foregoing, concatenated without whitespace or +other tokens between them +@item +Any reserved word (@t{case}, @t{do}, @t{else}, etc.) +@item +With global aliasing, any command separator, any redirection +operator, and `@t{(}' or `@t{)}' when not part of a glob pattern +@end itemize + +@noindent +Alias expansion is done on the shell input before any other expansion +except history expansion. Therefore, if an alias is defined for the +word @t{foo}, alias expansion may be avoided by quoting part of the +word, e.g. @t{\foo}. Any form of quoting works, although there is +nothing to prevent an alias being defined for the quoted form such as +@t{\foo} as well. + +@noindent +In particular, note that quoting must be used when using @t{unalias} to remove +global aliases: + +@noindent +@example +% alias -g foo=bar +% unalias foo +unalias: no such hash table element: bar +% unalias \foo +% +@end example + +@noindent +When @t{POSIX_ALIASES} is set, only plain unquoted strings are eligible +for aliasing. The @t{alias} builtin does not reject ineligible aliases, +but they are not expanded. + +@noindent +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. @t{'foo}; completion will +automatically add the trailing single quote. + +@noindent + +@subsection Alias difficulties +@noindent + +@noindent +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. + +@noindent +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 @t{aliases} described in +@ref{The zsh/parameter Module}). +However, as noted in the case of @t{POSIX_ALIASES} above, the shell does +not attempt to deduce whether the string corresponds to a word at the +time the alias is created. + +@noindent +For example, an expression containing an @t{=} at the start of +a command line is an assignment and cannot be expanded as an alias; +a lone @t{=} is not an assignment but can only be set as an alias +using the parameter, as otherwise the @t{=} is taken part of the +syntax of the builtin command. + +@noindent +It is not presently possible to alias the `@t{((}' token that +introduces arithmetic expressions, because until a full statement has been +parsed, it cannot be distinguished from two consecutive `@t{(}' +tokens introducing nested subshells. +Also, if a separator such as @t{&&} is aliased, +@t{\&&} turns into the two tokens @t{\&} and @t{&}, each of which may +have been aliased separately. Similarly for @t{\<<}, @t{\>|}, etc. + +@noindent +There is a commonly encountered problem with aliases +illustrated by the following code: + +@noindent +@example +alias echobar='echo bar'; echobar +@end example + +@noindent +This prints a message that the command @t{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 @t{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 `@t{source}' +or `@t{.}'. Consequently, use of functions rather than aliases is +recommended in non-interactive code. + +@noindent +@node Quoting, , Aliasing, Shell Grammar + +@section Quoting +@noindent +@cindex quoting +A character may be @emph{quoted} (that is, made +to stand for itself) by preceding it with a `@t{\}'. +`@t{\}' followed by a newline is ignored. + +@noindent +A string enclosed between `@t{$'}' and `@t{'}' is +processed the same way as the string arguments of the +@t{print} builtin, and the resulting string is considered to be +entirely quoted. A literal `@t{'}' character can be included in the +string by using the `@t{\'}' escape. + +@noindent +@pindex RC_QUOTES, use of +All characters enclosed between a pair of single quotes (@t{@value{dsq}}) that +is not preceded by a `@t{$}' are quoted. A single quote cannot appear +within single quotes unless the option @t{RC_QUOTES} is set, in which case +a pair of single quotes are turned into a single quote. For example, + +@noindent +@example +print @value{dsq}@value{dsq} +@end example + +@noindent +outputs nothing apart from a newline if @t{RC_QUOTES} is not set, but one +single quote if it is set. + +@noindent +Inside double quotes (@t{""}), parameter and +command substitution occur, and `@t{\}' quotes the characters +`@t{\}', `@t{`}', `@t{"}', `@t{$}', and the first character +of @t{$histchars} (default `@t{!}'). +@c (avoiding a yodl bug) +@c Yodl file: Zsh/redirect.yo +@node Redirection, Command Execution, Shell Grammar, Top + +@chapter Redirection +@noindent +@cindex redirection +@cindex file descriptors +@cindex descriptors, file +If a command is followed by @t{&} +and job control is not active, +then the default standard input +for the command is the empty file @t{/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. + +@noindent +The following may appear anywhere in a simple command +or may precede or follow a complex command. +Expansion occurs before @var{word} or @var{digit} +is used except as noted below. +If the result of substitution on @var{word} +produces more than one filename, +redirection occurs for each +separate filename in turn. + +@noindent +@table @asis +@item @t{<} @var{word} +Open file @var{word} for reading as standard input. +It is an error to open a file in this fashion if it does not exist. + +@item @t{<>} @var{word} +Open file @var{word} for reading and writing as standard input. +If the file does not exist then it is created. + +@item @t{>} @var{word} +Open file @var{word} for writing as standard output. +If the file does not exist then it is created. +If the file exists, and the @t{CLOBBER} option is unset, +this causes an error; +otherwise, it is truncated to zero length. + +@item @t{>|} @var{word} +@itemx @t{>!} @var{word} +Same as @t{>}, except that the file is truncated to zero length +if it exists, regardless of @t{CLOBBER}. + +@item @t{>>} @var{word} +Open file @var{word} for writing in append mode as standard output. +If the file does not exist, and the @t{CLOBBER} and @t{APPEND_CREATE} +options are both unset, this causes an error; +otherwise, the file is created. + +@item @t{>>|} @var{word} +@itemx @t{>>!} @var{word} +Same as @t{>>}, except that the file is created if it does not +exist, regardless of @t{CLOBBER} and @t{APPEND_CREATE}. + +@item @t{<<}[@t{-}] @var{word} +The shell input is read up to a line that is the same as +@var{word}, or to an end-of-file. +No parameter expansion, command substitution or +filename generation is performed on @var{word}. +The resulting document, called a +@emph{here-document}, becomes the standard input. + +@noindent +If any character of @var{word} is quoted with +single or double quotes or a `@t{\}', +no interpretation is placed upon the characters of the document. +Otherwise, parameter and command substitution +occurs, `@t{\}' followed by a newline is removed, +and `@t{\}' must be used to quote the characters +`@t{\}', `@t{$}', `@t{`}' and the first character of @var{word}. + +@noindent +Note that @var{word} itself does not undergo shell expansion. Backquotes +in @var{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 +@t{$'}@var{...}@t{'} have their standard effect of expanding backslashed +references to special characters. + +@noindent +If @t{<<-} is used, then all leading +tabs are stripped from @var{word} and from the document. + +@item @t{<<<} @var{word} +Perform shell expansion on @var{word} and pass the result +to standard input. This is known as a @emph{here-string}. +Compare the use of @var{word} in here-documents above, where @var{word} +does not undergo shell expansion. The result will have a trailing newline +after it. + +@item @t{<&} @var{number} +@itemx @t{>&} @var{number} +The standard input/output is duplicated from file descriptor +@var{number} (see dup2(2)). + +@item @t{<& -} +@itemx @t{>& -} +Close the standard input/output. + +@item @t{<& p} +@itemx @t{>& p} +The input/output from/to the coprocess is moved to the standard input/output. + +@item @t{>&} @var{word} +@itemx @t{&>} @var{word} +(Except where `@t{>&} @var{word}' matches one of the above syntaxes; +`@t{&>}' can always be used to avoid this ambiguity.) +Redirects both standard output and standard error (file descriptor 2) +in the manner of `@t{>} @var{word}'. +Note that this does @emph{not} have the same effect as `@t{>} @var{word} @t{2>&1}' +in the presence of multios (see the section below). + +@item @t{>&|} @var{word} +@itemx @t{>&!} @var{word} +@itemx @t{&>|} @var{word} +@itemx @t{&>!} @var{word} +Redirects both standard output and standard error (file descriptor 2) +in the manner of `@t{>|} @var{word}'. + +@item @t{>>&} @var{word} +@itemx @t{&>>} @var{word} +Redirects both standard output and standard error (file descriptor 2) +in the manner of `@t{>>} @var{word}'. + +@item @t{>>&|} @var{word} +@itemx @t{>>&!} @var{word} +@itemx @t{&>>|} @var{word} +@itemx @t{&>>!} @var{word} +Redirects both standard output and standard error (file descriptor 2) +in the manner of `@t{>>|} @var{word}'. + +@end table + +@noindent +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 +(@emph{file descriptor}, @emph{file}) +association at the time of evaluation. +For example: + +@noindent +@quotation +... @t{1>}@var{fname} @t{2>&1} +@end quotation + +@noindent +first associates file descriptor 1 with file @var{fname}. +It then associates file descriptor 2 with the file associated with file +descriptor 1 (that is, @var{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 @var{fname}. + +@noindent +The `@t{|&}' command separator described in +@ref{Simple Commands & Pipelines} +is a shorthand for `@t{2>&1 |}'. + +@noindent +The various forms of process substitution, `@t{<(}@var{list}@t{)}', +and `@t{=(}@var{list}@t{)}' for input and +`@t{>(}@var{list}@t{)}' for output, are often used together with +redirection. For example, if @var{word} in an output redirection is of the +form `@t{>(}@var{list}@t{)}' then the output is piped to the +command represented by @var{list}. See +@ref{Process Substitution}. + +@section Opening file descriptors using parameters +@noindent +@cindex file descriptors, use with parameters +@cindex parameters, for using file descriptors + +@noindent +When the shell is parsing arguments to a command, and the shell option +@t{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: + +@noindent +@quotation +... @t{@{myfd@}>&1} +@end quotation + +@noindent +This opens a new file descriptor that is a duplicate of file descriptor +1 and sets the parameter @t{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 @t{>&$myfd}. The file descriptor remains open in subshells +and forked external executables. + +@noindent +The syntax @t{@{}@var{varid}@t{@}>&-}, for example @t{@{myfd@}>&-}, may be used +to close a file descriptor opened in this fashion. Note that the +parameter given by @var{varid} must previously be set to a file descriptor +in this case. + +@noindent +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 @t{<&$}@var{param} or @t{>&$}@var{param} if @var{param} is +readonly. + +@noindent +If the option @t{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. + +@noindent +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 @t{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. + +@noindent +The following shows a typical sequence of allocation, use, and closing of a +file descriptor: + +@noindent +@example +integer myfd +exec @{myfd@}>~/logs/mylogfile.txt +print This is a log message. >&$myfd +exec @{myfd@}>&- +@end example + +@noindent +Note that the expansion of the variable in the expression @t{>&$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. + +@section Multios +@noindent +@cindex multios +@pindex MULTIOS, use of +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 @cite{tee}, +provided the @t{MULTIOS} option is set, as it is by default. Thus: + +@noindent +@example +date >foo >bar +@end example + +@noindent +writes the date to two files, named `@t{foo}' and `@t{bar}'. +Note that a pipe is an implicit redirection; thus + +@noindent +@example +date >foo | cat +@end example + +@noindent +writes the date to the file `@t{foo}', and also pipes it to cat. + +@noindent +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. + +@noindent +Note also that redirections are always expanded in order. This happens +regardless of the setting of the @t{MULTIOS} option, but with the option +in effect there are additional consequences. For example, +the meaning of the expression @t{>&1} will change after a previous +redirection: + +@noindent +@example +date >&1 >output +@end example + +@noindent +In the case above, the @t{>&1} refers to the standard output at the +start of the line; the result is similar to the @t{tee} command. +However, consider: + +@noindent +@example +date >output >&1 +@end example + +@noindent +As redirections are evaluated in order, when the @t{>&1} is encountered +the standard output is set to the file @t{output} and another copy of +the output is therefore sent to that file. This is unlikely to be what +is intended. + +@noindent +If the @t{MULTIOS} +option is set, the word after a redirection operator is also subjected +to filename generation (globbing). Thus + +@noindent +@example +: > * +@end example + +@noindent +will truncate all files in the current directory, +assuming there's at least one. (Without the @t{MULTIOS} +option, it would create an empty file called `@t{*}'.) +Similarly, you can do + +@noindent +@example +echo exit 0 >> *.sh +@end example + +@noindent +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 @t{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 @t{cat}, so if strictly standard behaviour +is needed, @t{cat} should be used instead. + +@noindent +Thus + +@noindent +@example +sort <foo <fubar +@end example + +@noindent +or even + +@noindent +@example +sort <f@{oo,ubar@} +@end example + +@noindent +is equivalent to `@t{cat foo fubar | sort}'. + +@noindent +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 @t{>&$myfd}. + +@noindent +Note that a pipe is an implicit redirection; thus + +@noindent +@example +cat bar | sort <foo +@end example + +@noindent +is equivalent to `@t{cat bar foo | sort}' (note the order of the inputs). + +@noindent +If the @t{MULTIOS} option is @emph{un}set, +each redirection replaces the previous redirection for that file descriptor. +However, all files redirected to are actually opened, so + +@noindent +@example +echo Hello > bar > baz +@end example + +@noindent +when @t{MULTIOS} is unset will truncate `@t{bar}', and write `@t{Hello}' +into `@t{baz}'. + +@noindent +There is a problem when an output multio is attached to an external +program. A simple example shows this: + +@noindent +@example +cat file >file1 >file2 +cat file1 file2 +@end example + +@noindent +Here, it is possible that the second `@t{cat}' will not display the full +contents of @t{file1} and @t{file2} (i.e. the original contents of +@t{file} repeated twice). + +@noindent +The reason for this is that the multios are spawned after the @t{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 @t{file1} and @t{file2} are completely written. +As a workaround, it is possible to run the @t{cat} process as part of a +job in the current shell: + +@noindent +@example +@{ cat file @} >file >file2 +@end example + +@noindent +Here, the @t{@{}@var{...}@t{@}} job will pause to wait for both files to be +written. + +@noindent + +@section Redirections with no command +@noindent +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. + +@noindent +@vindex NULLCMD, use of +@pindex CSH_NULLCMD, use of +If the parameter @t{NULLCMD} is not set or the option @t{CSH_NULLCMD} is +set, an error is caused. This is the @cite{csh} behavior and @t{CSH_NULLCMD} +is set by default when emulating @cite{csh}. + +@noindent +@pindex SH_NULLCMD, use of +If the option @t{SH_NULLCMD} is set, the builtin `@t{:}' is inserted as a +command with the given redirections. This is the default when emulating +@cite{sh} or @cite{ksh}. + +@noindent +@vindex READNULLCMD, use of +Otherwise, if the parameter @t{NULLCMD} is set, its value will be used as a +command with the given redirections. If both @t{NULLCMD} and +@t{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 +@t{NULLCMD} is `@t{cat}' and for @t{READNULLCMD} is `@t{more}'. Thus + +@noindent +@example +< file +@end example + +@noindent +shows the contents of @t{file} on standard output, with paging if that is a +terminal. @t{NULLCMD} and @t{READNULLCMD} may refer to shell functions. + +@noindent +@c (avoiding a yodl bug) +@c Yodl file: Zsh/exec.yo +@node Command Execution, Functions, Redirection, Top + +@chapter Command Execution +@noindent +@cindex command execution +@cindex execution, of commands +@cindex command not found, handling of +@findex command_not_found_handler +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 @ref{Functions}. If there exists +a shell builtin by that name, the builtin is invoked. + +@noindent +@vindex path, use of +Otherwise, the shell searches each element of @t{$path} for a +directory containing an executable file by that name. + +@noindent +If execution fails: an error message is printed, and one of the +following values is returned. + +@noindent +@table @asis +@item 127 +The search was unsuccessful. The error message is +`@t{command not found:} @var{cmd}'. +@item 126 +The executable file has insufficient permissions, is a +directory or special file, or is not a script and is in a format +unrecognized by the operating system. The exact conditions and error +message are operating system-dependent; see +execve(2). +@end table + +@noindent +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. @t{/bin/sh} is spawned to execute it. If the program +is a file beginning with `@t{#!}', 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. + +@noindent +If no external command is found but a function @t{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. 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. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/func.yo +@node Functions, Jobs & Signals, Command Execution, Top + +@chapter Functions +@noindent +@cindex functions +@findex function, use of +Shell functions are defined with the @t{function} reserved word or the +special syntax `@var{funcname} @t{()}'. +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 @ref{Command Execution}.) + +@noindent +Functions execute in the same process as the caller and +share all files +and present working directory with the +caller. A trap on @t{EXIT} set inside a function +is executed after the function completes in the environment +of the caller. + +@noindent +@findex return, use of +The @t{return} builtin is used to return from function calls. + +@noindent +@findex functions, use of +Function identifiers can be listed with the @t{functions} builtin. +@findex unfunction, use of +Functions can be undefined with the @t{unfunction} builtin. + +@section Autoloading Functions +@noindent +@cindex autoloading functions +@cindex functions, autoloading + +@noindent +@findex autoload, use of +@vindex fpath, use of +A function can be marked as @emph{undefined} using the @t{autoload} builtin +(or `@t{functions -u}' or `@t{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 @t{fpath} variable. Thus to define +functions for autoloading, a typical sequence is: + +@noindent +@example +fpath=(~/myfuncs $fpath) +autoload myfunc1 myfunc2 ... +@end example + +@noindent +The usual alias expansion during reading will be suppressed if the +@t{autoload} builtin or its equivalent is given the option @t{-U}. This is +recommended for the use of functions supplied with the zsh distribution. +@findex zcompile, use of +Note that for functions precompiled with the @t{zcompile} builtin command +the flag @t{-U} must be provided when the @t{.zwc} file is created, as the +corresponding information is compiled into the latter. + +@noindent +For each @var{element} in @t{fpath}, the shell looks for three possible +files, the newest of which is used to load the definition for the function: + +@noindent +@table @asis +@item @var{element}@t{.zwc} +A file created with the @t{zcompile} builtin command, which is expected to +contain the definitions for all functions in the directory named +@var{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. + +@noindent +If @var{element} already includes a @t{.zwc} extension (i.e. the extension +was explicitly given by the user), @var{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 @var{element} +without the suffix. Thus including an element such as +`@t{/usr/local/funcs.zwc}' in @t{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. + +@item @var{element}@t{/}@var{function}@t{.zwc} +A file created with @t{zcompile}, which is expected to contain the +definition for @var{function}. It may include other function definitions +as well, but those are neither loaded nor executed; a file found in this +way is searched @emph{only} for the definition of @var{function}. + +@item @var{element}@t{/}@var{function} +A file of zsh command text, taken to be the definition for @var{function}. + +@end table + +@noindent +In summary, the order of searching is, first, in the @emph{parents of} +directories in @t{fpath} for the newer of either a compiled directory or +a directory in @t{fpath}; second, if more than one of these contains a +definition for the function that is sought, the leftmost in the @t{fpath} +is chosen; and third, within a directory, the newer of either a compiled +function or an ordinary function definition is used. + +@noindent +@pindex KSH_AUTOLOAD, use of +If the @t{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. + +@noindent +Otherwise, the function body (with no surrounding `@var{funcname}@t{() +@{}@var{...}@t{@}}') 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. + +@noindent +For example, suppose the autoload file @t{func} contains + +@noindent +@example +func() @{ print This is func; @} +print func is initialized +@end example + +@noindent +then `@t{func; func}' with @t{KSH_AUTOLOAD} set will produce both messages +on the first call, but only the message `@t{This is func}' on the second +and subsequent calls. Without @t{KSH_AUTOLOAD} set, it will produce +the initialization message on the first call, and the other message on the +second and subsequent calls. + +@noindent +It is also possible to create a function that is not marked as autoloaded, +but which loads its own definition by searching @t{fpath}, by using +`@t{autoload -X}' within a shell function. For example, the following are +equivalent: + +@noindent +@example +myfunc() @{ + autoload -X +@} +myfunc args... +@end example + +@noindent +and + +@noindent +@example +unfunction myfunc # if myfunc was defined +autoload myfunc +myfunc args... +@end example + +@noindent +In fact, the @t{functions} command outputs `@t{builtin autoload -X}' as +the body of an autoloaded function. This is done so that + +@noindent +@example +eval "$(functions)" +@end example + +@noindent +produces a reasonable result. A true autoloaded function can be +identified by the presence of the comment `@t{# undefined}' in the body, +because all comments are discarded from defined functions. + +@noindent +To load the definition of an autoloaded function @t{myfunc} without +executing @t{myfunc}, use: + +@noindent +@example +autoload +X myfunc +@end example + +@noindent + +@section Anonymous Functions +@noindent +@cindex anonymous functions +@cindex functions, anonymous + +@noindent +If no name is given for a function, it is `anonymous' and is handled +specially. Either form of function definition may be used: a `@t{()}' with +no preceding name, or a `@t{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 `@t{(anon)}'. + +@noindent +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 @t{$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 `@t{else}' or `@t{fi}', which will +be treated as arguments to anonymous functions, so that a newline or +semicolon is needed to force keyword interpretation. + +@noindent +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). + +@noindent +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. + +@noindent +For example, + +@noindent +@example +variable=outside +function @{ + local variable=inside + print "I am $variable with arguments $*" +@} this and that +print "I am $variable" +@end example + +@noindent +outputs the following: + +@noindent +@example +I am inside with arguments this and that +I am outside +@end example + +@noindent +Note that function definitions with arguments that expand to nothing, +for example `@t{name=; function $name @{ }@var{...}@t{ @}}', are not +treated as anonymous functions. Instead, they are treated as normal +function definitions where the definition is silently discarded. + +@noindent + +@section Special Functions +@noindent +Certain functions, if defined, have special meaning to the shell. + +@noindent + +@subsection Hook Functions +@noindent +@findex functions, hook +@findex hook functions + +@noindent +For the functions below, it is possible to define an array that has the +same name as the function with `@t{_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 and same initial value of @t{$?} +as the basic function. For +example, if @t{$chpwd_functions} is an array containing the values +`@t{mychpwd}', `@t{chpwd_save_dirstack}', then the shell attempts to +execute the functions `@t{chpwd}', `@t{mychpwd}' and +`@t{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 @emph{hook function}. An error in any function causes subsequent +functions not to be run. Note further that an error in a @t{precmd} hook +causes an immediately following @t{periodic} function not to run (though +it may run at the next opportunity). + +@noindent +@table @asis +@findex chpwd +@vindex chpwd_functions +@item @t{chpwd} +Executed whenever the current working directory is changed. + +@findex periodic +@vindex periodic_functions +@item @t{periodic} +@vindex PERIOD +If the parameter @t{PERIOD} +is set, this function is executed every @t{$PERIOD} +seconds, just before a prompt. Note that if multiple functions +are defined using the array @t{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. + +@findex precmd +@vindex precmd_functions +@item @t{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. + +@findex preexec +@vindex preexec_functions +@item @t{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. + +@findex zshaddhistory +@vindex zshaddhistory_functions +@item @t{zshaddhistory} +@cindex history, hook when line is saved +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). + +@noindent +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. + +@noindent +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. + +@noindent +A hook function may call `@t{fc -p} @var{...}' to switch the history +context so that the history is saved in a different file from +that in the global @t{HISTFILE} parameter. This is handled specially: +the history context is automatically restored after the processing +of the history line is finished. + +@noindent +The following example function works with one of the options +@t{INC_APPEND_HISTORY} or @t{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. + +@noindent +@example +zshaddhistory() @{ + print -sr -- $@{1%%$'\n'@} + fc -p .zsh_local_history +@} +@end example + +@findex zshexit +@vindex zshexit_functions +@item @t{zshexit} +Executed at the point where the main shell is about to exit normally. +This is not called by exiting subshells, nor when the @t{exec} +precommand modifier is used before an external command. Also, unlike +@t{TRAPEXIT}, it is not called when functions exit. + +@end table + +@noindent + +@subsection Trap Functions +@noindent + +@noindent +The functions below are treated specially but do not have corresponding +hook arrays. + +@noindent +@table @asis +@item @t{TRAP}@var{NAL} +@cindex signals, trapping +@cindex trapping signals +If defined and non-null, +this function will be executed whenever the shell +catches a signal @t{SIG}@var{NAL}, where @var{NAL} is a signal +name as specified for the @t{kill} builtin. +The signal number will be passed as the first parameter to the function. + +@noindent +If a function of this form is defined and null, +the shell and processes spawned by it will ignore @t{SIG}@var{NAL}. + +@noindent +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. + +@noindent +Programs terminated by uncaught signals typically return the status 128 +plus the signal number. Hence the following causes the handler for +@t{SIGINT} to print a message, then mimic the usual effect of the signal. + +@noindent +@example +TRAPINT() @{ + print "Caught SIGINT, aborting." + return $(( 128 + $1 )) +@} +@end example + +@noindent +The functions @t{TRAPZERR}, @t{TRAPDEBUG} and @t{TRAPEXIT} are never +executed inside other traps. + +@findex TRAPDEBUG +@item @t{TRAPDEBUG} +If the option @t{DEBUG_BEFORE_CMD} is set (as it is by default), executed +before each command; otherwise executed after each command. See +the description of the @t{trap} builtin in +@ref{Shell Builtin Commands} for details of additional features provided +in debug traps. + +@findex TRAPEXIT +@item @t{TRAPEXIT} +Executed when the shell exits, +or when the current function exits if defined inside a function. +The value of @t{$?} at the start of execution is the exit status of the +shell or the return status of the function exiting. + +@findex TRAPZERR +@findex TRAPERR +@item @t{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 +`@t{&&}' or `@t{||}'; only the final command in a sublist of this type +causes the trap to be executed. The function @t{TRAPERR} acts the same as +@t{TRAPZERR} on systems where there is no @t{SIGERR} (this is the usual +case). + +@end table + +@noindent +@findex trap, use of +The functions beginning `@t{TRAP}' may alternatively be defined with the +@t{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 + +@noindent +@example +TRAPNAL() @{ + # code +@} +@end example + +@noindent +('function traps') and + +@noindent +@example +trap ' + # code +' NAL +@end example + +@noindent +('list traps') are equivalent in most ways, the exceptions being the +following: + +@noindent +@itemize @bullet + +@item +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. +@item +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. +@item +Function traps are not reset within subshells, in accordance with +zsh behaviour; list traps are reset, in accordance with POSIX +behaviour. +@end itemize +@c (avoiding a yodl bug) +@c Yodl file: Zsh/jobs.yo +@node Jobs & Signals, Arithmetic Evaluation, Functions, Top + +@chapter Jobs & Signals +@noindent + +@section Jobs +@noindent +@cindex jobs +@pindex MONITOR, use of +If the @t{MONITOR} option is set, +an interactive shell associates a @emph{job} with each pipeline. +It keeps a table of current jobs, printed by the @t{jobs} +command, and assigns them small integer numbers. +When a job is started asynchronously with `@t{&}', +the shell prints a line to standard error which looks like: + +@noindent +@example +[1] 1234 +@end example + +@noindent +indicating that the job which was started asynchronously was job number +1 and had one (top-level) process, whose process ID was 1234. + +@noindent +If a job is started with `@t{&|}' or `@t{&!}', +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. + +@noindent +If you are running a job and wish to do something else you may hit the key +^Z (control-Z) which sends a @t{TSTP} signal to the current job: this key +may be redefined by the @t{susp} option of the external @t{stty} command. +@cindex jobs, suspending +@cindex suspending jobs +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, +@findex bg, use of +putting it in the background with the @t{bg} command, or run some other +commands and then eventually bring the job back into the foreground with +@findex fg, use of +the foreground command @t{fg}. A ^Z takes effect immediately and +is like an interrupt in that pending output and unread input are discarded +when it is typed. + +@noindent +A job being run in the background will suspend if it tries to read +from the terminal. + +@noindent +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 @t{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. + +@noindent +One additional side effect is that use of @t{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. + +@noindent +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 +@t{if}, @t{for}, etc., in order that the entire block of code +can be managed as a single job. +@cindex background jobs, I/O +@cindex jobs, background, I/O +Background jobs are normally allowed to produce output, +but this can be disabled by giving the command `@t{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. + +@noindent +When a command is suspended and continued later with the @t{fg} or +@t{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 `@t{kill -CONT}', nor when it is continued with @t{bg}. + +@noindent +@cindex jobs, referring to +@cindex referring to jobs +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: + +@noindent +@table @asis +@item @t{%}@var{number} +The job with the given number. +@item @t{%}@var{string} +The last job whose command line begins with @var{string}. +@item @t{%?}@var{string} +The last job whose command line contains @var{string}. +@item @t{%%} +Current job. +@item @t{%+} +Equivalent to `@t{%%}'. +@item @t{%-} +Previous job. +@end table + +@noindent +The shell learns immediately whenever a process changes state. +@pindex NOTIFY, use of +It normally informs you whenever a job becomes blocked so that +no further progress is possible. If the @t{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. + +@noindent +When the monitor mode is on, each background job that completes +triggers any trap set for @t{CHLD}. + +@noindent +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 @t{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 @t{SIGHUP} signal, if the @t{HUP} option is set. +@pindex HUP, use of + +@noindent +@cindex jobs, disowning +@cindex disowning jobs +@findex disown, use of +To avoid having the shell terminate the running jobs, either +use the nohup(1) command +or the @t{disown} builtin. + +@section Signals +@noindent +The @t{INT} and @t{QUIT} signals for an invoked +command are ignored if the command is followed by +`@t{&}' and the @t{MONITOR} option is not active. +The shell itself always ignores the @t{QUIT} signal. +Otherwise, signals have the values +inherited by the shell from its parent +(but see the @t{TRAP}@var{NAL} special functions in @ref{Functions}). + +@noindent +@cindex exiting shell, and asynchronous jobs +@cindex asynchronous jobs, and exiting shell +@cindex jobs, asynchronous, and exiting shell +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 @t{exit} command +or exit due to the option @t{ERR_EXIT} will cause the shell to +exit without waiting. Examples of such asynchronous jobs are +process substitution, see +@ref{Process Substitution}, and the handler processes for +multios, see +the section @emph{Multios} in @ref{Redirection}. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/arith.yo +@node Arithmetic Evaluation, Conditional Expressions, Jobs & Signals, Top + +@chapter Arithmetic Evaluation +@noindent +@cindex arithmetic evaluation +@cindex evaluation, arithmetic +@findex let, use of +The shell can perform integer and floating point arithmetic, either using +the builtin @t{let}, or via a substitution of the form +@t{$((}@var{...}@t{))}. 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 `@t{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. + +@noindent +The @t{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 `@t{((}', all the characters until a +matching `@t{))}' are treated as a double-quoted expression and +arithmetic expansion performed as for an argument of @t{let}. More +precisely, `@t{((}@var{...}@t{))}' is equivalent to +`@t{let "}@var{...}@t{"}'. 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. + +@noindent +For example, the following statement + +@noindent +@example +(( val = 2 + 1 )) +@end example + +@noindent +is equivalent to + +@noindent +@example +let "val = 2 + 1" +@end example + +@noindent +both assigning the value 3 to the shell variable @t{val} and returning a +zero status. + +@noindent +@cindex arithmetic base +@cindex bases, in arithmetic +Integers can be in bases other than 10. +A leading `@t{0x}' or `@t{0X}' denotes hexadecimal and a leading +`@t{0b}' or `@t{0B}' binary. +Integers may also be of the form `@var{base}@t{#}@var{n}', +where @var{base} is a decimal number between two and thirty-six +representing the arithmetic base and @var{n} +is a number in that base (for example, `@t{16#ff}' is 255 in hexadecimal). +The @var{base}@t{#} may also be omitted, in which case +base 10 is used. For backwards compatibility the form +`@t{[}@var{base}@t{]}@var{n}' is also accepted. + +@noindent +An integer expression or a base given in the form +`@var{base}@t{#}@var{n}' may contain underscores (`@t{_}') after the +leading digit for visual guidance; these are ignored in computation. +Examples are @t{1_000_000} or @t{0xffff_ffff} which are equivalent to +@t{1000000} and @t{0xffffffff} respectively. + +@noindent +It is also possible to specify a base to be used for output in the form +`@t{[#}@var{base}@t{]}', for example `@t{[#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 `@t{-i} @var{base}' to +the @t{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: + +@noindent +@example +typeset -i 16 y +print $(( [#8] x = 32, y = 32 )) +print $x $y +@end example + +@noindent +outputs first `@t{8#40}', the rightmost value in the given output base, and +then `@t{8#40 16#20}', because @t{y} has been explicitly declared to +have output base 16, while @t{x} (assuming it does not already exist) is +implicitly typed by the arithmetic evaluation, where it acquires the output +base 8. + +@noindent +The @var{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: + +@noindent +@example +setopt cbases +print $(( [#16_4] 65536 ** 2 )) +@end example + +@noindent +outputs `@t{0x1_0000_0000}'. + +@noindent +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, + +@noindent +@example +zmodload zsh/mathfunc +print $(( [#_] sqrt(1e7) )) +@end example + +@noindent +outputs `@t{3_162.277_660_168_379_5}' (the number of decimal places +shown may vary). + +@noindent +@pindex C_BASES, use of +@pindex OCTAL_ZEROES, use of +If the @t{C_BASES} option is set, hexadecimal numbers are output in the standard C +format, for example `@t{0xFF}' instead of the usual `@t{16#FF}'. If the +option @t{OCTAL_ZEROES} is also set (it is not by default), octal numbers +will be treated similarly and hence appear as `@t{077}' instead of +`@t{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. + +@noindent +When an output base is specified using the `@t{[#}@var{base}@t{]}' syntax, +an appropriate base prefix will be output if necessary, so that the value +output is valid syntax for input. If the @t{#} is doubled, for example +`@t{[##16]}', then no base prefix is output. + +@noindent +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 @t{e} or @t{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. + +@noindent +@cindex arithmetic operators +@cindex operators, arithmetic +An arithmetic expression uses nearly the same syntax and +associativity of expressions as in C. + +@noindent +In the native mode of operation, the following operators are supported +(listed in decreasing order of precedence): + +@noindent +@table @asis +@item @t{+ - ! ~ ++ --} +unary plus/minus, logical NOT, complement, @{pre,post@}@{in,de@}crement +@item @t{<< >>} +bitwise shift left, right +@item @t{&} +bitwise AND +@item @t{^} +bitwise XOR +@item @t{|} +bitwise OR +@item @t{**} +exponentiation +@item @t{* / %} +multiplication, division, modulus (remainder) +@item @t{+ -} +addition, subtraction +@item @t{< > <= >=} +comparison +@item @t{== !=} +equality and inequality +@item @t{&&} +logical AND +@item @t{|| ^^} +logical OR, XOR +@item @t{? :} +ternary operator +@item @t{= += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=} +assignment +@item @t{,} +comma operator +@end table + +@noindent +The operators `@t{&&}', `@t{||}', `@t{&&=}', and `@t{||=}' 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. + +@noindent +With the option @t{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: + +@noindent +@table @asis +@item @t{+ - ! ~ ++ --} +unary plus/minus, logical NOT, complement, @{pre,post@}@{in,de@}crement +@item @t{**} +exponentiation +@item @t{* / %} +multiplication, division, modulus (remainder) +@item @t{+ -} +addition, subtraction +@item @t{<< >>} +bitwise shift left, right +@item @t{< > <= >=} +comparison +@item @t{== !=} +equality and inequality +@item @t{&} +bitwise AND +@item @t{^} +bitwise XOR +@item @t{|} +bitwise OR +@item @t{&&} +logical AND +@item @t{^^} +logical XOR +@item @t{||} +logical OR +@item @t{? :} +ternary operator +@item @t{= += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=} +assignment +@item @t{,} +comma operator +@end table + +@noindent +Note the precedence of exponentiation in both cases is below +that of unary operators, hence `@t{-3**2}' evaluates as `@t{9}', not +`@t{-9}'. Use parentheses where necessary: `@t{-(3**2)}'. This is +for compatibility with other shells. + +@noindent +@cindex mathematical functions, use of +@cindex functions, math, use of +Mathematical functions can be called with the syntax +`@var{func}@t{(}@var{args}@t{)}', where the function decides +if the @var{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 @t{zsh/mathfunc} may be loaded with +the @t{zmodload} builtin to provide standard floating point mathematical +functions. + +@noindent +An expression of the form `@t{##}@var{x}' where @var{x} is any character +sequence such as `@t{a}', `@t{^A}', or `@t{\M-\C-x}' gives the value of +this character and an expression of the form `@t{#}@var{name}' gives the +value of the first character of the contents of the parameter @var{name}. +Character values are according to the character set used in the current +locale; for multibyte character handling the option @t{MULTIBYTE} must be +set. Note that this form is different from `@t{$#}@var{name}', a standard +parameter substitution which gives the length of the parameter @var{name}. +`@t{#\}' is accepted instead of `@t{##}', but its use is deprecated. + +@noindent +Named parameters and subscripted arrays can be referenced by name within an +arithmetic expression without using the parameter expansion syntax. For +example, + +@noindent +@example +((val2 = val1 * 2)) +@end example + +@noindent +assigns twice the value of @t{$val1} to the parameter named @t{val2}. + +@noindent +An internal integer representation of a named parameter +can be specified with the @t{integer} builtin. +@cindex parameters, integer +@cindex integer parameters +@findex integer, use of +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. + +@noindent +@cindex parameters, floating point +@cindex floating point parameters +@findex float, use of +Likewise, floating point numbers can be declared with the @t{float} +builtin; there are two types, differing only in their output format, as +described for the @t{typeset} builtin. The output format can be bypassed +by using arithmetic substitution instead of the parameter substitution, +i.e. `@t{$@{}@var{float}@t{@}}' uses the defined format, but +`@t{$((}@var{float}@t{))}' uses a generic floating point +format. + +@noindent +Promotion of integer to floating point values is performed where +necessary. In addition, if any operator which requires an integer +(`@t{&}', `@t{|}', `@t{^}', `@t{<<}', `@t{>>}' and their equivalents with +assignment) is given a floating point argument, it will be silently rounded +towards zero except for `@t{~}' which rounds down. + +@noindent +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 @t{6/8} is truncated, +in this being rounded towards 0. The @t{FORCE_FLOAT} shell option can +be used in scripts or functions where floating point evaluation is +required throughout. + +@noindent +Scalar variables can hold integer or floating point values at different +times; there is no memory of the numeric type in this case. + +@noindent +If a variable is first assigned in a numeric context without previously +being declared, it will be implicitly typed as @t{integer} or @t{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 + +@noindent +@example +for (( f = 0; f < 1; f += 0.1 )); do +# use $f +done +@end example + +@noindent +if @t{f} has not already been declared, the first assignment will cause it +to be created as an integer, and consequently the operation `@t{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 `@t{f = 0.0}'. +It is therefore best to declare numeric variables with explicit types. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/cond.yo +@node Conditional Expressions, Prompt Expansion, Arithmetic Evaluation, Top + +@chapter Conditional Expressions +@noindent +@cindex conditional expressions +@cindex expressions, conditional +A @emph{conditional expression} is used with the @t{[[} +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: + +@noindent +@table @asis +@item @t{-a} @var{file} +true if @var{file} exists. + +@item @t{-b} @var{file} +true if @var{file} exists and is a block special file. + +@item @t{-c} @var{file} +true if @var{file} exists and is a character special file. + +@item @t{-d} @var{file} +true if @var{file} exists and is a directory. + +@item @t{-e} @var{file} +true if @var{file} exists. + +@item @t{-f} @var{file} +true if @var{file} exists and is a regular file. + +@item @t{-g} @var{file} +true if @var{file} exists and has its setgid bit set. + +@item @t{-h} @var{file} +true if @var{file} exists and is a symbolic link. + +@item @t{-k} @var{file} +true if @var{file} exists and has its sticky bit set. + +@item @t{-n} @var{string} +true if length of @var{string} is non-zero. + +@item @t{-o} @var{option} +true if option named @var{option} is on. @var{option} +may be a single character, in which case it is a single letter option name. +(See @ref{Specifying Options}.) + +@noindent +When no option named @var{option} exists, and the @t{POSIX_BUILTINS} option +hasn't been set, return 3 with a warning. If that option is set, return 1 +with no warning. + +@item @t{-p} @var{file} +true if @var{file} exists and is a FIFO special file (named pipe). + +@item @t{-r} @var{file} +true if @var{file} exists and is readable by current process. + +@item @t{-s} @var{file} +true if @var{file} exists and has size greater than zero. + +@item @t{-t} @var{fd} +true if file descriptor number @var{fd} +is open and associated with a terminal device. +(note: @var{fd} is not optional) + +@item @t{-u} @var{file} +true if @var{file} exists and has its setuid bit set. + +@item @t{-v} @var{varname} +true if shell variable @var{varname} is set. + +@item @t{-w} @var{file} +true if @var{file} exists and is writable by current process. + +@item @t{-x} @var{file} +true if @var{file} exists and is executable by current process. +If @var{file} exists and is a directory, then the current process +has permission to search in the directory. + +@item @t{-z} @var{string} +true if length of @var{string} is zero. + +@item @t{-L} @var{file} +true if @var{file} exists and is a symbolic link. + +@item @t{-O} @var{file} +true if @var{file} exists and is owned by the effective user ID of this process. + +@item @t{-G} @var{file} +true if @var{file} exists and its group matches +the effective group ID of this process. + +@item @t{-S} @var{file} +true if @var{file} exists and is a socket. + +@item @t{-N} @var{file} +true if @var{file} exists and its access time is +not newer than its modification time. + +@item @var{file1} @t{-nt} @var{file2} +true if @var{file1} exists and is newer than @var{file2}. + +@item @var{file1} @t{-ot} @var{file2} +true if @var{file1} exists and is older than @var{file2}. + +@item @var{file1} @t{-ef} @var{file2} +true if @var{file1} and @var{file2} exist and refer to the same file. + +@item @var{string} @t{=} @var{pattern} +@itemx @var{string} @t{==} @var{pattern} +true if @var{string} matches @var{pattern}. +The two forms are exactly equivalent. The `@t{=}' form is +the traditional shell syntax (and hence the only one generally used +with the @t{test} and @t{[} builtins); the `@t{==}' form provides +compatibility with other sorts of computer language. + +@item @var{string} @t{!=} @var{pattern} +true if @var{string} does not match @var{pattern}. + +@item @var{string} @t{=~} @var{regexp} +true if @var{string} matches the regular expression +@var{regexp}. If the option @t{RE_MATCH_PCRE} is set +@var{regexp} is tested as a PCRE regular expression using +the @t{zsh/pcre} module, else it is tested as a POSIX +extended regular expression using the @t{zsh/regex} module. +Upon successful match, some variables will be updated; no variables +are changed if the matching fails. + +@noindent +If the option @t{BASH_REMATCH} is not set the scalar parameter +@t{MATCH} is set to the substring that matched the pattern and +the integer parameters @t{MBEGIN} and @t{MEND} to the index of the start +and end, respectively, of the match in @var{string}, such that if +@var{string} is contained in variable @t{var} the expression +`@t{$@{var[$MBEGIN,$MEND]@}}' is identical to `@t{$MATCH}'. The setting +of the option @t{KSH_ARRAYS} is respected. Likewise, the array +@t{match} is set to the substrings that matched parenthesised +subexpressions and the arrays @t{mbegin} and @t{mend} to the indices of +the start and end positions, respectively, of the substrings within +@var{string}. The arrays are not set if there were no parenthesised +subexpressions. For example, if the string `@t{a short string}' is matched +against the regular expression `@t{s(...)t}', then (assuming the +option @t{KSH_ARRAYS} is not set) @t{MATCH}, @t{MBEGIN} +and @t{MEND} are `@t{short}', @t{3} and @t{7}, respectively, while @t{match}, +@t{mbegin} and @t{mend} are single entry arrays containing +the strings `@t{hor}', `@t{4}' and `@t{6}', respectively. + +@noindent +If the option @t{BASH_REMATCH} is set the array +@t{BASH_REMATCH} is set to the substring that matched the pattern +followed by the substrings that matched parenthesised +subexpressions within the pattern. + +@item @var{string1} @t{<} @var{string2} +true if @var{string1} comes before @var{string2} +based on ASCII value of their characters. + +@item @var{string1} @t{>} @var{string2} +true if @var{string1} comes after @var{string2} +based on ASCII value of their characters. + +@item @var{exp1} @t{-eq} @var{exp2} +true if @var{exp1} is numerically equal to @var{exp2}. +Note that for purely numeric comparisons use of the +@t{((}@var{...}@t{))} builtin described in +@ref{Arithmetic Evaluation} is more convenient than +conditional expressions. + +@item @var{exp1} @t{-ne} @var{exp2} +true if @var{exp1} is numerically not equal to @var{exp2}. + +@item @var{exp1} @t{-lt} @var{exp2} +true if @var{exp1} is numerically less than @var{exp2}. + +@item @var{exp1} @t{-gt} @var{exp2} +true if @var{exp1} is numerically greater than @var{exp2}. + +@item @var{exp1} @t{-le} @var{exp2} +true if @var{exp1} is numerically less than or equal to @var{exp2}. + +@item @var{exp1} @t{-ge} @var{exp2} +true if @var{exp1} is numerically greater than or equal to @var{exp2}. + +@item @t{(} @var{exp} @t{)} +true if @var{exp} is true. + +@item @t{!} @var{exp} +true if @var{exp} is false. + +@item @var{exp1} @t{&&} @var{exp2} +true if @var{exp1} and @var{exp2} are both true. + +@item @var{exp1} @t{||} @var{exp2} +true if either @var{exp1} or @var{exp2} is true. + +@end table + +@noindent +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, @t{[[ $var ]]} is the same as @t{[[ -n +$var ]]}. It is recommended that the second, explicit, form be used +where possible. + +@noindent +Normal shell expansion is performed on the @var{file}, @var{string} and +@var{pattern} arguments, but the result of each expansion is constrained to +be a single word, similar to the effect of double quotes. + +@noindent +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 @t{EXTENDED_GLOB} is in effect by +using an explicit glob qualifier of the form @t{(#q)} at the +end of the string. A normal glob qualifier expression may appear +between the `@t{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. + +@noindent +This special use of filename generation is only available with the +@t{[[} syntax. If the condition occurs within the @t{[} or @t{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. + +@noindent +For example, + +@noindent +@example +[[ -n file*(#qN) ]] +@end example + +@noindent +produces status zero if and only if there is at least one file in the +current directory beginning with the string `@t{file}'. The globbing +qualifier @t{N} ensures that the expression is empty if there is +no matching file. + +@noindent +Pattern metacharacters are active for the @var{pattern} arguments; +the patterns are the same as those used for filename generation, see +@ref{Filename Generation}, but there is no special behaviour +of `@t{/}' nor initial dots, and no glob qualifiers are allowed. + +@noindent +In each of the above expressions, if +@var{file} is of the form `@t{/dev/fd/}@var{n}', +where @var{n} is an integer, +then the test applied to the open file whose +descriptor number is @var{n}, +even if the underlying system does not support +the @t{/dev/fd} directory. + +@noindent +In the forms which do numeric comparison, the expressions @var{exp} +undergo arithmetic expansion as if they were enclosed in +@t{$((}@var{...}@t{))}. + +@noindent +For example, the following: + +@noindent +@example +[[ ( -f foo || -f bar ) && $report = y* ]] && print File exists. +@end example + +@noindent +tests if either file @t{foo} or file @t{bar} exists, and if so, if the +value of the parameter @t{report} begins with `@t{y}'; if the complete +condition is true, the message `@t{File exists.}' is printed. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/prompt.yo +@node Prompt Expansion, Expansion, Conditional Expressions, Top + +@chapter Prompt Expansion +@noindent + +@section Expansion of Prompt Sequences +@noindent +@cindex prompt expansion +@cindex expansion, prompt +Prompt sequences undergo a special form of expansion. This type of expansion +is also available using the @t{-P} option to the @t{print} builtin. + +@noindent +@pindex PROMPT_SUBST, use of +If the @t{PROMPT_SUBST} option is set, the prompt string is first subjected to +@emph{parameter expansion}, +@emph{command substitution} and +@emph{arithmetic expansion}. +See +@ref{Expansion}. + +@noindent +Certain escape sequences may be recognised in the prompt string. + +@noindent +@pindex PROMPT_BANG, use of +If the @t{PROMPT_BANG} option is set, a `@t{!}' in the prompt is replaced +by the current history event number. A literal `@t{!}' may then be +represented as `@t{!!}'. + +@noindent +@pindex PROMPT_PERCENT, use of +If the @t{PROMPT_PERCENT} option is set, certain escape sequences that +start with `@t{%}' are expanded. +Many escapes are followed by a single character, although some of these +take an optional integer argument that +should appear between the `@t{%}' and the next character of the +sequence. More complicated escape sequences are available to provide +conditional expansion. + +@noindent + +@section Simple Prompt Escapes +@noindent + +@noindent + +@subsection Special characters +@noindent +@table @asis +@item @t{%%} +A `@t{%}'. + +@item @t{%)} +A `@t{)}'. + +@end table + +@noindent + +@subsection Login information +@noindent +@table @asis +@item @t{%l} +The line (tty) the user is logged in on, without `@t{/dev/}' prefix. +If the name starts with `@t{/dev/tty}', that prefix is stripped. + +@item @t{%M} +The full machine hostname. + +@item @t{%m} +The hostname up to the first `@t{.}'. +An integer may follow the `@t{%}' to specify +how many components of the hostname are desired. With a negative integer, +trailing components of the hostname are shown. + +@item @t{%n} +@t{$USERNAME}. + +@item @t{%y} +The line (tty) the user is logged in on, without `@t{/dev/}' prefix. +This does not treat `@t{/dev/tty}' names specially. + +@end table + +@noindent + +@subsection Shell state +@noindent +@table @asis +@item @t{%#} +A `@t{#}' if the shell is running with privileges, a `@t{%}' if not. +Equivalent to `@t{%(!.#.%%)}'. +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. + +@item @t{%?} +The return status of the last command executed just before the prompt. + +@item @t{%_} +The status of the parser, i.e. the shell constructs (like `@t{if}' and +`@t{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 @t{PS2} for +continuation lines and @t{PS4} for debugging with the @t{XTRACE} option; in +the latter case it will also work non-interactively. + +@item @t{%^} +The status of the parser in reverse. This is the same as `@t{%_}' other than +the order of strings. It is often used in @t{RPS2}. + +@item @t{%d} +@itemx @t{%/} +Current working directory. If an integer follows the `@t{%}', +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. @t{%-1d} specifies the first component. + +@item @t{%~} +As @t{%d} and @t{%/}, but if the current working directory starts with +@t{$HOME}, that part is replaced by a `@t{~}'. Furthermore, if it has a named +directory as its prefix, that part is replaced by a `@t{~}' followed by +the name of the directory, but only if the result is shorter than +the full path; +@ref{Filename Expansion}. + +@item @t{%e} +Evaluation depth of the current sourced file, shell function, or @t{eval}. +This is incremented or decremented every time the value of @t{%N} is +set or reverted to a previous value, respectively. This is most useful +for debugging as part of @t{$PS4}. + +@item @t{%h} +@itemx @t{%!} +Current history event number. + +@item @t{%i} +The line number currently being executed in the script, sourced file, or +shell function given by @t{%N}. This is most useful for debugging as part +of @t{$PS4}. + +@item @t{%I} +The line number currently being executed in the file @t{%x}. This is +similar to @t{%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. + +@item @t{%j} +The number of jobs. + +@item @t{%L} +The current value of @t{$SHLVL}. + +@item @t{%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 @t{$0}. An integer may follow +the `@t{%}' to specify a number of trailing path components to show; zero +means the full path. A negative integer specifies leading components. + +@item @t{%x} +The name of the file containing the source code currently being +executed. This behaves as @t{%N} except that function and eval command +names are not shown, instead the file where they were defined. + +@item @t{%c} +@itemx @t{%.} +@itemx @t{%C} +Trailing component of the current working directory. +An integer may follow the `@t{%}' to get more than one component. +Unless `@t{%C}' is used, tilde contraction is performed first. These are +deprecated as @t{%c} and @t{%C} are equivalent to @t{%1~} and @t{%1/}, +respectively, while explicit positive integers have the same effect as for +the latter two sequences. + +@end table + +@noindent + +@subsection Date and time +@noindent +@table @asis +@item @t{%D} +The date in @var{yy}@t{-}@var{mm}@t{-}@var{dd} format. + +@item @t{%T} +Current time of day, in 24-hour format. + +@item @t{%t} +@itemx @t{%@@} +Current time of day, in 12-hour, am/pm format. + +@item @t{%*} +Current time of day in 24-hour format, with seconds. + +@item @t{%w} +The date in @var{day}@t{-}@var{dd} format. + +@item @t{%W} +The date in @var{mm}@t{/}@var{dd}@t{/}@var{yy} format. + +@item @t{%D@{}@var{string}@t{@}} +@var{string} is formatted using the @t{strftime} function. +See strftime(3) for more details. Various zsh +extensions provide numbers with no leading zero or space +if the number is a single digit: + +@noindent +@table @asis +@item @t{%f} +a day of the month +@item @t{%K} +the hour of the day on the 24-hour clock +@item @t{%L} +the hour of the day on the 12-hour clock +@end table + +@noindent +In addition, if the system supports the POSIX @t{gettimeofday} system +call, @t{%.} 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 @t{%}; hence @t{%6.} +outputs microseconds, and @t{%9.} outputs nanoseconds. (The latter +requires a nanosecond-precision @t{clock_gettime}; systems lacking this +will return a value multiplied by the appropriate power of 10.) A typical +example of this is the format `@t{%D@{%H:%M:%S.%.@}}'. + +@noindent +The GNU extension @t{%N} is handled as a synonym for @t{%9.}. + +@noindent +Additionally, the GNU extension that a `@t{-}' between the @t{%} and the +format character causes a leading zero or space to be stripped +is handled directly by the shell for the format characters @t{d}, @t{f}, +@t{H}, @t{k}, @t{l}, @t{m}, @t{M}, @t{S} and @t{y}; any other format +characters are provided to the system's strftime(3) +with any leading `@t{-}' 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. + +@end table + +@noindent + +@subsection Visual effects +@noindent +@table @asis +@item @t{%B} (@t{%b}) +Start (stop) boldface mode. + +@item @t{%E} +Clear to end of line. + +@item @t{%U} (@t{%u}) +Start (stop) underline mode. + +@item @t{%S} (@t{%s}) +Start (stop) standout mode. + +@item @t{%F} (@t{%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 @t{%F}, for example @t{%F@{red@}}. In the latter case +the values allowed are as described for the @t{fg} @t{zle_highlight} +attribute; +@ref{Character Highlighting}. This means that numeric +colours are allowed in the second format also. + +@item @t{%K} (@t{%k}) +Start (stop) using a different bacKground colour. The syntax is +identical to that for @t{%F} and @t{%f}. + +@item @t{%@{}...@t{%@}} +Include a string as a literal escape sequence. +The string within the braces should not change the cursor +position. Brace pairs can nest. + +@noindent +A positive numeric argument between the @t{%} and the @t{@{} is treated as +described for @t{%G} below. + +@item @t{%G} +Within a @t{%@{}...@t{%@}} 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 @t{%@{}...@t{%@}} +sequence together with the appropriate number of @t{%G} sequences to +indicate the correct width. An integer between the `@t{%}' and `@t{G}' +indicates a character width other than one. Hence @t{%@{}@var{seq}@t{%2G%@}} +outputs @var{seq} and assumes it takes up the width of two standard +characters. + +@noindent +Multiple uses of @t{%G} accumulate in the obvious fashion; the position +of the @t{%G} is unimportant. Negative integers are not handled. + +@noindent +Note that when prompt truncation is in use it is advisable to divide up +output into single characters within each @t{%@{}...@t{%@}} group so that +the correct truncation point can be found. + +@end table + +@noindent + +@section Conditional Substrings in Prompts +@noindent +@table @asis +@item @t{%v} +@vindex psvar, use of +The value of the first element of the @t{psvar} array parameter. Following +the `@t{%}' with an integer gives that element of the array. Negative +integers count from the end of the array. + +@item @t{%(}@var{x}@t{.}@var{true-text}@t{.}@var{false-text}@t{)} +Specifies a ternary expression. The character following the @var{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 @var{true-text}, except as part of a +%-escape +sequence. A `@t{)}' may appear in the @var{false-text} as `@t{%)}'. +@var{true-text} +and @var{false-text} may both contain arbitrarily-nested escape +sequences, including further ternary expressions. + +@noindent +The left parenthesis may be preceded or followed by a positive integer @var{n}, +which defaults to zero. A negative integer will be multiplied by -1, except +as noted below for `@t{l}'. +The test character @var{x} may be any of the following: + +@noindent +@table @asis +@item @t{!} +True if the shell is running with privileges. +@item @t{#} +True if the effective uid of the current process is @var{n}. +@item @t{?} +True if the exit status of the last command was @var{n}. +@item @t{_} +True if at least @var{n} shell constructs were started. +@item @t{C} +@itemx @t{/} +True if the current absolute path has at least @var{n} elements +relative to the root directory, hence @t{/} is counted as 0 elements. +@item @t{c} +@itemx @t{.} +@itemx @t{~} +True if the current path, with prefix replacement, has at +least @var{n} elements relative to the root directory, hence @t{/} is +counted as 0 elements. +@item @t{D} +True if the month is equal to @var{n} (January = 0). +@item @t{d} +True if the day of the month is equal to @var{n}. +@item @t{e} +True if the evaluation depth is at least @var{n}. +@item @t{g} +True if the effective gid of the current process is @var{n}. +@item @t{j} +True if the number of jobs is at least @var{n}. +@item @t{L} +True if the @t{SHLVL} parameter is at least @var{n}. +@item @t{l} +True if at least @var{n} characters have already been +printed on the current line. When @var{n} is negative, true if at least +@t{abs}@t{(}@var{n}@t{)} characters remain before the opposite +margin (thus the left margin for @t{RPROMPT}). +@item @t{S} +True if the @t{SECONDS} parameter is at least @var{n}. +@item @t{T} +True if the time in hours is equal to @var{n}. +@item @t{t} +True if the time in minutes is equal to @var{n}. +@item @t{v} +True if the array @t{psvar} has at least @var{n} elements. +@item @t{V} +True if element @var{n} of the array @t{psvar} is set and +non-empty. +@item @t{w} +True if the day of the week is equal to @var{n} (Sunday = 0). +@end table + +@item @t{%<}@var{string}@t{<} +@itemx @t{%>}@var{string}@t{>} +@itemx @t{%[}@var{xstring}@t{]} +Specifies truncation behaviour for the remainder of the prompt string. +The third, deprecated, form is equivalent to `@t{%}@var{xstringx}', +i.e. @var{x} may be `@t{<}' or `@t{>}'. +The @var{string} will be displayed in +place of the truncated portion of any string; note this does not +undergo prompt expansion. + +@noindent +The numeric argument, which in the third form may appear immediately +after the `@t{[}', 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 @var{n} characters +remain before the right margin (left margin for @t{RPROMPT}). + +@noindent +The forms with `@t{<}' truncate at the left of the string, +and the forms with `@t{>}' truncate at the right of the string. +For example, if the current directory is `@t{/home/pike}', +the prompt `@t{%8<..<%/}' will expand to `@t{..e/pike}'. +In this string, the terminating character (`@t{<}', `@t{>}' or `@t{]}'), +or in fact any character, may be quoted by a preceding `@t{\}'; note +when using @t{print -P}, however, that this must be doubled as the +string is also subject to standard @t{print} processing, in addition +to any backslashes removed by a double quoted string: the worst case +is therefore `@t{print -P "%<\\\\<<..."}'. + +@noindent +If the @var{string} is longer than the specified truncation length, +it will appear in full, completely replacing the truncated string. + +@noindent +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 `@t{%(}' +construct, or to the next truncation encountered at the same grouping +level (i.e. truncations inside a `@t{%(}' are separate), which +ever comes first. In particular, a truncation with argument zero +(e.g., `@t{%<<}') marks the end of the range of the string to be +truncated while turning off truncation from there on. For example, the +prompt `@t{%10<...<%~%<<%# }' will print a truncated representation of the +current directory, followed by a `@t{%}' or `@t{#}', followed by a +space. Without the `@t{%<<}', those two characters would be included +in the string to be truncated. Note that `@t{%-0<<}' is not equivalent +to `@t{%<<}' but specifies that the prompt is truncated at the right margin. + +@noindent +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 +`@t{%-}@var{n}@t{(l.}@var{true-text}@t{.}@var{false-text}@t{)}' to remove parts +of the prompt when the available space is less than @var{n}. + +@end table +@c (avoiding a yodl bug) +@c Yodl file: Zsh/expn.yo +@node Expansion, Parameters, Prompt Expansion, Top + +@chapter Expansion +@noindent + +@cindex expansion +The following types of expansions are performed in the indicated order in +five steps: + +@noindent +@table @asis +@item @emph{History Expansion} +This is performed only in interactive shells. + +@item @emph{Alias Expansion} +Aliases are expanded immediately before the command line is parsed as +explained +in @ref{Aliasing}. + +@item @emph{Process Substitution} +@itemx @emph{Parameter Expansion} +@itemx @emph{Command Substitution} +@itemx @emph{Arithmetic Expansion} +@itemx @emph{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 `@t{\}',`@t{'}' and `@t{"}' are +removed. + +@item @emph{Filename Expansion} +If the @t{SH_FILE_EXPANSION} option is set, the order of expansion is +modified for compatibility with @cite{sh} and @cite{ksh}. In that case +@emph{filename expansion} is performed immediately after @emph{alias expansion}, +preceding the set of five expansions mentioned above. + +@cindex globbing +@item @emph{Filename Generation} +This expansion, commonly referred to as @cite{globbing}, is always done last. + +@end table + +@noindent +The following sections explain the types of expansion in detail. + +@noindent +@menu +* History Expansion:: +* Process Substitution:: +* Parameter Expansion:: +* Command Substitution:: +* Arithmetic Expansion:: +* Brace Expansion:: +* Filename Expansion:: +* Filename Generation:: +@end menu +@node History Expansion, Process Substitution, , Expansion + +@section History Expansion +@noindent +@cindex history +@cindex history expansion +@cindex expansion, history +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. + +@noindent +@vindex HISTSIZE, use of +Immediately before execution, each command is saved in the history list, +the size of which is controlled by the @t{HISTSIZE} parameter. The one +most recent command is always retained in any case. Each saved command in +the history list is called a history @emph{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 +@ref{Prompt Expansion}) is the number that is to be assigned to the @emph{next} command. + +@noindent +@menu +* Overview:: +* Event Designators:: +* Word Designators:: +* Modifiers:: +@end menu +@node Overview, Event Designators, , History Expansion + +@subsection Overview +@noindent +@vindex histchars, use of +A history expansion begins with the first character of the @t{histchars} +parameter, which is `@t{!}' by default, and may occur anywhere on the +command line, including inside double quotes (but not inside single quotes +@t{'...'} or C-style quotes @t{$'...'} nor when escaped with a backslash). + +@noindent +The first character is followed by an optional event designator +(@ref{Event Designators}) and then an optional word +designator (@ref{Word Designators}); if neither of these designators is +present, no history expansion occurs. + +@noindent +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. + +@noindent +History expansions do not nest. + +@noindent +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. +@pindex CSH_JUNKIE_HISTORY, use of +However, if the option @t{CSH_JUNKIE_HISTORY} is set, then every history +reference with no event specification @emph{always} refers to the previous +command. + +@noindent +For example, `@t{!}' is the event designator for the previous command, so +`@t{!!:1}' always refers to the first word of the previous command, and +`@t{!!$}' always refers to the last word of the previous command. With +@t{CSH_JUNKIE_HISTORY} set, then `@t{!:1}' and `@t{!$}' function in the +same manner as `@t{!!:1}' and `@t{!!$}', respectively. Conversely, if +@t{CSH_JUNKIE_HISTORY} is unset, then `@t{!:1}' and `@t{!$}' 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. + +@noindent +The character sequence `@t{^}@var{foo}@t{^}@var{bar}' (where `@t{^}' is +actually the second character of the @t{histchars} parameter) +repeats the last command, replacing the string @var{foo} with @var{bar}. +More precisely, the sequence `@t{^}@var{foo}@t{^}@var{bar}@t{^}' is +synonymous with `@t{!!:s}@t{^}@var{foo}@t{^}@var{bar}@t{^}', hence other +modifiers (see @ref{Modifiers}) may follow the final `@t{^}'. +In particular, `@t{^}@var{foo}@t{^}@var{bar}@t{^:G}' performs a global +substitution. + +@noindent +If the shell encounters the character sequence `@t{!"}' +in the input, the history mechanism is temporarily disabled until +the current list (see +@ref{Shell Grammar}) is fully parsed. The `@t{!"}' is removed from the input, and any +subsequent `@t{!}' characters have no special significance. + +@noindent +@findex fc, use of +A less convenient but more comprehensible form of command history support +is provided by the @t{fc} builtin. +@node Event Designators, Word Designators, Overview, History Expansion + +@subsection Event Designators +@noindent +@cindex history event designators +@cindex event designators, history +An event designator is a reference to a command-line entry in the history +list. In the list below, remember that the initial @t{`!'} in each item +may be changed to another character by setting the @t{histchars} +parameter. + +@noindent +@table @asis +@item @t{!} +Start a history expansion, except when followed by a blank, newline, +`@t{=}' or `@t{(}'. If followed immediately by a word designator +(@ref{Word Designators}), this forms a history reference +with no event designator (@ref{Overview}). + +@item @t{!!} +Refer to the previous command. +By itself, this expansion +repeats the previous command. + +@item @t{!}@var{n} +Refer to command-line @var{n}. + +@item @t{!-}@var{n} +Refer to the current command-line minus @var{n}. + +@item @t{!}@var{str} +Refer to the most recent command starting with @var{str}. + +@item @t{!?}@var{str}[@t{?}] +Refer to the most recent command containing @var{str}. The trailing +`@t{?}' 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 @var{str}. + +@item @t{!#} +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 `@t{!#}' reference. + +@item @t{!@{}...@t{@}} +Insulate a history reference from adjacent characters (if necessary). + +@end table +@node Word Designators, Modifiers, Event Designators, History Expansion + +@subsection Word Designators +@noindent +@cindex history word designators +@cindex word designators, history +A word designator indicates which word or words of a given command line are +to be included in a history reference. A `@t{:}' usually +separates the event specification from the word designator. +It may be omitted only if the word designator begins with a +`@t{^}', `@t{$}', `@t{*}', `@t{-}' or `@t{%}'. +Word designators include: + +@noindent +@table @asis +@item @t{0} +The first input word (command). +@item @var{n} +The @var{n}th argument. +@item @t{^} +The first argument. That is, @t{1}. +@item @t{$} +The last argument. +@item @t{%} +The word matched by (the most recent) @t{?}@var{str} search. +@item @var{x}@t{-}@var{y} +A range of words; @var{x} defaults to @t{0}. +@item @t{*} +All the arguments, or a null value if there are none. +@item @var{x}@t{*} +Abbreviates `@var{x}@t{-$}'. +@item @var{x}@t{-} +Like `@var{x}@t{*}' but omitting word @t{$}. +@end table + +@noindent +Note that a `@t{%}' word designator works only when used in one of +`@t{!%}', `@t{!:%}' or `@t{!?}@var{str}@t{?:%}', and only when used after a +@t{!?} expansion (possibly in an earlier command). Anything else results +in an error, although the error may not be the most obvious one. +@node Modifiers, , Word Designators, History Expansion + +@subsection Modifiers +@noindent +@cindex modifiers +@cindex colon modifiers +@cindex history modifiers +@cindex globbing modifiers +@cindex parameter modifiers +After the optional word designator, you can add +a sequence of one or more of the following modifiers, +each preceded by a `@t{:}'. These modifiers also work on the result +of @emph{filename generation} and @emph{parameter expansion}, except where +noted. + +@noindent +@table @asis +@item @t{a} +Turn a file name into an absolute path: prepends the current directory, +if necessary; remove `@t{.}' path segments; and remove `@t{..}' path segments +and the segments that immediately precede them. + +@noindent +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 +@t{CHASE_DOTS} or @t{CHASE_LINKS} is set. For example, +`@t{/before/here/../after}' is always transformed to +`@t{/before/after}', regardless of whether `@t{/before/here}' exists or what +kind of object (dir, file, symlink, etc.) it is. + +@item @t{A} +Turn a file name into an absolute path as the `@t{a}' modifier does, and +@emph{then} pass the result through the @t{realpath(3)} library +function to resolve symbolic links. + +@noindent +Note: on systems that do not have a @t{realpath(3)} library +function, symbolic links are not resolved, so on those systems `@t{a}' and +`@t{A}' are equivalent. + +@noindent +Note: @t{foo:A} and @t{realpath(foo)} are different on some inputs. +For @t{realpath(foo)} semantics, see the `@t{P}` modifier. + +@item @t{c} +Resolve a command name into an absolute path by searching the command +path given by the @t{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. + +@item @t{e} +Remove all but the part of the filename extension following the `@t{.}'; +see the definition of the filename extension in the description of the +@t{r} modifier below. Note that according to that definition the result +will be empty if the string ends with a `@t{.}'. + +@item @t{h} [ @var{digits} ] +Remove a trailing pathname component, shortening the path by one +directory level: this is the `head' of the pathname. This works like +`@t{dirname}'. If the @t{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 `@t{/}' is the first component, so, +for example, if @t{var=/my/path/to/something}, then @t{$@{var:h3@}} +substitutes @t{/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 @t{$var:h2} is treated as @t{$@{var:h@}2}, not as +@t{$@{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). + +@item @t{l} +Convert the words to all lowercase. + +@item @t{p} +Print the new command but do not execute it. Only works with history +expansion. + +@item @t{P} +Turn a file name into an absolute path, like @t{realpath(3)}. +The resulting path will be absolute, +will refer to the same directory entry as the input filename, +and none of its components will be symbolic links or equal to +`@t{.}' or `@t{..}'. + +@noindent +Unlike @t{realpath(3)}, non-existent trailing components are +permitted and preserved. + +@item @t{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 @t{eval}. + +@item @t{Q} +Remove one level of quotes from the substituted words. + +@item @t{r} +Remove a filename extension leaving the root name. Strings with no +filename extension are not altered. A filename +extension is a `@t{.}' followed by any number of characters (including +zero) that are neither `@t{.}' nor `@t{/}' and that continue to the end +of the string. For example, the extension of +`@t{foo.orig.c}' is `@t{.c}', and `@t{dir.c/foo}' has no extension. + +@item @t{s/}@var{l}@t{/}@var{r}[@t{/}] +Substitute @var{r} for @var{l} as described below. +The substitution is done only for the +first string that matches @var{l}. For arrays and for filename +generation, this applies to each word of the expanded text. See +below for further notes on substitutions. + +@noindent +The forms `@t{gs/}@var{l}@t{/}@var{r}' and `@t{s/}@var{l}@t{/}@var{r}@t{/:G}' +perform global substitution, i.e. substitute every occurrence of @var{r} +for @var{l}. Note that the @t{g} or @t{:G} must appear in exactly the +position shown. + +@noindent +See further notes on this form of substitution below. + +@item @t{&} +Repeat the previous @t{s} substitution. Like @t{s}, may be preceded +immediately by a @t{g}. In parameter expansion the @t{&} must appear +inside braces, and in filename generation it must be quoted with a +backslash. + +@item @t{t} [ @var{digits} ] +Remove all leading pathname components, leaving the final component (tail). +This works like `@t{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. + +@item @t{u} +Convert the words to all uppercase. + +@item @t{x} +Like @t{q}, but break into words at whitespace. Does not work with +parameter expansion. + +@end table + +@noindent +The @t{s/}@var{l}@t{/}@var{r}@t{/} 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 `@t{/}'. A backslash quotes the delimiter character. The character +`@t{&}', in the right-hand-side @var{r}, is replaced by the text from the +left-hand-side @var{l}. The `@t{&}' can be quoted with a backslash. A +null @var{l} uses the previous string either from the previous @var{l} or +from the contextual scan string @var{s} from `@t{!?}@var{s}'. You can +omit the rightmost delimiter if a newline immediately follows @var{r}; +the rightmost `@t{?}' in a context scan can similarly be omitted. Note +the same record of the last @var{l} and @var{r} is maintained across all +forms of expansion. + +@noindent +Note that if a `@t{&}' is used within glob qualifiers an extra backslash +is needed as a @t{&} is a special character in this case. + +@noindent +Also note that the order of expansions affects the interpretation of +@var{l} and @var{r}. When used in a history expansion, which occurs before +any other expansions, @var{l} and @var{r} are treated as literal strings +(except as explained for @t{HIST_SUBST_PATTERN} below). When used in +parameter expansion, the replacement of @var{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 @var{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 `@t{:s}' expression itself is divided into +@var{l} and @var{r} sides. + +@noindent +If the option @t{HIST_SUBST_PATTERN} is set, @var{l} is treated as +a pattern of the usual form described in +@ref{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 +@t{(#q:s/}@var{...}@t{/}@var{...}@t{/)} 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 @t{NO_BAD_PATTERN} option so will cause an error. + +@noindent +When @t{HIST_SUBST_PATTERN} is set, @var{l} may start with a @t{#} +to indicate that the pattern must match at the start of the string +to be substituted, and a @t{%} may appear at the start or after an @t{#} +to indicate that the pattern must match at the end of the string +to be substituted. The @t{%} or @t{#} may be quoted with two +backslashes. + +@noindent +For example, the following piece of filename generation code +with the @t{EXTENDED_GLOB} option: + +@noindent +@example +print -r -- *.c(#q:s/#%(#b)s(*).c/'S$@{match[1]@}.C'/) +@end example + +@noindent +takes the expansion of @t{*.c} and applies the glob qualifiers in the +@t{(#q}@var{...}@t{)} expression, which consists of a substitution +modifier anchored to the start and end of each word (@t{#%}). This +turns on backreferences (@t{(#b)}), so that the parenthesised +subexpression is available in the replacement string as @t{$@{match[1]@}}. +The replacement string is quoted so that the parameter is not substituted +before the start of filename generation. + +@noindent +The following @t{f}, @t{F}, @t{w} and @t{W} modifiers work only with +parameter expansion and filename generation. They are listed here to +provide a single point of reference for all modifiers. + +@noindent +@table @asis +@item @t{f} +Repeats the immediately (without a colon) following modifier until the +resulting word doesn't change any more. + +@item @t{F:}@var{expr}@t{:} +Like @t{f}, but repeats only @var{n} times if the expression +@var{expr} evaluates to @var{n}. Any character can be used instead of +the `@t{:}'; if `@t{(}', `@t{[}', or `@t{@{}' +is used as the opening delimiter, +the closing delimiter should be '@t{)}', `@t{]}', or `@t{@}}', +respectively. + +@item @t{w} +Makes the immediately following modifier work on each word in the +string. + +@item @t{W:}@var{sep}@t{:} +Like @t{w} but words are considered to be the parts of the string +that are separated by @var{sep}. Any character can be used instead of +the `@t{:}'; opening parentheses are handled specially, see above. + +@end table +@node Process Substitution, Parameter Expansion, History Expansion, Expansion + +@section Process Substitution +@noindent +@cindex process substitution +@cindex substitution, process +Each part of a command argument that takes the form +`@t{<(}@var{list}@t{)}', +`@t{>(}@var{list}@t{)}' or +`@t{=(}@var{list}@t{)}' +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. + +@noindent +Note that `@t{<<(}@var{list}@t{)}' is not a special syntax; it +is equivalent to `@t{< <(}@var{list}@t{)}', 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. + +@noindent +In the case of the @t{<} or @t{>} forms, the shell runs the commands in +@var{list} as a subprocess of the job executing the shell command line. +If the system supports the @t{/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 +@t{>} is selected then writing on this special file will provide input for +@var{list}. If @t{<} is used, then the file passed as an argument will +be connected to the output of the @var{list} process. For example, + +@noindent +@example +@t{paste <(cut -f1} @var{file1}@t{) <(cut -f3} @var{file2}@t{) | +tee >(}@var{process1}@t{) >(}@var{process2}@t{) >/dev/null} +@end example + +@noindent +cuts fields 1 and 3 from the files @var{file1} and @var{file2} respectively, +pastes the results together, and sends it to the processes +@var{process1} and @var{process2}. + +@noindent +If @t{=(}@var{...}@t{)} is used instead of +@t{<(}@var{...}@t{)}, +then the file passed as an argument will be the name +of a temporary file containing the output of the @var{list} +process. This may be used instead of the @t{<} +form for a program that expects to lseek (see lseek(2)) +on the input file. + +@noindent +There is an optimisation for substitutions of the form +@t{=(<<<}@var{arg}@t{)}, where @var{arg} is a single-word argument +to the here-string redirection @t{<<<}. This form produces a file name +containing the value of @var{arg} after any substitutions have been +performed. This is handled entirely within the current shell. This is +effectively the reverse of the special form @t{$(<}@var{arg}@t{)} +which treats @var{arg} as a file name and replaces it with the file's +contents. + +@noindent +The @t{=} form is useful as both the @t{/dev/fd} and the named pipe +implementation of @t{<(}@var{...}@t{)} 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 lseek(2)) on the file will not work. + +@noindent +Also note that the previous example can be more compactly and +efficiently written (provided the @t{MULTIOS} option is set) as: + +@noindent +@example +@t{paste <(cut -f1} @var{file1}@t{) <(cut -f3} @var{file2}@t{)} @t{> >(}@var{process1}@t{) > >(}@var{process2}@t{)} +@end example + +@noindent +The shell uses pipes instead of FIFOs to implement the latter +two process substitutions in the above example. + +@noindent +There is an additional problem with @t{>(}@var{process}@t{)}; when +this is attached to an external command, the parent shell does not wait +for @var{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 @emph{MULTIOS} in +@ref{Redirection}. Hence in a simplified +version of the example above: + +@noindent +@example +@t{paste <(cut -f1} @var{file1}@t{) <(cut -f3} @var{file2}@t{)} @t{> >(}@var{process}@t{)} +@end example + +@noindent +(note that no @t{MULTIOS} are involved), @var{process} will be run +asynchronously as far as the parent shell is concerned. The workaround is: + +@noindent +@example +@t{@{ paste <(cut -f1} @var{file1}@t{) <(cut -f3} @var{file2}@t{) @}} @t{> >(}@var{process}@t{)} +@end example + +@noindent +The extra processes here are +spawned from the parent shell which will wait for their completion. + +@noindent +Another problem arises any time a job with a substitution that requires +a temporary file is disowned by the shell, including the case where +`@t{&!}' or `@t{&|}' 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, + +@noindent +@example +(mycmd =(myoutput)) &! +@end example + +@noindent +as the forked subshell will wait for the command to finish then remove +the temporary file. + +@noindent +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: + +@noindent +@example +() @{ + print File $1: + cat $1 +@} =(print This be the verse) +@end example + +@noindent +outputs something resembling the following + +@noindent +@example +File /tmp/zsh6nU0kS: +This be the verse +@end example + +@noindent +The temporary file created by the process substitution will be deleted +when the function exits. + +@noindent +@node Parameter Expansion, Command Substitution, Process Substitution, Expansion + +@section Parameter Expansion +@noindent +@cindex parameter expansion +@cindex expansion, parameter +The character `@t{$}' is used to introduce parameter expansions. +See +@ref{Parameters} +for a description of parameters, including arrays, associative arrays, +and subscript notation to access individual array elements. + +@noindent +Note in particular the fact that words of unquoted parameters are not +automatically split on whitespace unless the option @t{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. + +@noindent +With default options, after the assignments: + +@noindent +@example +array=("first word" "" "third word") +scalar="only word" +@end example + +@noindent +then @t{$array} substitutes two words, `@t{first word}' and `@t{third +word}', and @t{$scalar} substitutes a single word `@t{only word}'. Note +that second element of @t{array} was elided. Scalar parameters can +be elided too if their value is null (empty). To avoid elision, use quoting as +follows: @t{"$scalar"} for scalars and @t{"$@{array[@@]@}"} or @t{"$@{(@@)array@}"} +for arrays. (The last two forms are equivalent.) + +@noindent +Parameter expansions can involve @emph{flags}, as in `@t{$@{(@@kv)aliases@}}', +and other operators, such as `@t{$@{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. + +@noindent +In the expansions discussed below that require a pattern, the form of +the pattern is the same as that used for filename generation; +see @ref{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 +@ref{Modifiers} in @ref{History Expansion} can be +applied: for example, @t{$@{i:s/foo/bar/@}} performs string +substitution on the expansion of parameter @t{$i}. + +@noindent +In the following descriptions, `@var{word}' refers to a single word +substituted on the command line, not necessarily a space delimited word. + +@noindent +@table @asis +@item @t{$@{}@var{name}@t{@}} +The value, if any, of the parameter @var{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 @var{name}. In addition, more complicated forms of substitution +usually require the braces to be present; exceptions, which only apply if +the option @t{KSH_ARRAYS} is not set, are a single subscript or any colon +modifiers appearing after the name, or any of the characters `@t{^}', +`@t{=}', `@t{~}', `@t{#}' or `@t{+}' appearing before the name, all of +which work with or without braces. + +@noindent +If @var{name} is an array parameter, and the @t{KSH_ARRAYS} option is not +set, then the value of each +element of @var{name} is substituted, one element per word. Otherwise, the +expansion results in one word only; with @t{KSH_ARRAYS}, this is the first +element of an array. No field splitting is done on the result unless the +@t{SH_WORD_SPLIT} option is set. +See also the flags @t{=} and @t{s:}@var{string}@t{:}. + +@item @t{$@{+}@var{name}@t{@}} +If @var{name} is the name of a set parameter `@t{1}' is substituted, +otherwise `@t{0}' is substituted. + +@item @t{$@{}@var{name}@t{-}@var{word}@t{@}} +@itemx @t{$@{}@var{name}@t{:-}@var{word}@t{@}} +If @var{name} is set, or in the second form is non-null, then substitute +its value; otherwise substitute @var{word}. In the second form @var{name} +may be omitted, in which case @var{word} is always substituted. + +@item @t{$@{}@var{name}@t{+}@var{word}@t{@}} +@itemx @t{$@{}@var{name}@t{:+}@var{word}@t{@}} +If @var{name} is set, or in the second form is non-null, then substitute +@var{word}; otherwise substitute nothing. + +@item @t{$@{}@var{name}@t{=}@var{word}@t{@}} +@itemx @t{$@{}@var{name}@t{:=}@var{word}@t{@}} +@itemx @t{$@{}@var{name}@t{::=}@var{word}@t{@}} +In the first form, if @var{name} is unset then set it to @var{word}; in the +second form, if @var{name} is unset or null then set it to @var{word}; and +in the third form, unconditionally set @var{name} to @var{word}. In all +forms, the value of the parameter is then substituted. + +@item @t{$@{}@var{name}@t{?}@var{word}@t{@}} +@itemx @t{$@{}@var{name}@t{:?}@var{word}@t{@}} +In the first form, if @var{name} is set, or in the second form if @var{name} +is both set and non-null, then substitute its value; otherwise, print +@var{word} and exit from the shell. Interactive shells instead return to +the prompt. If @var{word} is omitted, then a standard message is printed. + +@end table + +@noindent +In any of the above expressions that test a variable and substitute an +alternate @var{word}, note that you can use standard shell quoting in the +@var{word} value to selectively override the splitting done by the +@t{SH_WORD_SPLIT} option and the @t{=} flag, but not splitting by the +@t{s:}@var{string}@t{:} flag. + +@noindent +In the following expressions, when @var{name} is an array and +the substitution is not quoted, or if the `@t{(@@)}' flag or the +@var{name}@t{[@@]} syntax is used, matching and replacement is +performed on each array element separately. + +@noindent +@table @asis +@item @t{$@{}@var{name}@t{#}@var{pattern}@t{@}} +@itemx @t{$@{}@var{name}@t{##}@var{pattern}@t{@}} +If the @var{pattern} matches the beginning of the value of +@var{name}, then substitute the value of @var{name} with +the matched portion deleted; otherwise, just +substitute the value of @var{name}. In the first +form, the smallest matching pattern is preferred; +in the second form, the largest matching pattern is +preferred. + +@item @t{$@{}@var{name}@t{%}@var{pattern}@t{@}} +@itemx @t{$@{}@var{name}@t{%%}@var{pattern}@t{@}} +If the @var{pattern} matches the end of the value of +@var{name}, then substitute the value of @var{name} with +the matched portion deleted; otherwise, just +substitute the value of @var{name}. In the first +form, the smallest matching pattern is preferred; +in the second form, the largest matching pattern is +preferred. + +@item @t{$@{}@var{name}@t{:#}@var{pattern}@t{@}} +If the @var{pattern} matches the value of @var{name}, then substitute +the empty string; otherwise, just substitute the value of @var{name}. +If @var{name} is an array +the matching array elements are removed (use the `@t{(M)}' flag to +remove the non-matched elements). + +@item @t{$@{}@var{name}@t{:|}@var{arrayname}@t{@}} +If @var{arrayname} is the name (N.B., not contents) of an array +variable, then any elements contained in @var{arrayname} are removed +from the substitution of @var{name}. If the substitution is scalar, +either because @var{name} is a scalar variable or the expression is +quoted, the elements of @var{arrayname} are instead tested against the +entire expression. + +@item @t{$@{}@var{name}@t{:*}@var{arrayname}@t{@}} +Similar to the preceding substitution, but in the opposite sense, +so that entries present in both the original substitution and as +elements of @var{arrayname} are retained and others removed. + +@item @t{$@{}@var{name}@t{:^}@var{arrayname}@t{@}} +@itemx @t{$@{}@var{name}@t{:^^}@var{arrayname}@t{@}} +Zips two arrays, such that the output array is twice as long as the +shortest (longest for `@t{:^^}') of @t{name} and @t{arrayname}, with +the elements alternatingly being picked from them. For `@t{:^}', if one +of the input arrays is longer, the output will stop when the end of the +shorter array is reached. Thus, + +@noindent +@example +a=(1 2 3 4); b=(a b); print $@{a:^b@} +@end example + +@noindent +will output `@t{1 a 2 b}'. For `@t{:^^}', then the input is repeated +until all of the longer array has been used up and the above will output +`@t{1 a 2 b 3 a 4 b}'. + +@noindent +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. + +@noindent +Currently the following code will output `@t{a b}' and `@t{1}' as two separate +elements, which can be unexpected. The second print provides a workaround which +should continue to work if this is changed. + +@noindent +@example +a=(a b); b=(1 2); print -l "$@{a:^b@}"; print -l "$@{$@{a:^b@}@}" +@end example + +@item @t{$@{}@var{name}@t{:}@var{offset}@t{@}} +@itemx @t{$@{}@var{name}@t{:}@var{offset}@t{:}@var{length}@t{@}} +This syntax gives effects similar to parameter subscripting +in the form @t{$}@var{name}@t{[}@var{start}@t{,}@var{end}@t{]}, but is +compatible with other shells; note that both @var{offset} and @var{length} +are interpreted differently from the components of a subscript. + +@noindent +If @var{offset} is non-negative, then if the variable @var{name} is a +scalar substitute the contents starting @var{offset} characters from the +first character of the string, and if @var{name} is an array substitute +elements starting @var{offset} elements from the first element. If +@var{length} is given, substitute that many characters or elements, +otherwise the entire rest of the scalar or array. + +@noindent +A positive @var{offset} is always treated as the offset of a character or +element in @var{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 @t{KSH_ARRAYS}. + +@noindent +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. + +@noindent +When positive, @var{length} counts from the @var{offset} position +toward the end of the scalar or array. When negative, @var{length} +counts back from the end. If this results in a position smaller +than @var{offset}, a diagnostic is printed and nothing is substituted. + +@noindent +The option @t{MULTIBYTE} is obeyed, i.e. the offset and length +count multibyte characters where appropriate. + +@noindent +@var{offset} and @var{length} undergo the same set of shell substitutions +as for scalar assignment; in addition, they are then subject to arithmetic +evaluation. Hence, for example + +@noindent +@example +print $@{foo:3@} +print $@{foo: 1 + 2@} +print $@{foo:$(( 1 + 2))@} +print $@{foo:$(echo 1 + 2)@} +@end example + +@noindent +all have the same effect, extracting the string starting at the fourth +character of @t{$foo} if the substitution would otherwise return a scalar, +or the array starting at the fourth element if @t{$foo} would return an +array. Note that with the option @t{KSH_ARRAYS} @t{$foo} always returns +a scalar (regardless of the use of the offset syntax) and a form +such as @t{$@{foo[*]:3@}} is required to extract elements of an array named +@t{foo}. + +@noindent +If @var{offset} is negative, the @t{-} may not appear immediately +after the @t{:} as this indicates the +@t{$@{}@var{name}@t{:-}@var{word}@t{@}} form of substitution. Instead, a space +may be inserted before the @t{-}. Furthermore, neither @var{offset} nor +@var{length} may begin with an alphabetic character or @t{&} 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 @t{$} as this +signifies the intention (parameter substitution can easily be rendered +unreadable); however, as arithmetic substitution is performed, the +expression @t{$@{var: offs@}} does work, retrieving the offset from +@t{$offs}. + +@noindent +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. @t{$@@} or @t{$*}, then offset 0 +instead refers to @t{$0}, offset 1 refers to @t{$1}, and so on. In +other words, the positional parameter array is effectively extended by +prepending @t{$0}. Hence @t{$@{*:0:1@}} substitutes @t{$0} and +@t{$@{*:1:1@}} substitutes @t{$1}. + +@item @t{$@{}@var{name}@t{/}@var{pattern}@t{/}@var{repl}@t{@}} +@itemx @t{$@{}@var{name}@t{//}@var{pattern}@t{/}@var{repl}@t{@}} +@itemx @t{$@{}@var{name}@t{:/}@var{pattern}@t{/}@var{repl}@t{@}} +Replace the longest possible match of @var{pattern} in the expansion of +parameter @var{name} by string @var{repl}. The first form +replaces just the first occurrence, the second form all occurrences, +and the third form replaces only if @var{pattern} matches the entire string. +Both @var{pattern} and @var{repl} are subject to double-quoted substitution, +so that expressions like @t{$@{name/$opat/$npat@}} will work, but obey the +usual rule that pattern characters in @t{$opat} are not treated specially +unless either the option @t{GLOB_SUBST} is set, or @t{$opat} is instead +substituted as @t{$@{~opat@}}. + +@noindent +The @var{pattern} may begin with a `@t{#}', in which case the +@var{pattern} must match at the start of the string, or `@t{%}', in +which case it must match at the end of the string, or `@t{#%}' in which +case the @var{pattern} must match the entire string. The @var{repl} may +be an empty string, in which case the final `@t{/}' may also be omitted. +To quote the final `@t{/}' in other cases it should be preceded by a +single backslash; this is not necessary if the +`@t{/}' occurs inside a substituted parameter. Note also that the `@t{#}', +`@t{%}' and `@t{#%} are not active if they occur inside a substituted +parameter, even at the start. + +@noindent +If, after quoting rules apply, @t{$@{}@var{name}@t{@}} expands to an array, +the replacements act on each element individually. Note also the +effect of the @t{I} and @t{S} parameter expansion flags below; however, +the flags @t{M}, @t{R}, @t{B}, @t{E} and @t{N} are not useful. + +@noindent +For example, + +@noindent +@example +foo="twinkle twinkle little star" sub="t*e" rep="spy" +print $@{foo//$@{~sub@}/$rep@} +print $@{(S)foo//$@{~sub@}/$rep@} +@end example + +@noindent +Here, the `@t{~}' ensures that the text of @t{$sub} is treated as a +pattern rather than a plain string. In the first case, the longest +match for @t{t*e} is substituted and the result is `@t{spy star}', +while in the second case, the shortest matches are taken and the +result is `@t{spy spy lispy star}'. + +@item @t{$@{#}@var{spec}@t{@}} +If @var{spec} is one of the above substitutions, substitute +the length in characters of the result instead of +the result itself. If @var{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 @var{spec}. +Note that `@t{^}', `@t{=}', and `@t{~}', below, must appear +to the left of `@t{#}' when these forms are combined. + +@noindent +If the option @t{POSIX_IDENTIFIERS} is not set, and @var{spec} is a +simple name, then the braces are optional; this is true even +for special parameters so e.g. @t{$#-} and @t{$#*} take the length +of the string @t{$-} and the array @t{$*} respectively. If +@t{POSIX_IDENTIFIERS} is set, then braces are required for +the @t{#} to be treated in this fashion. + +@item @t{$@{^}@var{spec}@t{@}} +@itemx @t{$@{^^}@var{spec}@t{@}} +@pindex RC_EXPAND_PARAM, toggle +@cindex array expansion style, rc +@cindex rc, array expansion style +Turn on the @t{RC_EXPAND_PARAM} option for the +evaluation of @var{spec}; if the `@t{^}' is doubled, turn it off. +When this option is set, array expansions of the form +@var{foo}@t{$@{}@var{xx}@t{@}}@var{bar}, +where the parameter @var{xx} +is set to @t{(}@var{a b c}@t{)}, are substituted with +`@var{fooabar foobbar foocbar}' instead of the default +`@var{fooa b cbar}'. Note that an empty array will therefore cause +all arguments to be removed. + +@noindent +Internally, each such expansion is converted into the +equivalent list for brace expansion. E.g., @t{$@{^var@}} becomes +@t{@{$var[1],$var[2],}...@t{@}}, and is processed as described in +@ref{Brace Expansion} below: note, however, the expansion +happens immediately, with any explicit brace expansion +happening later. If word splitting is also in effect the +@t{$var[}@var{N}@t{]} may themselves be split into different list +elements. + +@item @t{$@{=}@var{spec}@t{@}} +@itemx @t{$@{==}@var{spec}@t{@}} +@pindex SH_WORD_SPLIT, toggle +@cindex field splitting, sh style, parameter +@cindex sh, field splitting style, parameter +Perform word splitting using the rules for @t{SH_WORD_SPLIT} during the +evaluation of @var{spec}, but regardless of whether the parameter appears in +double quotes; if the `@t{=}' is doubled, turn it off. +@vindex IFS, use of +This forces parameter expansions to be split into +separate words before substitution, using @t{IFS} as a delimiter. +This is done by default in most other shells. + +@noindent +Note that splitting is applied to @var{word} in the assignment forms +of @var{spec} @emph{before} the assignment to @var{name} is performed. +This affects the result of array assignments with the @t{A} flag. + +@item @t{$@{~}@var{spec}@t{@}} +@itemx @t{$@{~~}@var{spec}@t{@}} +@pindex GLOB_SUBST, toggle +Turn on the @t{GLOB_SUBST} option for the evaluation of +@var{spec}; if the `@t{~}' 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 `@t{=}' and `@t{!=}' operators in conditions. + +@noindent +In nested substitutions, note that the effect of the @t{~} 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 @t{foo} is set to @t{*}, @t{$@{~foo//\*/*.c@}} is substituted by +the pattern @t{*.c}, which may be expanded by filename generation, but +@t{$@{$@{~foo@}//\*/*.c@}} substitutes to the string @t{*.c}, which will not +be further expanded. + +@end table + +@noindent +If a @t{$@{}...@t{@}} type parameter expression or a +@t{$(}...@t{)} type command substitution is used in place of +@var{name} above, it is expanded first and the result is used as if +it were the value of @var{name}. Thus it is +possible to perform nested operations: @t{$@{$@{foo#head@}%tail@}} +substitutes the value of @t{$foo} with both `@t{head}' and `@t{tail}' +deleted. The form with @t{$(}...@t{)} is often useful in +combination with the flags described next; see the examples below. +Each @var{name} or nested @t{$@{}...@t{@}} in a parameter expansion may +also be followed by a subscript expression as described in +@ref{Array Parameters}. + +@noindent +Note that double quotes may appear around nested expressions, in which +case only the part inside is treated as quoted; for example, +@t{$@{(f)"$(foo)"@}} quotes the result of @t{$(foo)}, but the flag `@t{(f)}' +(see below) is applied using the rules for unquoted expansions. Note +further that quotes are themselves nested in this context; for example, in +@t{"$@{(@@f)"$(foo)"@}"}, there are two sets of quotes, one surrounding the +whole expression, the other (redundant) surrounding the @t{$(foo)} as +before. + +@noindent + +@subsection Parameter Expansion Flags +@noindent +@cindex parameter expansion flags +@cindex flags, parameter expansion +@cindex substitution, parameter, 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, `(@t{q%q%q})' +means the same thing as the more readable `(@t{%%qqq})'. The +following flags are supported: + +@noindent +@table @asis +@item @t{#} +Evaluate the resulting words as numeric expressions and interpret +these as character codes. Output the corresponding characters. Note +that this form is entirely distinct from use of the @t{#} without +parentheses. + +@noindent +If the @t{MULTIBYTE} option is set and the number is greater than 127 +(i.e. not an ASCII character) it is treated as a Unicode character. + +@item @t{%} +Expand all @t{%} escapes in the resulting words in the same way as in +prompts (see +@ref{Prompt Expansion}). If this flag is given twice, +full prompt expansion is done on the resulting words, depending on the +setting of the @t{PROMPT_PERCENT}, @t{PROMPT_SUBST} and @t{PROMPT_BANG} +options. + +@item @t{@@} +In double quotes, array elements are put into separate words. +E.g., `@t{"$@{(@@)foo@}"}' is equivalent to `@t{"$@{foo[@@]@}"}' and +`@t{"$@{(@@)foo[1,2]@}"}' is the same as `@t{"$foo[1]" "$foo[2]"}'. +This is distinct from @emph{field splitting} by the @t{f}, @t{s} +or @t{z} flags, which still applies within each array element. + +@item @t{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 @t{$@{$@{(A}@t{)}@var{name}@t{@}[1]@}} +yields the full value of @var{name} when @var{name} is scalar. + +@noindent +This assigns an array parameter with `@t{$@{}...@t{=}...@t{@}}', +`@t{$@{}...@t{:=}...@t{@}}' or `@t{$@{}...@t{::=}...@t{@}}'. +If this flag is repeated (as in `@t{AA}'), assigns an associative +array parameter. Assignment is made before sorting or padding; +if field splitting is active, the @var{word} part is split before +assignment. The @var{name} part may be a subscripted range for +ordinary arrays; when assigning an associative array, the @var{word} +part @emph{must} be converted to an array, for example by using +`@t{$@{(AA)=}@var{name}@t{=}...@t{@}}' to activate field splitting. + +@noindent +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. + +@item @t{a} +Sort in array index order; when combined with `@t{O}' sort in reverse +array index order. Note that `@t{a}' is therefore equivalent to the +default but `@t{Oa}' is useful for obtaining an array's elements in reverse +order. + +@item @t{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 @t{GLOB_SUBST}, including the @t{$@{~}@var{...}@t{@}} switch. + +@noindent +Quoting using one of the @t{q} family of flags does not work +for this purpose since quotes are not stripped from non-pattern +characters by @t{GLOB_SUBST}. In other words, + +@noindent +@example +pattern=$@{(q)str@} +[[ $str = $@{~pattern@} ]] +@end example + +@noindent +works if @t{$str} is `@t{a*b}' but not if it is `@t{a b}', whereas + +@noindent +@example +pattern=$@{(b)str@} +[[ $str = $@{~pattern@} ]] +@end example + +@noindent +is always true for any possible value of @t{$str}. + +@item @t{c} +With @t{$@{#}@var{name}@t{@}}, 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. + +@item @t{C} +Capitalize the resulting words. `Words' in this case refers to sequences +of alphanumeric characters separated by non-alphanumerics, @emph{not} to words +that result from field splitting. + +@item @t{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 `@t{~}' substitution: see +@ref{Filename Expansion}. + +@item @t{e} +Perform single word shell expansions, namely @emph{parameter expansion}, +@emph{command substitution} and @emph{arithmetic expansion}, on the +result. Such expansions can be nested but too deep recursion may have +unpredictable effects. + +@item @t{f} +Split the result of the expansion at newlines. This is a shorthand +for `@t{ps:\n:}'. + +@item @t{F} +Join the words of arrays together using newline as a separator. +This is a shorthand for `@t{pj:\n:}'. + +@item @t{g:}@var{opts}@t{:} +Process escape sequences like the echo builtin when no options are given +(@t{g::}). With the @t{o} option, octal escapes don't take a leading +zero. With the @t{c} option, sequences like `@t{^X}' are also processed. +With the @t{e} option, processes `@t{\M-t}' and similar sequences like the +print builtin. With both of the @t{o} and @t{e} options, behaves like the +print builtin except that in none of these modes is `@t{\c}' interpreted. + +@item @t{i} +Sort case-insensitively. May be combined with `@t{n}' or `@t{O}'. + +@item @t{k} +If @var{name} refers to an associative array, substitute the @emph{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 +@t{KSH_ARRAYS} option a subscript `@t{[*]}' or `@t{[@@]}' is needed +to operate on the whole array, as usual. + +@item @t{L} +Convert all letters in the result to lower case. + +@item @t{n} +Sort decimal integers numerically; if the first differing +characters of two test strings are not digits, sorting +is lexical. `@t{+}' and `@t{-}' are not treated specially; they are treated as +any other non-digit. Integers with more initial zeroes +are sorted before those with fewer or none. Hence the array `@t{foo+24 foo1 foo02 +foo2 foo3 foo20 foo23}' is sorted into the order shown. +May be combined with `@t{i}' or `@t{O}'. + +@item @t{-} +As @t{n}, but a leading minus sign indicates a negative decimal +integer. A leading minus sign not followed by an integer does not trigger +numeric sorting. +Note that `@t{+}' signs are not handled specially (this may change in the +future). + +@item @t{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 `@t{a}', `@t{i}', `@t{n}' or `@t{-}'. + +@item @t{O} +Sort the resulting words in descending order; `@t{O}' without `@t{a}', +`@t{i}', `@t{n}' or `@t{-}' sorts in reverse lexical order. May be +combined with `@t{a}', `@t{i}', `@t{n}' or `@t{-}' to reverse the +order of sorting. + +@item @t{P} +This forces the value of the parameter @var{name} to be interpreted as a +further parameter name, whose value will be used where appropriate. +Note that flags set with one of the @t{typeset} family of commands +(in particular case transformations) are not applied to the value of +@var{name} used in this fashion. + +@noindent +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 `@t{foo=bar}' and `@t{bar=baz}', the strings @t{$@{(P)foo@}}, +@t{$@{(P)$@{foo@}@}}, and @t{$@{(P)$(echo bar)@}} will be expanded to +`@t{baz}'. + +@noindent +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 `@t{name=assoc}' where the parameter +@t{assoc} is an associative array, then +`@t{$@{$@{(P)name@}[elt]@}}' refers to the element of the associative +subscripted `@t{elt}'. + +@item @t{q} +Quote characters that are special to the shell in the resulting words with +backslashes; unprintable or invalid characters are quoted using the +@t{$'\}@var{NNN}@t{'} form, with separate quotes for each octet. + +@noindent +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 @t{$}. 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. + +@noindent +If a @t{q-} is given (only a single @t{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. + +@noindent +If a @t{q+} is given, an extended form of minimal quoting is used that +causes unprintable characters to be rendered using @t{$'}@var{...}@t{'}. +This quoting is similar to that used by the output of values by the +@t{typeset} family of commands. + +@item @t{Q} +Remove one level of quotes from the resulting words. + +@item @t{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 (`@t{-}'). The first keyword in the string describes +the main type, it can be one of `@t{scalar}', `@t{array}', `@t{integer}', +`@t{float}' or `@t{association}'. The other keywords describe the type in +more detail: + +@noindent +@table @asis +@item @t{local} +for local parameters + +@item @t{left} +for left justified parameters + +@item @t{right_blanks} +for right justified parameters with leading blanks + +@item @t{right_zeros} +for right justified parameters with leading zeros + +@item @t{lower} +for parameters whose value is converted to all lower case when it is +expanded + +@item @t{upper} +for parameters whose value is converted to all upper case when it is +expanded + +@item @t{readonly} +for readonly parameters + +@item @t{tag} +for tagged parameters + +@item @t{tied} +for parameters tied to another parameter in the manner of @t{PATH} +(colon-separated list) and @t{path} (array), whether these are +special parameters or user-defined with `@t{typeset -T}' + +@item @t{export} +for exported parameters + +@item @t{unique} +for arrays which keep only the first occurrence of duplicated values + +@item @t{hide} +for parameters with the `hide' flag + +@item @t{hideval} +for parameters with the `hideval' flag + +@item @t{special} +for special parameters defined by the shell + +@end table + +@item @t{u} +Expand only the first occurrence of each unique word. + +@item @t{U} +Convert all letters in the result to upper case. + +@item @t{v} +Used with @t{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. + +@item @t{V} +Make any special characters in the resulting words visible. + +@item @t{w} +With @t{$@{#}@var{name}@t{@}}, count words in arrays or strings; the @t{s} +flag may be used to set a word delimiter. + +@item @t{W} +Similar to @t{w} with the difference that empty words between +repeated delimiters are also counted. + +@item @t{X} +With this flag, parsing errors occurring with the @t{Q}, @t{e} and @t{#} +flags or the pattern matching forms such as +`@t{$@{}@var{name}@t{#}@var{pattern}@t{@}}' are reported. Without the flag, +errors are silently ignored. + +@item @t{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 @t{INTERACTIVE_COMMENTS} option unset +(however, see the @t{Z} flag below for related options) + +@noindent +Note that this is done very late, even later than the `@t{(s)}' flag. So to +access single words in the result use nested expansions as +in `@t{$@{$@{(z)foo@}[2]@}}'. Likewise, to remove the quotes in the +resulting words use `@t{$@{(Q)$@{(z)foo@}@}}'. + +@item @t{0} +Split the result of the expansion on null bytes. This is a shorthand +for `@t{ps:\0:}'. + +@end table + +@noindent +The following flags (except @t{p}) are followed by one or more arguments +as shown. Any character, or the matching pairs `@t{(}...@t{)}', +`@t{@{}...@t{@}}', `@t{[}...@t{]}', or `@t{<}...@t{>}', 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. + +@noindent +@table @asis +@item @t{p} +Recognize the same escape sequences as the @t{print} builtin +in string arguments to any of the flags described below that +follow this argument. + +@noindent +Alternatively, with this option string arguments may be in the form +@t{$}@var{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. + +@noindent +For example, + +@noindent +@example +sep=: +val=a:b:c +print $@{(ps.$sep.)val@} +@end example + +@noindent +splits the variable on a @t{:}. + +@item @t{~} +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 @t{~} within the same set of parentheses. Compare with @t{~} +outside parentheses, which forces the entire substituted string to +be treated as a pattern. Hence, for example, + +@noindent +@example +[[ "?" = $@{(~j.|.)array@} ]] +@end example + +@noindent +treats `@t{|}' as a pattern and succeeds if and only if @t{$array} +contains the string `@t{?}' as an element. The @t{~} may be +repeated to toggle the behaviour; its effect only lasts to the +end of the parenthesised group. + +@item @t{j:}@var{string}@t{:} +Join the words of arrays together using @var{string} as a separator. +@pindex SH_WORD_SPLIT, use of +Note that this occurs before field splitting by the @t{s:}@var{string}@t{:} +flag or the @t{SH_WORD_SPLIT} option. + +@item @t{l:}@var{expr}@t{::}@var{string1}@t{::}@var{string2}@t{:} +Pad the resulting words on the left. Each word will be truncated if +required and placed in a field @var{expr} characters wide. + +@noindent +The arguments @t{:}@var{string1}@t{:} and @t{:}@var{string2}@t{:} 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 @var{string1} (concatenated as +often as needed) or spaces if @var{string1} is not given. If both +@var{string1} and @var{string2} are given, @var{string2} is inserted once +directly to the left of each word, truncated if necessary, before +@var{string1} is used to produce any remaining padding. + +@noindent +If either of @var{string1} or @var{string2} is present but empty, +i.e. there are two delimiters together at that point, the first +character of @t{$IFS} is used instead. + +@noindent +If the @t{MULTIBYTE} option is in effect, the flag @t{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. + +@noindent +If the @t{MULTIBYTE} option is not in effect, each byte in the string is +treated as occupying one unit of width. + +@noindent +Control characters are always assumed to be one unit wide; this allows the +mechanism to be used for generating repetitions of control characters. + +@item @t{m} +Only useful together with one of the flags @t{l} or @t{r} or with the +@t{#} length operator when the @t{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. + +@noindent +If the @t{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). + +@item @t{r:}@var{expr}@t{::}@var{string1}@t{::}@var{string2}@t{:} +As @t{l}, but pad the words on the right and insert @var{string2} +immediately to the right of the string to be padded. + +@noindent +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. + +@item @t{s:}@var{string}@t{:} +Force field splitting at the +separator @var{string}. Note that a @var{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 @t{IFS} parameter. +See also the @t{=} flag and the @t{SH_WORD_SPLIT} option. An empty +string may also be given in which case every character will be a separate +element. + +@noindent +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: + +@noindent +@example +line="one::three" +print -l "$@{(s.:.)line@}" +@end example + +@noindent +produces two lines of output for @t{one} and @t{three} and elides the +empty field. To override this behaviour, supply the `@t{(@@)}' flag as well, +i.e. @t{"$@{(@@s.:.)line@}"}. + +@item @t{Z:}@var{opts}@t{:} +As @t{z} but takes a combination of option letters between a following +pair of delimiter characters. With no options the effect is identical +to @t{z}. The following options are available: + +@noindent +@table @asis +@item @t{(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. + +@item @t{(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 @t{$HISTCHARS}, default @t{#}, up to +the next newline is a comment. + +@item @t{(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. + +@end table + +@noindent +Options are combined within the same set of delimiters, +e.g. @t{(Z+Cn+)}. + +@item @t{_:}@var{flags}@t{:} +The underscore (@t{_}) flag is reserved for future use. As of this +revision of zsh, there are no valid @var{flags}; anything following an +underscore, other than an empty pair of delimiters, is treated as an +error, and the flag itself has no effect. + +@end table + +@noindent +The following flags are meaningful with the @t{$@{}...@t{#}...@t{@}} or +@t{$@{}...@t{%}...@t{@}} forms. The @t{S}, @t{I}, and @t{*} flags may also be +used with the @t{$@{}...@t{/}...@t{@}} forms. + +@noindent +@table @asis +@item @t{S} +With @t{#} or @t{##}, search for the match that starts closest to the start of +the string (a `substring match'). Of all matches at a particular position, +@t{#} selects the shortest and @t{##} the longest: + +@noindent +@example +% str="aXbXc" +% echo $@{(S)str#X*@} +abXc +% echo $@{(S)str##X*@} +a +% +@end example + +@noindent +With @t{%} or @t{%%}, search for the match that starts closest to the end of +the string: + +@noindent +@example +% str="aXbXc" +% echo $@{(S)str%X*@} +aXbc +% echo $@{(S)str%%X*@} +aXb +% +@end example + +@noindent +(Note that @t{%} and @t{%%} don't search for the match that ends closest to the +end of the string, as one might expect.) + +@noindent +With substitution via @t{$@{}...@t{/}...@t{@}} or +@t{$@{}...@t{//}...@t{@}}, specifies non-greedy matching, i.e. that the +shortest instead of the longest match should be replaced: + +@noindent +@example +% str="abab" +% echo $@{str/*b/_@} +_ +% echo $@{(S)str/*b/_@} +_ab +% +@end example + +@item @t{I:}@var{expr}@t{:} +Search the @var{expr}th match (where @var{expr} evaluates to a number). +This only applies when searching for substrings, either with the @t{S} +flag, or with @t{$@{}...@t{/}...@t{@}} (only the @var{expr}th match is +substituted) or @t{$@{}...@t{//}...@t{@}} (all matches from the +@var{expr}th on are substituted). The default is to take the first match. + +@noindent +The @var{expr}th 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 @t{$@{}...@t{%}...@t{@}} and @t{$@{}...@t{%%}...@t{@}} 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. + +@noindent +Hence with the string +@example +which switch is the right switch for Ipswich? +@end example +substitutions of the form +@t{$@{}(@t{SI:}@var{N}@t{:})@t{string#w*ch@}} as @var{N} increases +from 1 will match and remove `@t{which}', `@t{witch}', `@t{witch}' and +`@t{wich}'; the form using `@t{##}' will match and remove `@t{which switch +is the right switch for Ipswich}', `@t{witch is the right switch for +Ipswich}', `@t{witch for Ipswich}' and `@t{wich}'. The form using `@t{%}' +will remove the same matches as for `@t{#}', but in reverse order, and the +form using `@t{%%}' will remove the same matches as for `@t{##}' in reverse +order. + +@item @t{*} +@pindex EXTENDED_GLOB, enable +Enable @t{EXTENDED_GLOB} for substitution via @t{$@{}...@t{/}...@t{@}} or +@t{$@{}...@t{//}...@t{@}}. Note that `@t{**}' does not disable extendedglob. + +@item @t{B} +Include the index of the beginning of the match in the result. + +@item @t{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). + +@item @t{M} +Include the matched portion in the result. + +@item @t{N} +Include the length of the match in the result. + +@item @t{R} +Include the unmatched portion in the result (the @emph{R}est). + +@end table + +@noindent + +@subsection Rules +@noindent +@cindex parameter expansion rules +@cindex rules, parameter expansion +@cindex substitution, parameter, rules +Here is a summary of the rules for substitution; this assumes that braces +are present around the substitution, i.e. @t{$@{}@var{...}@t{@}}. Some particular +examples are given below. Note that the Zsh Development Group accepts +@emph{no responsibility} for any brain damage which may occur during the +reading of the following rules. + +@noindent +@table @asis +@item @t{1.} @emph{Nested substitution} +If multiple nested @t{$@{}@var{...}@t{@}} 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. + +@noindent +Note that, unless the `@t{(P)}' flag is present, the flags and any +subscripts apply directly to the value of the nested substitution; for +example, the expansion @t{$@{$@{foo@}@}} behaves exactly the same as +@t{$@{foo@}}. When the `@t{(P)}' flag is present in a nested substitution, +the other substitution rules are applied to the value @emph{before} it is +interpreted as a name, so @t{$@{$@{(P)foo@}@}} may differ from @t{$@{(P)foo@}}. + +@noindent +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 @t{~} and @t{=}). Thus, for example, @t{$@{$@{:-=cat@}:h@}} +expands to the directory where the @t{cat} program resides. (Explanation: +the internal substitution has no parameter but a default value @t{=cat}, +which is expanded by filename expansion to a full path; the outer +substitution then applies the modifier @t{:h} and takes the directory part +of the path.) + +@item @t{2.} @emph{Internal parameter flags} +Any parameter flags set by one of the @t{typeset} family of commands, in +particular the @t{-L}, @t{-R}, @t{-Z}, @t{-u} and @t{-l} options for +padding and capitalization, are applied directly to the parameter value. +Note these flags are options to the command, e.g. `@t{typeset -Z}'; they +are not the same as the flags used within parameter substitutions. + +@noindent +At the outermost level of substitution, the `@t{(P)}' flag (rule @t{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 +@t{$@{$@{(P)foo@}@}} form (rule @t{25.}). + +@item @t{3.} @emph{Parameter subscripting} +If the value is a raw parameter reference with a subscript, such as +@t{$@{}@var{var}@t{[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 @t{var} is an array, @t{$@{var[1][2]@}} is the second +character of the first word, but @t{$@{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 +`@t{(k)}' and `@t{(v)}' which alter the result of subscripting are applied. + +@item @t{4.} @emph{Parameter name replacement} +At the outermost level of nesting only, the `@t{(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 `@t{(P)}' flag appears in a nested +substitution. + +@noindent +If the value so far names a parameter that has internal flags (rule @t{2.}), +those internal flags are applied to the new value after replacement. + +@item @t{5.} @emph{Double-quoted joining} +If the value after this process is an array, and the substitution +appears in double quotes, and neither an `@t{(@@)}' flag nor a `@t{#}' +length operator is present at the current level, then words of the +value are joined with the first character of the parameter @t{$IFS}, +by default a space, between each word (single word arrays are not +modified). If the `@t{(j)}' flag is present, that is used for joining +instead of @t{$IFS}. + +@item @t{6.} @emph{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 +@t{3.}, multiple subscripts can appear. Note that @t{$@{foo[2,4][2]@}} is +thus equivalent to @t{$@{$@{foo[2,4]@}[2]@}} and also to +@t{"$@{$@{(@@)foo[2,4]@}[2]@}"} (the nested substitution returns an array in +both cases), but not to @t{"$@{$@{foo[2,4]@}[2]@}"} (the nested substitution +returns a scalar because of the quotes). + +@item @t{7.} @emph{Modifiers} +Any modifiers, as specified by a trailing `@t{#}', `@t{%}', `@t{/}' +(possibly doubled) or by a set of modifiers of the form `@t{:...}' (see +@ref{Modifiers} in @ref{History Expansion}), are applied to the words +of the value at this level. + +@item @t{8.} @emph{Character evaluation} +Any `@t{(#)}' flag is applied, evaluating the result so far numerically +as a character. + +@item @t{9.} @emph{Length} +Any initial `@t{#}' modifier, i.e. in the form @t{$@{#}@var{var}@t{@}}, is +used to evaluate the length of the expression so far. + +@item @t{10.} @emph{Forced joining} +If the `@t{(j)}' flag is present, or no `@t{(j)}' flag is present but +the string is to be split as given by rule @t{11.}, and joining +did not take place at rule @t{5.}, any words in the value are joined +together using the given string or the first character of @t{$IFS} if none. +Note that the `@t{(F)}' flag implicitly supplies a string for joining in this +manner. + +@item @t{11.} @emph{Simple word splitting} +If one of the `@t{(s)}' or `@t{(f)}' flags are present, or the `@t{=}' +specifier was present (e.g. @t{$@{=}@var{var}@t{@}}), the word is split on +occurrences of the specified string, or (for @t{=} with neither of the two +flags present) any of the characters in @t{$IFS}. + +@noindent +If no `@t{(s)}', `@t{(f)}' or `@t{=}' was given, but the word is not +quoted and the option @t{SH_WORD_SPLIT} is set, the word is split on +occurrences of any of the characters in @t{$IFS}. Note this step, too, +takes place at all levels of a nested substitution. + +@item @t{12.} @emph{Case modification} +Any case modification from one of the flags `@t{(L)}', `@t{(U)}' or `@t{(C)}' +is applied. + +@item @t{13.} @emph{Escape sequence replacement} +First any replacements from the `@t{(g)}' flag are performed, then any +prompt-style formatting from the `@t{(%)}' family of flags is applied. + +@item @t{14.} @emph{Quote application} +Any quoting or unquoting using `@t{(q)}' and `@t{(Q)}' and related flags +is applied. + +@item @t{15.} @emph{Directory naming} +Any directory name substitution using `@t{(D)}' flag is applied. + +@item @t{16.} @emph{Visibility enhancement} +Any modifications to make characters visible using the `@t{(V)}' flag +are applied. + +@item @t{17.} @emph{Lexical word splitting} +If the '@t{(z)}' flag or one of the forms of the '@t{(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 @t{11.}: it does not use @t{$IFS}, and +does not cause forced joining. + +@item @t{18.} @emph{Uniqueness} +If the result is an array and the `@t{(u)}' flag was present, duplicate +elements are removed from the array. + +@item @t{19.} @emph{Ordering} +If the result is still an array and one of the `@t{(o)}' or `@t{(O)}' flags +was present, the array is reordered. + +@item @t{20.} @t{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 @t{RC_EXPAND_PARAM} option or the `@t{^}' flag. + +@item @t{21.} @emph{Re-evaluation} +Any `@t{(e)}' flag is applied to the value, forcing it to be re-examined +for new parameter substitutions, but also for command and arithmetic +substitutions. + +@item @t{22.} @emph{Padding} +Any padding of the value by the `@t{(l.}@var{fill}@t{.)}' or +`@t{(r.}@var{fill}@t{.)}' flags is applied. + +@item @t{23.} @emph{Semantic joining} +In contexts where expansion semantics requires a single word to +result, all words are rejoined with the first character of @t{IFS} +between. So in `@t{$@{(P}@t{)$@{(f}@t{)lines@}@}}' +the value of @t{$@{lines@}} is split at newlines, but then must be +joined again before the `@t{(P)}' flag can be applied. + +@noindent +If a single word is not required, this rule is skipped. + +@item @t{24.} @emph{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. + +@noindent +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. + +@item @t{25.} @emph{Nested parameter name replacement} +If the `@t{(P)}' flag is present and rule @t{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 @t{2.}) applied to the new value. + +@end table + +@noindent + +@subsection Examples +@noindent +@cindex parameter expansion, examples +The flag @t{f} is useful to split a double-quoted substitution line by +line. For example, @t{$@{(f)"$(<}@var{file}@t{)"@}} +substitutes the contents of @var{file} divided so that each line is +an element of the resulting array. Compare this with the effect of +@t{$}@t{(<}@var{file}@t{)} 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. + +@noindent +The following illustrates the rules for nested parameter expansions. +Suppose that @t{$foo} contains the array @t{(bar baz}@t{)}: + +@noindent +@table @asis +@item @t{"$@{(@@)$@{foo@}[1]@}"} +This produces the result @t{b}. First, the inner substitution +@t{"$@{foo@}"}, which has no array (@t{@@}) flag, produces a single word +result @t{"bar baz"}. The outer substitution @t{"$@{(@@)...[1]@}"} detects +that this is a scalar, so that (despite the `@t{(@@)}' flag) the subscript +picks the first character. + +@item @t{"$@{$@{(@@)foo@}[1]@}"} +This produces the result `@t{bar}'. In this case, the inner substitution +@t{"$@{(@@)foo@}"} produces the array `@t{(bar baz}@t{)}'. The outer +substitution @t{"$@{...[1]@}"} detects that this is an array and picks the +first word. This is similar to the simple case @t{"$@{foo[1]@}"}. + +@end table + +@noindent +As an example of the rules for word splitting and joining, suppose @t{$foo} +contains the array `@t{(ax1 bx1}@t{)}'. Then + +@noindent +@table @asis +@item @t{$@{(s/x/)foo@}} +produces the words `@t{a}', `@t{1 b}' and `@t{1}'. + +@item @t{$@{(j/x/s/x/)foo@}} +produces `@t{a}', `@t{1}', `@t{b}' and `@t{1}'. + +@item @t{$@{(s/x/)foo%%1*@}} +produces `@t{a}' and `@t{ b}' (note the extra space). As substitution +occurs before either joining or splitting, the operation first generates +the modified array @t{(ax bx}@t{)}, which is joined to give +@t{"ax bx"}, and then split to give `@t{a}', `@t{ b}' and `'. The final +empty string will then be elided, as it is not in double quotes. + +@end table + +@noindent +@node Command Substitution, Arithmetic Expansion, Parameter Expansion, Expansion + +@section Command Substitution +@noindent +@cindex command substitution +@cindex substitution, command +A command enclosed in parentheses preceded by a dollar sign, like +`@t{$(}...@t{)}', or quoted with grave +accents, like `@t{`}...@t{`}', 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 @t{IFS} parameter. +@vindex IFS, use of + +@noindent +The substitution `@t{$(cat} @var{foo}@t{)}' may be replaced +by the faster `@t{$(<}@var{foo}@t{)}'. In this case @var{foo} +undergoes single word shell expansions (@emph{parameter expansion}, +@emph{command substitution} and @emph{arithmetic expansion}), but not +filename generation. + +@noindent +If the option @t{GLOB_SUBST} is set, the result of any unquoted command +substitution, including the special form just mentioned, is eligible for +filename generation. + +@noindent +@node Arithmetic Expansion, Brace Expansion, Command Substitution, Expansion + +@section Arithmetic Expansion +@noindent +@cindex arithmetic expansion +@cindex expansion, arithmetic +A string of the form `@t{$[}@var{exp}@t{]}' or +`@t{$((}@var{exp}@t{))}' is substituted +with the value of the arithmetic expression @var{exp}. @var{exp} is +subjected to @emph{parameter expansion}, @emph{command substitution} +and @emph{arithmetic expansion} before it is evaluated. +See @ref{Arithmetic Evaluation}. +@node Brace Expansion, Filename Expansion, Arithmetic Expansion, Expansion + +@section Brace Expansion +@noindent +@cindex brace expansion +@cindex expansion, brace +A string of the form +`@var{foo}@t{@{}@var{xx}@t{,}@var{yy}@t{,}@var{zz}@t{@}}@var{bar}' +is expanded to the individual words +`@var{fooxxbar}', `@var{fooyybar}' and `@var{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. + +@noindent +An expression of the form `@t{@{}@var{n1}@t{..}@var{n2}@t{@}}', +where @var{n1} and @var{n2} are integers, +is expanded to every number between +@var{n1} and @var{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 @t{-} character is also +included in the width. If the numbers are in decreasing order the +resulting sequence will also be in decreasing order. + +@noindent +An expression of the form `@t{@{}@var{n1}@t{..}@var{n2}@t{..}@var{n3}@t{@}}', +where @var{n1}, @var{n2}, and @var{n3} are integers, +is expanded as above, but only every @var{n3}th number starting from @var{n1} +is output. If @var{n3} is negative the numbers are output in reverse order, +this is slightly different from simply swapping @var{n1} and @var{n2} in the case +that the step @var{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 `@t{@{-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). + +@noindent +An expression of the form `@t{@{}@var{c1}@t{..}@var{c2}@t{@}}', where +@var{c1} and @var{c2} are single characters (which may be multibyte +characters), is expanded to every character in the range from @var{c1} to +@var{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. `@t{@{d..a@}}' is substituted as `@t{d c b a}'. + +@noindent +If a brace expression matches none of the above forms, it is left +unchanged, unless the option @t{BRACE_CCL} (an abbreviation for `brace +character class') is set. +@pindex BRACE_CCL, use of +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 +@t{[}...@t{]} expression in filename generation: +`@t{-}' is treated specially to denote a range of characters, but `@t{^}' or +`@t{!}' as the first character is treated normally. For example, +`@t{@{abcdef0-9@}}' expands to 16 words @t{0 1 2 3 4 5 6 7 8 9 a b c d e f}. + +@noindent +Note that brace expansion is not part of filename generation (globbing); an +expression such as @t{*/@{foo,bar@}} is split into two separate words +@t{*/foo} and @t{*/bar} before filename generation takes place. In +particular, note that this is liable to produce a `no match' error if +@emph{either} of the two expressions does not match; this is to be contrasted +with @t{*/(foo|bar)}, which is treated as a single pattern but otherwise +has similar effects. + +@noindent +To combine brace expansion with array expansion, see the +@t{$@{^}@var{spec}@t{@}} form described +in @ref{Parameter Expansion} +above. + +@noindent +@node Filename Expansion, Filename Generation, Brace Expansion, Expansion + +@section Filename Expansion +@noindent +@cindex filename expansion +@cindex expansion, filename +Each word is checked to see if it begins with an unquoted `@t{~}'. +If it does, then the word up to a `@t{/}', +or the end of the word if there is no `@t{/}', +is checked to see if it can be substituted in one of the ways +described here. If so, then the `@t{~}' and the checked portion are +replaced with the appropriate substitute value. + +@noindent +A `@t{~}' by itself is replaced by the value of @t{$HOME}. +A `@t{~}' followed by a `@t{+}' or a `@t{-}' is replaced by current +or previous working directory, respectively. + +@noindent +A `@t{~}' followed by a number is replaced by the directory at that +position in the directory stack. +`@t{~0}' is equivalent to `@t{~+}', +and `@t{~1}' is the top of the stack. +`@t{~+}' followed by a number is replaced by the directory at that +position in the directory stack. +`@t{~+0}' is equivalent to `@t{~+}', +and `@t{~+1}' is the top of the stack. +`@t{~-}' followed by a number is replaced by the directory that +many positions from the bottom of the stack. +`@t{~-0}' is the bottom of the stack. +@pindex PUSHD_MINUS, use of +The @t{PUSHD_MINUS} +option exchanges the effects of `@t{~+}' and `@t{~-}' where they are +followed by a number. + +@noindent +@menu +* Dynamic named directories:: +* Static named directories:: +* `=' expansion:: +* Notes:: +@end menu + +@noindent +@node Dynamic named directories, Static named directories, , Filename Expansion + +@subsection Dynamic named directories +@noindent +@cindex directories, named, dynamic +@cindex named directories, dynamic +@cindex dynamic named directories +If the function @t{zsh_directory_name} exists, or the shell variable +@t{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. + +@noindent +A `@t{~}' followed by a string @var{namstr} in unquoted square brackets is +treated specially as a dynamic directory name. Note that the first +unquoted closing square bracket always terminates @var{namstr}. The shell +function is passed two arguments: the string @t{n} (for name) and +@var{namstr}. It should either set the array @t{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 @t{NOMATCH} is set, +an error results. + +@noindent +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 @t{%~} in prompts. In this case each function is passed two +arguments: the string @t{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 `@t{~[}@var{...}@t{]}'), and the second is the +prefix length of the directory to be replaced. For example, if the trial +directory is @t{/home/myname/src/zsh} and the dynamic name for +@t{/home/myname/src} (which has 16 characters) is @t{s}, then the function +sets + +@noindent +@example +reply=(s 16) +@end example + +@noindent +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. + +@noindent +It is not a requirement that a function implements both +@t{n} and @t{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 @t{d} should cause a non-zero status to +be returned. + +@noindent +The completion system calls `@t{zsh_directory_name c}' followed by +equivalent calls to elements of the array +@t{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 +@ref{Completion System}. + +@noindent +As a working example, here is a function that expands any dynamic names +beginning with the string @t{p:} to directories below +@t{/home/pws/perforce}. In this simple case a static name for the +directory would be just as effective. + +@noindent +@example +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 +@} +@end example + +@noindent +@node Static named directories, `=' expansion, Dynamic named directories, Filename Expansion + +@subsection Static named directories +@noindent +@cindex directories, named, static +@cindex named directories, static +@cindex static named directories +A `@t{~}' followed by anything not already covered consisting +of any number of alphanumeric characters or underscore (`@t{_}'), +hyphen (`@t{-}'), or dot (`@t{.}') 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 `@t{~}' is the name +of a string shell parameter whose value begins with a `@t{/}'. +Note that trailing slashes will be removed from the path to the directory +(though the original parameter is not modified). + +@noindent +It is also possible to define directory names using the @t{-d} option to the +@t{hash} builtin. + +@noindent +When the shell prints a path (e.g. when expanding @t{%~} 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 +`@t{~}' 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 @t{$PWD} and @t{$OLDPWD} are never abbreviated in this fashion. + +@noindent +@node `=' expansion, Notes, Static named directories, Filename Expansion + +@subsection `=' expansion +@noindent + +@noindent +If a word begins with an unquoted `@t{=}' +and the @t{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. + +@noindent +@node Notes, , `=' expansion, Filename Expansion + +@subsection Notes +@noindent +@cindex filename expansion, notes +Filename expansion is performed on the right hand side of a parameter +assignment, including those appearing after commands of the +@t{typeset} family. In this case, the right hand side will be treated +as a colon-separated list in the manner of the @t{PATH} parameter, +so that a `@t{~}' or an `@t{=}' following a `@t{:}' is eligible for expansion. +All such behaviour can be +disabled by quoting the `@t{~}', the `@t{=}', or the whole expression (but not +simply the colon); the @t{EQUALS} option is also respected. + +@noindent +If the option @t{MAGIC_EQUAL_SUBST} is set, any unquoted shell +argument in the form `@var{identifier}@t{=}@var{expression}' becomes eligible +for file expansion as described in the previous paragraph. Quoting the +first `@t{=}' also inhibits this. + +@noindent +@node Filename Generation, , Filename Expansion, Expansion + +@section Filename Generation +@noindent +@cindex filename generation +If a word contains an unquoted instance of one of the characters +`@t{*}', `@t{(}', `@t{|}', `@t{<}', `@t{[}', or `@t{?}', it is regarded +as a pattern for filename generation, unless the @t{GLOB} option is unset. +@pindex GLOB, use of +If the @t{EXTENDED_GLOB} option is set, +@pindex EXTENDED_GLOB, use of +the `@t{^}' and `@t{#}' characters also denote a pattern; otherwise +they are not treated specially by the shell. + +@noindent +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 @t{NULL_GLOB} option is set, +@pindex NULL_GLOB, use of +in which case the word is deleted; or unless the @t{NOMATCH} +option is unset, in which case the word is left unchanged. +@pindex NOMATCH, use of + +@noindent +In filename generation, +the character `@t{/}' must be matched explicitly; +also, a `@t{.}' must be matched +explicitly at the beginning of a pattern or after a `@t{/}', unless the +@t{GLOB_DOTS} option is set. +@pindex GLOB_DOTS, use of +No filename generation pattern +matches the files `@t{.}' or `@t{..}'. In other instances of pattern +matching, the `@t{/}' and `@t{.}' are not treated specially. + +@subsection Glob Operators +@noindent +@cindex glob operators +@table @asis +@item @t{*} +Matches any string, including the null string. + +@item @t{?} +Matches any character. + +@item @t{[}...@t{]} +Matches any of the enclosed characters. Ranges of characters +can be specified by separating two characters by a `@t{-}'. +A `@t{-}' or `@t{]}' may be matched by including it as the +first character in the list. +@cindex character classes +There are also several named classes of characters, in the form +`@t{[:}@var{name}@t{:]}' 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 +ctype(3): + +@noindent +@table @asis +@item @t{[:alnum:]} +The character is alphanumeric + +@item @t{[:alpha:]} +The character is alphabetic + +@item @t{[:ascii:]} +The character is 7-bit, i.e. is a single-byte character without +the top bit set. + +@item @t{[:blank:]} +The character is a blank character + +@item @t{[:cntrl:]} +The character is a control character + +@item @t{[:digit:]} +The character is a decimal digit + +@item @t{[:graph:]} +The character is a printable character other than whitespace + +@item @t{[:lower:]} +The character is a lowercase letter + +@item @t{[:print:]} +The character is printable + +@item @t{[:punct:]} +The character is printable but neither alphanumeric nor whitespace + +@item @t{[:space:]} +The character is whitespace + +@item @t{[:upper:]} +The character is an uppercase letter + +@item @t{[:xdigit:]} +The character is a hexadecimal digit + +@end table + +@noindent +Another set of named classes is handled internally by the shell and +is not sensitive to the locale: + +@noindent +@table @asis +@item @t{[:IDENT:]} +The character is allowed to form part of a shell identifier, such +as a parameter name; this test respects the @t{POSIX_IDENTIFIERS} +option + +@item @t{[:IFS:]} +The character is used as an input field separator, i.e. is contained in the +@t{IFS} parameter + +@item @t{[:IFSSPACE:]} +The character is an IFS white space character; see the documentation +for @t{IFS} in +@ref{Parameters Used By The Shell}. + +@item @t{[: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 +`@t{[[:INCOMPLETE:]]*}'. This will never match a sequence starting +with a valid multibyte character. + +@item @t{[: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. + +@item @t{[:WORD:]} +The character is treated as part of a word; this test is sensitive +to the value of the @t{WORDCHARS} parameter + +@end table + +@noindent +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 `@t{[[:alnum:]]}'. Named +character sets can be used alongside other types, +e.g. `@t{[[:alpha:]0-9]}'. + +@item @t{[^}...@t{]} +@itemx @t{[!}...@t{]} +Like @t{[}...@t{]}, except that it matches any character which is +not in the given set. + +@item @t{<}[@var{x}]@t{-}[@var{y}]@t{>} +Matches any number in the range @var{x} to @var{y}, inclusive. +Either of the numbers may be omitted to make the range open-ended; +hence `@t{<->}' matches any number. To match individual digits, the +@t{[}...@t{]} form is more efficient. + +@noindent +Be careful when using other wildcards adjacent to patterns of this form; +for example, @t{<0-9>*} will actually match any number whatsoever at the +start of the string, since the `@t{<0-9>}' will match the first digit, and +the `@t{*}' 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 `@t{<0-9>[^[:digit:]]*}' can be +used instead. + +@item @t{(}...@t{)} +Matches the enclosed pattern. This is used for grouping. +If the @t{KSH_GLOB} option is set, then a +`@t{@@}', `@t{*}', `@t{+}', `@t{?}' or `@t{!}' immediately preceding +the `@t{(}' is treated specially, as detailed below. The option +@t{SH_GLOB} prevents bare parentheses from being used in this way, though +the @t{KSH_GLOB} option is still available. + +@noindent +Note that grouping cannot extend over multiple directories: it is an error +to have a `@t{/}' within a group (this only applies for patterns used in +filename generation). There is one exception: a group of the form +@t{(}@var{pat}@t{/)#} appearing as a complete path segment can +match a sequence of directories. For example, @t{foo/(a*/)#bar} matches +@t{foo/bar}, @t{foo/any/bar}, @t{foo/any/anyother/bar}, and so on. + +@item @var{x}@t{|}@var{y} +Matches either @var{x} or @var{y}. +This operator has lower precedence than any other. +The `@t{|}' character +must be within parentheses, to avoid interpretation as a pipeline. +The alternatives are tried in order from left to right. + +@item @t{^}@var{x} +(Requires @t{EXTENDED_GLOB} to be set.) +Matches anything except the pattern @var{x}. +This has a higher precedence than `@t{/}', so `@t{^foo/bar}' +will search directories in `@t{.}' except `@t{./foo}' +for a file named `@t{bar}'. + +@item @var{x}@t{~}@var{y} +(Requires @t{EXTENDED_GLOB} to be set.) +Match anything that matches the pattern @var{x} but does not match @var{y}. +This has lower precedence than any operator except `@t{|}', so +`@t{*/*~foo/bar}' will search for all files in all directories in `@t{.}' +and then exclude `@t{foo/bar}' if there was such a match. +Multiple patterns can be excluded by +`@var{foo}@t{~}@var{bar}@t{~}@var{baz}'. +In the exclusion pattern (@var{y}), `@t{/}' and `@t{.}' are not treated +specially the way they usually are in globbing. + +@item @var{x}@t{#} +(Requires @t{EXTENDED_GLOB} to be set.) +Matches zero or more occurrences of the pattern @var{x}. +This operator has high precedence; `@t{12#}' is equivalent to `@t{1(2#)}', +rather than `@t{(12)#}'. It is an error for an unquoted `@t{#}' to follow +something which cannot be repeated; this includes an empty string, a +pattern already followed by `@t{##}', or parentheses when part of a +@t{KSH_GLOB} pattern (for example, `@t{!(}@var{foo}@t{)#}' is +invalid and must be replaced by +`@t{*(!(}@var{foo}@t{))}'). + +@item @var{x}@t{##} +(Requires @t{EXTENDED_GLOB} to be set.) +Matches one or more occurrences of the pattern @var{x}. +This operator has high precedence; `@t{12##}' is equivalent to `@t{1(2##)}', +rather than `@t{(12)##}'. No more than two active `@t{#}' characters may +appear together. (Note the potential clash with glob qualifiers in the +form `@t{1(2##)}' which should therefore be avoided.) + +@end table + +@subsection ksh-like Glob Operators +@noindent +@pindex KSH_GLOB, use of +If the @t{KSH_GLOB} option is set, the effects of parentheses can be +modified by a preceding `@t{@@}', `@t{*}', `@t{+}', `@t{?}' or `@t{!}'. +This character need not be unquoted to have special effects, +but the `@t{(}' must be. + +@noindent +@table @asis +@item @t{@@(}...@t{)} +Match the pattern in the parentheses. (Like `@t{(}...@t{)}'.) + +@item @t{*(}...@t{)} +Match any number of occurrences. (Like `@t{(}...@t{)#}', +except that recursive directory searching is not supported.) + +@item @t{+(}...@t{)} +Match at least one occurrence. (Like `@t{(}...@t{)##}', +except that recursive directory searching is not supported.) + +@item @t{?(}...@t{)} +Match zero or one occurrence. (Like `@t{(|}...@t{)}'.) + +@item @t{!(}...@t{)} +Match anything but the expression in parentheses. +(Like `@t{(^(}...@t{))}'.) + +@end table + +@subsection Precedence +@noindent +@cindex precedence of glob operators +The precedence of the operators given above is (highest) `@t{^}', `@t{/}', +`@t{~}', `@t{|}' (lowest); the +remaining operators are simply treated from left to right as part of a +string, with `@t{#}' and `@t{##}' applying to the shortest possible +preceding unit (i.e. a character, `@t{?}', `@t{[}...@t{]}', +`@t{<}...@t{>}', or a parenthesised expression). As mentioned +above, a `@t{/}' used as a directory separator may not appear inside +parentheses, while a `@t{|}' must do so; in patterns used in other contexts +than filename generation (for example, in @t{case} statements and tests +within `@t{[[}...@t{]]}'), a `@t{/}' is not special; and `@t{/}' is also +not special after a `@t{~}' appearing outside parentheses in a filename +pattern. + +@subsection Globbing Flags +@noindent +@cindex globbing flags +@cindex glob 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 @t{EXTENDED_GLOB} option. All take the form +@t{(#}@var{X}@t{)} where @var{X} may have one of the following +forms: + +@noindent +@table @asis +@item @t{i} +Case insensitive: upper or lower case characters in the pattern match +upper or lower case characters. + +@item @t{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. + +@item @t{I} +Case sensitive: locally negates the effect of @t{i} or @t{l} from +that point on. + +@vindex match +@vindex mbegin +@vindex mend +@item @t{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 @t{$match}, the indices of the beginning of the matched +parentheses in the array @t{$mbegin}, and the indices of the end in the array +@t{$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 @t{$mend} and @t{$mbegin} may be used in +subscripts; the @t{KSH_ARRAYS} option is respected. Sets of globbing flags +are not considered parenthesised groups; only the first nine active +parentheses can be referenced. + +@noindent +For example, + +@noindent +@example +foo="a_string_with_a_message" +if [[ $foo = (a|an)_(#b)(*) ]]; then + print $@{foo[$mbegin[1],$mend[1]]@} +fi +@end example + +@noindent +prints `@t{string_with_a_message}'. +Note that the first set of parentheses is before the +@t{(#b)} and does not create a backreference. + +@noindent +Backreferences work with all forms of pattern matching other than filename +generation, but note that when performing matches on an entire array, such +as @t{$@{}@var{array}@t{#}@var{pattern}@t{@}}, or a global substitution, such +as @t{$@{}@var{param}@t{//}@var{pat}@t{/}@var{repl}@t{@}}, 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 @t{m} flag below. + +@noindent +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 `@t{#}' or `@t{##}'. Only the last match of the parenthesis is +remembered: for example, in `@t{[[ abab = (#b)([ab])# ]]}', only the final +`@t{b}' is stored in @t{match[1]}. Thus extra parentheses may be necessary +to match the complete segment: for example, use +`@t{X((ab|cd)#)Y}' to match +a whole string of either `@t{ab}' or `@t{cd}' between `@t{X}' and `@t{Y}', +using the value of @t{$match[1]} rather than @t{$match[2]}. + +@noindent +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 @t{#} and matched +zero times --- then the matched string is set to the empty string, and the +start and end indices are set to -1. + +@noindent +Pattern matching with backreferences is slightly slower than without. + +@item @t{B} +Deactivate backreferences, negating the effect of the @t{b} flag from that +point on. + +@item @t{c}@var{N}@t{,}@var{M} +The flag @t{(#c}@var{N}@t{,}@var{M}@t{)} can be used anywhere +that the @t{#} or @t{##} operators can be used except in the expressions +`@t{(*/)#}' and `@t{(*/)##}' in filename generation, where `@t{/}' +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 @t{@{}@var{N}@t{,}@var{M}@t{@}} in regular expressions. The previous +character or group is required to match between @var{N} and @var{M} times, +inclusive. The form @t{(#c}@var{N}@t{)} requires exactly @t{N} +matches; @t{(#c,}@var{M}@t{)} is equivalent to specifying @var{N} +as 0; @t{(#c}@var{N}@t{,)} specifies that there is no maximum +limit on the number of matches. + +@vindex MATCH +@vindex MBEGIN +@vindex MEND +@item @t{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 @t{$MATCH}, @t{$MBEGIN} and @t{$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. + +@noindent +For example, + +@noindent +@example +arr=(veldt jynx grimps waqf zho buck) +print $@{arr//(#m)[aeiou]/$@{(U)MATCH@}@} +@end example + +@noindent +forces all the matches (i.e. all vowels) into uppercase, printing +`@t{vEldt jynx grImps wAqf zhO bUck}'. + +@noindent +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. + +@item @t{M} +Deactivate the @t{m} flag, hence no references to match data will be +created. + +@item @t{a}@var{num} +Approximate matching: @var{num} errors are allowed in the string matched by +the pattern. The rules for this are described in the next subsection. + +@item @t{s}, @t{e} +Unlike the other flags, these have only a local effect, and each must +appear on its own: `@t{(#s)}' and `@t{(#e)}' are the only valid forms. +The `@t{(#s)}' flag succeeds only at the start of the test string, and the +`@t{(#e)}' flag succeeds only at the end of the test string; they +correspond to `@t{^}' and `@t{$}' 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, `@t{*((#s)|/)test((#e)|/)*}' matches +a path segment `@t{test}' in any of the following strings: @t{test}, +@t{test/at/start}, @t{at/end/test}, @t{in/test/middle}. + +@noindent +Another use is in parameter substitution; for example +`@t{$@{array/(#s)A*Z(#e)@}}' will remove only elements of an +array which +match the complete pattern `@t{A*Z}'. There are other ways of performing +many operations of this type, however the combination of the substitution +operations `@t{/}' and `@t{//}' with the `@t{(#s)}' and `@t{(#e)}' flags +provides a single simple and memorable method. + +@noindent +Note that assertions of the form `@t{(^(#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 `@t{(""~(#s))}' to match a zero-length portion of the string +not at the start. + +@item @t{q} +A `@t{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 `@t{(#b)(*).c(#q.)}' can be used both for globbing +and for +matching against a string. In the former case, the `@t{(#q.)}' will be +treated as a glob qualifier and the `@t{(#b)}' will not be useful, while in +the latter case the `@t{(#b)}' is useful for backreferences and the +`@t{(#q.)}' will be ignored. Note that colon modifiers in the glob +qualifiers are also not applied in ordinary pattern matching. + +@item @t{u} +Respect the current locale in determining the presence of multibyte +characters in a pattern, provided the shell was compiled with +@t{MULTIBYTE_SUPPORT}. This overrides the @t{MULTIBYTE} +option; the default behaviour is taken from the option. Compare @t{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.) + +@item @t{U} +All characters are considered to be a single byte long. The opposite +of @t{u}. This overrides the @t{MULTIBYTE} option. + +@end table + +@noindent +For example, the test string @t{fooxx} can be matched by the pattern +@t{(#i}@t{)FOOXX}, but not by @t{(#l}@t{)FOOXX}, +@t{(#i}@t{)FOO}@t{(#I}@t{)XX} or +@t{((#i}@t{)FOOX}@t{)X}. The string +@t{(#ia2}@t{)readme} specifies case-insensitive matching of +@t{readme} with up to two errors. + +@noindent +When using the ksh syntax for grouping both @t{KSH_GLOB} and +@t{EXTENDED_GLOB} must be set and the left parenthesis should be +preceded by @t{@@}. Note also that the flags do not affect letters +inside @t{[}...@t{]} groups, in other words @t{(#i}@t{)[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 +@t{(#i}@t{)/foo/bar/...} is potentially slow. + +@noindent + +@subsection Approximate Matching +@noindent +@cindex approximate matching +@cindex matching, approximate +When matching approximately, the shell keeps a count of the errors found, +which cannot exceed the number specified in the +@t{(#a}@var{num}@t{)} flags. Four types of error are recognised: + +@noindent +@table @asis +@item 1. +Different characters, as in @t{fooxbar} and @t{fooybar}. + +@item 2. +Transposition of characters, as in @t{banana} and @t{abnana}. + +@item 3. +A character missing in the target string, as with the pattern @t{road} and +target string @t{rod}. + +@item 4. +An extra character appearing in the target string, as with @t{stove} +and @t{strove}. + +@end table + +@noindent +Thus, the pattern @t{(#a3}@t{)abcd} matches @t{dcba}, with the +errors occurring by using the first rule twice and the second once, +grouping the string as @t{[d][cb][a]} and @t{[a][bc][d]}. + +@noindent +Non-literal parts of the pattern must match exactly, including characters +in character ranges: hence @t{(#a1}@t{)???} 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 @t{?} must match. Other characters +which must match exactly are initial dots in filenames (unless the +@t{GLOB_DOTS} option is set), and all slashes in filenames, so that +@t{a/bc} is two errors from @t{ab/c} (the slash cannot be transposed with +another character). Similarly, errors are counted separately for +non-contiguous strings in the pattern, so that @t{(ab|cd}@t{)ef} +is two errors from @t{aebf}. + +@noindent +When using exclusion via the @t{~} operator, approximate matching is +treated entirely separately for the excluded part and must be activated +separately. Thus, @t{(#a1}@t{)README~READ_ME} matches +@t{READ.ME} but not @t{READ_ME}, as the trailing @t{READ_ME} is matched +without approximation. However, +@t{(#a1}@t{)README~(#a1}@t{)READ_ME} +does not match any pattern of the form @t{READ}@var{?}@t{ME} as all +such forms are now excluded. + +@noindent +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, +@t{(#a1}@t{)cat}@t{((#a0}@t{)dog}@t{)fox} +allows one error in total, which may not occur in the @t{dog} section, and +the pattern +@t{(#a1}@t{)cat}@t{(#a0}@t{)dog}@t{(#a1}@t{)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, +@t{(#a1)abc(#a0)xyz} will not match @t{abcdxyz}, because the +error occurs at the `@t{x}', where approximation is turned off. + +@noindent +Entire path segments may be matched approximately, so that +`@t{(#a1)/foo/d/is/available/at/the/bar}' allows one error in any path +segment. This is much less efficient than without the @t{(#a1)}, however, +since every directory in the path must be scanned for a possible +approximate match. It is best to place the @t{(#a1)} after any path +segments which are known to be correct. + +@noindent + +@subsection Recursive Globbing +@noindent +@cindex recursive globbing +@cindex globbing, recursive +A pathname component of the form `@t{(}@var{foo}@t{/)#}' +matches a path consisting of zero or more directories +matching the pattern @var{foo}. + +@noindent +As a shorthand, `@t{**/}' is equivalent to `@t{(*/)#}'; note that this +therefore matches files in the current directory as well as +subdirectories. +Thus: + +@noindent +@example +ls -ld -- (*/)#bar +@end example + +@noindent +or + +@noindent +@example +ls -ld -- **/bar +@end example + +@noindent +does a recursive directory search for files named `@t{bar}' (potentially +including the file `@t{bar}' in the current directory). This form does not +follow symbolic links; the alternative form `@t{***/}' 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 `@t{*}' +operators revert to their usual effect. + +@noindent +Even shorter forms are available when the option @t{GLOB_STAR_SHORT} is +set. In that case if no @t{/} immediately follows a @t{**} or @t{***} +they are treated as if both a @t{/} plus a further @t{*} are present. +Hence: + +@noindent +@example +setopt GLOBSTARSHORT +ls -ld -- **.c +@end example + +@noindent +is equivalent to + +@noindent +@example +ls -ld -- **/*.c +@end example + +@subsection Glob Qualifiers +@noindent +@cindex globbing, qualifiers +@cindex qualifiers, globbing +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. + +@noindent +@pindex BARE_GLOB_QUAL, use of +If the option @t{BARE_GLOB_QUAL} is set, then a trailing set of parentheses +containing no `@t{|}' or `@t{(}' characters (or `@t{~}' 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 `@t{(^x)}', can be forced to be treated as part of +the glob pattern by doubling the parentheses, in this case producing +`@t{((^x))}'. + +@noindent +If the option @t{EXTENDED_GLOB} is set, a different syntax for glob +qualifiers is available, namely `@t{(#q}@var{x}@t{)}' +where @var{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 `@t{|}', `@t{(}' or +`@t{~}' 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 `@t{*(#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 +`@t{[[}' form the presence of a parenthesised expression +@t{(#q}@var{...}@t{)} 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 @t{(#q)}. This does +not apply to the right hand side of pattern match operators as the +syntax already has special significance. + +@noindent +A qualifier may be any one of the following: + +@noindent +@table @asis +@item @t{/} +directories + +@item @t{F} +`full' (i.e. non-empty) directories. Note that the +opposite sense @t{(^F}@t{)} expands to empty directories +and all non-directories. Use @t{(/^F}@t{)} for +empty directories. + +@item @t{.} +plain files + +@item @t{@@} +symbolic links + +@item @t{=} +sockets + +@item @t{p} +named pipes (FIFOs) + +@item @t{*} +executable plain files (0100 or 0010 or 0001) + +@item @t{%} +device files (character or block special) + +@item @t{%b} +block special files + +@item @t{%c} +character special files + +@item @t{r} +owner-readable files (0400) + +@item @t{w} +owner-writable files (0200) + +@item @t{x} +owner-executable files (0100) + +@item @t{A} +group-readable files (0040) + +@item @t{I} +group-writable files (0020) + +@item @t{E} +group-executable files (0010) + +@item @t{R} +world-readable files (0004) + +@item @t{W} +world-writable files (0002) + +@item @t{X} +world-executable files (0001) + +@item @t{s} +setuid files (04000) + +@item @t{S} +setgid files (02000) + +@item @t{t} +files with the sticky bit (01000) + +@item @t{f}@var{spec} +files with access rights matching @var{spec}. This @var{spec} may be a +octal number optionally preceded by a `@t{=}', a `@t{+}', or a +`@t{-}'. If none of these characters is given, the behavior is the +same as for `@t{=}'. The octal number describes the mode bits to be +expected, if combined with a `@t{=}', the value given must match the +file-modes exactly, with a `@t{+}', at least the bits in the +given number must be set in the file-modes, and with a `@t{-}', the +bits in the number must not be set. Giving a `@t{?}' 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 `@t{=}'. + +@noindent +If the qualifier `@t{f}' is followed by any other character anything +up to the next matching character (`@t{[}', `@t{@{}', and `@t{<}' match +`@t{]}', `@t{@}}', and `@t{>}' respectively, any other character +matches itself) is taken as a list of comma-separated +@var{sub-spec}s. Each @var{sub-spec} may be either an octal number as +described above or a list of any of the characters `@t{u}', `@t{g}', +`@t{o}', and `@t{a}', followed by a `@t{=}', a `@t{+}', or a +`@t{-}', followed by a list of any of the characters `@t{r}', `@t{w}', +`@t{x}', `@t{s}', and `@t{t}', or an octal digit. The first list of +characters specify which access rights are to be checked. If a `@t{u}' +is given, those for the owner of the file are used, if a `@t{g}' is +given, those of the group are checked, a `@t{o}' means to test those +of other users, and the `@t{a}' says to test all three groups. The +`@t{=}', `@t{+}', and `@t{-}' 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: `@t{r}' for read access, `@t{w}' for write access, +`@t{x}' for the right to execute the file (or to search a directory), +`@t{s}' for the setuid and setgid bits, and `@t{t}' for the sticky +bit. + +@noindent +Thus, `@t{*(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 +`@t{*(f-100)}' gives all files for which the owner does not have +execute permission, and `@t{*(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. + +@item @t{e}@var{string} +@itemx @t{+}@var{cmd} +The @var{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). + +@noindent +In the first form, the first character after the `@t{e}' +will be used as a separator and anything up to the next matching separator +will be taken as the @var{string}; `@t{[}', `@t{@{}', and `@t{<}' match +`@t{]}', `@t{@}}', and `@t{>}', respectively, while any other character +matches itself. Note that expansions must be quoted in the @var{string} +to prevent them from being expanded before globbing is done. +@var{string} is then executed as shell code. The string @t{globqual} +is appended to the array @t{zsh_eval_context} the duration of +execution. + +@noindent +@vindex REPLY, use of +@vindex reply, use of +During the execution of @var{string} the filename currently being tested is +available in the parameter @t{REPLY}; the parameter may be altered to +a string to be inserted into the list instead of the original +filename. In addition, the parameter @t{reply} may be set to an array or a +string, which overrides the value of @t{REPLY}. If set to an array, the +latter is inserted into the command line word by word. + +@noindent +For example, suppose a directory contains a single file `@t{lonely}'. Then +the expression `@t{*(e:'reply=($@{REPLY@}@{1,2@})':)}' will cause the words +`@t{lonely1}' and `@t{lonely2}' to be inserted into the command line. Note +the quoting of @var{string}. + +@noindent +The form @t{+}@var{cmd} has the same effect, but no delimiters appear +around @var{cmd}. Instead, @var{cmd} is taken as the longest sequence of +characters following the @t{+} that are alphanumeric or underscore. +Typically @var{cmd} will be the name of a shell function that contains the +appropriate test. For example, + +@noindent +@example +nt() @{ [[ $REPLY -nt $NTREF ]] @} +NTREF=reffile +ls -ld -- *(+nt) +@end example + +@noindent +lists all files in the directory that have been modified more recently than +@t{reffile}. + +@item @t{d}@var{dev} +files on the device @var{dev} + +@item @t{l}[@t{-}|@t{+}]@var{ct} +files having a link count less than @var{ct} (@t{-}), greater than +@var{ct} (@t{+}), or equal to @var{ct} + +@item @t{U} +files owned by the effective user ID + +@item @t{G} +files owned by the effective group ID + +@item @t{u}@var{id} +files owned by user ID @var{id} if that is a number. Otherwise, +@var{id} specifies a user name: the +character after the `@t{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 `@t{[}', `@t{@{}', and `@t{<}' +match the final separators `@t{]}', `@t{@}}', and `@t{>}', respectively; +any other character matches itself. The selected files are those +owned by this user. For example, `@t{u:foo:}' or `@t{u[foo]}' selects +files owned by user `@t{foo}'. + +@item @t{g}@var{id} +like @t{u}@var{id} but with group IDs or names + +@item @t{a}[@t{Mwhms}][@t{-}|@t{+}]@var{n} +files accessed exactly @var{n} days ago. Files accessed within the last +@var{n} days are selected using a negative value for @var{n} (@t{-}@var{n}). +Files accessed more than @var{n} days ago are selected by a positive @var{n} +value (@t{+}@var{n}). Optional unit specifiers `@t{M}', `@t{w}', +`@t{h}', `@t{m}' or `@t{s}' (e.g. `@t{ah5}') cause the check to be +performed with months (of 30 days), weeks, hours, minutes or seconds +instead of days, respectively. An explicit `@t{d}' for days is also +allowed. + +@noindent +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, `@t{echo *(ah-5)}' would echo files accessed within the last +five hours, while `@t{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. + +@item @t{m}[@t{Mwhms}][@t{-}|@t{+}]@var{n} +like the file access qualifier, except that it uses the file modification +time. + +@item @t{c}[@t{Mwhms}][@t{-}|@t{+}]@var{n} +like the file access qualifier, except that it uses the file inode change +time. + +@item @t{L}[@t{+}|@t{-}]@var{n} +files less than @var{n} bytes (@t{-}), more than @var{n} bytes (@t{+}), or +exactly @var{n} bytes in length. + +@noindent +If this flag is directly followed by a @emph{size specifier} `@t{k}' (`@t{K}'), +`@t{m}' (`@t{M}'), or `@t{p}' (`@t{P}') (e.g. `@t{Lk-50}') the check is +performed with kilobytes, megabytes, or blocks (of 512 bytes) instead. +(On some systems additional specifiers are available for gigabytes, +`@t{g}' or `@t{G}', and terabytes, `@t{t}' or `@t{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 `@t{*(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 `@t{*(Lm-1)}' only matches +files of zero size. + +@item @t{^} +negates all qualifiers following it + +@item @t{-} +toggles between making the qualifiers work on symbolic links (the +default) and the files they point to, if any; any symbolic link for +whose target the `@t{stat}' system call fails (whatever the cause of the +failure) is treated as a file in its own right + +@item @t{M} +sets the @t{MARK_DIRS} option for the current pattern +@pindex MARK_DIRS, setting in pattern + +@item @t{T} +appends a trailing qualifier mark to the filenames, analogous to the +@t{LIST_TYPES} option, for the current pattern (overrides @t{M}) + +@item @t{N} +sets the @t{NULL_GLOB} option for the current pattern +@pindex NULL_GLOB, setting in pattern + +@item @t{D} +sets the @t{GLOB_DOTS} option for the current pattern +@pindex GLOB_DOTS, setting in pattern + +@item @t{n} +sets the @t{NUMERIC_GLOB_SORT} option for the current pattern +@pindex NUMERIC_GLOB_SORT, setting in pattern + +@item @t{Y}@var{n} +enables short-circuit mode: the pattern will expand to at most @var{n} +filenames. If more than @var{n} matches exist, only the first @var{n} +matches in directory traversal order will be considered. + +@noindent +Implies @t{oN} when no @t{o}@var{c} qualifier is used. + +@item @t{o}@var{c} +specifies how the names of the files should be sorted. The following values +of @var{c} sort in the following ways: + +@noindent +@table @asis +@item @t{n} +By name. +@item @t{L} +By the size (length) of the files. +@item @t{l} +By number of links. +@item @t{a} +By time of last access, youngest first. +@item @t{m} +By time of last modification, youngest first. +@item @t{c} +By time of last inode change, youngest first. +@item @t{d} +By directories: 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 `@t{odon}' to sort on names for +files within the same directory. +@item @t{N} +No sorting is performed. +@item @t{e}@var{string} +@itemx @t{+}@var{cmd} +Sort by shell code (see below). +@end table + +@noindent +Note that the modifiers @t{^} and @t{-} are used, +so `@t{*(^-oL)}' gives a list of all files sorted by file size in descending +order, following any symbolic links. Unless @t{oN} is used, multiple order +specifiers may occur to resolve ties. + +@noindent +The default sorting is @t{n} (by name) unless the @t{Y} glob qualifier is used, +in which case it is @t{N} (unsorted). + +@noindent +@t{oe} and @t{o+} are special cases; they are each followed by shell code, +delimited as for the @t{e} glob qualifier and the @t{+} glob qualifier +respectively (see above). The code is executed for each matched file with +the parameter @t{REPLY} set to the name of the file on entry and +@t{globsort} appended to @t{zsh_eval_context}. The code +should modify the parameter @t{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, @t{oe} and @t{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. + +@item @t{O}@var{c} +like `@t{o}', but sorts in descending order; i.e. `@t{*(^o}@var{c}@t{)}' is the +same as `@t{*(O}@var{c}@t{)}' and `@t{*(^O}@var{c}@t{)}' is the same as `@t{*(o}@var{c}@t{)}'; `@t{Od}' +puts files in the current directory before those in subdirectories at each +level of the search. + +@item @t{[}@var{beg}[@t{,}@var{end}]@t{]} +specifies which of the matched filenames should be included in the +returned list. The syntax is the same as for array +subscripts. @var{beg} and the optional @var{end} may be mathematical +expressions. As in parameter subscripting they may be negative to make +them count from the last match backward. E.g.: `@t{*(-OL[1,3])}' +gives a list of the names of the three largest files. + +@item @t{P}@var{string} +The @var{string} will be prepended to each glob match as a separate +word. @var{string} is delimited in the same way as arguments to the +@t{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. + +@noindent +A typical use for this is to prepend an option before all occurrences +of a file name; for example, the pattern `@t{*(P:-f:)}' produces the +command line arguments `@t{-f} @var{file1} @t{-f} @var{file2} ...' + +@noindent +If the modifier @t{^} is active, then @var{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 +`@t{*(P:foo:^P:bar:^P:baz:)}' which produces the command line arguments +`@t{foo} @t{baz} @var{file1} @t{bar} ...' + +@end table + +@noindent +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 `@t{M}', `@t{T}', +`@t{N}', `@t{D}', `@t{n}', `@t{o}', `@t{O}' and the subscripts given +in brackets (`@t{[}@var{...}@t{]}'). + +@noindent +If a `@t{:}' appears in a qualifier list, the remainder of the expression in +parenthesis is interpreted as a modifier (see @ref{Modifiers} +in @ref{History Expansion}). Each modifier must be introduced by a +separate `@t{:}'. 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 `@t{(:}@var{...}@t{)}' +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 @t{NULL_GLOB}. Thus: + +@noindent +@example +ls -ld -- *(-/) +@end example + +@noindent +lists all directories and symbolic links that point to directories, +and + +@noindent +@example +ls -ld -- *(-@@) +@end example + +@noindent +lists all broken symbolic links, and + +@noindent +@example +ls -ld -- *(%W) +@end example + +@noindent +lists all world-writable device files in the current directory, and + +@noindent +@example +ls -ld -- *(W,X) +@end example + +@noindent +lists all files in the current directory that are +world-writable or world-executable, and + +@noindent +@example +print -rC1 /tmp/foo*(u0^@@:t) +@end example + +@noindent +outputs the basename of all root-owned files beginning with the string +`@t{foo}' in @t{/tmp}, ignoring symlinks, and + +@noindent +@example +ls -ld -- *.*~(lex|parse).[ch](^D^l1) +@end example + +@noindent +lists all files having a link count of one whose names contain a dot +(but not those starting with a dot, since @t{GLOB_DOTS} is explicitly +switched off) except for @t{lex.c}, @t{lex.h}, @t{parse.c} and @t{parse.h}. + +@noindent +@example +print -rC1 b*.pro(#q:s/pro/shmo/)(#q.:s/builtin/shmiltin/) +@end example + +@noindent +demonstrates how colon modifiers and other qualifiers may be chained +together. The ordinary qualifier `@t{.}' is applied first, then the colon +modifiers in order from left to right. So if @t{EXTENDED_GLOB} is set and +the base pattern matches the regular file @t{builtin.pro}, the shell will +print `@t{shmiltin.shmo}'. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/params.yo +@node Parameters, Options, Expansion, Top + +@chapter Parameters +@noindent +@cindex parameters +@cindex variables + +@section Description +@noindent +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 +`@t{*}', `@t{@@}', `@t{#}', `@t{?}', `@t{-}', `@t{$}', or `@t{!}'. +A parameter whose name begins with an alphanumeric or underscore is also +referred to as a @emph{variable}. + +@noindent +@cindex scalar +@cindex parameters, scalar +@cindex parameters, array +@cindex parameters, associative array +@cindex hash +The attributes of a parameter determine the @emph{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 @emph{scalar} (a string, an integer, or a floating +point number), an array (indexed numerically), or an @emph{associative} +array (an unordered set of name-value pairs, indexed by name, also +referred to as a @emph{hash}). + +@noindent +@cindex export +@cindex environment +@cindex environment variables +@cindex variables, environment +Named scalar parameters may have the @emph{exported}, @t{-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 +@emph{environment variables}. The shell also @emph{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. + +@noindent +@cindex special parameters +@cindex parameters, special +Parameters may also be @emph{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. + +@noindent +To declare the type of a parameter, or to assign a string or numeric value +to a scalar parameter, use the @t{typeset} builtin. +@findex typeset, use of + +@noindent +The value of a scalar parameter may also be assigned by writing: +@cindex assignment + +@quotation +@var{name}@t{=}@var{value} +@end quotation + +@noindent +In scalar assignment, @var{value} is expanded as a single string, in +which the elements of arrays are joined together; filename expansion is +not performed unless the option @t{GLOB_ASSIGN} is set. + +@noindent +When the integer attribute, @t{-i}, or a floating point attribute, @t{-E} +or @t{-F}, is set for @var{name}, the @var{value} is subject to arithmetic +evaluation. Furthermore, by replacing `@t{=}' with `@t{+=}', a parameter +can be incremented or appended to. See @ref{Array Parameters} and +@ref{Arithmetic Evaluation} +for additional forms of assignment. + +@noindent +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 @t{GLOB_ASSIGN} assigning a +pattern to a variable may change its type to an array. + +@noindent +To reference the value of a parameter, write `@t{$}@var{name}' or +`@t{$@{}@var{name}@t{@}}'. See +@ref{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:: +@end menu +@node Array Parameters, Positional Parameters, , Parameters + +@section Array Parameters +@noindent +To assign an array value, write one of: +@findex set, use of +@cindex array assignment + +@quotation +@t{set -A} @var{name} @var{value} ... +@end quotation +@quotation +@var{name}@t{=(}@var{value} ...@t{)} +@end quotation +@quotation +@var{name}@t{=(}@t{[}@var{key}@t{]=}@var{value} ...@t{)} +@end quotation + +@noindent +If no parameter @var{name} exists, an ordinary array parameter is created. +If the parameter @var{name} exists and is a scalar, it is replaced by a new +array. + +@noindent +In the third form, @var{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 @var{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: @t{[} and @t{]=} must +not be quoted, and @var{key} may not consist of the unquoted string +@t{]=}, 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. + +@noindent +The syntaxes with and without the explicit key may be mixed. An implicit +@var{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. + +@noindent +For example, assuming the option @t{KSH_ARRAYS} is not set, the following: + +@noindent +@example +array=(one [3]=three four) +@end example + +@noindent +causes the array variable @t{array} to contain four elements @t{one}, +an empty string, @t{three} and @t{four}, in that order. + +@noindent +In the forms where only @var{value} is specified, full command +line expansion is performed. + +@noindent +In the @t{[}@var{key}@t{]=}@var{value} form, +both @var{key} and @var{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 +@t{(e)} as described in +@ref{Parameter Expansion}. +Nested parentheses may surround @var{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: + +@quotation +@var{name}@t{=(}@t{[a-z]'='*)} +@end quotation + +@noindent +To append to an array without changing the existing values, use +one of the following: + +@quotation +@var{name}@t{+=(}@var{value} ...@t{)} +@end quotation +@quotation +@var{name}@t{+=(}@t{[}@var{key}@t{]=}@var{value} ...@t{)} +@end quotation + +@noindent +In the second form @var{key} may specify an existing index as well as an +index off the end of the old array; any existing value is overwritten by +@var{value}. Also, it is possible to use @t{[}@var{key}@t{]+=}@var{value} +to append to the existing value at that index. + +@noindent +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 @var{value}s. Any consecutive sequence of such +characters has the same effect. + +@noindent +Ordinary array parameters may also be explicitly declared with: +@findex typeset, use of + +@quotation +@t{typeset -a} @var{name} +@end quotation + +@noindent +Associative arrays @emph{must} be declared before assignment, by using: + +@quotation +@t{typeset -A} @var{name} +@end quotation + +@noindent +When @var{name} refers to an associative array, the list in an assignment +is interpreted as alternating keys and values: + +@quotation +@t{set -A} @var{name} @var{key} @var{value} ... +@end quotation +@quotation +@var{name}@t{=(}@var{key} @var{value} ...@t{)} +@end quotation +@quotation +@var{name}@t{=(}@t{[}@var{key}@t{]=}@var{value} ...@t{)} +@end quotation + +@noindent +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. + +@noindent +Every @var{key} must have a @var{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: + +@quotation +@var{name}@t{+=(}@var{key} @var{value} ...@t{)} +@end quotation +@quotation +@var{name}@t{+=(}@t{[}@var{key}@t{]=}@var{value} ...@t{)} +@end quotation + +@noindent +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 @t{[}@var{key}@t{]+=}@var{value} to +append to the existing value at that key. Expansion is performed +identically to the corresponding forms for normal arrays, as +described above. + +@noindent +To create an empty array (including associative arrays), use one of: + +@quotation +@t{set -A} @var{name} +@end quotation +@quotation +@var{name}@t{=()} +@end quotation + +@noindent + +@subsection Array Subscripts +@noindent +@cindex subscripts +Individual elements of an array may be selected using a subscript. A +subscript of the form `@t{[}@var{exp}@t{]}' selects the single element +@var{exp}, where @var{exp} is an arithmetic expression which will be subject +to arithmetic expansion as if it were surrounded by +`@t{$((}...@t{))}'. The elements are numbered +beginning with 1, unless the @t{KSH_ARRAYS} option is set in which case +they are numbered from zero. +@pindex KSH_ARRAYS, use of + +@noindent +Subscripts may be used inside braces used to delimit a parameter name, thus +`@t{$@{foo[2]@}}' is equivalent to `@t{$foo[2]}'. If the @t{KSH_ARRAYS} +option is set, the braced form is the only one that works, as bracketed +expressions otherwise are not treated as subscripts. + +@noindent +If the @t{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 @t{KSH_ZERO_SUBSCRIPT} +option can be set to cause subscript values 0 and 1 to be equivalent; see +the description of the option in @ref{Description of Options}. + +@noindent +The same subscripting syntax is used for associative arrays, except that +no arithmetic expansion is applied to @var{exp}. However, the parsing +rules for arithmetic expressions still apply, which affects the way that +certain special characters must be protected from interpretation. See +@emph{Subscript Parsing} below for details. + +@noindent +A subscript of the form `@t{[*]}' or `@t{[@@]}' evaluates to all elements +of an array; there is no difference between the two except when they +appear within double quotes. +`@t{"$foo[*]"}' evaluates to `@t{"$foo[1] $foo[2] }...@t{"}', whereas +`@t{"$foo[@@]"}' evaluates to `@t{"$foo[1]" "$foo[2]" }...'. For +associative arrays, `@t{[*]}' or `@t{[@@]}' evaluate to all the values, +in no particular order. Note that this does not substitute +the keys; see the documentation for the `@t{k}' flag under +@ref{Parameter Expansion} +for complete details. +When an array parameter is referenced as `@t{$}@var{name}' (with no +subscript) it evaluates to `@t{$}@var{name}@t{[*]}', unless the @t{KSH_ARRAYS} +option is set in which case it evaluates to `@t{$@{}@var{name}@t{[0]@}}' (for +an associative array, this means the value of the key `@t{0}', which may +not exist even if there are values for other keys). + +@noindent +A subscript of the form `@t{[}@var{exp1}@t{,}@var{exp2}@t{]}' +selects all elements in the range @var{exp1} to @var{exp2}, +inclusive. (Associative arrays are unordered, and so do not support +ranges.) If one of the subscripts evaluates to a negative number, +say @t{-}@var{n}, then the @var{n}th element from the end +of the array is used. Thus `@t{$foo[-3]}' is the third element +from the end of the array @t{foo}, and +`@t{$foo[1,-1]}' is the same as `@t{$foo[*]}'. + +@noindent +Subscripting may also be performed on non-array values, in which +case the subscripts specify a substring to be extracted. +For example, if @t{FOO} is set to `@t{foobar}', then +`@t{echo $FOO[2,5]}' prints `@t{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, + +@noindent +@example +string="abcdefghijklm" +print $@{string[(r)d?,(r)h?]@} +@end example + +@noindent +prints `@t{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). + +@noindent +Note that in substring operations the second subscript is handled +differently by the @t{r} and @t{R} subscript flags: the former takes the +shortest match as the length and the latter the longest match. Hence +in the former case a @t{*} 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. + +@noindent + +@subsection Array Element Assignment +@noindent + +@noindent +A subscript may be used on the left side of an assignment like so: + +@quotation +@var{name}@t{[}@var{exp}@t{]=}@var{value} +@end quotation + +@noindent +In this form of assignment the element or range specified by @var{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.) + +@noindent +This syntax also works as an argument to the @t{typeset} command: + +@quotation +@t{typeset} @t{"}@var{name}@t{[}@var{exp}@t{]"=}@var{value} +@end quotation + +@noindent +The @var{value} may @emph{not} be a parenthesized list in this case; only +single-element assignments may be made with @t{typeset}. Note that quotes +are necessary in this case to prevent the brackets from being interpreted +as filename generation operators. The @t{noglob} precommand modifier +could be used instead. + +@noindent +To delete an element of an ordinary array, assign `@t{()}' to +that element. To delete an element of an associative array, use the +@t{unset} command: + +@quotation +@t{unset} @t{"}@var{name}@t{[}@var{exp}@t{]"} +@end quotation + +@noindent + +@subsection Subscript Flags +@noindent +@cindex 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 +`@var{name}@t{[(}@var{flags}@t{)}@var{exp}@t{]}'. + +@noindent +The flags @t{s}, @t{n} and @t{b} take an argument; the delimiter +is shown below as `@t{:}', but any character, or the matching pairs +`@t{(}...@t{)}', `@t{@{}...@t{@}}', `@t{[}...@t{]}', or +`@t{<}...@t{>}', may be used, but note that `@t{<}...@t{>}' 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. + +@noindent +The flags currently understood are: + +@noindent +@table @asis +@item @t{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 @t{i} or @t{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. + +@item @t{s:}@var{string}@t{:} +This gives the @var{string} that separates words (for use with the +@t{w} flag). The delimiter character @t{:} is arbitrary; see above. + +@item @t{p} +Recognize the same escape sequences as the @t{print} builtin in +the string argument of a subsequent `@t{s}' flag. + +@item @t{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 `@t{pws:\n:}'. + +@item @t{r} +Reverse subscripting: if this flag is given, the @var{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 `@t{w}' flag is given, respectively). The subscript used +is the number of the matching element, so that pairs of subscripts such as +`@t{$foo[(r)??,3]}' and `@t{$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. + +@noindent +If a search through an ordinary array failed, the search sets the +subscript to one past the end of the array, and hence +@t{$@{array[(r)}@var{pattern}@t{]@}} will substitute the empty string. Thus the +success of a search can be tested by using the @t{(i)} flag, for +example (assuming the option @t{KSH_ARRAYS} is not in effect): + +@noindent +@example +[[ $@{array[(i)pattern]@} -le $@{#array@} ]] +@end example + +@noindent +If @t{KSH_ARRAYS} is in effect, the @t{-le} should be replaced by @t{-lt}. + +@item @t{R} +Like `@t{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 @t{KSH_ARRAYS} or +@t{KSH_ZERO_SUBSCRIPT} is in effect. + +@noindent +Note that in subscripts with both `@t{r}' and `@t{R}' pattern characters +are active even if they were substituted for a parameter (regardless of the +setting of @t{GLOB_SUBST} which controls this feature in normal pattern +matching). The flag `@t{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: + +@noindent +@example +key2='original key' +print $@{array[(Re)$key2]@} +@end example + +@item @t{i} +Like `@t{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 `@t{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 `@t{r}', or the empty string for an +associative array. + +@noindent +Note: Although `@t{i}' may be applied to a scalar substitution to find +the offset of a substring, the results are likely to be misleading when +searching within substitutions that yield an empty string, or when +searching for the empty substring. + +@item @t{I} +Like `@t{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. + +@noindent +Note: If the option @t{KSH_ARRAYS} is in effect and no match is found, the +result is indistinguishable from the case when the first element of the array +matches. + +@item @t{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 @var{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 `@t{r}'. + +@item @t{K} +On an associative array this is like `@t{k}' but returns all values where +@var{exp} is matched by the keys. On other types of parameters this has +the same effect as `@t{R}'. + +@item @t{n:}@var{expr}@t{:} +If combined with `@t{r}', `@t{R}', `@t{i}' or `@t{I}', makes them give +the @var{n}th or @var{n}th last match (if @var{expr} evaluates to +@var{n}). This flag is ignored when the array is associative. +The delimiter character @t{:} is arbitrary; see above. + +@item @t{b:}@var{expr}@t{:} +If combined with `@t{r}', `@t{R}', `@t{i}' or `@t{I}', makes them begin +at the @var{n}th or @var{n}th last element, word, or character (if @var{expr} +evaluates to @var{n}). This flag is ignored when the array is associative. +The delimiter character @t{:} is arbitrary; see above. + +@item @t{e} +This flag causes any pattern matching that would be performed on the +subscript to use plain string matching instead. Hence +`@t{$@{array[(re)*]@}}' matches only the array element whose value is @t{*}. +Note that other forms of substitution such as parameter substitution are +not inhibited. + +@noindent +This flag can also be used to force @t{*} or @t{@@} 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. + +@end table + +@noindent +See @emph{Parameter Expansion Flags} (@ref{Parameter Expansion}) for additional ways to manipulate the results of array subscripting. + +@noindent + +@subsection Subscript Parsing +@noindent + +@noindent +This discussion applies mainly to associative array key strings and to +patterns used for reverse subscripting (the `@t{r}', `@t{R}', `@t{i}', +etc. flags), but it may also affect parameter substitutions that appear +as part of an arithmetic expression in an ordinary subscript. + +@noindent +To avoid subscript parsing limitations in assignments to associative array +elements, use the append syntax: + +@noindent +@example +aa+=('key with "*strange*" characters' 'value string') +@end example + +@noindent +The basic rule to remember when writing a subscript expression is that all +text between the opening `@t{[}' and the closing `@t{]}' is interpreted +@emph{as if} it were in double quotes (@ref{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. + +@noindent +The first difference is that brackets (`@t{[}' and `@t{]}') must appear as +balanced pairs in a subscript expression unless they are preceded by a +backslash (`@t{\}'). Therefore, within a subscript expression (and unlike +true double-quoting) the sequence `@t{\[}' becomes `@t{[}', and similarly +`@t{\]}' becomes `@t{]}'. This applies even in cases where a backslash is +not normally required; for example, the pattern `@t{[^[]}' (to match any +character other than an open bracket) should be written `@t{[^\[]}' in a +reverse-subscript pattern. However, note that `@t{\[^\[\]}' and even +`@t{\[^[]}' mean the @emph{same} thing, because backslashes are always +stripped when they appear before brackets! + +@noindent +The same rule applies to parentheses (`@t{(}' and `@t{)}') and +braces (`@t{@{}' and `@t{@}}'): 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. + +@noindent +The second difference is that a double-quote (`@t{"}') may appear as part +of a subscript expression without being preceded by a backslash, and +therefore that the two characters `@t{\"}' remain as two characters in the +subscript (in true double-quoting, `@t{\"}' becomes `@t{"}'). 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 `@t{\"}' (rather than `@t{\\\"}') for `@t{"}'. + +@noindent +To use an odd number of double quotes as a key in an assignment, use the +@t{typeset} builtin and an enclosing pair of double quotes; to refer to +the value of that key, again use double quotes: + +@noindent +@example +typeset -A aa +typeset "aa[one\"two\"three\"quotes]"=QQQ +print "$aa[one\"two\"three\"quotes]" +@end example + +@noindent +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. + +@noindent +A further complication arises from a way in which subscript parsing is +@emph{not} different from double quote parsing. As in true double-quoting, +the sequences `@t{\*}', and `@t{\@@}' remain as two characters when they +appear in a subscript expression. To use a literal `@t{*}' or `@t{@@}' as +an associative array key, the `@t{e}' flag must be used: + +@noindent +@example +typeset -A aa +aa[(e)*]=star +print $aa[(e)*] +@end example + +@noindent +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 @t{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 @emph{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 `@t{$@{(q}@t{)}@var{name}@t{@}}' (@ref{Parameter Expansion}) to quote the expanded value. + +@noindent +Note that the `@t{k}' and `@t{K}' flags are reverse subscripting for an +ordinary array, but are @emph{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.) + +@noindent +One final note, not directly related to subscripting: the numeric names +of positional parameters (@ref{Positional Parameters}) are parsed specially, so for example `@t{$2foo}' is equivalent to +`@t{$@{2@}foo}'. Therefore, to use subscript syntax to extract a substring +from a positional parameter, the expansion must be surrounded by braces; +for example, `@t{$@{2[3,5]@}}' evaluates to the third through fifth +characters of the second positional parameter, but `@t{$2[3,5]}' is the +entire second parameter concatenated with the filename generation pattern +`@t{[3,5]}'. + +@noindent +@node Positional Parameters, Local Parameters, Array Parameters, Parameters + +@section Positional Parameters +@noindent +The positional parameters provide access to the command-line arguments +of a shell function, shell script, or the shell itself; see +@ref{Invocation}, and also @ref{Functions}. +The parameter @var{n}, where @var{n} is a number, +is the @var{n}th positional parameter. +The parameter `@t{$0}' is a special case, see +@ref{Parameters Set By The Shell}. + +@noindent +The parameters @t{*}, @t{@@} and @t{argv} are +arrays containing all the positional parameters; +thus `@t{$argv[}@var{n}@t{]}', etc., is equivalent to simply `@t{$}@var{n}'. +Note that the options @t{KSH_ARRAYS} or @t{KSH_ZERO_SUBSCRIPT} apply +to these arrays as well, so with either of those options set, +`@t{$@{argv[0]@}}' is equivalent to `@t{$1}' and so on. + +@noindent +Positional parameters may be changed after the shell or function starts by +using the @t{set} builtin, by assigning to the @t{argv} array, or by direct +assignment of the form `@var{n}@t{=}@var{value}' where @var{n} is the number of +the positional parameter to be changed. This also creates (with empty +values) any of the positions from 1 to @var{n} that do not already have +values. Note that, because the positional parameters form an array, an +array assignment of the form `@var{n}@t{=(}@var{value} ...@t{)}' is +allowed, and has the effect of shifting all the values at positions greater +than @var{n} by as many positions as necessary to accommodate the new values. + +@noindent +@node Local Parameters, Parameters Set By The Shell, Positional Parameters, Parameters + +@section Local Parameters +@noindent +Shell function executions delimit scopes for shell parameters. +(Parameters are dynamically scoped.) The @t{typeset} builtin, and its +alternative forms @t{declare}, @t{integer}, @t{local} and @t{readonly} +(but not @t{export}), can be used to declare a parameter as being local +to the innermost scope. + +@noindent +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 @t{export}, +causes it to be created in the @emph{outer}most scope. + +@noindent +Local parameters disappear when their scope ends. +@t{unset} can be used to delete a parameter while it is still in scope; +any outer parameter of the same name remains hidden. + +@noindent +Special parameters may also be made local; they retain their special +attributes unless either the existing or the newly-created parameter +has the @t{-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: + +@noindent +@example +typeset PATH=/new/directory:$PATH +@end example + +@noindent +is valid for temporarily allowing the shell or programmes called from it to +find the programs in @t{/new/directory} inside a function. + +@noindent +Note that the restriction in older versions of zsh that local parameters +were never exported has been removed. + +@noindent +@node Parameters Set By The Shell, Parameters Used By The Shell, Local Parameters, Parameters + +@section Parameters Set By The Shell +@noindent +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 @t{sh} or @t{ksh} emulation mode. + +@noindent +The parameters `@t{!}', `@t{#}', `@t{*}', `@t{-}', `@t{?}', `@t{@@}', +`@t{$}', `@t{ARGC}', `@t{HISTCMD}', `@t{LINENO}', `@t{PPID}', +`@t{status}', `@t{TTYIDLE}', `@t{zsh_eval_context}', +`@t{ZSH_EVAL_CONTEXT}', and `@t{ZSH_SUBSHELL}' are read-only and thus +cannot be restored by the user, so they are not output by +`@t{typeset -p}'. This also applies to many read-only parameters loaded +from modules. + +@noindent +The following parameters are automatically set by the shell: + +@noindent +@table @asis +@vindex ! +@item @t{!} <S> +The process ID of the last command started in the background with @t{&}, +put into the background with the @t{bg} builtin, or spawned with @t{coproc}. + +@vindex # +@item @t{#} <S> +The number of positional parameters in decimal. Note that some confusion +may occur with the syntax @t{$#}@var{param} which substitutes the length of +@var{param}. Use @t{$@{#@}} to resolve ambiguities. In particular, the +sequence `@t{$#-}@var{...}' in an arithmetic expression is interpreted as +the length of the parameter @t{-}, q.v. + +@vindex ARGC +@item @t{ARGC} <S> <Z> +Same as @t{#}. + +@vindex $ +@item @t{$} <S> +The process ID of this shell, set when the shell initializes. Processes +forked from the shell without executing a new program, such as command +substitutions and commands grouped with @t{(}@var{...}@t{)}, +are subshells that duplicate the current shell, and thus substitute the +same value for @t{$$} as their parent shell. + +@vindex - +@item @t{-} <S> +Flags supplied to the shell on invocation or by the @t{set} +or @t{setopt} commands. + +@vindex * +@item @t{*} <S> +An array containing the positional parameters. + +@vindex argv +@item @t{argv} <S> <Z> +Same as @t{*}. Assigning to @t{argv} changes the local positional +parameters, but @t{argv} is @emph{not} itself a local parameter. +Deleting @t{argv} with @t{unset} in any function deletes it everywhere, +although only the innermost positional parameter array is deleted (so +@t{*} and @t{@@} in other scopes are not affected). + +@vindex @@ +@item @t{@@} <S> +Same as @t{argv[@@]}, even when @t{argv} is not set. + +@vindex ? +@item @t{?} <S> +The exit status returned by the last command. + +@vindex 0 +@item @t{0} <S> +The name used to invoke the current shell, or as set by the @t{-c} command +line option upon invocation. If the @t{FUNCTION_ARGZERO} option is set, +@t{$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. + +@vindex status +@item @t{status} <S> <Z> +Same as @t{?}. + +@vindex pipestatus +@item @t{pipestatus} <S> <Z> +An array containing the exit statuses returned by all commands in the +last pipeline. + +@vindex _ +@item @t{_} <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. + +@vindex CPUTYPE +@item @t{CPUTYPE} +The machine type (microprocessor class or machine model), +as determined at run time. + +@vindex EGID +@item @t{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 `@t{(EGID=}@var{gid}@t{; command)}' + +@noindent +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally. + +@vindex EUID +@item @t{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 `@t{(EUID=}@var{uid}@t{; command)}' + +@noindent +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally. + +@vindex ERRNO +@item @t{ERRNO} <S> +The value of @t{errno} (see 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 @t{zsh/system} module which +allows the number to be turned into a name or message. + +@noindent +To use this parameter, it must first be assigned a value (typically +0 (zero)). It is initially unset for scripting compatibility. + +@vindex FUNCNEST +@item @t{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. + +@vindex GID +@item @t{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 `@t{(GID=}@var{gid}@t{; command)}' + +@noindent +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally. + +@vindex HISTCMD +@item @t{HISTCMD} +The current history event number in an interactive shell, in other +words the event number for the command that caused @t{$HISTCMD} +to be read. If the current history event modifies the history, +@t{HISTCMD} changes to the new maximum history event number. + +@vindex HOST +@item @t{HOST} +The current hostname. + +@vindex LINENO +@item @t{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 @t{functions} builtin. + +@vindex LOGNAME +@item @t{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 @t{typeset} builtin. The value +is set to the string returned by the getlogin(3) system call +if that is available. + +@vindex MACHTYPE +@item @t{MACHTYPE} +The machine type (microprocessor class or machine model), +as determined at compile time. + +@vindex OLDPWD +@item @t{OLDPWD} +The previous working directory. This is set when the shell initializes +and whenever the directory changes. + +@vindex OPTARG +@item @t{OPTARG} <S> +The value of the last option argument processed by the @t{getopts} +command. + +@vindex OPTIND +@item @t{OPTIND} <S> +The index of the last option argument processed by the @t{getopts} +command. + +@vindex OSTYPE +@item @t{OSTYPE} +The operating system, as determined at compile time. + +@vindex PPID +@item @t{PPID} <S> +The process ID of the parent of the shell, set when the shell initializes. +As with @t{$$}, the value does not change in subshells created as a +duplicate of the current shell. + +@vindex PWD +@item @t{PWD} +The present working directory. This is set when the shell initializes +and whenever the directory changes. + +@vindex RANDOM +@item @t{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 @t{RANDOM}. + +@noindent +The values of @t{RANDOM} form an intentionally-repeatable pseudo-random +sequence; subshells that reference @t{RANDOM} will result +in identical pseudo-random values unless the value of @t{RANDOM} is +referenced or seeded in the parent shell in between subshell invocations. + +@vindex SECONDS +@item @t{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. + +@noindent +Unlike other special parameters, the type of the @t{SECONDS} parameter can +be changed using the @t{typeset} command. The type may be changed only +to one of the floating point types or back to integer. For example, +`@t{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 @t{typeset}. See +the documentation for the builtin @t{typeset} in +@ref{Shell Builtin Commands} for more details. + +@vindex SHLVL +@item @t{SHLVL} <S> +Incremented by one each time a new shell is started. + +@vindex signals +@item @t{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 +@t{HUP} is signal number 1, but is referred to as @t{$signals[2]}. This +is because of @t{EXIT} at position 1 in the array, which is used +internally by zsh but is not known to the operating system. + +@vindex TRY_BLOCK_ERROR +@item @t{TRY_BLOCK_ERROR} <S> +In an @t{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 +@ref{Complex Commands} + +@vindex TRY_BLOCK_INTERRUPT +@item @t{TRY_BLOCK_INTERRUPT} <S> +This variable works in a similar way to @t{TRY_BLOCK_ERROR}, but +represents the status of an interrupt from the signal SIGINT, which +typically comes from the keyboard when the user types @t{^C}. If set to +0, any such interrupt will be reset; otherwise, the interrupt is +propagated after the @t{always} block. + +@noindent +Note that it is possible that an interrupt arrives during the execution +of the @t{always} block; this interrupt is also propagated. + +@vindex TTY +@item @t{TTY} +The name of the tty associated with the shell, if any. + +@vindex TTYIDLE +@item @t{TTYIDLE} <S> +The idle time of the tty associated with the shell in seconds or -1 if there +is no such tty. + +@vindex UID +@item @t{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 `@t{(UID=}@var{uid}@t{; command)}' + +@noindent +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally. + +@vindex USERNAME +@item @t{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 `@t{(USERNAME=}@var{username}@t{; command)}' + +@vindex VENDOR +@item @t{VENDOR} +The vendor, as determined at compile time. + +@vindex zsh_eval_context +@vindex ZSH_EVAL_CONTEXT +@item @t{zsh_eval_context} <S> <Z> (@t{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. + +@noindent +Note that the variable does not give information on syntactic context such +as pipelines or subshells. Use @t{$ZSH_SUBSHELL} to detect subshells. + +@noindent +The context is one of the following: +@table @asis +@item @t{cmdarg} +Code specified by the @t{-c} option to the command line that invoked +the shell. + +@item @t{cmdsubst} +Command substitution using the @t{`}@var{...}@t{`} or +@t{$(}@var{...}@t{)} construct. + +@item @t{equalsubst} +File substitution using the @t{=(}@var{...}@t{)} construct. + +@item @t{eval} +Code executed by the @t{eval} builtin. + +@item @t{evalautofunc} +Code executed with the @t{KSH_AUTOLOAD} mechanism in order to define +an autoloaded function. + +@item @t{fc} +Code from the shell history executed by the @t{-e} option to the @t{fc} +builtin. + +@item @t{file} +Lines of code being read directly from a file, for example by +the @t{source} builtin. + +@item @t{filecode} +Lines of code being read from a @t{.zwc} file instead of directly +from the source file. + +@item @t{globqual} +Code executed by the @t{e} or @t{+} glob qualifier. + +@item @t{globsort} +Code executed to order files by the @t{o} glob qualifier. + +@item @t{insubst} +File substitution using the @t{<(}@var{...}@t{)} construct. + +@item @t{loadautofunc} +Code read directly from a file to define an autoloaded function. + +@item @t{outsubst} +File substitution using the @t{>(}@var{...}@t{)} construct. + +@item @t{sched} +Code executed by the @t{sched} builtin. + +@item @t{shfunc} +A shell function. + +@item @t{stty} +Code passed to @t{stty} by the @t{STTY} environment variable. +Normally this is passed directly to the system's @t{stty} command, +so this value is unlikely to be seen in practice. + +@item @t{style} +Code executed as part of a style retrieved by the @t{zstyle} builtin +from the @t{zsh/zutil} module. + +@item @t{toplevel} +The highest execution level of a script or interactive shell. + +@item @t{trap} +Code executed as a trap defined by the @t{trap} builtin. Traps +defined as functions have the context @t{shfunc}. As traps are +asynchronous they may have a different hierarchy from other +code. + +@item @t{zpty} +Code executed by the @t{zpty} builtin from the @t{zsh/zpty} module. + +@item @t{zregexparse-guard} +Code executed as a guard by the @t{zregexparse} command from the +@t{zsh/zutil} module. + +@item @t{zregexparse-action} +Code executed as an action by the @t{zregexparse} command from the +@t{zsh/zutil} module. + +@end table + +@vindex ZSH_ARGZERO +@item @t{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 @t{$0} when the @t{POSIX_ARGZERO} option is +set, but is always available. + +@vindex ZSH_EXECUTION_STRING +@item @t{ZSH_EXECUTION_STRING} +If the shell was started with the option @t{-c}, this contains +the argument passed to the option. Otherwise it is not set. + +@vindex ZSH_NAME +@item @t{ZSH_NAME} +Expands to the basename of the command used to invoke this instance +of zsh. + +@vindex ZSH_PATCHLEVEL +@item @t{ZSH_PATCHLEVEL} +The output of `@t{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 +@t{$ZSH_VERSION}. + +@item @t{zsh_scheduled_events} +See @ref{The zsh/sched Module}. + +@vindex ZSH_SCRIPT +@item @t{ZSH_SCRIPT} +If zsh was invoked to run a script, this is the name of the script, +otherwise it is unset. + +@vindex ZSH_SUBSHELL <S> +@item @t{ZSH_SUBSHELL} +Readonly integer. Initially zero, incremented each time the shell forks +to create a subshell for executing code. Hence `@t{(print $ZSH_SUBSHELL)}' +and `@t{print $(print $ZSH_SUBSHELL)}' output 1, while +`@t{( (print $ZSH_SUBSHELL) )}' outputs 2. + +@vindex ZSH_VERSION +@item @t{ZSH_VERSION} +The version number of the release of zsh. + +@end table +@node Parameters Used By The Shell, , Parameters Set By The Shell, Parameters + +@section Parameters Used By The Shell +@noindent +The following parameters are used by the shell. Again, `<S>' indicates +that the parameter is special and `<Z>' indicates that the parameter does +not exist when the shell initializes in @t{sh} or @t{ksh} emulation mode. + +@noindent +In cases where there are two parameters with an upper- and lowercase +form of the same name, such as @t{path} and @t{PATH}, the lowercase form +is an array and the uppercase form is a scalar with the elements of the +array joined together by colons. These are similar to tied parameters +created via `@t{typeset -T}'. The normal use for the colon-separated +form is for exporting to the environment, while the array form is easier +to manipulate within the shell. Note that unsetting either of the pair +will unset the other; they retain their special properties when +recreated, and recreating one of the pair will recreate the other. + +@noindent +@table @asis +@vindex ARGV0 +@item @t{ARGV0} +If exported, its value is used as the @t{argv[0]} of external commands. +Usually used in constructs like `@t{ARGV0=emacs nethack}'. + +@cindex editing over slow connection +@cindex slow connection, editing over +@vindex BAUD +@item @t{BAUD} +The rate in bits per second at which data reaches the terminal. +The line editor will use this value in order to compensate for a slow +terminal by delaying updates to the display until necessary. If the +parameter is unset or the value is zero the compensation mechanism is +turned off. The parameter is not set by default. + +@noindent +This parameter may be profitably set in some circumstances, e.g. +for slow modems dialing into a communications server, or on a slow wide +area network. It should be set to the baud +rate of the slowest part of the link for best performance. + +@vindex cdpath +@vindex CDPATH +@item @t{cdpath} <S> <Z> (@t{CDPATH} <S>) +An array (colon-separated list) +of directories specifying the search path for the @t{cd} command. + +@vindex COLUMNS +@item @t{COLUMNS} <S> +The number of columns for this terminal session. +Used for printing select lists and for the line editor. + +@vindex CORRECT_IGNORE +@item @t{CORRECT_IGNORE} +If set, is treated as a pattern during spelling correction. Any +potential correction that matches the pattern is ignored. For example, +if the value is `@t{_*}' then completion functions (which, by +convention, have names beginning with `@t{_}') will never be offered +as spelling corrections. The pattern does not apply to the correction +of file names, as applied by the @t{CORRECT_ALL} option (so with the +example just given files beginning with `@t{_}' in the current +directory would still be completed). + +@vindex CORRECT_IGNORE_FILE +@item @t{CORRECT_IGNORE_FILE} +If set, is treated as a pattern during spelling correction of file names. +Any file name that matches the pattern is never offered as a correction. +For example, if the value is `@t{.*}' then dot file names will never be +offered as spelling corrections. This is useful with the +@t{CORRECT_ALL} option. + +@vindex DIRSTACKSIZE +@item @t{DIRSTACKSIZE} +The maximum size of the directory stack, by default there is no limit. If the +stack gets larger than this, it will be truncated automatically. +This is useful with the @t{AUTO_PUSHD} option. +@pindex AUTO_PUSHD, use of + +@vindex ENV +@item @t{ENV} +If the @t{ENV} environment variable is set when zsh is invoked as @t{sh} +or @t{ksh}, @t{$ENV} is sourced after the profile scripts. The value of +@t{ENV} is subjected to parameter expansion, command substitution, and +arithmetic expansion before being interpreted as a pathname. Note that +@t{ENV} is @emph{not} used unless the shell is interactive and zsh is +emulating @cite{sh} or @cite{ksh}. + +@vindex FCEDIT +@item @t{FCEDIT} +The default editor for the @t{fc} builtin. If @t{FCEDIT} is not set, +the parameter @t{EDITOR} is used; if that is not set either, a builtin +default, usually @t{vi}, is used. + +@vindex fignore +@vindex FIGNORE +@item @t{fignore} <S> <Z> (@t{FIGNORE} <S>) +An array (colon separated list) +containing the suffixes of files to be ignored +during filename completion. However, if completion only generates files +with suffixes in this list, then these files are completed anyway. + +@vindex fpath +@vindex FPATH +@item @t{fpath} <S> <Z> (@t{FPATH} <S>) +An array (colon separated list) +of directories specifying the search path for +function definitions. This path is searched when a function +with the @t{-u} attribute is referenced. If an executable +file is found, then it is read and executed in the current environment. + +@vindex histchars +@item @t{histchars} <S> +Three characters used by the shell's history and lexical analysis +mechanism. The first character signals the start of a history +expansion (default `@t{!}'). The second character signals the +start of a quick history substitution (default `@t{^}'). The third +character is the comment character (default `@t{#}'). + +@noindent +The characters must be in the ASCII character set; any attempt to set +@t{histchars} to characters with a locale-dependent meaning will be +rejected with an error message. + +@vindex HISTCHARS +@item @t{HISTCHARS} <S> <Z> +Same as @t{histchars}. (Deprecated.) + +@vindex HISTFILE +@item @t{HISTFILE} +The file to save the history in when an interactive shell exits. +If unset, the history is not saved. + +@vindex HISTORY_IGNORE +@item @t{HISTORY_IGNORE} +If set, is treated as a pattern at the time history files are written. +Any potential history entry that matches the pattern is skipped. For +example, if the value is `@t{fc *}' then commands that invoke the +interactive history editor are never written to the history file. + +@noindent +Note that @t{HISTORY_IGNORE} defines a single pattern: to +specify alternatives use the +`@t{(}@var{first}@t{|}@var{second}@t{|}@var{...}@t{)}' syntax. + +@noindent +Compare the @t{HIST_NO_STORE} option or the @t{zshaddhistory} hook, +either of which would prevent such commands from being added to the +interactive history at all. If you wish to use @t{HISTORY_IGNORE} to +stop history being added in the first place, you can define the +following hook: + +@noindent +@example +zshaddhistory() @{ + emulate -L zsh + ## uncomment if HISTORY_IGNORE + ## should use EXTENDED_GLOB syntax + # setopt extendedglob + [[ $1 != $@{~HISTORY_IGNORE@} ]] +@} +@end example + +@vindex HISTSIZE +@item @t{HISTSIZE} <S> +The maximum number of events stored in the internal history list. +If you use the @t{HIST_EXPIRE_DUPS_FIRST} option, setting this value +larger than the @t{SAVEHIST} size will give you the difference as a +cushion for saving duplicated history events. + +@noindent +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally. + +@vindex HOME +@item @t{HOME} <S> +The default argument for the @t{cd} command. This is not set automatically +by the shell in @t{sh}, @t{ksh} or @t{csh} emulation, but it is typically +present in the environment anyway, and if it becomes set it has its usual +special behaviour. + +@vindex IFS +@item @t{IFS} <S> +Internal field separators (by default space, tab, newline and NUL), that +are used to separate words which result from +command or parameter expansion and words read by +the @t{read} builtin. Any characters from the set space, tab and +newline that appear in the IFS are called @emph{IFS white space}. +One or more IFS white space characters or one non-IFS white space +character together with any adjacent IFS white space character delimit +a field. If an IFS white space character appears twice consecutively +in the IFS, this character is treated as if it were not an IFS white +space character. + +@noindent +If the parameter is unset, the default is used. Note this has +a different effect from setting the parameter to an empty string. + +@vindex KEYBOARD_HACK +@item @t{KEYBOARD_HACK} +This variable defines a character to be removed from the end of the +command line before interpreting it (interactive shells only). It is +intended to fix the problem with keys placed annoyingly close to return +and replaces the @t{SUNKEYBOARDHACK} option which did this for +backquotes only. Should the chosen character be one of singlequote, +doublequote or backquote, there must also be an odd number of them +on the command line for the last one to be removed. + +@noindent +For backward compatibility, if the @t{SUNKEYBOARDHACK} option is +explicitly set, the value of @t{KEYBOARD_HACK} reverts to backquote. +If the option is explicitly unset, this variable is set to empty. + +@vindex KEYTIMEOUT +@item @t{KEYTIMEOUT} +The time the shell waits, in hundredths of seconds, for another key to +be pressed when reading bound multi-character sequences. + +@vindex LANG +@item @t{LANG} <S> +This variable determines the locale category for any category not +specifically selected via a variable starting with `@t{LC_}'. + +@vindex LC_ALL +@item @t{LC_ALL} <S> +This variable overrides the value of the `@t{LANG}' variable and the value +of any of the other variables starting with `@t{LC_}'. + +@vindex LC_COLLATE +@item @t{LC_COLLATE} <S> +This variable determines the locale category for character collation +information within ranges in glob brackets and for sorting. + +@vindex LC_CTYPE +@item @t{LC_CTYPE} <S> +This variable determines the locale category for character handling +functions. If the @t{MULTIBYTE} option is in effect this variable or +@t{LANG} should contain a value that reflects the character set in +use, even if it is a single-byte character set, unless only the +7-bit subset (ASCII) is used. For example, if the character set +is ISO-8859-1, a suitable value might be @t{en_US.iso88591} (certain +Linux distributions) or @t{en_US.ISO8859-1} (MacOS). + +@vindex LC_MESSAGES +@item @t{LC_MESSAGES} <S> +This variable determines the language in which messages should be +written. Note that zsh does not use message catalogs. + +@vindex LC_NUMERIC +@item @t{LC_NUMERIC} <S> +This variable affects the decimal point character and thousands +separator character for the formatted input/output functions +and string conversion functions. Note that zsh ignores this +setting when parsing floating point mathematical expressions. + +@vindex LC_TIME +@item @t{LC_TIME} <S> +This variable determines the locale category for date and time +formatting in prompt escape sequences. + +@vindex LINES +@item @t{LINES} <S> +The number of lines for this terminal session. +Used for printing select lists and for the line editor. + +@vindex LISTMAX +@item @t{LISTMAX} +In the line editor, the number of matches to list without asking +first. If the value is negative, the list will be shown if it spans at +most as many lines as given by the absolute value. +If set to zero, the shell asks only if the top of the listing would scroll +off the screen. + +@vindex MAIL +@item @t{MAIL} +If this parameter is set and @t{mailpath} is not set, +the shell looks for mail in the specified file. + +@vindex MAILCHECK +@item @t{MAILCHECK} +The interval in seconds between checks for new mail. + +@vindex mailpath +@vindex MAILPATH +@item @t{mailpath} <S> <Z> (@t{MAILPATH} <S>) +An array (colon-separated list) of filenames to check for +new mail. Each filename can be followed by a `@t{?}' and a +message that will be printed. The message will undergo +parameter expansion, command substitution and arithmetic +expansion with the variable @t{$_} defined as the name +of the file that has changed. The default message is +`@t{You have new mail}'. If an element is a directory +instead of a file the shell will recursively check every +file in every subdirectory of the element. + +@vindex manpath +@vindex MANPATH +@item @t{manpath} <S> <Z> (@t{MANPATH} <S> <Z>) +An array (colon-separated list) +whose value is not used by the shell. The @t{manpath} +array can be useful, however, since setting it also sets +@t{MANPATH}, and vice versa. + +@item @t{match} +@itemx @t{mbegin} +@itemx @t{mend} +Arrays set by the shell when the @t{b} globbing flag is used in pattern +matches. See the subsection @emph{Globbing flags} in +@ref{Filename Generation}. + +@item @t{MATCH} +@itemx @t{MBEGIN} +@itemx @t{MEND} +Set by the shell when the @t{m} globbing flag is used in pattern +matches. See the subsection @emph{Globbing flags} in +@ref{Filename Generation}. + +@vindex module_path +@vindex MODULE_PATH +@item @t{module_path} <S> <Z> (@t{MODULE_PATH} <S>) +An array (colon-separated list) +of directories that @t{zmodload} +searches for dynamically loadable modules. +This is initialized to a standard pathname, +usually `@t{/usr/local/lib/zsh/$ZSH_VERSION}'. +(The `@t{/usr/local/lib}' part varies from installation to installation.) +For security reasons, any value set in the environment when the shell +is started will be ignored. + +@noindent +These parameters only exist if the installation supports dynamic +module loading. + +@vindex NULLCMD +@cindex null command style +@cindex csh, null command style +@cindex ksh, null command style +@item @t{NULLCMD} <S> +The command name to assume if a redirection is specified +with no command. Defaults to @t{cat}. For @cite{sh}/@cite{ksh} +behavior, change this to @t{:}. For @cite{csh}-like +behavior, unset this parameter; the shell will print an +error message if null commands are entered. + +@vindex path +@vindex PATH +@item @t{path} <S> <Z> (@t{PATH} <S>) +An array (colon-separated list) +of directories to search for commands. +When this parameter is set, each directory is scanned +and all files found are put in a hash table. + +@vindex POSTEDIT +@item @t{POSTEDIT} <S> +This string is output whenever the line editor exits. +It usually contains termcap strings to reset the terminal. + +@vindex PROMPT +@item @t{PROMPT} <S> <Z> +@vindex PROMPT2 +@itemx @t{PROMPT2} <S> <Z> +@vindex PROMPT3 +@itemx @t{PROMPT3} <S> <Z> +@vindex PROMPT4 +@itemx @t{PROMPT4} <S> <Z> +Same as @t{PS1}, @t{PS2}, @t{PS3} and @t{PS4}, +respectively. + +@vindex prompt +@item @t{prompt} <S> <Z> +Same as @t{PS1}. + +@vindex PROMPT_EOL_MARK +@item @t{PROMPT_EOL_MARK} +When the @t{PROMPT_CR} and @t{PROMPT_SP} options are set, the +@t{PROMPT_EOL_MARK} parameter can be used to customize how the end of +partial lines are shown. This parameter undergoes prompt expansion, with +the @t{PROMPT_PERCENT} option set. If not set, the default behavior is +equivalent to the value `@t{%B%S%#%s%b}'. + +@vindex PS1 +@item @t{PS1} <S> +The primary prompt string, printed before a command is read. +It undergoes a special form of expansion +before being displayed; see +@ref{Prompt Expansion}. The default is `@t{%m%# }'. + +@vindex PS2 +@item @t{PS2} <S> +The secondary prompt, printed when the shell needs more information +to complete a command. +It is expanded in the same way as @t{PS1}. +The default is `@t{%_> }', which displays any shell constructs or quotation +marks which are currently being processed. + +@vindex PS3 +@item @t{PS3} <S> +Selection prompt used within a @t{select} loop. +It is expanded in the same way as @t{PS1}. +The default is `@t{?# }'. + +@vindex PS4 +@item @t{PS4} <S> +The execution trace prompt. Default is `@t{+%N:%i> }', which displays +the name of the current shell structure and the line number within it. +In sh or ksh emulation, the default is `@t{+ }'. + +@vindex psvar +@vindex PSVAR +@item @t{psvar} <S> <Z> (@t{PSVAR} <S>) +An array (colon-separated list) whose elements can be used in +@t{PROMPT} strings. Setting @t{psvar} also sets @t{PSVAR}, and +vice versa. + +@vindex READNULLCMD +@item @t{READNULLCMD} <S> +The command name to assume if a single input redirection +is specified with no command. Defaults to @t{more}. + +@vindex REPORTMEMORY +@item @t{REPORTMEMORY} +If nonnegative, commands whose maximum resident set size (roughly +speaking, main memory usage) in kilobytes is greater than this +value have timing statistics reported. The format used to output +statistics is the value of the @t{TIMEFMT} parameter, which is the same +as for the @t{REPORTTIME} variable and the @t{time} builtin; note that +by default this does not output memory usage. Appending +@t{" max RSS %M"} to the value of @t{TIMEFMT} causes it to output the +value that triggered the report. If @t{REPORTTIME} is also in use, +at most a single report is printed for both triggers. This feature +requires the @t{getrusage()} system call, commonly supported by +modern Unix-like systems. + +@vindex REPORTTIME +@item @t{REPORTTIME} +If nonnegative, commands whose combined user and system execution times +(measured in seconds) are greater than this value have timing +statistics printed for them. Output is suppressed for commands +executed within the line editor, including completion; commands +explicitly marked with the @t{time} keyword still cause the summary +to be printed in this case. + +@vindex REPLY +@item @t{REPLY} +This parameter is reserved by convention to pass string values between +shell scripts and shell builtins in situations where a function call or +redirection are impossible or undesirable. The @t{read} builtin and the +@t{select} complex command may set @t{REPLY}, and filename generation both +sets and examines its value when evaluating certain expressions. Some +modules also employ @t{REPLY} for similar purposes. + +@vindex reply +@item @t{reply} +As @t{REPLY}, but for array values rather than strings. + +@vindex RPROMPT +@item @t{RPROMPT} <S> +@vindex RPS1 +@itemx @t{RPS1} <S> +This prompt is displayed on the right-hand side of the screen +when the primary prompt is being displayed on the left. +This does not work if the @t{SINGLE_LINE_ZLE} option is set. +It is expanded in the same way as @t{PS1}. + +@vindex RPROMPT2 +@item @t{RPROMPT2} <S> +@vindex RPS2 +@itemx @t{RPS2} <S> +This prompt is displayed on the right-hand side of the screen +when the secondary prompt is being displayed on the left. +This does not work if the @t{SINGLE_LINE_ZLE} option is set. +It is expanded in the same way as @t{PS2}. + +@vindex SAVEHIST +@item @t{SAVEHIST} +The maximum number of history events to save in the history file. + +@noindent +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally. + +@vindex SPROMPT +@item @t{SPROMPT} <S> +The prompt used for spelling correction. The sequence +`@t{%R}' expands to the string which presumably needs spelling +correction, and `@t{%r}' expands to the proposed correction. +All other prompt escapes are also allowed. + +@noindent +The actions available at the prompt are @t{[nyae]}: +@table @asis +@item @t{n} (`no') (default) +Discard the correction and run the command. +@item @t{y} (`yes') +Make the correction and run the command. +@item @t{a} (`abort') +Discard the entire command line without running it. +@item @t{e} (`edit') +Resume editing the command line. +@end table + +@vindex STTY +@item @t{STTY} +If this parameter is set in a command's environment, the shell runs the +@t{stty} command with the value of this parameter as arguments in order to +set up the terminal before executing the command. The modes apply only to the +command, and are reset when it finishes or is suspended. If the command is +suspended and continued later with the @t{fg} or @t{wait} builtins it will +see the modes specified by @t{STTY}, as if it were not suspended. This +(intentionally) does not apply if the command is continued via `@t{kill +-CONT}'. @t{STTY} is ignored if the command is run in the background, or +if it is in the environment of the shell but not explicitly assigned to in +the input line. This avoids running stty at every external command by +accidentally exporting it. Also note that @t{STTY} should not be used for +window size specifications; these will not be local to the command. + +@noindent +If the parameter is set and empty, all of the above applies except +that @t{stty} is not run. This can be useful as a way to freeze the tty +around a single command, blocking its changes to tty settings, +similar to the @t{ttyctl} builtin. + +@vindex TERM +@item @t{TERM} <S> +The type of terminal in use. This is used when looking up termcap +sequences. An assignment to @t{TERM} causes zsh to re-initialize the +terminal, even if the value does not change (e.g., `@t{TERM=$TERM}'). It +is necessary to make such an assignment upon any change to the terminal +definition database or terminal type in order for the new settings to +take effect. + +@vindex TERMINFO +@item @t{TERMINFO} <S> +A reference to your terminfo database, used by the `terminfo' library when the +system has it; see terminfo(5). +If set, this causes the shell to reinitialise the terminal, making the +workaround `@t{TERM=$TERM}' unnecessary. + +@vindex TERMINFO_DIRS +@item @t{TERMINFO_DIRS} <S> +A colon-seprarated list of terminfo databases, used by the `terminfo' library +when the system has it; see terminfo(5). This variable is only +used by certain terminal libraries, in particular ncurses; see +terminfo(5) to check support on your system. If set, this +causes the shell to reinitialise the terminal, making the workaround +`@t{TERM=$TERM}' unnecessary. Note that unlike other colon-separated +arrays this is not tied to a zsh array. + +@vindex TIMEFMT +@item @t{TIMEFMT} +The format of process time reports with the @t{time} keyword. +The default is `@t{%J %U user %S system %P cpu %*E total}'. +Recognizes the following escape sequences, although not all +may be available on all systems, and some that are available +may not be useful: + +@noindent +@table @asis +@item @t{%%} +A `@t{%}'. +@item @t{%U} +CPU seconds spent in user mode. +@item @t{%S} +CPU seconds spent in kernel mode. +@item @t{%E} +Elapsed time in seconds. +@item @t{%P} +The CPU percentage, computed as +100*(@t{%U}+@t{%S})/@t{%E}. +@item @t{%W} +Number of times the process was swapped. +@item @t{%X} +The average amount in (shared) text space used in kilobytes. +@item @t{%D} +The average amount in (unshared) data/stack space used in +kilobytes. +@item @t{%K} +The total space used (@t{%X}+@t{%D}) in kilobytes. +@item @t{%M} +The maximum memory the process had in use at any time in +kilobytes. +@item @t{%F} +The number of major page faults (page needed to be brought +from disk). +@item @t{%R} +The number of minor page faults. +@item @t{%I} +The number of input operations. +@item @t{%O} +The number of output operations. +@item @t{%r} +The number of socket messages received. +@item @t{%s} +The number of socket messages sent. +@item @t{%k} +The number of signals received. +@item @t{%w} +Number of voluntary context switches (waits). +@item @t{%c} +Number of involuntary context switches. +@item @t{%J} +The name of this job. +@end table + +@noindent +A star may be inserted between the percent sign and flags printing time +(e.g., `@t{%*E}'); this causes the time to be printed in +`@var{hh}@t{:}@var{mm}@t{:}@var{ss}@t{.}@var{ttt}' +format (hours and minutes are only printed if they are not zero). +Alternatively, `@t{m}' or `@t{u}' may be used (e.g., `@t{%mE}') to produce +time output in milliseconds or microseconds, respectively. + +@vindex TMOUT +@item @t{TMOUT} +If this parameter is nonzero, the shell will receive an @t{ALRM} +signal if a command is not entered within the specified number of +seconds after issuing a prompt. If there is a trap on @t{SIGALRM}, it +will be executed and a new alarm is scheduled using the value of the +@t{TMOUT} parameter after executing the trap. If no trap is set, and +the idle time of the terminal is not less than the value of the +@t{TMOUT} parameter, zsh terminates. Otherwise a new alarm is +scheduled to @t{TMOUT} seconds after the last keypress. + +@vindex TMPPREFIX +@item @t{TMPPREFIX} +A pathname prefix which the shell will use for all temporary files. +Note that this should include an initial part for the file name as +well as any directory names. The default is `@t{/tmp/zsh}'. + +@vindex TMPSUFFIX +@item @t{TMPSUFFIX} +A filename suffix which the shell will use for temporary files created +by process substitutions (e.g., `@t{=(@var{list})}'). +Note that the value should include a leading dot `@t{.}' if intended +to be interpreted as a file extension. The default is not to append +any suffix, thus this parameter should be assigned only when needed +and then unset again. + +@vindex WORDCHARS +@item @t{WORDCHARS} <S> +A list of non-alphanumeric characters considered part of a word +by the line editor. + +@vindex ZBEEP +@item @t{ZBEEP} +If set, this gives a string of characters, which can use all the same codes +as the @t{bindkey} command as described in +@ref{The zsh/zle Module}, that will be output to the terminal +instead of beeping. This may have a visible instead of an audible effect; +for example, the string `@t{\e[?5h\e[?5l}' on a vt100 or xterm will have +the effect of flashing reverse video on and off (if you usually use reverse +video, you should use the string `@t{\e[?5l\e[?5h}' instead). This takes +precedence over the @t{NOBEEP} option. + +@vindex ZDOTDIR +@item @t{ZDOTDIR} +The directory to search for shell startup files (.zshrc, etc), +if not @t{$HOME}. + +@vindex zle_bracketed_paste +@cindex bracketed paste +@cindex enabling bracketed paste +@item @t{zle_bracketed_paste} +Many terminal emulators have a feature that allows applications to +identify when text is pasted into the terminal rather than being typed +normally. For ZLE, this means that special characters such as tabs +and newlines can be inserted instead of invoking editor commands. +Furthermore, pasted text forms a single undo event and if the region is +active, pasted text will replace the region. + +@noindent +This two-element array contains the terminal escape sequences for +enabling and disabling the feature. These escape sequences are used to +enable bracketed paste when ZLE is active and disable it at other times. +Unsetting the parameter has the effect of ensuring that bracketed paste +remains disabled. + +@vindex zle_highlight +@item @t{zle_highlight} +An array describing contexts in which ZLE should highlight the input text. +See @ref{Character Highlighting}. + +@vindex ZLE_LINE_ABORTED +@item @t{ZLE_LINE_ABORTED} +This parameter is set by the line editor when an error occurs. It +contains the line that was being edited at the point of the error. +`@t{print -zr -- $ZLE_LINE_ABORTED}' can be used to recover the line. +Only the most recent line of this kind is remembered. + +@vindex ZLE_REMOVE_SUFFIX_CHARS +@vindex ZLE_SPACE_SUFFIX_CHARS +@item @t{ZLE_REMOVE_SUFFIX_CHARS} +@itemx @t{ZLE_SPACE_SUFFIX_CHARS} +These parameters are used by the line editor. In certain circumstances +suffixes (typically space or slash) added by the completion system +will be removed automatically, either because the next editing command +was not an insertable character, or because the character was marked +as requiring the suffix to be removed. + +@noindent +These variables can contain the sets of characters that will cause the +suffix to be removed. If @t{ZLE_REMOVE_SUFFIX_CHARS} is set, those +characters will cause the suffix to be removed; if +@t{ZLE_SPACE_SUFFIX_CHARS} is set, those characters will cause the +suffix to be removed and replaced by a space. + +@noindent +If @t{ZLE_REMOVE_SUFFIX_CHARS} is not set, the default behaviour is +equivalent to: + +@noindent +@example +ZLE_REMOVE_SUFFIX_CHARS=$' \t\n;&|' +@end example + +@noindent +If @t{ZLE_REMOVE_SUFFIX_CHARS} is set but is empty, no characters have this +behaviour. @t{ZLE_SPACE_SUFFIX_CHARS} takes precedence, so that the +following: + +@noindent +@example +ZLE_SPACE_SUFFIX_CHARS=$'&|' +@end example + +@noindent +causes the characters `@t{&}' and `@t{|}' to remove the suffix but to +replace it with a space. + +@noindent +To illustrate the difference, suppose that the option @t{AUTO_REMOVE_SLASH} +is in effect and the directory @t{DIR} has just been completed, with an +appended @t{/}, following which the user types `@t{&}'. The default result +is `@t{DIR&}'. With @t{ZLE_REMOVE_SUFFIX_CHARS} set but without including +`@t{&}' the result is `@t{DIR/&}'. With @t{ZLE_SPACE_SUFFIX_CHARS} set to +include `@t{&}' the result is `@t{DIR &}'. + +@noindent +Note that certain completions may provide their own suffix removal +or replacement behaviour which overrides the values described here. +See the completion system documentation in +@ref{Completion System}. + +@vindex ZLE_RPROMPT_INDENT +@item @t{ZLE_RPROMPT_INDENT} <S> +If set, used to give the indentation between the right hand side of +the right prompt in the line editor as given by @t{RPS1} or @t{RPROMPT} +and the right hand side of the screen. If not set, the value 1 is used. + +@noindent +Typically this will be used to set the value to 0 so that the prompt +appears flush with the right hand side of the screen. This is not the +default as many terminals do not handle this correctly, in particular +when the prompt appears at the extreme bottom right of the screen. +Recent virtual terminals are more likely to handle this case correctly. +Some experimentation is necessary. + +@end table +@c (avoiding a yodl bug) +@c Yodl file: Zsh/options.yo +@node Options, Shell Builtin Commands, Parameters, Top + +@chapter Options +@noindent +@cindex options +@menu +* Specifying Options:: +* Description of Options:: +* Option Aliases:: +* Single Letter Options:: +@end menu +@node Specifying Options, Description of Options, , Options + +@section Specifying Options +@noindent +@cindex options, specifying +Options are primarily referred to by name. +These names are case insensitive and underscores are ignored. +For example, `@t{allexport}' is equivalent to `@t{A__lleXP_ort}'. + +@noindent +The sense of an option name may be inverted by preceding it with +`@t{no}', so `@t{setopt No_Beep}' is equivalent to `@t{unsetopt beep}'. +This inversion can only be done once, so `@t{nonobeep}' is @emph{not} +a synonym for `@t{beep}'. Similarly, `@t{tify}' is not a synonym for +`@t{nonotify}' (the inversion of `@t{notify}'). + +@noindent +Some options also have one or more single letter names. +There are two sets of single letter options: one used by default, +and another used to emulate @cite{sh}/@cite{ksh} (used when the +@t{SH_OPTION_LETTERS} option is set). +The single letter options can be used on the shell command line, +or with the @t{set}, @t{setopt} and @t{unsetopt} +builtins, as normal Unix options preceded by `@t{-}'. + +@noindent +The sense of the single letter options may be inverted by using +`@t{+}' instead of `@t{-}'. +Some of the single letter option names refer to an option being off, +in which case the inversion of that name refers to the option being on. +For example, `@t{+n}' is the short name of `@t{exec}', and +`@t{-n}' is the short name of its inversion, `@t{noexec}'. + +@noindent +In strings of single letter options supplied to the shell at startup, +trailing whitespace will be ignored; for example the string `@t{-f }' +will be treated just as `@t{-f}', but the string `@t{-f i}' is an error. +This is because many systems which implement the `@t{#!}' mechanism for +calling scripts do not strip trailing whitespace. + +@noindent +It is possible for options to be set within a function scope. See the +description of the option @t{LOCAL_OPTIONS} below. + +@noindent +@node Description of Options, Option Aliases, Specifying Options, Options + +@section Description of Options +@noindent +@cindex options, description +In the following list, options set by default in all emulations are marked +<D>; those set by default only in csh, ksh, sh, or zsh emulations are marked +<C>, <K>, <S>, <Z> as appropriate. When listing options (by `@t{setopt}', +`@t{unsetopt}', `@t{set -o}' or `@t{set +o}'), those turned on by default +appear in the list prefixed with `@t{no}'. Hence (unless +@t{KSH_OPTION_PRINT} is set), `@t{setopt}' shows all options whose settings +are changed from the default. + +@noindent + +@subsection Changing Directories +@noindent +@table @asis +@pindex AUTO_CD +@pindex NO_AUTO_CD +@pindex AUTOCD +@pindex NOAUTOCD +@cindex cd, automatic +@item @t{AUTO_CD} (@t{-J}) +If a command is issued that can't be executed as a normal command, +and the command is the name of a directory, perform the @t{cd} +command to that directory. +This option is only applicable if the option @t{SHIN_STDIN} is set, +i.e. if commands are being read from standard input. The option +is designed for interactive use; it is recommended that @t{cd} +be used explicitly in scripts to avoid ambiguity. + +@pindex AUTO_PUSHD +@pindex NO_AUTO_PUSHD +@pindex AUTOPUSHD +@pindex NOAUTOPUSHD +@cindex cd, behaving like pushd +@cindex pushd, making cd behave like +@item @t{AUTO_PUSHD} (@t{-N}) +Make @t{cd} push the old directory onto the directory stack. + +@pindex CDABLE_VARS +@pindex NO_CDABLE_VARS +@pindex CDABLEVARS +@pindex NOCDABLEVARS +@cindex cd, to parameter +@item @t{CDABLE_VARS} (@t{-T}) +If the argument to a @t{cd} command (or an implied @t{cd} with the +@t{AUTO_CD} option set) is not a directory, and does not begin with a +slash, try to expand the expression as if it were preceded by a `@t{~}' (see +@ref{Filename Expansion}). + +@pindex CD_SILENT +@pindex NO_CD_SILENT +@pindex CDSILENT +@pindex NOCDSILENT +@cindex cd, silencing +@cindex autocd, silencing +@item @t{CD_SILENT} +Never print the working directory after a @t{cd} (whether explicit or +implied with the @t{AUTO_CD} option set). @t{cd} normally prints the +working directory when the argument given to it was @t{-}, a stack entry, or +the name of a directory found under @t{CDPATH}. Note that this is distinct +from @t{pushd}'s stack-printing behaviour, which is controlled by +@t{PUSHD_SILENT}. This option overrides the printing-related effects of +@t{POSIX_CD}. + +@pindex CHASE_DOTS +@pindex NO_CHASE_DOTS +@pindex CHASEDOTS +@pindex NOCHASEDOTS +@cindex cd, with .. in argument +@item @t{CHASE_DOTS} +When changing to a directory containing a path segment `@t{..}' which would +otherwise be treated as canceling the previous segment in the path (in +other words, `@t{foo/..}' would be removed from the path, or if `@t{..}' is +the first part of the path, the last part of the current working directory +would be removed), instead resolve the path to the physical directory. +This option is overridden by @t{CHASE_LINKS}. + +@noindent +For example, suppose @t{/foo/bar} is a link to the directory @t{/alt/rod}. +Without this option set, `@t{cd /foo/bar/..}' changes to @t{/foo}; with it +set, it changes to @t{/alt}. The same applies if the current directory +is @t{/foo/bar} and `@t{cd ..}' is used. Note that all other symbolic +links in the path will also be resolved. + +@pindex CHASE_LINKS +@pindex NO_CHASE_LINKS +@pindex CHASELINKS +@pindex NOCHASELINKS +@cindex links, symbolic +@cindex symbolic links +@item @t{CHASE_LINKS} (@t{-w}) +Resolve symbolic links to their true values when changing directory. +This also has the effect of @t{CHASE_DOTS}, i.e. a `@t{..}' path segment +will be treated as referring to the physical parent, even if the preceding +path segment is a symbolic link. + +@pindex POSIX_CD +@pindex POSIXCD +@pindex NO_POSIX_CD +@pindex NOPOSIXCD +@cindex CDPATH, order of checking +@item @t{POSIX_CD} <K> <S> +Modifies the behaviour of @t{cd}, @t{chdir} and @t{pushd} commands +to make them more compatible with the POSIX standard. The behaviour with +the option unset is described in the documentation for the @t{cd} +builtin in +@ref{Shell Builtin Commands}. +If the option is set, the shell does not test for directories beneath +the local directory (`@t{.}') until after all directories in @t{cdpath} +have been tested, and the @t{cd} and @t{chdir} commands do not recognise +arguments of the form `@{@t{+}|@t{-}@}@var{n}' as directory stack entries. + +@noindent +Also, if the option is set, the conditions under which the shell +prints the new directory after changing to it are modified. It is +no longer restricted to interactive shells (although printing of +the directory stack with @t{pushd} is still limited to interactive +shells); and any use of a component of @t{CDPATH}, including a `@t{.}' but +excluding an empty component that is otherwise treated as `@t{.}', causes +the directory to be printed. + +@pindex PUSHD_IGNORE_DUPS +@pindex NO_PUSHD_IGNORE_DUPS +@pindex PUSHDIGNOREDUPS +@pindex NOPUSHDIGNOREDUPS +@cindex directory stack, ignoring duplicates +@item @t{PUSHD_IGNORE_DUPS} +Don't push multiple copies of the same directory onto the directory stack. + +@pindex PUSHD_MINUS +@pindex NO_PUSHD_MINUS +@pindex PUSHDMINUS +@pindex NOPUSHDMINUS +@cindex directory stack, controlling syntax +@item @t{PUSHD_MINUS} +Exchanges the meanings of `@t{+}' and `@t{-}' +when used with a number to specify a directory in the stack. + +@pindex PUSHD_SILENT +@pindex NO_PUSHD_SILENT +@pindex PUSHDSILENT +@pindex NOPUSHDSILENT +@cindex directory stack, silencing +@item @t{PUSHD_SILENT} (@t{-E}) +Do not print the directory stack after @t{pushd} or @t{popd}. + +@pindex PUSHD_TO_HOME +@pindex NO_PUSHD_TO_HOME +@pindex PUSHDTOHOME +@pindex NOPUSHDTOHOME +@cindex pushd, to home +@item @t{PUSHD_TO_HOME} (@t{-D}) +Have @t{pushd} with no arguments act like `@t{pushd $HOME}'. + +@end table + +@noindent + +@subsection Completion +@noindent +@table @asis +@pindex ALWAYS_LAST_PROMPT +@pindex NO_ALWAYS_LAST_PROMPT +@pindex ALWAYSLASTPROMPT +@pindex NOALWAYSLASTPROMPT +@item @t{ALWAYS_LAST_PROMPT} <D> +If unset, key functions that list completions try to return to the last +prompt if given a numeric argument. If set these functions try to +return to the last prompt if given @emph{no} numeric argument. + +@pindex ALWAYS_TO_END +@pindex NO_ALWAYS_TO_END +@pindex ALWAYSTOEND +@pindex NOALWAYSTOEND +@item @t{ALWAYS_TO_END} +If a completion is performed with the cursor within a word, and a +full completion is inserted, the cursor is moved to the end of the +word. That is, the cursor is moved to the end of the word if either +a single match is inserted or menu completion is performed. + +@pindex AUTO_LIST +@pindex NO_AUTO_LIST +@pindex AUTOLIST +@pindex NOAUTOLIST +@cindex completion, listing choices +@item @t{AUTO_LIST} (@t{-9}) <D> +Automatically list choices on an ambiguous completion. + +@pindex AUTO_MENU +@pindex NO_AUTO_MENU +@pindex AUTOMENU +@pindex NOAUTOMENU +@cindex completion, menu +@item @t{AUTO_MENU} <D> +Automatically use menu completion after the second consecutive request for +completion, for example by pressing the tab key repeatedly. This option +is overridden by @t{MENU_COMPLETE}. + +@pindex AUTO_NAME_DIRS +@pindex NO_AUTO_NAME_DIRS +@pindex AUTONAMEDIRS +@pindex NOAUTONAMEDIRS +@cindex directories, named +@item @t{AUTO_NAME_DIRS} +Any parameter that is set to the absolute name of a directory +immediately becomes a name for that directory, that will be used +by the `@t{%~}' +and related prompt sequences, and will be available when completion +is performed on a word starting with `@t{~}'. +(Otherwise, the parameter must be used in the form `@t{~}@var{param}' first.) + +@pindex AUTO_PARAM_KEYS +@pindex NO_AUTO_PARAM_KEYS +@pindex AUTOPARAMKEYS +@pindex NOAUTOPARAMKEYS +@item @t{AUTO_PARAM_KEYS} <D> +If a parameter name was completed and a following character +(normally a space) automatically +inserted, and the next character typed is one +of those that have to come directly after the name (like `@t{@}}', `@t{:}', +etc.), the automatically added character is deleted, so that the character +typed comes immediately after the parameter name. +Completion in a brace expansion is affected similarly: the added character +is a `@t{,}', which will be removed if `@t{@}}' is typed next. + +@pindex AUTO_PARAM_SLASH +@pindex NO_AUTO_PARAM_SLASH +@pindex AUTOPARAMSLASH +@pindex NOAUTOPARAMSLASH +@item @t{AUTO_PARAM_SLASH} <D> +If a parameter is completed whose content is the name of a directory, +then add a trailing slash instead of a space. + +@pindex AUTO_REMOVE_SLASH +@pindex NO_AUTO_REMOVE_SLASH +@pindex AUTOREMOVESLASH +@pindex NOAUTOREMOVESLASH +@cindex slash, removing trailing +@item @t{AUTO_REMOVE_SLASH} <D> +When the last character resulting from a completion is a slash and the next +character typed is a word delimiter, a slash, or a character that ends +a command (such as a semicolon or an ampersand), remove the slash. + +@pindex BASH_AUTO_LIST +@pindex NO_BASH_AUTO_LIST +@pindex BASHAUTOLIST +@pindex NOBASHAUTOLIST +@cindex completion, listing choices, bash style +@item @t{BASH_AUTO_LIST} +On an ambiguous completion, automatically list choices when the +completion function is called twice in succession. This takes +precedence over @t{AUTO_LIST}. The setting of @t{LIST_AMBIGUOUS} is +respected. If @t{AUTO_MENU} is set, the menu behaviour will then start +with the third press. Note that this will not work with +@t{MENU_COMPLETE}, since repeated completion calls immediately cycle +through the list in that case. + +@pindex COMPLETE_ALIASES +@pindex NO_COMPLETE_ALIASES +@pindex COMPLETEALIASES +@pindex NOCOMPLETEALIASES +@cindex aliases, completion of +@item @t{COMPLETE_ALIASES} +Prevents aliases on the command line from being internally substituted +before completion is attempted. The effect is to make the alias a +distinct command for completion purposes. + +@pindex COMPLETE_IN_WORD +@pindex NO_COMPLETE_IN_WORD +@pindex COMPLETEINWORD +@pindex NOCOMPLETEINWORD +@item @t{COMPLETE_IN_WORD} +If unset, the cursor is set to the end of the word if completion is +started. Otherwise it stays there and completion is done from both ends. + +@pindex GLOB_COMPLETE +@pindex NO_GLOB_COMPLETE +@pindex GLOBCOMPLETE +@pindex NOGLOBCOMPLETE +@item @t{GLOB_COMPLETE} +When the current word has a glob pattern, do not insert all the words +resulting from the expansion but generate matches as for completion and +cycle through them like @t{MENU_COMPLETE}. The matches are generated as if +a `@t{*}' was added to the end of the word, or inserted at the cursor when +@t{COMPLETE_IN_WORD} is set. This actually uses pattern matching, not +globbing, so it works not only for files but for any completion, such as +options, user names, etc. + +@noindent +Note that when the pattern matcher is used, matching control (for example, +case-insensitive or anchored matching) cannot be used. This limitation +only applies when the current word contains a pattern; simply turning +on the @t{GLOB_COMPLETE} option does not have this effect. + +@pindex HASH_LIST_ALL +@pindex NO_HASH_LIST_ALL +@pindex HASHLISTALL +@pindex NOHASHLISTALL +@item @t{HASH_LIST_ALL} <D> +Whenever a command completion or spelling correction is attempted, make +sure the entire command path is hashed first. This makes the first +completion slower but avoids false reports of spelling errors. + +@pindex LIST_AMBIGUOUS +@pindex NO_LIST_AMBIGUOUS +@pindex LISTAMBIGUOUS +@pindex NOLISTAMBIGUOUS +@cindex ambiguous completion +@cindex completion, ambiguous +@item @t{LIST_AMBIGUOUS} <D> +This option works when @t{AUTO_LIST} or @t{BASH_AUTO_LIST} is also +set. If there is an unambiguous prefix to insert on the command line, +that is done without a completion list being displayed; in other +words, auto-listing behaviour only takes place when nothing would be +inserted. In the case of @t{BASH_AUTO_LIST}, this means that the list +will be delayed to the third call of the function. + +@pindex LIST_BEEP +@pindex NO_LIST_BEEP +@pindex LISTBEEP +@pindex NOLISTBEEP +@cindex beep, ambiguous completion +@cindex completion, beep on ambiguous +@item @t{LIST_BEEP} <D> +Beep on an ambiguous completion. More accurately, this forces the +completion widgets to return status 1 on an ambiguous completion, which +causes the shell to beep if the option @t{BEEP} is also set; this may +be modified if completion is called from a user-defined widget. + +@pindex LIST_PACKED +@pindex NO_LIST_PACKED +@pindex LISTPACKED +@pindex NOLISTPACKED +@cindex completion, listing +@item @t{LIST_PACKED} +Try to make the completion list smaller (occupying less lines) by +printing the matches in columns with different widths. + +@pindex LIST_ROWS_FIRST +@pindex NO_LIST_ROWS_FIRST +@pindex LISTROWSFIRST +@pindex NOLISTROWSFIRST +@cindex completion, listing order +@item @t{LIST_ROWS_FIRST} +Lay out the matches in completion lists sorted horizontally, that is, +the second match is to the right of the first one, not under it as +usual. + +@pindex LIST_TYPES +@pindex NO_LIST_TYPES +@pindex LISTTYPES +@pindex NOLISTTYPES +@cindex marking file types +@cindex files, marking type of +@item @t{LIST_TYPES} (@t{-X}) <D> +When listing files that are possible completions, show the +type of each file with a trailing identifying mark. + +@pindex MENU_COMPLETE +@pindex NO_MENU_COMPLETE +@pindex MENUCOMPLETE +@pindex NOMENUCOMPLETE +@cindex completion, menu +@item @t{MENU_COMPLETE} (@t{-Y}) +On an ambiguous completion, instead of listing possibilities or beeping, +insert the first match immediately. Then when completion is requested +again, remove the first match and insert the second match, etc. +When there are no more matches, go back to the first one again. +@t{reverse-menu-complete} may be used to loop through the list +in the other direction. This option overrides @t{AUTO_MENU}. + +@pindex REC_EXACT +@pindex NO_REC_EXACT +@pindex RECEXACT +@pindex NORECEXACT +@cindex completion, exact matches +@item @t{REC_EXACT} (@t{-S}) +If the string on the command line exactly matches one of the possible +completions, it is accepted, even if there is another completion (i.e. that +string with something else added) that also matches. + +@end table + +@noindent + +@subsection Expansion and Globbing +@noindent +@table @asis +@pindex BAD_PATTERN +@pindex NO_BAD_PATTERN +@pindex BADPATTERN +@pindex NOBADPATTERN +@cindex globbing, bad pattern +@cindex filename generation, bad pattern +@item @t{BAD_PATTERN} (@t{+2}) <C> <Z> +If a pattern for filename generation is badly formed, print an error message. +(If this option is unset, the pattern will be left unchanged.) + +@pindex BARE_GLOB_QUAL +@pindex NO_BARE_GLOB_QUAL +@pindex BAREGLOBQUAL +@pindex NOBAREGLOBQUAL +@cindex globbing qualifiers, enable +@cindex enable globbing qualifiers +@item @t{BARE_GLOB_QUAL} <Z> +In a glob pattern, treat a trailing set of parentheses as a qualifier +list, if it contains no `@t{|}', `@t{(}' or (if special) `@t{~}' +characters. See @ref{Filename Generation}. + +@pindex BRACE_CCL +@pindex NO_BRACE_CCL +@pindex BRACECCL +@pindex NOBRACECCL +@cindex brace expansion, extending +@cindex expansion, brace, extending +@item @t{BRACE_CCL} +Expand expressions in braces which would not otherwise undergo brace +expansion to a lexically ordered list of all the characters. See +@ref{Brace Expansion}. + +@pindex CASE_GLOB +@pindex NO_CASE_GLOB +@pindex CASEGLOB +@pindex NOCASEGLOB +@cindex case-insensitive globbing, option +@item @t{CASE_GLOB} <D> +Make globbing (filename generation) sensitive to case. Note that other +uses of patterns are always sensitive to case. If the option is unset, +the presence of any character which is special to filename generation +will cause case-insensitive matching. For example, @t{cvs(/)} +can match the directory @t{CVS} owing to the presence of the globbing flag +(unless the option @t{BARE_GLOB_QUAL} is unset). + +@pindex CASE_MATCH +@pindex NO_CASE_MATCH +@pindex CASEMATCH +@pindex NOCASEMATCH +@cindex case-insensitive regular expression matches, option +@cindex regular expressions, case-insensitive matching, option +@item @t{CASE_MATCH} <D> +Make regular expressions using the @t{zsh/regex} module (including +matches with @t{=~}) sensitive to case. + +@pindex CASE_PATHS +@pindex NO_CASE_PATHS +@pindex CASEPATHS +@pindex NOCASEPATHS +@cindex case-sensitive globbing, option +@item @t{CASE_PATHS} +If @t{CASE_PATHS} is not set (the default), @t{CASE_GLOB} affects the +interpretation of @emph{every} path component, whenever a special +character appears in @emph{any} component. When @t{CASE_PATHS} is set, +file path components that do @emph{not} contain special filename +generation characters are always sensitive to case, thus restricting +@t{NO_CASE_GLOB} to components that contain globbing characters. + +@noindent +Note that if the filesystem itself is not sensitive to case, then +@t{CASE_PATHS} has no effect. + +@pindex CSH_NULL_GLOB +@pindex NO_CSH_NULL_GLOB +@pindex CSHNULLGLOB +@pindex NOCSHNULLGLOB +@cindex csh, null globbing style +@cindex null globbing style, csh +@cindex globbing, null, style, csh +@item @t{CSH_NULL_GLOB} <C> +If a pattern for filename generation has no matches, +delete the pattern from the argument list; +do not report an error unless all the patterns +in a command have no matches. +Overrides @t{NOMATCH}. + +@pindex EQUALS +@pindex NO_EQUALS +@pindex NOEQUALS +@cindex filename expansion, = +@item @t{EQUALS} <Z> +Perform @t{=} filename expansion. +(See @ref{Filename Expansion}.) + +@pindex EXTENDED_GLOB +@pindex NO_EXTENDED_GLOB +@pindex EXTENDEDGLOB +@pindex NOEXTENDEDGLOB +@cindex globbing, extended +@item @t{EXTENDED_GLOB} +Treat the `@t{#}', `@t{~}' and `@t{^}' characters as part of patterns +for filename generation, etc. (An initial unquoted `@t{~}' +always produces named directory expansion.) + +@pindex FORCE_FLOAT +@pindex NO_FORCE_FLOAT +@pindex FORCEFLOAT +@pindex NOFORCEFLOAT +@cindex floating point, forcing use of +@cindex forcing use of floating point +@item @t{FORCE_FLOAT} +Constants in arithmetic evaluation will be treated as +floating point even without the use of a decimal point; the +values of integer variables will be converted to floating point when +used in arithmetic expressions. Integers in any base will be converted. + +@pindex GLOB +@pindex NO_GLOB +@pindex NOGLOB +@cindex globbing, enabling +@cindex enabling globbing +@item @t{GLOB} (@t{+F}, ksh: @t{+f}) <D> +Perform filename generation (globbing). +(See @ref{Filename Generation}.) + +@pindex GLOB_ASSIGN +@pindex NO_GLOB_ASSIGN +@pindex GLOBASSIGN +@pindex NOGLOBASSIGN +@item @t{GLOB_ASSIGN} <C> +If this option is set, filename generation (globbing) is +performed on the right hand side of scalar parameter assignments of +the form `@var{name}@t{=}@var{pattern} (e.g. `@t{foo=*}'). +If the result has more than one word the parameter will become an array +with those words as arguments. This option is provided for backwards +compatibility only: globbing is always performed on the right hand side +of array assignments of the form `@var{name}@t{=(}@var{value}@t{)}' +(e.g. `@t{foo=(*)}') and this form is recommended for clarity; +with this option set, it is not possible to predict whether the result +will be an array or a scalar. + +@pindex GLOB_DOTS +@pindex NO_GLOB_DOTS +@pindex GLOBDOTS +@pindex NOGLOBDOTS +@cindex globbing, of . files +@item @t{GLOB_DOTS} (@t{-4}) +Do not require a leading `@t{.}' in a filename to be matched explicitly. + +@pindex GLOB_STAR_SHORT +@pindex NO_GLOB_STAR_SHORT +@pindex GLOBSTARSHORT +@pindex NOGLOBSTARSHORT +@cindex globbing, short forms +@cindex globbing, ** special +@item @t{GLOB_STAR_SHORT} +When this option is set and the default zsh-style globbing is in +effect, the pattern `@t{**/*}' can be abbreviated to `@t{**}' and the +pattern `@t{***/*}' can be abbreviated to @t{***}. Hence `@t{**.c}' +finds a file ending in @t{.c} in any subdirectory, and `@t{***.c}' does +the same while also following symbolic links. A @t{/} immediately +after the `@t{**}' or `@t{***}' forces the pattern to be treated as the +unabbreviated form. + +@pindex GLOB_SUBST +@pindex NO_GLOB_SUBST +@pindex GLOBSUBST +@pindex NOGLOBSUBST +@item @t{GLOB_SUBST} <C> <K> <S> +Treat any characters resulting from parameter expansion as being +eligible for filename expansion and filename generation, and any +characters resulting from command substitution as being eligible for +filename generation. Braces (and commas in between) do not become eligible +for expansion. + +@pindex HIST_SUBST_PATTERN +@pindex NO_HIST_SUBST_PATTERN +@pindex HISTSUBSTPATTERN +@pindex NOHISTSUBSTPATTERN +@item @t{HIST_SUBST_PATTERN} +Substitutions using the @t{:s} and @t{:&} history modifiers are performed +with pattern matching instead of string matching. This occurs wherever +history modifiers are valid, including glob qualifiers and parameters. +See +@ref{Modifiers}. + +@pindex IGNORE_BRACES +@pindex NO_IGNORE_BRACES +@pindex IGNOREBRACES +@pindex NOIGNOREBRACES +@cindex disabling brace expansion +@cindex brace expansion, disabling +@cindex expansion, brace, disabling +@item @t{IGNORE_BRACES} (@t{-I}) <S> +Do not perform brace expansion. For historical reasons this +also includes the effect of the @t{IGNORE_CLOSE_BRACES} option. + +@pindex IGNORE_CLOSE_BRACES +@pindex NO_IGNORE_CLOSE_BRACES +@pindex IGNORECLOSEBRACES +@pindex NOIGNORECLOSEBRACES +@item @t{IGNORE_CLOSE_BRACES} +When neither this option nor @t{IGNORE_BRACES} is set, a sole +close brace character `@t{@}}' is syntactically significant at any +point on a command line. This has the effect that no semicolon +or newline is necessary before the brace terminating a function +or current shell construct. When either option is set, a closing brace +is syntactically significant only in command position. Unlike +@t{IGNORE_BRACES}, this option does not disable brace expansion. + +@noindent +For example, with both options unset a function may be defined +in the following fashion: + +@noindent +@example +args() @{ echo $# @} +@end example + +@noindent +while if either option is set, this does not work and something +equivalent to the following is required: + +@noindent +@example +args() @{ echo $#; @} +@end example + +@noindent + +@pindex KSH_GLOB +@pindex NO_KSH_GLOB +@pindex KSHGLOB +@pindex NOKSHGLOB +@item @t{KSH_GLOB} <K> +In pattern matching, the interpretation of parentheses is affected by +a preceding `@t{@@}', `@t{*}', `@t{+}', `@t{?}' or `@t{!}'. +See @ref{Filename Generation}. + +@pindex MAGIC_EQUAL_SUBST +@pindex NO_MAGIC_EQUAL_SUBST +@pindex MAGICEQUALSUBST +@pindex NOMAGICEQUALSUBST +@item @t{MAGIC_EQUAL_SUBST} +All unquoted arguments of the form `@var{anything}@t{=}@var{expression}' +appearing after the command name have filename expansion (that is, +where @var{expression} has a leading `@t{~}' or `@t{=}') performed on +@var{expression} as if it were a parameter assignment. The argument is +not otherwise treated specially; it is passed to the command as a single +argument, and not used as an actual parameter assignment. For example, in +@t{echo foo=~/bar:~/rod}, both occurrences of @t{~} would be replaced. +Note that this happens anyway with @t{typeset} and similar statements. + +@noindent +This option respects the setting of the @t{KSH_TYPESET} option. In other +words, if both options are in effect, arguments looking like +assignments will not undergo word splitting. + +@pindex MARK_DIRS +@pindex NO_MARK_DIRS +@pindex MARKDIRS +@pindex NOMARKDIRS +@cindex directories, marking +@cindex marking directories +@item @t{MARK_DIRS} (@t{-8}, ksh: @t{-X}) +Append a trailing `@t{/}' to all directory +names resulting from filename generation (globbing). + +@pindex MULTIBYTE +@pindex NO_MULTIBYTE +@pindex NOMULTIBYTE +@cindex characters, multibyte, in expansion and globbing +@cindex multibyte characters, in expansion and globbing +@item @t{MULTIBYTE} <D> +Respect multibyte characters when found in strings. +When this option is set, strings are examined using the +system library to determine how many bytes form a character, depending +on the current locale. This affects the way characters are counted in +pattern matching, parameter values and various delimiters. + +@noindent +The option is on by default if the shell was compiled with +@t{MULTIBYTE_SUPPORT}; otherwise it is off by default and has no effect +if turned on. + +@noindent +If the option is off a single byte is always treated as a single +character. This setting is designed purely for examining strings +known to contain raw bytes or other values that may not be characters +in the current locale. It is not necessary to unset the option merely +because the character set for the current locale does not contain multibyte +characters. + +@noindent +The option does not affect the shell's editor, which always uses the +locale to determine multibyte characters. This is because +the character set displayed by the terminal emulator is independent of +shell settings. + +@pindex NOMATCH +@pindex NO_NOMATCH +@pindex NONOMATCH +@cindex globbing, no matches +@item @t{NOMATCH} (@t{+3}) <C> <Z> +If a pattern for filename generation has no matches, +print an error, instead of +leaving it unchanged in the argument list. +This also applies to file expansion +of an initial `@t{~}' or `@t{=}'. + +@pindex NULL_GLOB +@pindex NO_NULL_GLOB +@pindex NULLGLOB +@pindex NONULLGLOB +@cindex globbing, no matches +@item @t{NULL_GLOB} (@t{-G}) +If a pattern for filename generation has no matches, +delete the pattern from the argument list instead +of reporting an error. Overrides @t{NOMATCH}. + +@pindex NUMERIC_GLOB_SORT +@pindex NO_NUMERIC_GLOB_SORT +@pindex NUMERICGLOBSORT +@pindex NONUMERICGLOBSORT +@cindex globbing, sorting numerically +@item @t{NUMERIC_GLOB_SORT} +If numeric filenames are matched by a filename generation pattern, +sort the filenames numerically rather than lexicographically. + +@pindex RC_EXPAND_PARAM +@pindex NO_RC_EXPAND_PARAM +@pindex RCEXPANDPARAM +@pindex NORCEXPANDPARAM +@cindex rc, parameter expansion style +@cindex parameter expansion style, rc +@item @t{RC_EXPAND_PARAM} (@t{-P}) +Array expansions of the form +`@var{foo}@t{$@{}@var{xx}@t{@}}@var{bar}', where the parameter +@var{xx} is set to @t{(}@var{a b c}@t{)}, are substituted with +`@var{fooabar foobbar foocbar}' instead of the default +`@var{fooa b cbar}'. Note that an empty array will therefore cause +all arguments to be removed. + +@pindex REMATCH_PCRE +@pindex NO_REMATCH_PCRE +@pindex REMATCHPCRE +@pindex NOREMATCHPCRE +@cindex regexp, PCRE +@cindex PCRE, regexp +@item @t{REMATCH_PCRE} +If set, regular expression matching with the @t{=~} operator will use +Perl-Compatible Regular Expressions from the PCRE library. +(The @t{zsh/pcre} module must be available.) +If not set, regular expressions will use the extended regexp syntax +provided by the system libraries. + +@pindex SH_GLOB +@pindex NO_SH_GLOB +@pindex SHGLOB +@pindex NOSHGLOB +@cindex sh, globbing style +@cindex globbing style, sh +@item @t{SH_GLOB} <K> <S> +Disables the special meaning of `@t{(}', `@t{|}', `@t{)}' +and '@t{<}' for globbing the result of parameter and command substitutions, +and in some other places where +the shell accepts patterns. If @t{SH_GLOB} is set but @t{KSH_GLOB} is +not, the shell allows the interpretation of +subshell expressions enclosed in parentheses in some cases where there +is no space before the opening parenthesis, e.g. @t{!(true)} +is interpreted as if there were a space after the @t{!}. This option is +set by default if zsh is invoked as @t{sh} or @t{ksh}. + +@pindex UNSET +@pindex NO_UNSET +@pindex NOUNSET +@cindex parameters, substituting unset +@cindex unset parameters, substituting +@item @t{UNSET} (@t{+u}, ksh: @t{+u}) <K> <S> <Z> +Treat unset parameters as if they were empty when substituting, and as if +they were zero when reading their values in arithmetic expansion and +arithmetic commands. +Otherwise they are treated as an error. + +@pindex WARN_CREATE_GLOBAL +@pindex NO_WARN_CREATE_GLOBAL +@pindex WARNCREATEGLOBAL +@pindex NOWARNCREATEGLOBAL +@cindex parameters, warning when created globally +@item @t{WARN_CREATE_GLOBAL} +Print a warning message when a global parameter is created in a function +by an assignment or in math context. +This often indicates that a parameter has not been +declared local when it should have been. Parameters explicitly declared +global from within a function using @t{typeset -g} do not cause a warning. +Note that there is no warning when a local parameter is assigned to in +a nested function, which may also indicate an error. + +@pindex WARN_NESTED_VAR +@pindex NO_WARN_NESTED_VAR +@pindex WARNNESTEDVAR +@pindex NO_WARNNESTEDVAR +@cindex parameters, warning when setting in enclosing scope +@item @t{WARN_NESTED_VAR} +Print a warning message when an existing parameter from an +enclosing function scope, or global, is set in a function +by an assignment or in math context. Assignment to shell +special parameters does not cause a warning. This is the companion +to @t{WARN_CREATE_GLOBAL} as in this case the warning is only +printed when a parameter is @emph{not} created. Where possible, +use of @t{typeset -g} to set the parameter suppresses the error, +but note that this needs to be used every time the parameter is set. +To restrict the effect of this option to a single function scope, +use `@t{functions -W}'. + +@noindent +For example, the following code produces a warning for the assignment +inside the function @t{nested} as that overrides the value within +@t{toplevel} + +@noindent +@example +toplevel() @{ + local foo="in fn" + nested +@} +nested() @{ + foo="in nested" +@} +setopt warn_nested_var +toplevel +@end example + +@end table + +@noindent + +@subsection History +@noindent +@table @asis +@pindex APPEND_HISTORY +@pindex NO_APPEND_HISTORY +@pindex APPENDHISTORY +@pindex NOAPPENDHISTORY +@cindex history, appending to a file +@item @t{APPEND_HISTORY} <D> +If this is set, zsh sessions will append their history list to +the history file, rather than replace it. Thus, multiple parallel +zsh sessions will all have the new entries from their history lists +added to the history file, in the order that they exit. +The file will still be periodically re-written to trim it when the +number of lines grows 20% beyond the value specified by +@t{$SAVEHIST} (see also the @t{HIST_SAVE_BY_COPY} option). + +@pindex BANG_HIST +@pindex NO_BANG_HIST +@pindex BANGHIST +@pindex NOBANGHIST +@cindex history, enable substitution +@cindex enable history substitution +@item @t{BANG_HIST} (@t{+K}) <C> <Z> +Perform textual history expansion, @cite{csh}-style, +treating the character `@t{!}' specially. + +@pindex EXTENDED_HISTORY +@pindex NO_EXTENDED_HISTORY +@pindex EXTENDEDHISTORY +@pindex NOEXTENDEDHISTORY +@cindex history, timestamping +@item @t{EXTENDED_HISTORY} <C> +Save each command's beginning timestamp (in seconds since the epoch) +and the duration (in seconds) to the history file. The format of +this prefixed data is: + +@noindent +`@t{: }@var{<beginning time>}@t{:}@var{<elapsed seconds>}@t{;}@var{<command>}'. + +@pindex HIST_ALLOW_CLOBBER +@pindex NO_HIST_ALLOW_CLOBBER +@pindex HISTALLOWCLOBBER +@pindex NOHISTALLOWCLOBBER +@item @t{HIST_ALLOW_CLOBBER} +Add `@t{|}' to output redirections in the history. This allows history +references to clobber files even when @t{CLOBBER} is unset. + +@pindex HIST_BEEP +@pindex NO_HIST_BEEP +@pindex HISTBEEP +@pindex NOHISTBEEP +@cindex history beeping +@cindex beep, history +@item @t{HIST_BEEP} <D> +Beep in ZLE when a widget attempts to access a history entry which +isn't there. + +@pindex HIST_EXPIRE_DUPS_FIRST +@pindex NO_HIST_EXPIRE_DUPS_FIRST +@pindex HISTEXPIREDUPSFIRST +@pindex NOHISTEXPIREDUPSFIRST +@cindex history, expiring duplicates +@item @t{HIST_EXPIRE_DUPS_FIRST} +If the internal history needs to be trimmed to add the current command line, +setting this option will cause the oldest history event that has a duplicate +to be lost before losing a unique event from the list. +You should be sure to set the value of @t{HISTSIZE} to a larger number +than @t{SAVEHIST} in order to give you some room for the duplicated +events, otherwise this option will behave just like +@t{HIST_IGNORE_ALL_DUPS} once the history fills up with unique events. + +@pindex HIST_FCNTL_LOCK +@pindex NO_HIST_FCNTL_LOCK +@pindex HISTFCNTLLOCK +@pindex NOHISTFCNTLLOCK +@item @t{HIST_FCNTL_LOCK} +When writing out the history file, by default zsh uses ad-hoc file locking +to avoid known problems with locking on some operating systems. With this +option locking is done by means of the system's @t{fcntl} call, where +this method is available. On recent operating systems this may +provide better performance, in particular avoiding history corruption when +files are stored on NFS. + +@pindex HIST_FIND_NO_DUPS +@pindex NO_HIST_FIND_NO_DUPS +@pindex HISTFINDNODUPS +@pindex NOHISTFINDNODUPS +@cindex history, ignoring duplicates in search +@item @t{HIST_FIND_NO_DUPS} +When searching for history entries in the line editor, do not display +duplicates of a line previously found, even if the duplicates are not +contiguous. + +@pindex HIST_IGNORE_ALL_DUPS +@pindex NO_HIST_IGNORE_ALL_DUPS +@pindex HISTIGNOREALLDUPS +@pindex NOHISTIGNOREALLDUPS +@cindex history, ignoring all duplicates +@item @t{HIST_IGNORE_ALL_DUPS} +If a new command line being added to the history list duplicates an +older one, the older command is removed from the list (even if it is +not the previous event). + +@pindex HIST_IGNORE_DUPS +@pindex NO_HIST_IGNORE_DUPS +@pindex HISTIGNOREDUPS +@pindex NOHISTIGNOREDUPS +@cindex history, ignoring duplicates +@item @t{HIST_IGNORE_DUPS} (@t{-h}) +Do not enter command lines into the history list +if they are duplicates of the previous event. + +@pindex HIST_IGNORE_SPACE +@pindex NO_HIST_IGNORE_SPACE +@pindex HISTIGNORESPACE +@pindex NOHISTIGNORESPACE +@cindex history, ignoring spaces +@item @t{HIST_IGNORE_SPACE} (@t{-g}) +Remove command lines from the history list when the first character on +the line is a space, or when one of the expanded aliases contains a +leading space. Only normal aliases (not global or suffix aliases) +have this behaviour. +Note that the command lingers in the internal history until the next +command is entered before it vanishes, allowing you to briefly reuse +or edit the line. If you want to make it vanish right away without +entering another command, type a space and press return. + +@pindex HIST_LEX_WORDS +@pindex NO_HIST_LEX_WORDS +@pindex HISTLEXWORDS +@pindex NOHISTLEXWORDS +@item @t{HIST_LEX_WORDS} +By default, shell history that is read in from files is split into +words on all white space. This means that arguments with quoted +whitespace are not correctly handled, with the consequence that +references to words in history lines that have been read from a file +may be inaccurate. When this option is set, words read in from a +history file are divided up in a similar fashion to normal shell +command line handling. Although this produces more accurately delimited +words, if the size of the history file is large this can be slow. Trial +and error is necessary to decide. + +@pindex HIST_NO_FUNCTIONS +@pindex NO_HIST_NO_FUNCTIONS +@pindex HISTNOFUNCTIONS +@pindex NOHISTNOFUNCTIONS +@item @t{HIST_NO_FUNCTIONS} +Remove function definitions from the history list. +Note that the function lingers in the internal history until the next +command is entered before it vanishes, allowing you to briefly reuse +or edit the definition. + +@pindex HIST_NO_STORE +@pindex NO_HIST_NO_STORE +@pindex HISTNOSTORE +@pindex NOHISTNOSTORE +@item @t{HIST_NO_STORE} +Remove the @t{history} (@t{fc -l}) command from the history list +when invoked. +Note that the command lingers in the internal history until the next +command is entered before it vanishes, allowing you to briefly reuse +or edit the line. + +@pindex HIST_REDUCE_BLANKS +@pindex NO_HIST_REDUCE_BLANKS +@pindex HISTREDUCEBLANKS +@pindex NOHISTREDUCEBLANKS +@item @t{HIST_REDUCE_BLANKS} +Remove superfluous blanks from each command line +being added to the history list. + +@pindex HIST_SAVE_BY_COPY +@pindex NO_HIST_SAVE_BY_COPY +@pindex HISTSAVEBYCOPY +@pindex NOHISTSAVEBYCOPY +@item @t{HIST_SAVE_BY_COPY} <D> +When the history file is re-written, we normally write out a copy of +the file named @t{$HISTFILE.new} and then rename it over the old one. +However, if this option is unset, we instead truncate the old +history file and write out the new version in-place. If one of the +history-appending options is enabled, this option only has an effect +when the enlarged history file needs to be re-written to trim it +down to size. Disable this only if you have special needs, as doing +so makes it possible to lose history entries if zsh gets interrupted +during the save. + +@noindent +When writing out a copy of the history file, zsh preserves the old +file's permissions and group information, but will refuse to write +out a new file if it would change the history file's owner. + +@pindex HIST_SAVE_NO_DUPS +@pindex NO_HIST_SAVE_NO_DUPS +@pindex HISTSAVENODUPS +@pindex NOHISTSAVENODUPS +@item @t{HIST_SAVE_NO_DUPS} +When writing out the history file, older commands that duplicate +newer ones are omitted. + +@pindex HIST_VERIFY +@pindex NO_HIST_VERIFY +@pindex HISTVERIFY +@pindex NOHISTVERIFY +@cindex history, verifying substitution +@item @t{HIST_VERIFY} +Whenever the user enters a line with history expansion, +don't execute the line directly; instead, perform +history expansion and reload the line into the editing buffer. + +@pindex INC_APPEND_HISTORY +@pindex NO_INC_APPEND_HISTORY +@pindex INCAPPENDHISTORY +@pindex NOINCAPPENDHISTORY +@cindex history, incremental appending to a file +@item @t{INC_APPEND_HISTORY} +This option works like @t{APPEND_HISTORY} except that new history lines +are added to the @t{$HISTFILE} incrementally (as soon as they are +entered), rather than waiting until the shell exits. +The file will still be periodically re-written to trim it when the +number of lines grows 20% beyond the value specified by +@t{$SAVEHIST} (see also the @t{HIST_SAVE_BY_COPY} option). + +@pindex INC_APPEND_HISTORY_TIME +@pindex NO_INC_APPEND_HISTORY_TIME +@pindex INCAPPENDHISTORYTIME +@pindex NOINCAPPENDHISTORYTIME +@cindex history, incremental appending to a file with time +@item @t{INC_APPEND_HISTORY_TIME} +This option is a variant of @t{INC_APPEND_HISTORY} in which, where +possible, the history entry is written out to the file after the +command is finished, so that the time taken by the command is recorded +correctly in the history file in @t{EXTENDED_HISTORY} format. This +means that the history entry will not be available immediately from +other instances of the shell that are using the same history file. + +@noindent +This option is only useful if @t{INC_APPEND_HISTORY} and +@t{SHARE_HISTORY} are turned off. The three options should be +considered mutually exclusive. + +@pindex SHARE_HISTORY +@pindex NO_SHARE_HISTORY +@pindex SHAREHISTORY +@pindex NOSHAREHISTORY +@cindex share history +@cindex history, sharing +@item @t{SHARE_HISTORY} <K> + +@noindent +This option both imports new commands from the history file, and also +causes your typed commands to be appended to the history file (the +latter is like specifying @t{INC_APPEND_HISTORY}, which should be turned +off if this option is in effect). The history lines are also output +with timestamps ala @t{EXTENDED_HISTORY} (which makes it easier to find +the spot where we left off reading the file after it gets re-written). + +@noindent +By default, history movement commands visit the imported lines as +well as the local lines, but you can toggle this on and off with the +set-local-history zle binding. It is also possible to create a zle +widget that will make some commands ignore imported commands, and +some include them. + +@noindent +If you find that you want more control over when commands +get imported, you may wish to turn @t{SHARE_HISTORY} off, +@t{INC_APPEND_HISTORY} or @t{INC_APPEND_HISTORY_TIME} (see above) on, +and then manually import commands whenever you need them using `@t{fc +-RI}'. + +@end table + +@noindent + +@subsection Initialisation +@noindent +@table @asis +@pindex ALL_EXPORT +@pindex NO_ALL_EXPORT +@pindex ALLEXPORT +@pindex NOALLEXPORT +@cindex export, automatic +@item @t{ALL_EXPORT} (@t{-a}, ksh: @t{-a}) +All parameters subsequently defined are automatically exported. + +@pindex GLOBAL_EXPORT +@pindex NO_GLOBAL_EXPORT +@pindex GLOBALEXPORT +@pindex NOGLOBALEXPORT +@cindex environment, and local parameters +@item @t{GLOBAL_EXPORT} <Z> +If this option is set, passing the @t{-x} flag to the builtins @t{declare}, +@t{float}, @t{integer}, @t{readonly} and @t{typeset} (but not @t{local}) +will also set the @t{-g} flag; hence parameters exported to +the environment will not be made local to the enclosing function, unless +they were already or the flag @t{+g} is given explicitly. If the option is +unset, exported parameters will be made local in just the same way as any +other parameter. + +@noindent +This option is set by default for backward compatibility; it is not +recommended that its behaviour be relied upon. Note that the builtin +@t{export} always sets both the @t{-x} and @t{-g} flags, and hence its +effect extends beyond the scope of the enclosing function; this is the +most portable way to achieve this behaviour. + +@cindex exporting, and local parameters +@pindex GLOBAL_RCS +@pindex NO_GLOBAL_RCS +@pindex GLOBALRCS +@pindex NOGLOBALRCS +@cindex startup files, global, inhibiting +@cindex files, global startup, inhibiting +@item @t{GLOBAL_RCS} (@t{+d}) <D> +If this option is unset, the startup files @t{/etc/zprofile}, +@t{/etc/zshrc}, @t{/etc/zlogin} and @t{/etc/zlogout} will not be run. It +can be disabled and re-enabled at any time, including inside local startup +files (@t{.zshrc}, etc.). + +@pindex RCS +@pindex NO_RCS +@pindex NORCS +@cindex startup files, sourcing +@item @t{RCS} (@t{+f}) <D> +After @t{/etc/zshenv} is sourced on startup, source the +@t{.zshenv}, @t{/etc/zprofile}, @t{.zprofile}, +@t{/etc/zshrc}, @t{.zshrc}, @t{/etc/zlogin}, @t{.zlogin}, and @t{.zlogout} +files, as described in @ref{Files}. +If this option is unset, the @t{/etc/zshenv} file is still sourced, but any +of the others will not be; it can be set at any time to prevent the +remaining startup files after the currently executing one from +being sourced. + +@end table + +@noindent + +@subsection Input/Output +@noindent +@table @asis +@pindex ALIASES +@pindex NO_ALIASES +@pindex NOALIASES +@cindex aliases, expansion +@item @t{ALIASES} <D> +Expand aliases. + +@pindex CLOBBER +@pindex NO_CLOBBER +@pindex NOCLOBBER +@cindex clobbering, of files +@cindex file clobbering, allowing +@item @t{CLOBBER} (@t{+C}, ksh: @t{+C}) <D> +Allows `@t{>}' redirection to truncate existing files. +Otherwise `@t{>!}' or `@t{>|}' must be used to truncate a file. + +@noindent +If the option is not set, and the option @t{APPEND_CREATE} is also +not set, `@t{>>!}' or `@t{>>|}' must be used to create a file. +If either option is set, `@t{>>}' may be used. + +@pindex CLOBBER_EMPTY +@pindex NO_CLOBBER_EMPTY +@pindex CLOBBEREMPTY +@pindex NOCLOBBEREMPTY +@cindex clobbering, of empty files +@cindex file clobbering, of empty files +@item @t{CLOBBER_EMPTY} +This option is only used if the option @t{CLOBBER} is not set: note that +it is set by default. + +@noindent +If this option is set, then regular files of zero length may be +ovewritten (`clobbered'). Note that it is possible another process +has written to the file between this test and use of the file by +the current process. This option should therefore not be used in +cases where files to be clobbered may be written to asynchronously. + +@pindex CORRECT +@pindex NO_CORRECT +@pindex NOCORRECT +@cindex correction, spelling +@cindex spelling correction +@item @t{CORRECT} (@t{-0}) +Try to correct the spelling of commands. +Note that, when the @t{HASH_LIST_ALL} option is not set or when some +directories in the path are not readable, this may falsely report spelling +errors the first time some commands are used. + +@noindent +The shell variable @t{CORRECT_IGNORE} may be set to a pattern to +match words that will never be offered as corrections. + +@pindex CORRECT_ALL +@pindex NO_CORRECT_ALL +@pindex CORRECTALL +@pindex NOCORRECTALL +@item @t{CORRECT_ALL} (@t{-O}) +Try to correct the spelling of all arguments in a line. + +@noindent +The shell variable @t{CORRECT_IGNORE_FILE} may be set to a pattern to +match file names that will never be offered as corrections. + +@pindex DVORAK +@pindex NO_DVORAK +@pindex NODVORAK +@item @t{DVORAK} +Use the Dvorak keyboard instead of the standard qwerty keyboard as a basis +for examining spelling mistakes for the @t{CORRECT} and @t{CORRECT_ALL} +options and the @t{spell-word} editor command. + +@pindex FLOW_CONTROL +@pindex NO_FLOW_CONTROL +@pindex FLOWCONTROL +@pindex NOFLOWCONTROL +@cindex flow control +@item @t{FLOW_CONTROL} <D> +If this option is unset, +output flow control via start/stop characters (usually assigned to +^S/^Q) is disabled in the shell's editor. + +@pindex IGNORE_EOF +@pindex NO_IGNORE_EOF +@pindex IGNOREEOF +@pindex NOIGNOREEOF +@cindex EOF, ignoring +@item @t{IGNORE_EOF} (@t{-7}) +Do not exit on end-of-file. Require the use +of @t{exit} or @t{logout} instead. +However, ten consecutive EOFs will cause the shell to exit anyway, +to avoid the shell hanging if its tty goes away. + +@noindent +Also, if this option is set and the Zsh Line Editor is used, widgets +implemented by shell functions can be bound to EOF (normally +Control-D) without printing the normal warning message. This works +only for normal widgets, not for completion widgets. + +@pindex INTERACTIVE_COMMENTS +@pindex NO_INTERACTIVE_COMMENTS +@pindex INTERACTIVECOMMENTS +@pindex NOINTERACTIVECOMMENTS +@cindex comments, in interactive shells +@item @t{INTERACTIVE_COMMENTS} (@t{-k}) <K> <S> +Allow comments even in interactive shells. + +@pindex HASH_CMDS +@pindex NO_HASH_CMDS +@pindex HASHCMDS +@pindex NOHASHCMDS +@cindex hashing, of commands +@cindex command hashing +@item @t{HASH_CMDS} <D> +Note the location of each command the first time it is executed. +Subsequent invocations of the same command will use the +saved location, avoiding a path search. +If this option is unset, no path hashing is done at all. +However, when @t{CORRECT} is set, commands whose names do not appear in +the functions or aliases hash tables are hashed in order to avoid +reporting them as spelling errors. + +@pindex HASH_DIRS +@pindex NO_HASH_DIRS +@pindex HASHDIRS +@pindex NOHASHDIRS +@cindex hashing, of directories +@cindex directories, hashing +@item @t{HASH_DIRS} <D> +Whenever a command name is hashed, hash the directory containing it, +as well as all directories that occur earlier in the path. +Has no effect if neither @t{HASH_CMDS} nor @t{CORRECT} is set. + +@pindex HASH_EXECUTABLES_ONLY +@pindex NO_HASH_EXECUTABLES_ONLY +@pindex HASHEXECUTABLESONLY +@pindex NOHASHEXECUTABLESONLY +@cindex hashing, of executables +@cindex executables, hashing +@item @t{HASH_EXECUTABLES_ONLY} +When hashing commands because of @t{HASH_CMDS}, check that the +file to be hashed is actually an executable. This option +is unset by default as if the path contains a large number of commands, +or consists of many remote files, the additional tests can take +a long time. Trial and error is needed to show if this option is +beneficial. + +@pindex MAIL_WARNING +@pindex NO_MAIL_WARNING +@pindex MAILWARNING +@pindex NOMAILWARNING +@cindex mail, warning of reading +@item @t{MAIL_WARNING} (@t{-U}) +Print a warning message if a mail file has been +accessed since the shell last checked. + +@pindex PATH_DIRS +@pindex NO_PATH_DIRS +@pindex PATHDIRS +@pindex NOPATHDIRS +@cindex path search, extended +@item @t{PATH_DIRS} (@t{-Q}) +Perform a path search even on command names with slashes in them. +Thus if `@t{/usr/local/bin}' is in the user's path, and he or she types +`@t{X11/xinit}', the command `@t{/usr/local/bin/X11/xinit}' will be executed +(assuming it exists). +Commands explicitly beginning with `@t{/}', `@t{./}' or `@t{../}' +are not subject to the path search. +This also applies to the `@t{.}' and @t{source} builtins. + +@noindent +Note that subdirectories of the current directory are always searched for +executables specified in this form. This takes place before any search +indicated by this option, and regardless of whether `@t{.}' or the current +directory appear in the command search path. + +@pindex PATH_SCRIPT +@pindex NO_PATH_SCRIPT +@pindex PATHSCRIPT +@pindex NOPATHSCRIPT +@cindex path search, for script argument to shell +@item @t{PATH_SCRIPT} <K> <S> +If this option is not set, a script passed as the first non-option argument +to the shell must contain the name of the file to open. If this +option is set, and the script does not specify a directory path, +the script is looked for first in the current directory, then in the +command path. See +@ref{Invocation}. + +@pindex PRINT_EIGHT_BIT +@pindex NO_PRINT_EIGHT_BIT +@pindex PRINTEIGHTBIT +@pindex NOPRINTEIGHTBIT +@cindex eight bit characters, printing +@item @t{PRINT_EIGHT_BIT} +Print eight bit characters literally in completion lists, etc. +This option is not necessary if your system correctly returns the +printability of eight bit characters (see ctype(3)). + +@pindex PRINT_EXIT_VALUE +@pindex NO_PRINT_EXIT_VALUE +@pindex PRINTEXITVALUE +@pindex NOPRINTEXITVALUE +@cindex exit status, printing +@item @t{PRINT_EXIT_VALUE} (@t{-1}) +Print the exit value of programs with non-zero exit status. +This is only available at the command line in interactive shells. + +@pindex RC_QUOTES +@pindex NO_RC_QUOTES +@pindex RCQUOTES +@pindex NORCQUOTES +@cindex rc, quoting style +@cindex quoting style, rc +@item @t{RC_QUOTES} +Allow the character sequence `@t{@value{dsq}}' to signify a single quote +within singly quoted strings. Note this does not apply in quoted strings +using the format @t{$'}@var{...}@t{'}, where a backslashed single quote can +be used. + +@pindex RM_STAR_SILENT +@pindex NO_RM_STAR_SILENT +@pindex RMSTARSILENT +@pindex NORMSTARSILENT +@cindex rm *, querying before +@cindex querying before rm * +@item @t{RM_STAR_SILENT} (@t{-H}) <K> <S> +Do not query the user before executing `@t{rm *}' or `@t{rm path/*}'. + +@pindex RM_STAR_WAIT +@pindex NO_RM_STAR_WAIT +@pindex RMSTARWAIT +@pindex NORMSTARWAIT +@cindex rm *, waiting before +@cindex waiting before rm * +@item @t{RM_STAR_WAIT} +If querying the user before executing `@t{rm *}' or `@t{rm path/*}', +first wait ten seconds and ignore anything typed in that time. +This avoids the problem of reflexively answering `yes' to the query +when one didn't really mean it. The wait and query can always be +avoided by expanding the `@t{*}' in ZLE (with tab). + +@pindex SHORT_LOOPS +@pindex NO_SHORT_LOOPS +@pindex SHORTLOOPS +@pindex NOSHORTLOOPS +@item @t{SHORT_LOOPS} <C> <Z> +Allow the short forms of @t{for}, @t{repeat}, @t{select}, +@t{if}, and @t{function} constructs. + +@pindex SHORT_REPEAT +@pindex NO_SHORT_REPEAT +@pindex SHORTREPEAT +@pindex NOSHORTREPEAT +@item @t{SHORT_REPEAT} +Allow the short form @t{repeat} as @t{SHORT_LOOPS} but without enabling +it for the other constructs. + +@pindex SUN_KEYBOARD_HACK +@pindex NO_SUN_KEYBOARD_HACK +@pindex SUNKEYBOARDHACK +@pindex NOSUNKEYBOARDHACK +@cindex sun keyboard, annoying +@cindex annoying keyboard, sun +@item @t{SUN_KEYBOARD_HACK} (@t{-L}) +If a line ends with a backquote, and there are an odd number +of backquotes on the line, ignore the trailing backquote. +This is useful on some keyboards where the return key is +too small, and the backquote key lies annoyingly close to it. +As an alternative the variable @t{KEYBOARD_HACK} lets you choose the +character to be removed. + +@end table + +@noindent + +@subsection Job Control +@noindent +@table @asis +@pindex AUTO_CONTINUE +@pindex NO_AUTO_CONTINUE +@pindex AUTOCONTINUE +@pindex NOAUTOCONTINUE +@cindex jobs, continuing automatically +@cindex continuing jobs automatically +@item @t{AUTO_CONTINUE} +With this option set, stopped jobs that are removed from the job table +with the @t{disown} builtin command are automatically sent a @t{CONT} +signal to make them running. + +@pindex AUTO_RESUME +@pindex NO_AUTO_RESUME +@pindex AUTORESUME +@pindex NOAUTORESUME +@cindex jobs, resuming automatically +@cindex resuming jobs automatically +@item @t{AUTO_RESUME} (@t{-W}) +Treat single word simple commands without redirection +as candidates for resumption of an existing job. + +@pindex BG_NICE +@pindex NO_BG_NICE +@pindex BGNICE +@pindex NOBGNICE +@cindex jobs, background priority +@cindex background jobs, priority of +@cindex priority of background jobs +@item @t{BG_NICE} (@t{-6}) <C> <Z> +Run all background jobs at a lower priority. This option +is set by default. + +@pindex CHECK_JOBS +@pindex NO_CHECK_JOBS +@pindex CHECKJOBS +@pindex NOCHECKJOBS +@cindex exiting, checking jobs when +@cindex logging out, checking jobs when +@item @t{CHECK_JOBS} <Z> +Report the status of background and suspended jobs before exiting a shell +with job control; a second attempt to exit the shell will succeed. +@t{NO_CHECK_JOBS} is best used only in combination with @t{NO_HUP}, else +such jobs will be killed automatically. + +@noindent +The check is omitted if the commands run from the previous command line +included a `@t{jobs}' command, since it is assumed the user is aware that +there are background or suspended jobs. A `@t{jobs}' command run from one +of the hook functions defined in +the section `Special Functions' in @ref{Functions} +is not counted for this purpose. + +@pindex CHECK_RUNNING_JOBS +@pindex NO_CHECK_RUNNING_JOBS +@pindex CHECKRUNNINGJOBS +@pindex NOCHECKRUNNINGJOBS +@cindex exiting, checking running jobs when +@cindex logging out, checking running jobs when +@item @t{CHECK_RUNNING_JOBS} <Z> +Check for both running and suspended jobs when @t{CHECK_JOBS} is enabled. +When this option is disabled, zsh checks only for suspended jobs, which +matches the default behavior of bash. + +@noindent +This option has no effect unless @t{CHECK_JOBS} is set. + +@pindex HUP +@pindex NO_HUP +@pindex NOHUP +@cindex jobs, HUP +@item @t{HUP} <Z> +Send the @t{HUP} signal to running jobs when the +shell exits. + +@pindex LONG_LIST_JOBS +@pindex NO_LONG_LIST_JOBS +@pindex LONGLISTJOBS +@pindex NOLONGLISTJOBS +@cindex jobs, list format +@item @t{LONG_LIST_JOBS} (@t{-R}) +Print job notifications in the long format by default. + +@pindex MONITOR +@pindex NO_MONITOR +@pindex NOMONITOR +@cindex job control, allowing +@item @t{MONITOR} (@t{-m}, ksh: @t{-m}) +Allow job control. Set by default in interactive shells. + +@pindex NOTIFY +@pindex NO_NOTIFY +@pindex NONOTIFY +@cindex background jobs, notification +@cindex notification of background jobs +@item @t{NOTIFY} (@t{-5}, ksh: @t{-b}) <Z> +Report the status of background jobs immediately, rather than +waiting until just before printing a prompt. + +@pindex POSIX_JOBS +@pindex POSIXJOBS +@pindex NO_POSIX_JOBS +@pindex NOPOSIXJOBS +@cindex bg, output in POSIX format +@cindex fg, output in POSIX format +@cindex job control, in subshell +@cindex jobs, output in subshell +@item @t{POSIX_JOBS} <K> <S> +This option makes job control more compliant with the POSIX standard. + +@noindent +When the option is not set, the @t{MONITOR} option is unset on entry to +subshells, so that job control is no longer active. When the option is +set, the @t{MONITOR} option and job control remain active in the +subshell, but note that the subshell has no access to jobs in the parent +shell. + +@noindent +When the option is not set, jobs put in the background or foreground +with @t{bg} or @t{fg} are displayed with the same information that would +be reported by @t{jobs}. When the option is set, only the text is +printed. The output from @t{jobs} itself is not affected by the option. + +@noindent +When the option is not set, job information from the parent +shell is saved for output within a subshell (for example, within a +pipeline). When the option is set, the output of @t{jobs} is empty +until a job is started within the subshell. + +@noindent +In previous versions of the shell, it was necessary to enable +@t{POSIX_JOBS} in order for the builtin command @t{wait} to return the +status of background jobs that had already exited. This is no longer +the case. + +@end table + +@noindent + +@subsection Prompting +@noindent +@table @asis +@pindex PROMPT_BANG +@pindex NO_PROMPT_BANG +@pindex PROMPTBANG +@pindex NOPROMPTBANG +@cindex prompt, ! expansion +@item @t{PROMPT_BANG} <K> +If set, `@t{!}' is treated specially in prompt expansion. +See +@ref{Prompt Expansion}. + +@pindex PROMPT_CR +@pindex NO_PROMPT_CR +@pindex PROMPTCR +@pindex NOPROMPTCR +@cindex prompt, with CR +@item @t{PROMPT_CR} (@t{+V}) <D> +Print a carriage return just before printing +a prompt in the line editor. This is on by default as multi-line editing +is only possible if the editor knows where the start of the line appears. + +@pindex PROMPT_SP +@pindex NO_PROMPT_SP +@pindex PROMPTSP +@pindex NOPROMPTSP +@cindex prompt, save partial lines +@item @t{PROMPT_SP} <D> +Attempt to preserve a partial line (i.e. a line that did not end with a +newline) that would otherwise be covered up by the command prompt due to +the @t{PROMPT_CR} option. This works by outputting some cursor-control +characters, including a series of spaces, that should make the terminal +wrap to the next line when a partial line is present (note that this is +only successful if your terminal has automatic margins, which is typical). + +@noindent +When a partial line is preserved, by default you will see an inverse+bold +character at the end of the partial line: a `@t{%}' for a normal user or +a `@t{#}' for root. If set, the shell parameter @t{PROMPT_EOL_MARK} can be +used to customize how the end of partial lines are shown. + +@noindent +NOTE: if the @t{PROMPT_CR} option is not set, enabling this option will +have no effect. This option is on by default. + +@pindex PROMPT_PERCENT +@pindex NO_PROMPT_PERCENT +@pindex PROMPTPERCENT +@pindex NOPROMPTPERCENT +@cindex prompt, % expansion +@item @t{PROMPT_PERCENT} <C> <Z> +If set, `@t{%}' is treated specially in prompt expansion. +See +@ref{Prompt Expansion}. + +@pindex PROMPT_SUBST +@pindex NO_PROMPT_SUBST +@pindex PROMPTSUBST +@pindex NOPROMPTSUBST +@cindex prompt, parameter expansion +@item @t{PROMPT_SUBST} <K> <S> +If set, @emph{parameter expansion}, @emph{command substitution} and +@emph{arithmetic expansion} are performed in prompts. Substitutions +within prompts do not affect the command status. + +@pindex TRANSIENT_RPROMPT +@pindex NO_TRANSIENT_RPROMPT +@pindex TRANSIENTRPROMPT +@pindex NOTRANSIENTRPROMPT +@item @t{TRANSIENT_RPROMPT} +Remove any right prompt from display when accepting a command +line. This may be useful with terminals with other cut/paste methods. + +@end table + +@noindent + +@subsection Scripts and Functions +@noindent +@table @asis +@pindex ALIAS_FUNC_DEF +@pindex NO_ALIAS_FUNC_DEF +@pindex ALIASFUNCDEF +@pindex NOALIASFUNCDEF +@cindex functions, defining with expanded aliases +@cindex aliases, expanding in function definition +@item @t{ALIAS_FUNC_DEF} <S> +By default, zsh does not allow the definition of functions using +the `@var{name} @t{()}' syntax if @var{name} was expanded as an +alias: this causes an error. This is usually the desired behaviour, as +otherwise the combination of an alias and a function based on the same +definition can easily cause problems. + +@noindent +When this option is set, aliases can be used for defining functions. + +@noindent +For example, consider the following definitions as they might +occur in a startup file. + +@noindent +@example +alias foo=bar +foo() @{ + print This probably does not do what you expect. +@} +@end example + +@noindent +Here, @t{foo} is expanded as an alias to @t{bar} before the +@t{()} is encountered, so the function defined would be named +@t{bar}. By default this is instead an error in native mode. Note that +quoting any part of the function name, or using the keyword +@t{function}, avoids the problem, so is recommended when the function +name can also be an alias. + +@pindex C_BASES +@pindex NO_C_BASES +@pindex CBASES +@pindex NOCBASES +@cindex bases, output in C format +@cindex hexadecimal, output in C format +@cindex octal, output in C format +@item @t{C_BASES} +Output hexadecimal numbers in the standard C format, for example `@t{0xFF}' +instead of the usual `@t{16#FF}'. If the option @t{OCTAL_ZEROES} is also +set (it is not by default), octal numbers will be treated similarly and +hence appear as `@t{077}' instead of `@t{8#77}'. This option has no effect +on the choice of the output base, nor on the output of bases other than +hexadecimal and octal. Note that these formats will be understood on input +irrespective of the setting of @t{C_BASES}. + +@pindex C_PRECEDENCES +@pindex NO_C_PRECEDENCES +@pindex CPRECEDENCES +@pindex NOCPRECEDENCES +@cindex precedence, operator +@cindex operator precedence +@item @t{C_PRECEDENCES} +This alters the precedence of arithmetic operators to be more +like C and other programming languages; +@ref{Arithmetic Evaluation} +has an explicit list. + +@pindex DEBUG_BEFORE_CMD +@pindex NO_DEBUG_BEFORE_CMD +@pindex DEBUGBEFORECMD +@pindex NODEBUGBEFORECMD +@cindex traps, DEBUG, before or after command +@cindex DEBUG trap, before or after command +@item @t{DEBUG_BEFORE_CMD} <D> +Run the @t{DEBUG} trap before each command; otherwise it is run after +each command. Setting this option mimics the behaviour of ksh 93; with +the option unset the behaviour is that of ksh 88. + +@pindex ERR_EXIT +@pindex NO_ERR_EXIT +@pindex ERREXIT +@pindex NOERREXIT +@cindex exit status, trapping +@item @t{ERR_EXIT} (@t{-e}, ksh: @t{-e}) +If a command has a non-zero exit status, execute the @t{ZERR} +trap, if set, and exit. This is disabled while running initialization +scripts. + +@noindent +The behaviour is also disabled inside @t{DEBUG} traps. In this +case the option is handled specially: it is unset on entry to +the trap. If the option @t{DEBUG_BEFORE_CMD} is set, +as it is by default, and the option @t{ERR_EXIT} is found to have been set +on exit, then the command for which the @t{DEBUG} trap is being executed is +skipped. The option is restored after the trap exits. + +@noindent +Non-zero status in a command list containing @t{&&} or @t{||} is ignored +for commands not at the end of the list. Hence + +@noindent +@example +false && true +@end example + +@noindent +does not trigger exit. + +@noindent +Exiting due to @t{ERR_EXIT} has certain interactions with asynchronous +jobs noted in +@ref{Jobs & Signals}. + +@pindex ERR_RETURN +@pindex NO_ERR_RETURN +@pindex ERRRETURN +@pindex NOERRRETURN +@cindex function return, on error +@cindex return from function, on error +@item @t{ERR_RETURN} +If a command has a non-zero exit status, return immediately from the +enclosing function. The logic is similar to that for @t{ERR_EXIT}, +except that an implicit @t{return} statement is executed instead of an +@t{exit}. This will trigger an exit at the outermost level of a +non-interactive script. + +@noindent +Normally this option inherits the behaviour of @t{ERR_EXIT} that +code followed by `@t{&&}' `@t{||}' does not trigger a return. Hence +in the following: + +@noindent +@example +summit || true +@end example + +@noindent +no return is forced as the combined effect always has a zero return +status. + +@noindent +Note. however, that if @t{summit} in the above example is itself a +function, code inside it is considered separately: it may force a return +from @t{summit} (assuming the option remains set within @t{summit}), but +not from the enclosing context. This behaviour is different from +@t{ERR_EXIT} which is unaffected by function scope. + +@pindex EVAL_LINENO +@pindex NO_EVAL_LINENO +@pindex EVALLINENO +@pindex NOEVALLINENO +@cindex line number, in evaluated expression +@item @t{EVAL_LINENO} <Z> +If set, line numbers of expressions evaluated using the builtin @t{eval} +are tracked separately of the enclosing environment. This applies both +to the parameter @t{LINENO} and the line number output by the prompt +escape @t{%i}. If the option is set, the prompt escape @t{%N} will output +the string `@t{(eval)}' instead of the script or function name as an +indication. (The two prompt escapes are typically used in the parameter +@t{PS4} to be output when the option @t{XTRACE} is set.) If +@t{EVAL_LINENO} is unset, the line number of the surrounding script or +function is retained during the evaluation. + +@pindex EXEC +@pindex NO_EXEC +@pindex NOEXEC +@cindex command execution, enabling +@item @t{EXEC} (@t{+n}, ksh: @t{+n}) <D> +Do execute commands. Without this option, commands are +read and checked for syntax errors, but not executed. +This option cannot be turned off in an interactive shell, +except when `@t{-n}' is supplied to the shell at startup. + +@pindex FUNCTION_ARGZERO +@pindex NO_FUNCTION_ARGZERO +@pindex FUNCTIONARGZERO +@pindex NOFUNCTIONARGZERO +@cindex $0, setting +@item @t{FUNCTION_ARGZERO} <C> <Z> +When executing a shell function or sourcing a script, set @t{$0} +temporarily to the name of the function/script. Note that toggling +@t{FUNCTION_ARGZERO} from on to off (or off to on) does not change the +current value of @t{$0}. Only the state upon entry to the function or +script has an effect. Compare @t{POSIX_ARGZERO}. + +@pindex LOCAL_LOOPS +@pindex NO_LOCAL_LOOPS +@pindex LOCALLOOPS +@pindex NOLOCALLOOPS +@cindex break, inside function +@cindex continue, inside function +@cindex function, scope of break and continue +@item @t{LOCAL_LOOPS} +When this option is not set, the effect of @t{break} and @t{continue} +commands may propagate outside function scope, affecting loops in +calling functions. When the option is set in a calling function, a +@t{break} or a @t{continue} that is not caught within a called function +(regardless of the setting of the option within that function) +produces a warning and the effect is cancelled. + +@pindex LOCAL_OPTIONS +@pindex NO_LOCAL_OPTIONS +@pindex LOCALOPTIONS +@pindex NOLOCALOPTIONS +@item @t{LOCAL_OPTIONS} <K> +If this option is set at the point of return from a shell function, +most options (including this one) which were in force upon entry to +the function are restored; options that are not restored are +@t{PRIVILEGED} and @t{RESTRICTED}. Otherwise, only this option, +and the @t{LOCAL_LOOPS}, @t{XTRACE} and @t{PRINT_EXIT_VALUE} options are +restored. Hence if this is explicitly unset by a shell function the +other options in force at the point of return will remain so. +A shell function can also guarantee itself a known shell configuration +with a formulation like `@t{emulate -L zsh}'; the @t{-L} activates +@t{LOCAL_OPTIONS}. + +@pindex LOCAL_PATTERNS +@pindex NO_LOCAL_PATTERNS +@pindex LOCALPATTERNS +@pindex NOLOCALPATTERNS +@item @t{LOCAL_PATTERNS} +If this option is set at the point of return from a shell function, +the state of pattern disables, as set with the builtin command +`@t{disable -p}', is restored to what it was when the function was +entered. The behaviour of this option is similar to the effect +of @t{LOCAL_OPTIONS} on options; hence `@t{emulate -L sh}' (or +indeed any other emulation with the @t{-L} option) activates +@t{LOCAL_PATTERNS}. + +@pindex LOCAL_TRAPS +@pindex NO_LOCAL_TRAPS +@pindex LOCALTRAPS +@pindex NOLOCALTRAPS +@item @t{LOCAL_TRAPS} <K> +If this option is set when a signal trap is set inside a function, then the +previous status of the trap for that signal will be restored when the +function exits. Note that this option must be set @emph{prior} to altering the +trap behaviour in a function; unlike @t{LOCAL_OPTIONS}, the value on exit +from the function is irrelevant. However, it does not need to be set +before any global trap for that to be correctly restored by a function. +For example, + +@noindent +@example +unsetopt localtraps +trap - INT +fn() @{ setopt localtraps; trap @value{dsq} INT; sleep 3; @} +@end example + +@noindent +will restore normal handling of @t{SIGINT} after the function exits. + +@pindex MULTI_FUNC_DEF +@pindex NO_MULTI_FUNC_DEF +@pindex MULTIFUNCDEF +@pindex NOMULTIFUNCDEF +@item @t{MULTI_FUNC_DEF} <Z> +Allow definitions of multiple functions at once in the form `@t{fn1 +fn2}@var{...}@t{()}'; if the option is not set, this causes +a parse error. Definition of multiple functions with the @t{function} +keyword is always allowed. Multiple function definitions are not often +used and can cause obscure errors. + +@pindex MULTIOS +@pindex NO_MULTIOS +@pindex NOMULTIOS +@item @t{MULTIOS} <Z> +Perform implicit @cite{tee}s or @cite{cat}s when multiple +redirections are attempted (see @ref{Redirection}). + +@pindex OCTAL_ZEROES +@pindex NO_OCTAL_ZEROES +@pindex OCTALZEROES +@pindex NOOCTALZEROES +@cindex octal, arithmetic expressions +@item @t{OCTAL_ZEROES} <S> +Interpret any integer constant beginning with a 0 as octal, per IEEE Std +1003.2-1992 (ISO 9945-2:1993). This is not enabled by default as it +causes problems with parsing of, for example, date and time strings with +leading zeroes. + +@noindent +Sequences of digits indicating a numeric base such as the `@t{08}' +component in `@t{08#77}' are always interpreted as decimal, regardless +of leading zeroes. + +@pindex PIPE_FAIL +@pindex NO_PIPE_FAIL +@pindex PIPEFAIL +@pindex NOPIPEFAIL +@cindex exit status from pipeline +@cindex status, on exit from pipeline +@cindex pipeline, exit status from +@item @t{PIPE_FAIL} +By default, when a pipeline exits the exit status recorded by the shell +and returned by the shell variable @t{$?} reflects that of the +rightmost element of a pipeline. If this option is set, the exit status +instead reflects the status of the rightmost element of the pipeline +that was non-zero, or zero if all elements exited with zero status. + +@pindex SOURCE_TRACE +@pindex NO_SOURCE_TRACE +@pindex SOURCETRACE +@pindex NOSOURCETRACE +@item @t{SOURCE_TRACE} +If set, zsh will print an informational message announcing the name of +each file it loads. The format of the output is similar to that +for the @t{XTRACE} option, with the message @t{<sourcetrace>}. +A file may be loaded by the shell itself when it +starts up and shuts down (@t{Startup/Shutdown Files}) or by the use of +the `@t{source}' and `@t{dot}' builtin commands. + +@pindex TYPESET_SILENT +@pindex NO_TYPESET_SILENT +@pindex TYPESETSILENT +@pindex NOTYPESETSILENT +@item @t{TYPESET_SILENT} +If this is unset, executing any of the `@t{typeset}' family of +commands with no options and a list of parameters that have no values +to be assigned but already exist will display the value of the parameter. +If the option is set, they will only be shown when parameters are selected +with the `@t{-m}' option. The option `@t{-p}' is available whether or not +the option is set. + +@pindex TYPESET_TO_UNSET +@pindex NO_TYPESET_TO_UNSET +@pindex TYPESETTOUNSET +@pindex NOTYPESETTOUNSET +@item @t{TYPESET_TO_UNSET} <K> <S> +When declaring a new parameter with any of the `@t{typeset}' family of +related commands, the parameter remains unset unless and until a +value is explicity assigned to it, either in the `@t{typeset}' command +itself or as a later assignment statement. + +@pindex VERBOSE +@pindex NO_VERBOSE +@pindex NOVERBOSE +@cindex tracing, of input lines +@cindex input, tracing +@item @t{VERBOSE} (@t{-v}, ksh: @t{-v}) +Print shell input lines as they are read. + +@pindex XTRACE +@pindex NO_XTRACE +@pindex NOXTRACE +@cindex tracing, of commands +@cindex commands, tracing +@item @t{XTRACE} (@t{-x}, ksh: @t{-x}) +Print commands and their arguments as they are executed. The +output is preceded by the value of @t{$PS4}, formatted as described +in +@ref{Prompt Expansion}. + +@end table + +@noindent + +@subsection Shell Emulation +@noindent +@table @asis +@pindex APPEND_CREATE +@pindex NO_APPEND_CREATE +@pindex APPENDCREATE +@pindex NOAPPENDCREATE +@cindex clobbering, POSIX compatibility +@cindex file clobbering, POSIX compatibility +@cindex no clobber, POSIX compatible +@item @t{APPEND_CREATE} <K> <S> +This option only applies when @t{NO_CLOBBER} (-@t{C}) is in effect. + +@noindent +If this option is not set, the shell will report an error when a +append redirection (@t{>>}) is used on a file that does not already +exists (the traditional zsh behaviour of @t{NO_CLOBBER}). If the option +is set, no error is reported (POSIX behaviour). + +@pindex BASH_REMATCH +@pindex NO_BASH_REMATCH +@pindex BASHREMATCH +@pindex NOBASHREMATCH +@cindex bash, BASH_REMATCH variable +@cindex regexp, bash BASH_REMATCH variable +@item @t{BASH_REMATCH} +When set, matches performed with the @t{=~} operator will set the +@t{BASH_REMATCH} array variable, instead of the default @t{MATCH} and +@t{match} variables. The first element of the @t{BASH_REMATCH} array +will contain the entire matched text and subsequent elements will contain +extracted substrings. This option makes more sense when @t{KSH_ARRAYS} is +also set, so that the entire matched portion is stored at index 0 and the +first substring is at index 1. Without this option, the @t{MATCH} variable +contains the entire matched text and the @t{match} array variable contains +substrings. + +@pindex BSD_ECHO +@pindex NO_BSD_ECHO +@pindex BSDECHO +@pindex NOBSDECHO +@cindex echo, BSD compatible +@item @t{BSD_ECHO} <S> +Make the @t{echo} builtin compatible with the BSD echo(1) command. +This disables backslashed escape sequences in echo strings unless the +@t{-e} option is specified. + +@pindex CONTINUE_ON_ERROR +@pindex NO_CONTINUE_ON_ERROR +@pindex CONTINUEONERROR +@pindex NOCONTINUEONERROR +@cindex error, option to continue script on +@item @t{CONTINUE_ON_ERROR} +If a fatal error is encountered (see +@ref{Errors}), and the code is running +in a script, the shell will resume execution at the next statement +in the script at the top level, in other words outside all functions +or shell constructs such as loops and conditions. This mimics the +behaviour of interactive shells, where the shell returns to the +line editor to read a new command; it was the normal behaviour in versions +of zsh before 5.0.1. + +@pindex CSH_JUNKIE_HISTORY +@pindex NO_CSH_JUNKIE_HISTORY +@pindex CSHJUNKIEHISTORY +@pindex NOCSHJUNKIEHISTORY +@cindex csh, history style +@cindex history style, csh +@item @t{CSH_JUNKIE_HISTORY} <C> +A history reference without an event specifier will always refer to the +previous command. Without this option, such a history reference refers +to the same event as the previous history reference on the current +command line, defaulting to the previous command. + +@pindex CSH_JUNKIE_LOOPS +@pindex NO_CSH_JUNKIE_LOOPS +@pindex CSHJUNKIELOOPS +@pindex NOCSHJUNKIELOOPS +@cindex csh, loop style +@cindex loop style, csh +@item @t{CSH_JUNKIE_LOOPS} <C> +Allow loop bodies to take the form `@var{list}@t{; end}' instead of +`@t{do }@var{list}@t{; done}'. + +@pindex CSH_JUNKIE_QUOTES +@pindex NO_CSH_JUNKIE_QUOTES +@pindex CSHJUNKIEQUOTES +@pindex NOCSHJUNKIEQUOTES +@cindex csh, quoting style +@cindex quoting style, csh +@item @t{CSH_JUNKIE_QUOTES} <C> +Changes the rules for single- and double-quoted text to match that of +@cite{csh}. These require that embedded newlines be preceded by a backslash; +unescaped newlines will cause an error message. +In double-quoted strings, it is made impossible to escape `@t{$}', `@t{`}' +or `@t{"}' (and `@t{\}' itself no longer needs escaping). +Command substitutions are only expanded once, and cannot be nested. + +@pindex CSH_NULLCMD +@pindex NO_CSH_NULLCMD +@pindex CSHNULLCMD +@pindex NOCSHNULLCMD +@vindex NULLCMD, ignoring +@vindex READNULLCMD, ignoring +@cindex redirections with no command, csh +@cindex csh, redirections with no command +@item @t{CSH_NULLCMD} <C> +Do not use the values of @t{NULLCMD} and @t{READNULLCMD} +when running redirections with no command. This make +such redirections fail (see @ref{Redirection}). + +@pindex KSH_ARRAYS +@pindex NO_KSH_ARRAYS +@pindex KSHARRAYS +@pindex NOKSHARRAYS +@cindex arrays, ksh style +@cindex array style, ksh +@cindex ksh, array style +@item @t{KSH_ARRAYS} <K> <S> +Emulate @cite{ksh} array handling as closely as possible. If this option +is set, array elements are numbered from zero, an array parameter +without subscript refers to the first element instead of the whole array, +and braces are required to delimit a subscript (`@t{$@{path[2]@}}' rather +than just `@t{$path[2]}') or to apply modifiers to any parameter +(`@t{$@{PWD:h@}}' rather than `@t{$PWD:h}'). + +@pindex KSH_AUTOLOAD +@pindex NO_KSH_AUTOLOAD +@pindex KSHAUTOLOAD +@pindex NOKSHAUTOLOAD +@item @t{KSH_AUTOLOAD} <K> <S> +Emulate @cite{ksh} function autoloading. This means that when a function is +autoloaded, the corresponding file is merely executed, and must define +the function itself. (By default, the function is defined to the contents +of the file. However, the most common @cite{ksh}-style case - of the file +containing only a simple definition of the function - is always handled +in the @cite{ksh}-compatible manner.) + +@pindex KSH_OPTION_PRINT +@pindex NO_KSH_OPTION_PRINT +@pindex KSHOPTIONPRINT +@pindex NOKSHOPTIONPRINT +@cindex option printing, ksh style +@cindex option printing style, ksh +@cindex ksh, option printing style +@item @t{KSH_OPTION_PRINT} <K> +Alters the way options settings are printed: instead of separate lists of +set and unset options, all options are shown, marked `on' if +they are in the non-default state, `off' otherwise. + +@pindex KSH_TYPESET +@pindex NO_KSH_TYPESET +@pindex KSHTYPESET +@pindex NOKSHTYPESET +@cindex argument splitting, in typeset etc. +@cindex ksh, argument splitting in typeset +@item @t{KSH_TYPESET} +This option is now obsolete: a better appropximation to the behaviour of +other shells is obtained with the reserved word interface to +@t{declare}, @t{export}, @t{float}, @t{integer}, @t{local}, @t{readonly} +and @t{typeset}. Note that the option is only applied when the reserved +word interface is @emph{not} in use. + +@noindent +Alters the way arguments to the @t{typeset} family of commands, including +@t{declare}, @t{export}, @t{float}, @t{integer}, @t{local} and +@t{readonly}, are processed. Without this option, zsh will perform normal +word splitting after command and parameter expansion in arguments of an +assignment; with it, word splitting does not take place in those cases. + +@pindex KSH_ZERO_SUBSCRIPT +@pindex NO_KSH_ZERO_SUBSCRIPT +@pindex KSHZEROSUBSCRIPT +@pindex NOKSHZEROSUBSCRIPT +@cindex arrays, behaviour of index zero +@item @t{KSH_ZERO_SUBSCRIPT} +Treat use of a subscript of value zero in array or string expressions as a +reference to the first element, i.e. the element that usually has the +subscript 1. Ignored if @t{KSH_ARRAYS} is also set. + +@noindent +If neither this option nor @t{KSH_ARRAYS} is set, accesses to an element of +an array or string with subscript zero return an empty element or string, +while attempts to set element zero of an array or string are treated as an +error. However, attempts to set an otherwise valid subscript range that +includes zero will succeed. For example, if @t{KSH_ZERO_SUBSCRIPT} is not +set, + +@noindent +@example +array[0]=(element) +@end example + +@noindent +is an error, while + +@noindent +@example +array[0,1]=(element) +@end example + +@noindent +is not and will replace the first element of the array. + +@noindent +This option is for compatibility with older versions of the shell and +is not recommended in new code. + +@pindex POSIX_ALIASES +@pindex NO_POSIX_ALIASES +@pindex POSIXALIASES +@pindex NOPOSIXALIASES +@item @t{POSIX_ALIASES} <K> <S> +When this option is set, reserved words are not candidates for +alias expansion: it is still possible to declare any of them as an alias, +but the alias will never be expanded. Reserved words are described in +@ref{Reserved Words}. + +@noindent +Alias expansion takes place while text is being read; hence when this +option is set it does not take effect until the end of any function or +other piece of shell code parsed as one unit. Note this may +cause differences from other shells even when the option is in +effect. For example, when running a command with `@t{zsh -c}', +or even `@t{zsh -o posixaliases -c}', the entire command argument is parsed +as one unit, so aliases defined within the argument are not available even +in later lines. If in doubt, avoid use of aliases in non-interactive +code. + +@pindex POSIX_ARGZERO +@pindex NO_POSIX_ARGZERO +@pindex POSIXARGZERO +@pindex NOPOSIXARGZERO +@cindex $0, using +@item @t{POSIX_ARGZERO} +This option may be used to temporarily disable @t{FUNCTION_ARGZERO} and +thereby restore the value of @t{$0} to the name used to invoke the shell +(or as set by the @t{-c} command line option). For compatibility with +previous versions of the shell, emulations use @t{NO_FUNCTION_ARGZERO} +instead of @t{POSIX_ARGZERO}, which may result in unexpected scoping of +@t{$0} if the emulation mode is changed inside a function or script. +To avoid this, explicitly enable @t{POSIX_ARGZERO} in the @t{emulate} +command: + +@noindent +@example +emulate sh -o POSIX_ARGZERO +@end example + +@noindent +Note that @t{NO_POSIX_ARGZERO} has no effect unless @t{FUNCTION_ARGZERO} +was already enabled upon entry to the function or script. + +@pindex POSIX_BUILTINS +@pindex NO_POSIX_BUILTINS +@pindex POSIXBUILTINS +@pindex NOPOSIXBUILTINS +@item @t{POSIX_BUILTINS} <K> <S> +When this option is set the @t{command} builtin can be used to execute +shell builtin commands. Parameter assignments specified before shell +functions and special builtins are kept after the command completes unless +the special builtin is prefixed with the @t{command} builtin. Special +builtins are +@t{.}, +@t{:}, +@t{break}, +@t{continue}, +@t{declare}, +@t{eval}, +@t{exit}, +@t{export}, +@t{integer}, +@t{local}, +@t{readonly}, +@t{return}, +@t{set}, +@t{shift}, +@t{source}, +@t{times}, +@t{trap} and +@t{unset}. + +@noindent +In addition, various error conditions associated with the above builtins +or @t{exec} cause a non-interactive shell to exit and an interactive +shell to return to its top-level processing. + +@noindent +Furthermore, functions and shell builtins are not executed after +an @t{exec} prefix; the command to be executed must be an external +command found in the path. + +@noindent +Furthermore, the @t{getopts} builtin behaves in a POSIX-compatible +fashion in that the associated variable @t{OPTIND} is not made +local to functions, and its value is calculated differently to match +other shells. + +@noindent +Moreover, the warning and special exit code from +@t{[[ -o }@var{non_existent_option}@t{ ]]} are suppressed. + +@pindex POSIX_IDENTIFIERS +@pindex NO_POSIX_IDENTIFIERS +@pindex POSIXIDENTIFIERS +@pindex NOPOSIXIDENTIFIERS +@cindex identifiers, non-portable characters in +@cindex parameter names, non-portable characters in +@item @t{POSIX_IDENTIFIERS} <K> <S> +When this option is set, only the ASCII characters @t{a} to @t{z}, @t{A} to +@t{Z}, @t{0} to @t{9} and @t{_} may be used in identifiers (names +of shell parameters and modules). + +@noindent +In addition, setting this option limits the effect of parameter +substitution with no braces, so that the expression @t{$#} is treated as +the parameter @t{$#} even if followed by a valid parameter name. +When it is unset, zsh allows expressions of the form @t{$#}@var{name} +to refer to the length of @t{$}@var{name}, even for special variables, +for example in expressions such as @t{$#-} and @t{$#*}. + +@noindent +Another difference is that with the option set assignment to an +unset variable in arithmetic context causes the variable to be created +as a scalar rather than a numeric type. So after `@t{unset t; (( t = 3 +))}'. without @t{POSIX_IDENTIFIERS} set @t{t} has integer type, while with +it set it has scalar type. + +@noindent +When the option is unset and multibyte character support is enabled (i.e. it +is compiled in and the option @t{MULTIBYTE} is set), then additionally any +alphanumeric characters in the local character set may be used in +identifiers. Note that scripts and functions written with this feature are +not portable, and also that both options must be set before the script +or function is parsed; setting them during execution is not sufficient +as the syntax @var{variable}@t{=}@var{value} has already been parsed as +a command rather than an assignment. + +@noindent +If multibyte character support is not compiled into the shell this option is +ignored; all octets with the top bit set may be used in identifiers. +This is non-standard but is the traditional zsh behaviour. + +@pindex POSIX_STRINGS +@pindex NO_POSIX_STRINGS +@pindex POSIXSTRINGS +@pindex NOPOSIXSTRINGS +@cindex discarding embedded nulls in $'...' +@cindex embedded nulls, in $'...' +@cindex nulls, embedded in $'...' +@item @t{POSIX_STRINGS} <K> <S> +This option affects processing of quoted strings. Currently it only +affects the behaviour of null characters, i.e. character 0 in the +portable character set corresponding to US ASCII. + +@noindent +When this option is not set, null characters embedded within strings +of the form @t{$'}@var{...}@t{'} are treated as ordinary characters. The +entire string is maintained within the shell and output to files where +necessary, although owing to restrictions of the library interface +the string is truncated at the null character in file names, environment +variables, or in arguments to external programs. + +@noindent +When this option is set, the @t{$'}@var{...}@t{'} expression is truncated at +the null character. Note that remaining parts of the same string +beyond the termination of the quotes are not truncated. + +@noindent +For example, the command line argument @t{a$'b\0c'd} is treated with +the option off as the characters @t{a}, @t{b}, null, @t{c}, @t{d}, +and with the option on as the characters @t{a}, @t{b}, @t{d}. + +@pindex POSIX_TRAPS +@pindex NO_POSIX_TRAPS +@pindex POSIXTRAPS +@pindex NOPOSIXTRAPS +@cindex traps, on function exit +@cindex traps, POSIX compatibility +@item @t{POSIX_TRAPS} <K> <S> +When this option is set, the usual zsh behaviour of executing +traps for @t{EXIT} on exit from shell functions is suppressed. +In that case, manipulating @t{EXIT} traps always alters the global +trap for exiting the shell; the @t{LOCAL_TRAPS} option is +ignored for the @t{EXIT} trap. + +@noindent +Also, a @t{return} statement executed in a trap with no argument passes +back from the function the value from the surrounding context, not from +code executed within the trap. + +@noindent +Furthermore, if a trap is set to be ignored, this state persists when +a subshell is entered. Without the option, the trap would be reset to +its default state at this point. + +@pindex SH_FILE_EXPANSION +@pindex NO_SH_FILE_EXPANSION +@pindex SHFILEEXPANSION +@pindex NOSHFILEEXPANSION +@cindex sh, expansion style +@cindex expansion style, sh +@item @t{SH_FILE_EXPANSION} <K> <S> +Perform filename expansion (e.g., @t{~} expansion) @emph{before} +parameter expansion, command substitution, arithmetic expansion +and brace expansion. +If this option is unset, it is performed @emph{after} +brace expansion, so things like `@t{~$USERNAME}' and +`@t{~@{pfalstad,rc@}}' will work. + +@pindex SH_NULLCMD +@pindex NO_SH_NULLCMD +@pindex SHNULLCMD +@pindex NOSHNULLCMD +@vindex NULLCMD, ignoring +@vindex READNULLCMD, ignoring +@cindex sh, redirections with no command +@cindex ksh, redirections with no command +@cindex redirections with no command, sh +@cindex redirections with no command, ksh +@item @t{SH_NULLCMD} <K> <S> +Do not use the values of @t{NULLCMD} and @t{READNULLCMD} +when doing redirections, use `@t{:}' instead (see @ref{Redirection}). + +@pindex SH_OPTION_LETTERS +@pindex NO_SH_OPTION_LETTERS +@pindex SHOPTIONLETTERS +@pindex NOSHOPTIONLETTERS +@cindex sh, single letter options style +@cindex ksh, single letter options style +@cindex single letter options, ksh style +@cindex options, single letter, ksh style +@item @t{SH_OPTION_LETTERS} <K> <S> +If this option is set the shell tries to interpret single letter options +(which are used with @t{set} and @t{setopt}) like @cite{ksh} does. +This also affects the value of the @t{-} special parameter. + +@pindex SH_WORD_SPLIT +@pindex NO_SH_WORD_SPLIT +@pindex SHWORDSPLIT +@pindex NOSHWORDSPLIT +@cindex field splitting, sh style +@cindex sh, field splitting style +@item @t{SH_WORD_SPLIT} (@t{-y}) <K> <S> +Causes field splitting to be performed on unquoted parameter expansions. +Note that this option has nothing to do with word splitting. +(See +@ref{Parameter Expansion}.) + +@pindex TRAPS_ASYNC +@pindex NO_TRAPS_ASYNC +@pindex TRAPSASYNC +@pindex NOTRAPSASYNC +@cindex traps, asynchronous +@item @t{TRAPS_ASYNC} +While waiting for a program to exit, handle signals and run traps +immediately. Otherwise the trap is run after a child process has exited. +Note this does not affect the point at which traps are run for any case +other than when the shell is waiting for a child process. + +@end table + +@noindent + +@subsection Shell State +@noindent +@table @asis +@pindex INTERACTIVE +@pindex NO_INTERACTIVE +@pindex NOINTERACTIVE +@item @t{INTERACTIVE} (@t{-i}, ksh: @t{-i}) +This is an interactive shell. This option is set upon initialisation if +the standard input is a tty and commands are being read from standard input. +(See the discussion of @t{SHIN_STDIN}.) +This heuristic may be overridden by specifying a state for this option +on the command line. +The value of this option can only be changed via flags supplied at +invocation of the shell. +It cannot be changed once zsh is running. + +@pindex LOGIN +@pindex NO_LOGIN +@pindex NOLOGIN +@item @t{LOGIN} (@t{-l}, ksh: @t{-l}) +This is a login shell. +If this option is not explicitly set, the shell becomes a login shell if +the first character of the @t{argv[0]} passed to the shell is a `@t{-}'. + +@pindex PRIVILEGED +@pindex NO_PRIVILEGED +@pindex NOPRIVILEGED +@cindex privileged mode +@cindex mode, privileged +@item @t{PRIVILEGED} (@t{-p}, ksh: @t{-p}) +Turn on privileged mode. Typically this is used when script is to be run +with elevated privileges. This should be done as follows directly with +the @t{-p} option to zsh so that it takes effect during startup. + +@noindent +@example +#!/bin/zsh -p +@end example + +@noindent +The option is enabled automatically on startup if the effective user +(group) ID is not equal to the real user (group) ID. In this case, +turning the option off causes the effective user and group IDs to be set +to the real user and group IDs. Be aware that if that fails the shell may +be running with different IDs than was intended so a script should check +for failure and act accordingly, for example: + +@noindent +@example +unsetopt privileged || exit +@end example + +@noindent +The @t{PRIVILEGED} option disables sourcing user startup files. +If zsh is invoked as `@t{sh}' or `@t{ksh}' with this option set, +@t{/etc/suid_profile} is sourced (after @t{/etc/profile} on interactive +shells). Sourcing @t{~/.profile} is disabled and the contents of the +@t{ENV} variable is ignored. This option cannot be changed using the +@t{-m} option of @t{setopt} and @t{unsetopt}, and changing it inside a +function always changes it globally regardless of the @t{LOCAL_OPTIONS} +option. + +@pindex RESTRICTED +@pindex NO_RESTRICTED +@pindex NORESTRICTED +@cindex restricted shell +@item @t{RESTRICTED} (@t{-r}) +Enables restricted mode. This option cannot be changed using +@t{unsetopt}, and setting it inside a function always changes it +globally regardless of the @t{LOCAL_OPTIONS} option. See +@ref{Restricted Shell}. + +@pindex SHIN_STDIN +@pindex NO_SHIN_STDIN +@pindex SHINSTDIN +@pindex NOSHINSTDIN +@item @t{SHIN_STDIN} (@t{-s}, ksh: @t{-s}) +Commands are being read from the standard input. +Commands are read from standard input if no command is specified with +@t{-c} and no file of commands is specified. If @t{SHIN_STDIN} +is set explicitly on the command line, +any argument that would otherwise have been +taken as a file to run will instead be treated as a normal positional +parameter. +Note that setting or unsetting this option on the command line does not +necessarily affect the state the option will have while the shell is +running - that is purely an indicator of whether or not commands are +@emph{actually} being read from standard input. +The value of this option can only be changed via flags supplied at +invocation of the shell. +It cannot be changed once zsh is running. + +@pindex SINGLE_COMMAND +@pindex NO_SINGLE_COMMAND +@pindex SINGLECOMMAND +@pindex NOSINGLECOMMAND +@cindex single command +@pindex INTERACTIVE, use of +@item @t{SINGLE_COMMAND} (@t{-t}, ksh: @t{-t}) +If the shell is reading from standard input, it exits after a single command +has been executed. This also makes the shell non-interactive, unless the +@t{INTERACTIVE} option is explicitly set on the command line. +The value of this option can only be changed via flags supplied at +invocation of the shell. +It cannot be changed once zsh is running. + +@end table + +@noindent + +@subsection Zle +@noindent +@table @asis +@pindex BEEP +@pindex NO_BEEP +@pindex NOBEEP +@cindex beep, enabling +@cindex enabling the beep +@item @t{BEEP} (@t{+B}) <D> +Beep on error in ZLE. + +@pindex COMBINING_CHARS +@pindex NO_COMBINING_CHARS +@pindex COMBININGCHARS +@pindex NOCOMBININGCHARS +@cindex characters, (Unicode) combining +@cindex combining characters (Unicode) +@cindex Unicode combining characters +@item @t{COMBINING_CHARS} +Assume that the terminal displays combining characters correctly. +Specifically, if a base alphanumeric character is followed by one or more +zero-width punctuation characters, assume that the zero-width characters +will be displayed as modifications to the base character within the +same width. Not all terminals handle this. If this option is not +set, zero-width characters are displayed separately with special +mark-up. + +@noindent +If this option is set, the pattern test @t{[[:WORD:]]} matches a +zero-width punctuation character on the assumption that it will be +used as part of a word in combination with a word character. +Otherwise the base shell does not handle combining characters specially. + +@pindex EMACS +@pindex NO_EMACS +@pindex NOEMACS +@item @t{EMACS} +If ZLE is loaded, turning on this option has the equivalent effect +of `@t{bindkey -e}'. In addition, the VI option is unset. +Turning it off has no effect. The option setting is +not guaranteed to reflect the current keymap. This option is +provided for compatibility; @t{bindkey} is the recommended interface. + +@pindex OVERSTRIKE +@pindex NO_OVERSTRIKE +@pindex NOOVERSTRIKE +@cindex editor, overstrike mode +@cindex overstrike mode, of editor +@item @t{OVERSTRIKE} +Start up the line editor in overstrike mode. + +@pindex SINGLE_LINE_ZLE +@pindex NO_SINGLE_LINE_ZLE +@pindex SINGLELINEZLE +@pindex NOSINGLELINEZLE +@cindex editor, single line mode +@item @t{SINGLE_LINE_ZLE} (@t{-M}) <K> +Use single-line command line editing instead of multi-line. + +@noindent +Note that although this is on by default in ksh emulation it only +provides superficial compatibility with the ksh line editor and +reduces the effectiveness of the zsh line editor. As it has no +effect on shell syntax, many users may wish to disable this option +when using ksh emulation interactively. + +@pindex VI +@pindex NO_VI +@pindex NOVI +@item @t{VI} +If ZLE is loaded, turning on this option has the equivalent effect +of `@t{bindkey -v}'. In addition, the EMACS option is unset. +Turning it off has no effect. The option setting is +not guaranteed to reflect the current keymap. This option is +provided for compatibility; @t{bindkey} is the recommended interface. + +@pindex ZLE +@pindex NO_ZLE +@pindex NOZLE +@cindex editor, enabling +@cindex enabling the editor +@item @t{ZLE} (@t{-Z}) +Use the zsh line editor. Set by default in interactive shells connected to +a terminal. + +@end table + +@noindent +@node Option Aliases, Single Letter Options, Description of Options, Options + +@section Option Aliases +@noindent +@cindex options, aliases +Some options have alternative names. These aliases are never used for +output, but can be used just like normal option names when specifying +options to the shell. + +@noindent +@table @asis +@pindex BRACE_EXPAND +@pindex NO_BRACE_EXPAND +@pindex BRACEEXPAND +@pindex NOBRACEEXPAND +@item @t{BRACE_EXPAND} +@emph{NO_}@t{IGNORE_BRACES} +(ksh and bash compatibility) + +@pindex DOT_GLOB +@pindex NO_DOT_GLOB +@pindex DOTGLOB +@pindex NODOTGLOB +@item @t{DOT_GLOB} +@t{GLOB_DOTS} +(bash compatibility) + +@pindex HASH_ALL +@pindex NO_HASH_ALL +@pindex HASHALL +@pindex NOHASHALL +@item @t{HASH_ALL} +@t{HASH_CMDS} +(bash compatibility) + +@pindex HIST_APPEND +@pindex NO_HIST_APPEND +@pindex HISTAPPEND +@pindex NOHISTAPPEND +@item @t{HIST_APPEND} +@t{APPEND_HISTORY} +(bash compatibility) + +@pindex HIST_EXPAND +@pindex NO_HIST_EXPAND +@pindex HISTEXPAND +@pindex NOHISTEXPAND +@item @t{HIST_EXPAND} +@t{BANG_HIST} +(bash compatibility) + +@pindex LOG +@pindex NO_LOG +@pindex NOLOG +@item @t{LOG} +@emph{NO_}@t{HIST_NO_FUNCTIONS} +(ksh compatibility) + +@pindex MAIL_WARN +@pindex NO_MAIL_WARN +@pindex MAILWARN +@pindex NOMAILWARN +@item @t{MAIL_WARN} +@t{MAIL_WARNING} +(bash compatibility) + +@pindex ONE_CMD +@pindex NO_ONE_CMD +@pindex ONECMD +@pindex NOONECMD +@item @t{ONE_CMD} +@t{SINGLE_COMMAND} +(bash compatibility) + +@pindex PHYSICAL +@pindex NO_PHYSICAL +@pindex NOPHYSICAL +@item @t{PHYSICAL} +@t{CHASE_LINKS} +(ksh and bash compatibility) + +@pindex PROMPT_VARS +@pindex NO_PROMPT_VARS +@pindex PROMPTVARS +@pindex NOPROMPTVARS +@item @t{PROMPT_VARS} +@t{PROMPT_SUBST} +(bash compatibility) + +@pindex STDIN +@pindex NO_STDIN +@pindex NOSTDIN +@item @t{STDIN} +@t{SHIN_STDIN} +(ksh compatibility) + +@pindex TRACK_ALL +@pindex NO_TRACK_ALL +@pindex TRACKALL +@pindex NOTRACKALL +@item @t{TRACK_ALL} +@t{HASH_CMDS} +(ksh compatibility) + +@end table +@node Single Letter Options, , Option Aliases, Options + +@section Single Letter Options +@noindent +@cindex options, single letter +@cindex single letter options + +@subsection Default set +@noindent +@table @asis +@item @t{-0} +CORRECT +@item @t{-1} +PRINT_EXIT_VALUE +@item @t{-2} +@emph{NO_}BAD_PATTERN +@item @t{-3} +@emph{NO_}NOMATCH +@item @t{-4} +GLOB_DOTS +@item @t{-5} +NOTIFY +@item @t{-6} +BG_NICE +@item @t{-7} +IGNORE_EOF +@item @t{-8} +MARK_DIRS +@item @t{-9} +AUTO_LIST +@item @t{-B} +@emph{NO_}BEEP +@item @t{-C} +@emph{NO_}CLOBBER +@item @t{-D} +PUSHD_TO_HOME +@item @t{-E} +PUSHD_SILENT +@item @t{-F} +@emph{NO_}GLOB +@item @t{-G} +NULL_GLOB +@item @t{-H} +RM_STAR_SILENT +@item @t{-I} +IGNORE_BRACES +@item @t{-J} +AUTO_CD +@item @t{-K} +@emph{NO_}BANG_HIST +@item @t{-L} +SUN_KEYBOARD_HACK +@item @t{-M} +SINGLE_LINE_ZLE +@item @t{-N} +AUTO_PUSHD +@item @t{-O} +CORRECT_ALL +@item @t{-P} +RC_EXPAND_PARAM +@item @t{-Q} +PATH_DIRS +@item @t{-R} +LONG_LIST_JOBS +@item @t{-S} +REC_EXACT +@item @t{-T} +CDABLE_VARS +@item @t{-U} +MAIL_WARNING +@item @t{-V} +@emph{NO_}PROMPT_CR +@item @t{-W} +AUTO_RESUME +@item @t{-X} +LIST_TYPES +@item @t{-Y} +MENU_COMPLETE +@item @t{-Z} +ZLE +@item @t{-a} +ALL_EXPORT +@item @t{-e} +ERR_EXIT +@item @t{-f} +@emph{NO_}RCS +@item @t{-g} +HIST_IGNORE_SPACE +@item @t{-h} +HIST_IGNORE_DUPS +@item @t{-i} +INTERACTIVE +@item @t{-k} +INTERACTIVE_COMMENTS +@item @t{-l} +LOGIN +@item @t{-m} +MONITOR +@item @t{-n} +@emph{NO_}EXEC +@item @t{-p} +PRIVILEGED +@item @t{-r} +RESTRICTED +@item @t{-s} +SHIN_STDIN +@item @t{-t} +SINGLE_COMMAND +@item @t{-u} +@emph{NO_}UNSET +@item @t{-v} +VERBOSE +@item @t{-w} +CHASE_LINKS +@item @t{-x} +XTRACE +@item @t{-y} +SH_WORD_SPLIT +@end table + +@subsection sh/ksh emulation set +@noindent +@table @asis +@item @t{-C} +@emph{NO_}CLOBBER +@item @t{-T} +TRAPS_ASYNC +@item @t{-X} +MARK_DIRS +@item @t{-a} +ALL_EXPORT +@item @t{-b} +NOTIFY +@item @t{-e} +ERR_EXIT +@item @t{-f} +@emph{NO_}GLOB +@item @t{-i} +INTERACTIVE +@item @t{-l} +LOGIN +@item @t{-m} +MONITOR +@item @t{-n} +@emph{NO_}EXEC +@item @t{-p} +PRIVILEGED +@item @t{-r} +RESTRICTED +@item @t{-s} +SHIN_STDIN +@item @t{-t} +SINGLE_COMMAND +@item @t{-u} +@emph{NO_}UNSET +@item @t{-v} +VERBOSE +@item @t{-x} +XTRACE +@end table + +@subsection Also note +@noindent +@table @asis +@item @t{-A} +Used by @t{set} for setting arrays +@item @t{-b} +Used on the command line to specify end of option processing +@item @t{-c} +Used on the command line to specify a single command +@item @t{-m} +Used by @t{setopt} for pattern-matching option setting +@item @t{-o} +Used in all places to allow use of long option names +@item @t{-s} +Used by @t{set} to sort positional parameters +@end table +@c (avoiding a yodl bug) +@c Yodl file: Zsh/builtins.yo +@node Shell Builtin Commands, Zsh Line Editor, Options, Top + +@chapter Shell Builtin Commands +@noindent + +@cindex builtin commands +@cindex commands, builtin +Some shell builtin commands take options as described in individual +entries; these are often referred to in the list below as `@t{flags}' to +avoid confusion with shell options, which may also have an effect on the +behaviour of builtin commands. In this introductory section, +`@t{option}' always has the meaning of an option to a command that should +be familiar to most command line users. + +@noindent +Typically, options are single letters preceded by a hyphen (@t{-}). +Options that take an argument accept it either immediately following the +option letter or after white space, for example `@t{print -C3 @{1..9@}}' or +`@t{print -C 3 @{1..9@}}' are equivalent. Arguments to options are not the +same as arguments to the command; the documentation indicates which is +which. Options that do not take an argument may be combined in a single +word, for example `@t{print -rca -- *}' and `@t{print -r -c -a -- *}' are +equivalent. + +@noindent +Some shell builtin commands also take options that begin with `@t{+}' +instead of `@t{-}'. The list below makes clear which commands these +are. + +@noindent +Options (together with their individual arguments, if any) must appear +in a group before any non-option arguments; once the first non-option +argument has been found, option processing is terminated. + +@noindent +All builtin commands other than `@t{echo}' and precommand modifiers, +even those that have no options, can be given the argument `@t{-}@t{-}' +to terminate option processing. This indicates that the following words +are non-option arguments, but is otherwise ignored. This is useful in +cases where arguments to the command may begin with `@t{-}'. For +historical reasons, most builtin commands (including `@t{echo}') also +recognize a single `@t{-}' in a separate word for this purpose; note +that this is less standard and use of `@t{-}@t{-}' is recommended. + +@noindent +@table @asis +@item @t{-} @var{simple command} +See @ref{Precommand Modifiers}. + +@findex . +@item @t{.} @var{file} [ @var{arg} ... ] +Read commands from @var{file} and execute them in the current shell +environment. + +@noindent +If @var{file} does not contain a slash, or if @t{PATH_DIRS} is set, +the shell looks in the components of @t{$path} to find the directory +containing @var{file}. Files in the current directory are not read +unless `@t{.}' appears somewhere in @t{$path}. If a file named +`@var{file}@t{.zwc}' is found, is newer than @var{file}, and is the +compiled form (created with the @t{zcompile} builtin) of @var{file}, +then commands are read from that file instead of @var{file}. + +@noindent +If any arguments @var{arg} are given, +they become the positional parameters; the old positional +parameters are restored when the @var{file} is done executing. +However, if no arguments are given, +the positional parameters remain those of the calling context, +and no restoring is done. + +@noindent +If @var{file} was not found the return status is 127; if @var{file} was found +but contained a syntax error the return status is 126; else the return +status is the exit status of the last command executed. + +@findex : +@cindex expanding parameters +@cindex parameters, expanding +@cindex doing nothing +@item @t{:} [ @var{arg} ... ] +This command does nothing, although normal argument expansions is performed +which may have effects on shell parameters. A zero exit status is returned. + +@findex alias +@cindex aliases, defining +@cindex aliases, listing +@item @t{alias} [ @{@t{+}|@t{-}@}@t{gmrsL} ] [ @var{name}[@t{=}@var{value}] ... ] +For each @var{name} with a corresponding @var{value}, define an alias +with that value. A trailing space in @var{value} causes the next word +to be checked for alias expansion. If the @t{-g} flag is present, +define a global alias; global aliases are expanded even if they do not +occur in command position: + +@noindent +@example +% perldoc --help 2>&1 | grep 'built-in functions' + -f Search Perl built-in functions +% alias -g HG='--help 2>&1 | grep' +% perldoc HG 'built-in functions' + -f Search Perl built-in functions +@end example + +@noindent +If the @t{-s} flag is present, define a suffix alias: if the command +word on a command line is in the form `@var{text}@t{.}@var{name}', where +@var{text} is any non-empty string, it is replaced by the text +`@var{value} @var{text}@t{.}@var{name}'. Note that @var{name} is treated as +a literal string, not a pattern. A trailing space in @var{value} is not +special in this case. For example, + +@noindent +@example +alias -s ps='gv --' +@end example + +@noindent +will cause the command `@t{*.ps}' to be expanded to `@t{gv -- *.ps}'. As +alias expansion is carried out earlier than globbing, the `@t{*.ps}' will +then be expanded. Suffix aliases constitute a different name space from +other aliases (so in the above example it is still possible +to create an alias for the command @t{ps}) and the two sets are never +listed together. + +@noindent +For each @var{name} with no @var{value}, +print the value of @var{name}, if any. With no arguments, print all +currently defined aliases other than suffix aliases. If the @t{-m} flag +is given the arguments are taken as patterns (they should be quoted to +preserve them from being interpreted as glob patterns), and the aliases +matching these patterns are printed. When printing aliases and one of +the @t{-g}, @t{-r} or @t{-s} flags is present, restrict the printing to +global, regular or suffix aliases, respectively; a regular alias is one +which is neither a global nor a suffix alias. Using `@t{+}' +instead of `@t{-}', or ending the option list with a single +`@t{+}', prevents the values of the aliases from being printed. + +@noindent +If the @t{-L} flag is present, then print each +alias in a manner suitable for putting in a startup script. The exit +status is nonzero if a @var{name} (with no @var{value}) is given for +which no alias has been defined. + +@noindent +For more on aliases, include common problems, see +@ref{Aliasing}. + +@findex autoload +@cindex functions, autoloading +@cindex autoloading functions +@item @t{autoload} [ @{@t{+}|@t{-}@}@t{RTUXdkmrtWz} ] [ @t{-w} ] [ @var{name} ... ] +@vindex fpath, searching +See the section `Autoloading Functions' in @ref{Functions} for full details. The @t{fpath} parameter +will be searched to find the function definition when the function is +first referenced. + +@noindent +If @var{name} consists of an absolute path, the function is defined to +load from the file given (searching as usual for dump files in the given +location). The name of the function is the basename (non-directory +part) of the file. It is normally an error if the function is not found +in the given location; however, if the option @t{-d} is given, searching +for the function defaults to @t{$fpath}. If a function is loaded by +absolute path, any functions loaded from it that are marked for +@t{autoload} without an absolute path have the load path of the parent +function temporarily prepended to @t{$fpath}. + +@noindent +If the option @t{-r} or @t{-R} is given, the function is searched for +immediately and the location is recorded internally for use when the +function is executed; a relative path is expanded using the value of +@t{$PWD}. This protects against a change to @t{$fpath} after the call +to @t{autoload}. With @t{-r}, if the function is not found, it is +silently left unresolved until execution; with @t{-R}, an error message +is printed and command processing aborted immediately the search fails, +i.e. at the @t{autoload} command rather than at function execution.. + +@noindent +The flag @t{-X} may be used only inside a shell function. It causes the +calling function to be marked for autoloading and then immediately +loaded and executed, with the current array of positional parameters as +arguments. This replaces the previous definition of the function. If +no function definition is found, an error is printed and the function +remains undefined and marked for autoloading. If an argument is given, +it is used as a directory (i.e. it does not include the name of the +function) in which the function is to be found; this may be combined +with the @t{-d} option to allow the function search to default to @t{$fpath} +if it is not in the given location. + +@noindent +The flag @t{+X} attempts to load each @var{name} as an autoloaded function, +but does @emph{not} execute it. The exit status is zero (success) if the +function was not previously defined @emph{and} a definition for it was found. +This does @emph{not} replace any existing definition of the function. The +exit status is nonzero (failure) if the function was already defined or +when no definition was found. In the latter case the function remains +undefined and marked for autoloading. If ksh-style autoloading is +enabled, the function created will contain the contents of the file +plus a call to the function itself appended to it, thus giving normal +ksh autoloading behaviour on the first call to the function. +If the @t{-m} flag is also given each @var{name} is treated as a +pattern and all functions already marked for autoload that match the +pattern are loaded. + +@noindent +With the @t{-t} flag, turn on execution tracing; with @t{-T}, turn on +execution tracing only for the current function, turning it off on entry +to any called functions that do not also have tracing enabled. + +@noindent +With the @t{-U} flag, alias expansion is suppressed when the function is +loaded. + +@noindent +With the @t{-w} flag, the @var{name}s are taken as names of files compiled +with the @t{zcompile} builtin, and all functions defined in them are +marked for autoloading. + +@noindent +The flags @t{-z} and @t{-k} mark the function to be autoloaded using the +zsh or ksh style, as if the option @t{KSH_AUTOLOAD} were unset or were +set, respectively. The flags override the setting of the option at the +time the function is loaded. + +@noindent +Note that the @t{autoload} command makes no attempt to ensure the +shell options set during the loading or execution of the file have +any particular value. For this, the @t{emulate} command can be used: + +@noindent +@example +emulate zsh -c 'autoload -Uz @var{func}' +@end example + +@noindent +arranges that when @var{func} is loaded the shell is in native @t{zsh} +emulation, and this emulation is also applied when @var{func} is run. + +@noindent +Some of the functions of @t{autoload} are also provided by @t{functions +-u} or @t{functions -U}, but @t{autoload} is a more comprehensive +interface. + +@findex bg +@cindex jobs, backgrounding +@item @t{bg} [ @var{job} ... ] +@itemx @var{job} ... @t{&} +Put each specified @var{job} in the background, +or the current job if none is specified. + +@item @t{bindkey} +See @ref{Zle Builtins}. + +@findex break +@cindex exiting loops +@cindex loops, exiting +@item @t{break} [ @var{n} ] +Exit from an enclosing @t{for}, @t{while}, +@t{until}, @t{select} or @t{repeat} loop. If an arithmetic expression @var{n} +is specified, then break @var{n} levels instead of just one. + +@findex builtin +@item @t{builtin} @var{name} [ @var{args} ... ] +Executes the builtin @var{name}, with the given @var{args}. + +@findex bye +@item @t{bye} +Same as @t{exit}. + +@item @t{cap} +See @ref{The zsh/cap Module}. + +@findex cd +@cindex directories, changing +@item @t{cd} [ @t{-qsLP} ] [ @var{arg} ] +@itemx @t{cd} [ @t{-qsLP} ] @var{old} @var{new} +@itemx @t{cd} [ @t{-qsLP} ] @{@t{+}|@t{-}@}@var{n} +Change the current directory. In the first form, change the +current directory to @var{arg}, or to the value of @t{$HOME} if +@var{arg} is not specified. If @var{arg} is `@t{-}', change to the +previous directory. + +@noindent +Otherwise, if @var{arg} begins with a slash, attempt to change to the +directory given by @var{arg}. + +@noindent +If @var{arg} does not begin with a slash, the behaviour depends on whether +the current directory `@t{.}' occurs in the list of directories contained +in the shell parameter @t{cdpath}. If it does not, first attempt to change +to the directory @var{arg} under the current directory, and if that fails +but @t{cdpath} is set and contains at least one element attempt to change +to the directory @var{arg} under each component of @t{cdpath} in turn until +successful. If `@t{.}' occurs in @t{cdpath}, then @t{cdpath} is searched +strictly in order so that `@t{.}' is only tried at the appropriate point. + +@noindent +The order of testing @t{cdpath} is modified if the option @t{POSIX_CD} +is set, as described in the documentation for the option. + +@noindent +If no directory is found, the option @t{CDABLE_VARS} is set, and a +parameter named @var{arg} exists whose value begins with a slash, treat its +value as the directory. In that case, the parameter is added to the named +directory hash table. + +@noindent +The second form of @t{cd} substitutes the string @var{new} +for the string @var{old} in the name of the current directory, +and tries to change to this new directory. + +@noindent +The third form of @t{cd} extracts an entry from the directory +stack, and changes to that directory. An argument of the form +`@t{+}@var{n}' identifies a stack entry by counting from the left +of the list shown by the @t{dirs} command, starting with zero. +An argument of the form `@t{-}@var{n}' counts from the right. +If the @t{PUSHD_MINUS} option is set, the meanings of `@t{+}' +and `@t{-}' in this context are swapped. +If the @t{POSIX_CD} option is set, this form of @t{cd} is not recognised +and will be interpreted as the first form. + +@noindent +If the @t{-q} (quiet) option is specified, the hook function @t{chpwd} +and the functions in the array @t{chpwd_functions} are not called. +This is useful for calls to @t{cd} that do not change the environment +seen by an interactive user. + +@noindent +If the @t{-s} option is specified, @t{cd} refuses to change the current +directory if the given pathname contains symlinks. If the @t{-P} option +is given or the @t{CHASE_LINKS} option is set, symbolic links are resolved +to their true values. If the @t{-L} option is given symbolic links are +retained in the directory (and not resolved) regardless of the state of +the @t{CHASE_LINKS} option. + +@findex chdir +@item @t{chdir} +Same as @t{cd}. + +@item @t{clone} +See @ref{The zsh/clone Module}. + +@findex command +@item @t{command} [ @t{-pvV} ] @var{simple command} +The simple command argument is taken as an external command instead of +a function or builtin and is executed. If the @t{POSIX_BUILTINS} option +is set, builtins will also be executed but certain special properties +of them are suppressed. The @t{-p} flag causes a default path to be +searched instead of that in @t{$path}. With the @t{-v} flag, @t{command} +is similar to @t{whence} and with @t{-V}, it is equivalent to @t{whence +-v}. + +@noindent +See also @ref{Precommand Modifiers}. + +@item @t{comparguments} +See @ref{The zsh/computil Module}. + +@item @t{compcall} +See @ref{The zsh/compctl Module}. + +@item @t{compctl} +See @ref{The zsh/compctl Module}. + +@item @t{compdescribe} +See @ref{The zsh/computil Module}. + +@item @t{compfiles} +See @ref{The zsh/computil Module}. + +@item @t{compgroups} +See @ref{The zsh/computil Module}. + +@item @t{compquote} +See @ref{The zsh/computil Module}. + +@item @t{comptags} +See @ref{The zsh/computil Module}. + +@item @t{comptry} +See @ref{The zsh/computil Module}. + +@item @t{compvalues} +See @ref{The zsh/computil Module}. + +@findex continue +@cindex loops, continuing +@cindex continuing loops +@item @t{continue} [ @var{n} ] +Resume the next iteration of the enclosing +@t{for}, @t{while}, @t{until}, @t{select} or +@t{repeat} loop. If an arithmetic expression @var{n} is specified, break out of +@var{n}-1 loops and resume at the @var{n}th enclosing loop. + +@findex declare +@item @t{declare} +Same as @t{typeset}. + +@findex dirs +@cindex directory stack, printing +@item @t{dirs} [ @t{-c} ] [ @var{arg} ... ] +@itemx @t{dirs} [ @t{-lpv} ] +With no arguments, print the contents of the directory stack. +Directories are added to this stack with the @t{pushd} command, +and removed with the @t{cd} or @t{popd} commands. +If arguments are specified, load them onto the directory stack, +replacing anything that was there, and push the current directory +onto the stack. + +@noindent +@table @asis +@item @t{-c} +clear the directory stack. + +@item @t{-l} +print directory names in full instead of using of using @t{~} expressions (@ref{Filename Expansion}). + +@item @t{-p} +print directory entries one per line. + +@item @t{-v} +number the directories in the stack when printing. + +@end table + +@noindent + +@findex disable +@cindex disabling commands +@cindex commands, disabling +@item @t{disable} [ @t{-afmprs} ] @var{name} ... +Temporarily disable the @var{name}d hash table elements or patterns. The default +is to disable builtin commands. This allows you to use an external +command with the same name as a builtin command. The @t{-a} option +causes @t{disable} to act on regular or global aliases. The @t{-s} +option causes @t{disable} to act on suffix aliases. The @t{-f} option causes +@t{disable} to act on shell functions. The @t{-r} options causes +@t{disable} to act on reserved words. Without arguments all disabled +hash table elements from the corresponding hash table are printed. +With the @t{-m} flag the arguments are taken as patterns (which should be +quoted to prevent them from undergoing filename expansion), and all hash +table elements from the corresponding hash table matching these patterns +are disabled. Disabled objects can be enabled with the @t{enable} +command. + +@noindent +With the option @t{-p}, @var{name} ... refer to elements of the +shell's pattern syntax as described in @ref{Filename Generation}. +Certain elements can be disabled separately, as given below. + +@noindent +Note that patterns +not allowed by the current settings for the options @t{EXTENDED_GLOB}, +@t{KSH_GLOB} and @t{SH_GLOB} are never enabled, regardless of the +setting here. For example, if @t{EXTENDED_GLOB} is not active, +the pattern @t{^} is ineffective even if `@t{disable -p "^"}' has +not been issued. The list below indicates any option settings +that restrict the use of the pattern. It should be noted that +setting @t{SH_GLOB} has a wider effect than merely disabling patterns +as certain expressions, in particular those involving parentheses, +are parsed differently. + +@noindent +The following patterns may be disabled; all +the strings need quoting on the command line to prevent them from +being interpreted immediately as patterns and the patterns are +shown below in single quotes as a reminder. + +@noindent +@table @asis +@item @t{'?'} +The pattern character @t{?} wherever it occurs, including when preceding +a parenthesis with @t{KSH_GLOB}. + +@item @t{'*'} +The pattern character @t{*} wherever it occurs, including recursive +globbing and when preceding a parenthesis with @t{KSH_GLOB}. + +@item @t{'['} +Character classes. + +@item @t{'<'} (@t{NO_SH_GLOB}) +Numeric ranges. + +@item @t{'|'} (@t{NO_SH_GLOB}) +Alternation in grouped patterns, case statements, or KSH_GLOB +parenthesised expressions. + +@item @t{'('} (@t{NO_SH_GLOB}) +Grouping using single parentheses. Disabling this does not disable the +use of parentheses for @t{KSH_GLOB} where they are introduced by a +special character, nor for glob qualifiers (use `@t{setopt +NO_BARE_GLOB_QUAL}' to disable glob qualifiers that use parentheses +only). + +@item @t{'~'} (@t{EXTENDED_GLOB}) +Exclusion in the form @var{A}@t{~}@var{B}. + +@item @t{'^'} (@t{EXTENDED_GLOB}) +Exclusion in the form @var{A}@t{^}@var{B}. + +@item @t{'#'} (@t{EXTENDED_GLOB}) +The pattern character @t{#} wherever it occurs, both for +repetition of a previous pattern and for indicating globbing flags. + +@item @t{'?('} (@t{KSH_GLOB}) +The grouping form @t{?(}@var{...}@t{)}. Note this is also +disabled if @t{'?'} is disabled. + +@item @t{'*('} (@t{KSH_GLOB}) +The grouping form @t{*(}@var{...}@t{)}. Note this is also +disabled if @t{'*'} is disabled. + +@item @t{'+('} (@t{KSH_GLOB}) +The grouping form @t{+(}@var{...}@t{)}. + +@item @t{'!('} (@t{KSH_GLOB}) +The grouping form @t{!(}@var{...}@t{)}. + +@item @t{'@@('} (@t{KSH_GLOB}) +The grouping form @t{@@(}@var{...}@t{)}. + +@end table + +@findex disown +@cindex jobs, disowning +@item @t{disown} [ @var{job} ... ] +@itemx @var{job} ... @t{&|} +@itemx @var{job} ... @t{&!} +Remove the specified @var{job}s from the job table; the shell will +no longer report their status, and will not complain if you +try to exit an interactive shell with them running or stopped. +If no @var{job} is specified, disown the current job. + +@noindent +If the @var{job}s are currently stopped and the @t{AUTO_CONTINUE} option +is not set, a warning is printed containing information about how to +make them running after they have been disowned. If one of the latter +two forms is used, the @var{job}s will automatically be made running, +independent of the setting of the @t{AUTO_CONTINUE} option. + +@findex echo +@item @t{echo} [ @t{-neE} ] [ @var{arg} ... ] +Write each @var{arg} on the standard output, with a space separating +each one. +If the @t{-n} flag is not present, print a newline at the end. +@t{echo} recognizes the following escape sequences: + +@noindent +@table @asis +@item @t{\a} +bell character +@item @t{\b} +backspace +@item @t{\c} +suppress subsequent characters and final newline +@item @t{\e} +escape +@item @t{\f} +form feed +@item @t{\n} +linefeed (newline) +@item @t{\r} +carriage return +@item @t{\t} +horizontal tab +@item @t{\v} +vertical tab +@item @t{\\} +backslash +@item @t{\0}@var{NNN} +character code in octal +@item @t{\x}@var{NN} +character code in hexadecimal +@item @t{\u}@var{NNNN} +unicode character code in hexadecimal +@item @t{\U}@var{NNNNNNNN} +unicode character code in hexadecimal +@end table + +@noindent +@pindex BSD_ECHO, use of +The @t{-E} flag, or the @t{BSD_ECHO} option, can be used to disable +these escape sequences. In the latter case, @t{-e} flag can be used to +enable them. + +@noindent +Note that for standards compliance a double dash does not terminate +option processing; instead, it is printed directly. However, a +single dash does terminate option processing, so the first dash, +possibly following options, is not printed, but everything following it +is printed as an argument. The single dash behaviour is different +from other shells. For a more portable way of printing text, see +@t{printf}, and for a more controllable way of printing text within zsh, +see @t{print}. + +@item @t{echotc} +See @ref{The zsh/termcap Module}. + +@item @t{echoti} +See @ref{The zsh/terminfo Module}. + +@findex emulate +@cindex compatibility, sh +@cindex compatibility, ksh +@cindex compatibility, csh +@cindex sh, compatibility +@cindex ksh, compatibility +@cindex csh, compatibility +@item @t{emulate} [ @t{-lLR} ] [ @{@t{zsh}|@t{sh}|@t{ksh}|@t{csh}@} [ @var{flags} ... ] ] +Without any argument print current emulation mode. + +@noindent +With single argument set up zsh options to emulate the specified shell +as much as possible. +@cite{csh} will never be fully emulated. +If the argument is not one of the shells listed above, @t{zsh} +will be used as a default; more precisely, the tests performed on the +argument are the same as those used to determine the emulation at startup +based on the shell name, see +@ref{Compatibility} +. In addition to setting shell options, the command also restores +the pristine state of pattern enables, as if all patterns had been +enabled using @t{enable -p}. + +@noindent +If the @t{emulate} command occurs inside a function that has been +marked for execution tracing with @t{functions -t} then the @t{xtrace} +option will be turned on regardless of emulation mode or other options. +Note that code executed inside the function by the @t{.}, @t{source}, or +@t{eval} commands is not considered to be running directly from the +function, hence does not provoke this behaviour. + +@noindent +If the @t{-R} switch is given, all settable options +are reset to their default value corresponding to the specified emulation +mode, except for certain options describing the interactive +environment; otherwise, only those options likely to cause portability +problems in scripts and functions are altered. If the @t{-L} switch is given, +the options @t{LOCAL_OPTIONS}, @t{LOCAL_PATTERNS} and @t{LOCAL_TRAPS} +will be set as +well, causing the effects of the @t{emulate} command and any @t{setopt}, +@t{disable -p} or @t{enable -p}, and @t{trap} commands to be local to +the immediately surrounding shell +function, if any; normally these options are turned off in all emulation +modes except @t{ksh}. The @t{-L} switch is mutually exclusive with the +use of @t{-c} in @var{flags}. + +@noindent +If there is a single argument and the @t{-l} switch is given, the +options that would be set or unset (the latter indicated with the prefix +`@t{no}') are listed. @t{-l} can be combined with @t{-L} or @t{-R} and +the list will be modified in the appropriate way. Note the list does +not depend on the current setting of options, i.e. it includes all +options that may in principle change, not just those that would actually +change. + +@noindent +The @var{flags} may be any of the invocation-time flags described in +@ref{Invocation}, +except that `@t{-o EMACS}' and `@t{-o VI}' may not be used. Flags such +as `@t{+r}'/`@t{+o RESTRICTED}' may be prohibited in some circumstances. + +@noindent +If @t{-c} @var{arg} appears in @var{flags}, @var{arg} is evaluated while the +requested emulation is temporarily in effect. In this case the emulation +mode and all options are restored to their previous values before +@t{emulate} returns. The @t{-R} switch may precede the name of the shell +to emulate; note this has a meaning distinct from including @t{-R} in +@var{flags}. + +@noindent +Use of @t{-c} enables `sticky' emulation mode for functions defined +within the evaluated expression: the emulation mode is associated +thereafter with the function so that whenever the function is executed +the emulation (respecting the @t{-R} switch, if present) and all +options are set (and pattern disables cleared) +before entry to the function, and the state is restored after exit. +If the function is called when the sticky emulation is already in +effect, either within an `@t{emulate} @var{shell} @t{-c}' expression or +within another function with the same sticky emulation, entry and exit +from the function do not cause options to be altered (except due to +standard processing such as the @t{LOCAL_OPTIONS} option). This also +applies to functions marked for autoload within the sticky emulation; +the appropriate set of options will be applied at the point the +function is loaded as well as when it is run. + +@noindent +For example: + +@noindent +@example +emulate sh -c 'fni() @{ setopt cshnullglob; @} +fno() @{ fni; @}' +fno +@end example + +@noindent +The two functions @t{fni} and @t{fno} are defined with sticky @t{sh} +emulation. @t{fno} is then executed, causing options associated +with emulations to be set to their values in @t{sh}. @t{fno} then +calls @t{fni}; because @t{fni} is also marked for sticky @t{sh} +emulation, no option changes take place on entry to or exit from it. +Hence the option @t{cshnullglob}, turned off by @t{sh} emulation, will +be turned on within @t{fni} and remain on return to @t{fno}. On exit +from @t{fno}, the emulation mode and all options will be restored to the +state they were in before entry to the temporary emulation. + +@noindent +The documentation above is typically sufficient for the intended +purpose of executing code designed for other shells in a suitable +environment. More detailed rules follow. +@table @asis +@item 1. +The sticky emulation environment provided by `@t{emulate} +@var{shell} @t{-c}' is identical to that provided by entry to +a function marked for sticky emulation as a consequence of being +defined in such an environment. Hence, for example, the sticky +emulation is inherited by subfunctions defined within functions +with sticky emulation. +@item 2. +No change of options takes place on entry to or exit from +functions that are not marked for sticky emulation, other than those +that would normally take place, even if those functions are called +within sticky emulation. +@item 3. +No special handling is provided for functions marked for +@t{autoload} nor for functions present in wordcode created by +the @t{zcompile} command. +@item 4. +The presence or absence of the @t{-R} switch to @t{emulate} +corresponds to different sticky emulation modes, so for example +`@t{emulate sh -c}', `@t{emulate -R sh -c}' and `@t{emulate csh -c}' +are treated as three distinct sticky emulations. +@item 5. +Difference in shell options supplied in addition to the +basic emulation also mean the sticky emulations are different, so for +example `@t{emulate zsh -c}' and `@t{emulate zsh -o cbases -c}' are +treated as distinct sticky emulations. +@end table + +@findex enable +@cindex enabling commands +@cindex commands, enabling +@item @t{enable} [ @t{-afmprs} ] @var{name} ... +Enable the @var{name}d hash table elements, presumably disabled +earlier with @t{disable}. The default is to enable builtin commands. +The @t{-a} option causes @t{enable} to act on regular or global aliases. +The @t{-s} option causes @t{enable} to act on suffix aliases. +The @t{-f} option causes @t{enable} to act on shell functions. The @t{-r} +option causes @t{enable} to act on reserved words. Without arguments +all enabled hash table elements from the corresponding hash table are +printed. With the @t{-m} flag the arguments are taken as patterns +(should be quoted) and all hash table elements from the corresponding +hash table matching these patterns are enabled. Enabled objects can be +disabled with the @t{disable} builtin command. + +@noindent +@t{enable -p} reenables patterns disabled with @t{disable -p}. Note +that it does not override globbing options; for example, `@t{enable -p +"~"}' does not cause the pattern character @t{~} to be active unless +the @t{EXTENDED_GLOB} option is also set. To enable all possible +patterns (so that they may be individually disabled with @t{disable -p}), +use `@t{setopt EXTENDED_GLOB KSH_GLOB NO_SH_GLOB}'. + +@findex eval +@cindex evaluating arguments as commands +@item @t{eval} [ @var{arg} ... ] +Read the arguments as input to the shell and execute the resulting +command(s) in the current shell process. The return status is +the same as if the commands had been executed directly by the shell; +if there are no @var{args} or they contain no commands (i.e. are +an empty string or whitespace) the return status is zero. + +@item @t{exec} [ @t{-cl} ] [ @t{-a} @var{argv0} ] [ @var{command} [ @var{arg} ... ] ] +Replace the current shell with @var{command} rather than forking. +If @var{command} is a shell builtin command or a shell function, +the shell executes it, and exits when the command is complete. + +@noindent +With @t{-c} clear the environment; with @t{-l} prepend @t{-} to the +@t{argv[0]} string of the command executed (to simulate a login shell); +with @t{-a} @var{argv0} set the @t{argv[0]} string of the command +executed. +See @ref{Precommand Modifiers}. + +@noindent +If the option @t{POSIX_BUILTINS} is set, @var{command} is never +interpreted as a shell builtin command or shell function. This +means further precommand modifiers such as @t{builtin} and +@t{noglob} are also not interpreted within the shell. Hence +@var{command} is always found by searching the command path. + +@noindent +@cindex redirection, current shell's I/O +If @var{command} is omitted but any redirections are specified, +then the redirections will take effect in the current shell. + +@findex exit +@item @t{exit} [ @var{n} ] +Exit the shell with the exit status specified by an arithmetic +expression @var{n}; if none +is specified, use the exit status from the last command executed. +@pindex IGNORE_EOF, use of +An EOF condition will also cause the shell to exit, unless +the @t{IGNORE_EOF} option is set. + +@noindent +See notes at the end of +@ref{Jobs & Signals} for some possibly unexpected interactions +of the @t{exit} command with jobs. + +@findex export +@item @t{export} [ @var{name}[@t{=}@var{value}] ... ] +The specified @var{name}s are marked for automatic export +to the environment of subsequently executed commands. +Equivalent to @t{typeset -gx}. +If a parameter specified does not +already exist, it is created in the global scope. + +@findex false +@cindex doing nothing, unsuccessfully +@item @t{false} [ @var{arg} ... ] +Do nothing and return an exit status of 1. + +@findex fc +@cindex history, editing +@cindex editing history + +@item @t{fc} [ @t{-e} @var{ename} ] [ @t{-s} ] [ @t{-LI} ] [ @t{-m} @var{match} ] [ @var{old}@t{=}@var{new} ... ] [ @var{first} [ @var{last} ] ] +@itemx @t{fc -l }[ @t{-LI} ] [ @t{-nrdfEiD} ] [ @t{-t} @var{timefmt} ] [ @t{-m} @var{match} ] +@itemx @t{@ @ @ @ @ @ }[ @var{old}@t{=}@var{new} ... ] [ @var{first} [ @var{last} ] ] +@itemx @t{fc -p }[ @t{-a} ] [ @var{filename} [ @var{histsize} [ @var{savehistsize} ] ] ] +@itemx @t{fc} @t{-P} +@itemx @t{fc} @t{-ARWI} [ @var{filename} ] +The @t{fc} command controls the interactive history mechanism. Note +that reading and writing of history options is only performed if the +shell is interactive. Usually this is detected automatically, but +it can be forced by setting the @t{interactive} option when starting the +shell. + +@noindent +The first two forms of this command select a range of events from +@var{first} to @var{last} from the history list. The arguments @var{first} +and @var{last} may be specified as a number or as a string. A negative +number is used as an offset to the current history event number. A string +specifies the most recent event beginning with the given string. All +substitutions @var{old}@t{=}@var{new}, if any, are then performed on the +text of the events. + +@noindent +The range of events selected by numbers can be narrowed further by the +following flags. +@table @asis +@item @t{-I} +restricts to only internal events (not from @t{$HISTFILE}) +@item @t{-L} +restricts to only local events (not from other shells, see +@t{SHARE_HISTORY} in @ref{Description of Options} -- note that @t{$HISTFILE} is +considered local when read at startup) +@item @t{-m} +takes the first argument as a pattern (which should be +quoted) and only the history events matching this pattern are considered +@end table + +@noindent +If @var{first} is not specified, it will be set to -1 (the most recent +event), or to -16 if the @t{-l} flag is given. +If @var{last} is not specified, it will be set to @var{first}, +or to -1 if the @t{-l} flag is given. +However, if the current event has added entries to the history with +`@t{print -s}' or `@t{fc -R}', then the default @var{last} for @t{-l} +includes all new history entries since the current event began. + +@noindent +When the @t{-l} flag is given, the resulting events are listed on +standard output. Otherwise the editor program specified by @t{-e} @var{ename} +is invoked on a file containing these history events. If @t{-e} is not given, the +value of the parameter @t{FCEDIT} is used; if that is not set the value of +the parameter @t{EDITOR} is used; if that is not set a builtin default, +usually `@t{vi}' is used. If @var{ename} is `@t{-}', no editor is invoked. +When editing is complete, the edited command is executed. + +@noindent +The flag `@t{-s}' is equivalent to `@t{-e -}'. +The flag @t{-r} reverses the order of the events and the +flag @t{-n} suppresses event numbers when listing. + +@noindent +Also when listing, +@table @asis +@item @t{-d} +prints timestamps for each event +@item @t{-f} +prints full time-date stamps in the US +`@var{MM}@t{/}@var{DD}@t{/}@var{YY} @var{hh}@t{:}@var{mm}' format +@item @t{-E} +prints full time-date stamps in the European +`@var{dd}@t{.}@var{mm}@t{.}@var{yyyy} @var{hh}@t{:}@var{mm}' format +@item @t{-i} +prints full time-date stamps in ISO8601 +`@var{yyyy}@t{-}@var{mm}@t{-}@var{dd} @var{hh}@t{:}@var{mm}' format +@item @t{-t} @var{fmt} +prints time and date stamps in the given format; +@var{fmt} is formatted with the strftime function with the zsh extensions +described for the @t{%D@{}@var{string}@t{@}} prompt format in +@ref{Prompt Expansion}. The resulting formatted string must be +no more than 256 characters or will not be printed + +@item @t{-D} +prints elapsed times; may be combined with one of the +options above +@end table + +@noindent +@cindex history, stack +@cindex stack, history +`@t{fc -p}' pushes the current history list onto a stack and switches to a +new history list. If the @t{-a} option is also specified, this history list +will be automatically popped when the current function scope is exited, which +is a much better solution than creating a trap function to call `@t{fc -P}' +manually. If no arguments are specified, the history list is left empty, +@t{$HISTFILE} is unset, and @t{$HISTSIZE} & @t{$SAVEHIST} are set to their +default values. If one argument is given, @t{$HISTFILE} is set to that +filename, @t{$HISTSIZE} & @t{$SAVEHIST} are left unchanged, and the history +file is read in (if it exists) to initialize the new list. If a second +argument is specified, @t{$HISTSIZE} & @t{$SAVEHIST} are instead set to the +single specified numeric value. Finally, if a third argument is specified, +@t{$SAVEHIST} is set to a separate value from @t{$HISTSIZE}. You are free to +change these environment values for the new history list however you desire +in order to manipulate the new history list. + +@noindent +`@t{fc -P}' pops the history list back to an older list saved by `@t{fc -p}'. +The current list is saved to its @t{$HISTFILE} before it is destroyed +(assuming that @t{$HISTFILE} and @t{$SAVEHIST} are set appropriately, of +course). The values of @t{$HISTFILE}, @t{$HISTSIZE}, and @t{$SAVEHIST} are +restored to the values they had when `@t{fc -p}' was called. Note that this +restoration can conflict with making these variables "local", so your best +bet is to avoid local declarations for these variables in functions that use +`@t{fc -p}'. The one other guaranteed-safe combination is declaring these +variables to be local at the top of your function and using the automatic +option (@t{-a}) with `@t{fc -p}'. Finally, note that it is legal to manually +pop a push marked for automatic popping if you need to do so before the +function exits. + +@noindent +@cindex history, file +@cindex file, history +`@t{fc -R}' reads the history from the given file, +`@t{fc -W}' writes the history out to the given file, +and `@t{fc -A}' appends the history out to the given file. +If no filename is specified, the @t{$HISTFILE} is assumed. +If the @t{-I} option is added to @t{-R}, only those events that are +not already contained within the internal history list are added. +If the @t{-I} option is added to @t{-A} or @t{-W}, only those +events that are new since last incremental append/write to +the history file are appended/written. +In any case, the created file will have no more than @t{$SAVEHIST} +entries. + +@findex fg +@cindex jobs, foregrounding +@cindex jobs, resuming +@item @t{fg} [ @var{job} ... ] +@itemx @var{job} ... +Bring each specified @var{job} in turn to the foreground. +If no @var{job} is specified, resume the current job. + +@findex float +@item @t{float} [ @{@t{+}|@t{-}@}@t{Hghlprtux} ] [ @{@t{+}|@t{-}@}@t{EFLRZ} [ @var{n} ] ] [ @var{name}[@t{=}@var{value}] ... ] +Equivalent to @t{typeset -E}, except that options irrelevant to floating +point numbers are not permitted. + +@findex functions +@item @t{functions} [ @{@t{+}|@t{-}@}@t{UkmtTuWz} ] [ @t{-x} @var{num} ] [ @var{name} ... ] +@itemx @t{functions -c} @var{oldfn} @var{newfn} +@itemx @t{functions -M} [@t{-s}] @var{mathfn} [ @var{min} [ @var{max} [ @var{shellfn} ] ] ] +@itemx @t{functions -M} [ @t{-m} @var{pattern} ... ] +@itemx @t{functions +M} [ @t{-m} ] @var{mathfn} ... +Equivalent to @t{typeset -f}, with the exception of the @t{-c}, @t{-x}, +@t{-M} and @t{-W} options. For @t{functions -u} and @t{functions -U}, +see @t{autoload}, which provides additional options. + +@noindent +The @t{-x} option indicates that any functions output will have +each leading tab for indentation, added by the shell to show syntactic +structure, expanded to the given number @var{num} of spaces. @var{num} +can also be 0 to suppress all indentation. + +@noindent +The @t{-W} option turns on the option @t{WARN_NESTED_VAR} for the named +function or functions only. The option is turned off at the start of +nested functions (apart from anonoymous functions) unless the called +function also has the @t{-W} attribute. + +@noindent +The @t{-c} option causes @var{oldfn} to be copied to @var{newfn}. The +copy is efficiently handled internally by reference counting. If +@var{oldfn} was marked for autoload it is first loaded and if this +fails the copy fails. Either function may subsequently be redefined +without affecting the other. A typical idiom is that @var{oldfn} is the +name of a library shell function which is then redefined to call +@t{newfn}, thereby installing a modified version of the function. + +@noindent +@emph{The }@t{-M}@emph{ and }@t{+M}@emph{ flags} +@cindex defining mathematical functions +@cindex functions, defining mathematical + +@noindent +Use of the @t{-M} option may not be combined with any of the options +handled by @t{typeset -f}. + +@noindent +@t{functions -M} @var{mathfn} defines @var{mathfn} as the name of +a mathematical function recognised in all forms of arithmetical expressions; +see +@ref{Arithmetic Evaluation}. By default @var{mathfn} may take +any number of comma-separated arguments. If @var{min} is given, +it must have exactly @var{min} args; if @var{min} and @var{max} are +both given, it must have at least @var{min} and at most @var{max} +args. @var{max} may be -1 to indicate that there is no upper limit. + +@noindent +By default the function is implemented by a shell function of the same +name; if @var{shellfn} is specified it gives the name of the corresponding +shell function while @var{mathfn} remains the name used in arithmetical +expressions. The name of the function in @t{$0} is @var{mathfn} (not +@var{shellfn} as would usually be the case), provided the option +@t{FUNCTION_ARGZERO} is in effect. The positional parameters in the shell +function correspond to the arguments of the mathematical function call. + +@noindent +The result of the last arithmetical expression evaluated inside the shell +function gives the result of the mathematical function. This is not limited to +arithmetic substitutions of the form @t{$((}@var{...}@t{))}, +but also includes arithmetical expressions evaluated in any other way, including +by the @t{let} builtin, +by @t{((}@var{...}@t{))} statements, +and even +by the @t{return} builtin +and +by array subscripts. +Therefore, care must be taken not to use syntactical constructs that perform +arithmetic evaluation after evaluating what is to be the result of the function. +For example: + +@noindent +@findex zmath_cube +@findex cube +@example +# WRONG +zmath_cube() @{ + (( $1 * $1 * $1 )) + return 0 +@} +functions -M cube 1 1 zmath_cube +print $(( cube(3) )) +@end example + +@noindent +This will print `@t{0}' because of the @t{return}. + +@noindent +Commenting the @t{return} out would lead to a different problem: the +@t{((}@var{...}@t{))} statement would become +the last statement in the function, so the @emph{return status} (@t{$?}) of the +function would be non-zero (indicating failure) whenever the @emph{arithmetic +result} of the function would happen to be zero (numerically): + +@noindent +@example +# WRONG +zmath_cube() @{ + (( $1 * $1 * $1 )) +@} +functions -M cube 1 1 zmath_cube +print $(( cube(0) )) +@end example + +@noindent +Instead, the @t{true} builtin can be used: + +@noindent +@example +# RIGHT +zmath_cube() @{ + (( $1 * $1 * $1 )) + true +@} +functions -M cube 1 1 zmath_cube +print $(( cube(3) )) +@end example + +@noindent +If the additional option @t{-s} is given to @t{functions -M}, the +argument to the function is a single string: anything between the +opening and matching closing parenthesis is passed to the function as a +single argument, even if it includes commas or white space. The minimum +and maximum argument specifiers must therefore be 1 if given. An empty +argument list is passed as a zero-length string. +Thus, the following string function takes a single argument, including +the commas, and prints 11: + +@noindent +@example +stringfn() @{ (( $#1 )); true @} +functions -Ms stringfn +print $(( stringfn(foo,bar,rod) )) +@end example + +@noindent +@t{functions -M} with no arguments lists all such user-defined functions in +the same form as a definition. With the additional option @t{-m} and +a list of arguments, all functions whose @var{mathfn} matches one of +the pattern arguments are listed. + +@noindent +@t{function +M} removes the list of mathematical functions; with the +additional option @t{-m} the arguments are treated as patterns and +all functions whose @var{mathfn} matches the pattern are removed. Note +that the shell function implementing the behaviour is not removed +(regardless of whether its name coincides with @var{mathfn}). + +@item @t{getcap} +See @ref{The zsh/cap Module}. + +@findex getln +@cindex line, reading +@cindex reading a line +@item @t{getln} [ @t{-AclneE} ] @var{name} ... +Read the top value from the buffer stack and put it in +the shell parameter @var{name}. Equivalent to +@t{read -zr}. + +@findex getopts +@cindex options, processing +@item @t{getopts} @var{optstring} @var{name} [ @var{arg} ... ] +Checks the @var{arg}s for legal options. If the @var{arg}s are omitted, +use the positional parameters. A valid option argument +begins with a `@t{+}' or a `@t{-}'. An argument not beginning with +a `@t{+}' or a `@t{-}', or the argument `@t{-}@t{-}', ends the options. +Note that a single `@t{-}' is not considered a valid option argument. +@var{optstring} contains the letters that @t{getopts} +recognizes. If a letter is followed by a `@t{:}', that option +requires an argument. The options can be +separated from the argument by blanks. + +@noindent +Each time it is invoked, @t{getopts} places the option letter it finds +in the shell parameter @var{name}, prepended with a `@t{+}' when +@var{arg} begins with a `@t{+}'. The index of the next @var{arg} +is stored in @t{OPTIND}. The option argument, if any, +is stored in @t{OPTARG}. +@vindex OPTIND, use of +@vindex OPTARG, use of + +@noindent +The first option to be examined may be changed by explicitly assigning +to @t{OPTIND}. @t{OPTIND} has an initial value of @t{1}, and is +normally set to @t{1} upon entry to a shell function and restored +upon exit. (The @t{POSIX_BUILTINS} option disables this, and also changes +the way the value is calculated to match other shells.) @t{OPTARG} +is not reset and retains its value from the most recent call to +@t{getopts}. If either of @t{OPTIND} or @t{OPTARG} is explicitly +unset, it remains unset, and the index or option argument is not +stored. The option itself is still stored in @var{name} in this case. + +@noindent +A leading `@t{:}' in @var{optstring} causes @t{getopts} to store the +letter of any invalid option in @t{OPTARG}, and to set @var{name} to +`@t{?}' for an unknown option and to `@t{:}' when a required argument is +missing. Otherwise, @t{getopts} sets @var{name} to `@t{?}' and prints +an error message when an option is invalid. The exit status is +nonzero when there are no more options. + +@findex hash +@item @t{hash} [ @t{-Ldfmrv} ] [ @var{name}[@t{=}@var{value}] ] ... +@t{hash} can be used to directly modify the contents of the command +hash table, and the named directory hash table. Normally one would +modify these tables by modifying one's @t{PATH} +(for the command hash table) or by creating appropriate shell parameters +(for the named directory hash table). +The choice of hash table to work on is determined by the @t{-d} option; +without the option the command hash table is used, and with the option the +named directory hash table is used. + +@noindent +A command @var{name} starting with a @t{/} is never hashed, whether by +explicit use of the @t{hash} command or otherwise. Such a command +is always found by direct look up in the file system. + +@noindent +Given no arguments, and neither the @t{-r} or @t{-f} options, +the selected hash table will be listed in full. + +@noindent +The @t{-r} option causes the selected hash table to be emptied. +It will be subsequently rebuilt in the normal fashion. +The @t{-f} option causes the selected hash table to be fully +rebuilt immediately. For the command hash table this hashes +all the absolute directories in the @t{PATH}, +and for the named directory hash table this adds all users' home directories. +These two options cannot be used with any arguments. + +@noindent +The @t{-m} option causes the arguments to be taken as patterns +(which should be quoted) and the elements of the hash table +matching those patterns are printed. This is the only way to display +a limited selection of hash table elements. + +@noindent +For each @var{name} with a corresponding @var{value}, put `@var{name}' in +the selected hash table, associating it with the pathname `@var{value}'. +In the command hash table, this means that +whenever `@var{name}' is used as a command argument, the shell will try +to execute the file given by `@var{value}'. +In the named directory hash table, this means +that `@var{value}' may be referred to as `@t{~}@var{name}'. + +@noindent +For each @var{name} with no +corresponding @var{value}, attempt to add @var{name} to the hash table, +checking what the appropriate @t{value} is in the normal manner for +that hash table. If an appropriate @t{value} can't be found, then +the hash table will be unchanged. + +@noindent +The @t{-v} option causes hash table entries to be listed as they are +added by explicit specification. If has no effect if used with @t{-f}. + +@noindent +If the @t{-L} flag is present, then each hash table entry is printed in +the form of a call to hash. + +@findex history +@item @t{history} +Same as @t{fc -l}. + +@findex integer +@item @t{integer} [ @{@t{+}|@t{-}@}@t{Hghlprtux} ] [ @{@t{+}|@t{-}@}@t{LRZi} [ @var{n} ] ] [ @var{name}[@t{=}@var{value}] ... ] +Equivalent to @t{typeset -i}, except that options irrelevant to +integers are not permitted. + +@findex jobs +@item @t{jobs} [ @t{-dlprs} ] [ @var{job} ... ] +@itemx @t{jobs -Z} @var{string} +Lists information about each given job, or all jobs +if @var{job} is omitted. The @t{-l} flag lists process +IDs, and the @t{-p} flag lists process groups. +If the @t{-r} flag is specified only running jobs will be listed +and if the @t{-s} flag is given only stopped jobs are shown. +If the @t{-d} flag is given, the directory from which the job was +started (which may not be the current directory of the job) will also +be shown. + +@noindent +The @t{-Z} option replaces the shell's argument and environment space with +the given string, truncated if necessary to fit. This will normally be +visible in @t{ps} (ps(1)) listings. This feature is typically +used by daemons, to indicate their state. + +@noindent +Full job control is only available in the top-level interactive shell, +not in commands run in the left hand side of pipelines or within +the @t{(}@var{...}@t{)} construct. However, a snapshot +of the job state at that point is taken, so it is still possible +to use the @t{jobs} builtin, or any parameter providing job information. +This gives information about the state of jobs at the point the subshell +was created. If background processes are created within the subshell, +then instead information about those processes is provided. + +@noindent +For example, + +@noindent +@example +sleep 10 & # Job in background +( # Shell forks +jobs # Shows information about "sleep 10 &" +sleep 5 & # Process in background (no job control) +jobs # Shows information about "sleep 5 &" +) +@end example + +@findex kill +@cindex killing jobs +@cindex jobs, killing +@item @t{kill} [ @t{-s} @var{signal_name} | @t{-n} @var{signal_number} | @t{-}@var{sig} ] @var{job} ... +@itemx @t{kill} @t{-l} [ @var{sig} ... ] +Sends either @t{SIGTERM} or the specified signal to the given +jobs or processes. +Signals are given by number or by names, with or without the `@t{SIG}' +prefix. +If the signal being sent is not `@t{KILL}' or `@t{CONT}', then the job +will be sent a `@t{CONT}' signal if it is stopped. +The argument @var{job} can be the process ID of a job +not in the job list. +In the second form, @t{kill -l}, if @var{sig} is not +specified the signal names are listed. Otherwise, for each +@var{sig} that is a name, the corresponding signal number is +listed. For each @var{sig} that is a signal number or a number +representing the exit status of a process which was terminated or +stopped by a signal the name of the signal is printed. + +@noindent +On some systems, alternative signal names are allowed for a few signals. +Typical examples are @t{SIGCHLD} and @t{SIGCLD} or @t{SIGPOLL} and +@t{SIGIO}, assuming they correspond to the same signal number. @t{kill +-l} will only list the preferred form, however @t{kill -l} @var{alt} will +show if the alternative form corresponds to a signal number. For example, +under Linux @t{kill -l IO} and @t{kill -l POLL} both output 29, hence +@t{kill -IO} and @t{kill -POLL} have the same effect. + +@noindent +Many systems will allow process IDs to be negative to kill a process +group or zero to kill the current process group. + +@findex let +@item @t{let} @var{arg} ... +Evaluate each @var{arg} as an arithmetic expression. +See +@ref{Arithmetic Evaluation} +for a description of arithmetic expressions. The exit status is 0 if the +value of the last expression is nonzero, 1 if it is zero, and 2 if +an error occurred. + +@findex limit +@cindex resource limits +@cindex limits, resource +@item @t{limit} [ @t{-hs} ] [ @var{resource} [ @var{limit} ] ] ... +Set or display resource limits. Unless the @t{-s} flag is given, +the limit applies only the children of the shell. If @t{-s} is +given without other arguments, the resource limits of the current +shell is set to the previously set resource limits of the children. + +@noindent +If @var{limit} is not specified, print the current limit placed +on @var{resource}, otherwise +set the limit to the specified value. If the @t{-h} flag +is given, use hard limits instead of soft limits. +If no @var{resource} is given, print all limits. + +@noindent +When looping over multiple resources, the shell will abort immediately if +it detects a badly formed argument. However, if it fails to set a limit +for some other reason it will continue trying to set the remaining limits. + +@noindent +@var{resource} can be one of: + +@noindent +@table @asis +@item @t{addressspace} +Maximum amount of address space used. +@item @t{aiomemorylocked} +Maximum amount of memory locked in RAM for AIO operations. +@item @t{aiooperations} +Maximum number of AIO operations. +@item @t{cachedthreads} +Maximum number of cached threads. +@item @t{coredumpsize} +Maximum size of a core dump. +@item @t{cputime} +Maximum CPU seconds per process. +@item @t{datasize} +Maximum data size (including stack) for each process. +@item @t{descriptors} +Maximum value for a file descriptor. +@item @t{filesize} +Largest single file allowed. +@item @t{kqueues} +Maximum number of kqueues allocated. +@item @t{maxproc} +Maximum number of processes. +@item @t{maxpthreads} +Maximum number of threads per process. +@item @t{memorylocked} +Maximum amount of memory locked in RAM. +@item @t{memoryuse} +Maximum resident set size. +@item @t{msgqueue} +Maximum number of bytes in POSIX message queues. +@item @t{posixlocks} +Maximum number of POSIX locks per user. +@item @t{pseudoterminals} +Maximum number of pseudo-terminals. +@item @t{resident} +Maximum resident set size. +@item @t{sigpending} +Maximum number of pending signals. +@item @t{sockbufsize} +Maximum size of all socket buffers. +@item @t{stacksize} +Maximum stack size for each process. +@item @t{swapsize} +Maximum amount of swap used. +@item @t{vmemorysize} +Maximum amount of virtual memory. +@end table + +@noindent +Which of these resource limits are available depends on the system. +@var{resource} can be abbreviated to any unambiguous prefix. It +can also be an integer, which corresponds to the integer defined +for the resource by the operating system. + +@noindent +If argument corresponds to a number which is out of the range of the +resources configured into the shell, the shell will try to read or write +the limit anyway, and will report an error if this fails. As the shell +does not store such resources internally, an attempt to set the limit will +fail unless the @t{-s} option is present. + +@noindent +@var{limit} is a number, with an optional scaling factor, as follows: + +@noindent +@table @asis +@item @var{n}@t{h} +hours +@item @var{n}@t{k} +kilobytes (default) +@item @var{n}@t{m} +megabytes or minutes +@item @var{n}@t{g} +gigabytes +@item [@var{mm}@t{:}]@var{ss} +minutes and seconds +@end table + +@noindent +The @t{limit} command is not made available by default when the +shell starts in a mode emulating another shell. It can be made available +with the command `@t{zmodload -F zsh/rlimits b:limit}'. + +@findex local +@item @t{local} [ @{@t{+}|@t{-}@}@t{AHUahlprtux} ] [ @{@t{+}|@t{-}@}@t{EFLRZi} [ @var{n} ] ] [ @var{name}[@t{=}@var{value}] ... ] +Same as @t{typeset}, except that the options @t{-g}, and +@t{-f} are not permitted. In this case the @t{-x} option does not force +the use of @t{-g}, i.e. exported variables will be local to functions. + +@findex logout +@item @t{logout} [ @var{n} ] +Same as @t{exit}, except that it only works in a login shell. + +@item @t{noglob} @var{simple command} +See @ref{Precommand Modifiers}. + +@findex popd +@item @t{popd} [ @t{-q} ] [ @{@t{+}|@t{-}@}@var{n} ] +Remove an entry from the directory stack, and perform a @t{cd} to +the new top directory. With no argument, the current top entry is +removed. An argument of the form `@t{+}@var{n}' identifies a stack +entry by counting from the left of the list shown by the @t{dirs} command, +starting with zero. An argument of the form @t{-}@var{n} counts from the right. +@pindex PUSHD_MINUS, use of +If the @t{PUSHD_MINUS} option is set, the meanings of `@t{+}' and +`@t{-}' in this context are swapped. + +@noindent +If the @t{-q} (quiet) option is specified, the hook function @t{chpwd} +and the functions in the array @t{$chpwd_functions} are not called, +and the new directory stack is not printed. This is useful for calls to +@t{popd} that do not change the environment seen by an interactive user. + +@findex print +@item @t{print }[ @t{-abcDilmnNoOpPrsSz} ] [ @t{-u} @var{n} ] [ @t{-f} @var{format} ] [ @t{-C} @var{cols} ] +@itemx @t{@ @ @ @ @ @ }[ @t{-v} @var{name} ] [ @t{-xX} @var{tabstop} ] [ @t{-R} [ @t{-en} ]] [ @var{arg} ... ] +With the `@t{-f}' option the arguments are printed as described by @t{printf}. +With no flags or with the flag `@t{-}', the arguments are printed on +the standard output as described by @t{echo}, with the following differences: +the escape sequence `@t{\M-}@var{x}' (or `@t{\M}@var{x}') metafies the character +@var{x} (sets the highest bit), +`@t{\C-}@var{x}' (or `@t{\C}@var{x}') produces a control character +(`@t{\C-@@}' and `@t{\C-?}' give the characters NULL and delete), +a character code in octal is represented by `@t{\}@var{NNN}' +(instead of `@t{\0}@var{NNN}'), +and `@t{\E}' is a synonym for `@t{\e}'. +Finally, if not in an escape +sequence, `@t{\}' escapes the following character and is not printed. + +@noindent +@table @asis +@item @t{-a} +Print arguments with the column incrementing first. Only useful with the +@t{-c} and @t{-C} options. + +@item @t{-b} +Recognize all the escape sequences defined for the @t{bindkey} command, +see +@ref{Zle Builtins}. + +@item @t{-c} +Print the arguments in columns. Unless @t{-a} is also given, arguments are +printed with the row incrementing first. + +@item @t{-C} @var{cols} +Print the arguments in @var{cols} columns. Unless @t{-a} is also given, +arguments are printed with the row incrementing first. + +@item @t{-D} +Treat the arguments as paths, replacing directory prefixes with @t{~} +expressions corresponding to directory names, as appropriate. + +@item @t{-i} +If given together with @t{-o} or @t{-O}, sorting is performed +case-independently. + +@item @t{-l} +Print the arguments separated by newlines instead of spaces. Note: if +the list of arguments is empty, @t{print -l} will still output one empty +line. To print a possibly-empty list of arguments one per line, use +@t{print -C1}, as in `@t{print -rC1 -- "$list[@@]"}'. + +@item @t{-m} +Take the first argument as a pattern (should be quoted), and remove +it from the argument list together with subsequent arguments that +do not match this pattern. + +@item @t{-n} +Do not add a newline to the output. + +@item @t{-N} +Print the arguments separated and terminated by nulls. Again, +@t{print -rNC1 -- "$list[@@]"} is a canonical way to print an +arbitrary list as null-delimited records. + +@item @t{-o} +Print the arguments sorted in ascending order. + +@item @t{-O} +Print the arguments sorted in descending order. + +@item @t{-p} +Print the arguments to the input of the coprocess. + +@item @t{-P} +Perform prompt expansion (see +@ref{Prompt Expansion}). +In combination with `@t{-f}', +prompt escape sequences are parsed only within interpolated arguments, +not within the format string. + +@item @t{-r} +Ignore the escape conventions of @t{echo}. + +@item @t{-R} +Emulate the BSD @t{echo} command, which does not process escape sequences +unless the @t{-e} flag is given. The @t{-n} flag suppresses the trailing +newline. Only the @t{-e} and @t{-n} flags are recognized after +@t{-R}; all other arguments and options are printed. + +@item @t{-s} +Place the results in the history list instead of on the standard output. +Each argument to the @t{print} command is treated as a single word in the +history, regardless of its content. + +@item @t{-S} +Place the results in the history list instead of on the standard output. +In this case only a single argument is allowed; it will be split into +words as if it were a full shell command line. The effect is +similar to reading the line from a history file with the +@t{HIST_LEX_WORDS} option active. + +@item @t{-u} @var{n} +Print the arguments to file descriptor @var{n}. + +@item @t{-v} @var{name} +Store the printed arguments as the value of the parameter @var{name}. + +@item @t{-x} @var{tab-stop} +Expand leading tabs on each line of output in the printed string +assuming a tab stop every @var{tab-stop} characters. This is appropriate +for formatting code that may be indented with tabs. Note that leading +tabs of any argument to print, not just the first, are expanded, even if +@t{print} is using spaces to separate arguments (the column count +is maintained across arguments but may be incorrect on output +owing to previous unexpanded tabs). + +@noindent +The start of the output of each print command is assumed to be aligned +with a tab stop. Widths of multibyte characters are handled if the +option @t{MULTIBYTE} is in effect. This option is ignored if other +formatting options are in effect, namely column alignment or +@t{printf} style, or if output is to a special location such as shell +history or the command line editor. + +@item @t{-X} @var{tab-stop} +This is similar to @t{-x}, except that all tabs in the printed string +are expanded. This is appropriate if tabs in the arguments are +being used to produce a table format. + +@item @t{-z} +Push the arguments onto the editing buffer stack, separated by spaces. + +@end table + +@noindent +If any of `@t{-m}', `@t{-o}' or `@t{-O}' are used in combination with +`@t{-f}' and there are no arguments (after the removal process in the +case of `@t{-m}') then nothing is printed. + +@findex printf +@item @t{printf} [ @t{-v} @var{name} ] @var{format} [ @var{arg} ... ] +Print the arguments according to the format specification. Formatting +rules are the same as used in C. The same escape sequences as for @t{echo} +are recognised in the format. All C conversion specifications ending in +one of @t{csdiouxXeEfgGn} are handled. In addition to this, `@t{%b}' can be +used instead of `@t{%s}' to cause escape sequences in the argument to be +recognised and `@t{%q}' can be used to quote the argument in such a way +that allows it to be reused as shell input. With the numeric format +specifiers, if the corresponding argument starts with a quote character, +the numeric value of the following character is used as the number to +print; otherwise the argument is evaluated as an arithmetic expression. See +@ref{Arithmetic Evaluation} +for a description of arithmetic +expressions. With `@t{%n}', the corresponding argument is taken as an +identifier which is created as an integer parameter. + +@noindent +Normally, conversion specifications are applied to each argument in order +but they can explicitly specify the @var{n}th argument is to be used by +replacing `@t{%}' by `@t{%}@var{n}@t{$}' and `@t{*}' by `@t{*}@var{n}@t{$}'. +It is recommended that you do not mix references of this explicit style +with the normal style and the handling of such mixed styles may be subject +to future change. + +@noindent +If arguments remain unused after formatting, the format string is reused +until all arguments have been consumed. With the @t{print} builtin, this +can be suppressed by using the @t{-r} option. If more arguments are +required by the format than have been specified, the behaviour is as if +zero or an empty string had been specified as the argument. + +@noindent +The @t{-v} option causes the output to be stored as the value of the +parameter @var{name}, instead of printed. If @var{name} is an array and +the format string is reused when consuming arguments then one +array element will be used for each use of the format string. + +@findex pushd +@pindex PUSHD_TO_HOME, use of +@pindex PUSHD_MINUS, use of +@pindex CDABLE_VARS, use of +@pindex PUSHD_SILENT, use of +@item @t{pushd} [ @t{-qsLP} ] [ @var{arg} ] +@itemx @t{pushd} [ @t{-qsLP} ] @var{old} @var{new} +@itemx @t{pushd} [ @t{-qsLP} ] @{@t{+}|@t{-}@}@var{n} +Change the current directory, and push the old current directory +onto the directory stack. In the first form, change the +current directory to @var{arg}. +If @var{arg} is not specified, change to the second directory +on the stack (that is, exchange the top two entries), or +change to @t{$HOME} if the @t{PUSHD_TO_HOME} +option is set or if there is only one entry on the stack. +Otherwise, @var{arg} is interpreted as it would be by @t{cd}. +The meaning of @var{old} and @var{new} in the second form is also +the same as for @t{cd}. + +@noindent +The third form of @t{pushd} changes directory by rotating the +directory list. An argument of the form `@t{+}@var{n}' identifies a stack +entry by counting from the left of the list shown by the @t{dirs} +command, starting with zero. An argument of the form `@t{-}@var{n}' counts +from the right. If the @t{PUSHD_MINUS} option is set, the meanings +of `@t{+}' and `@t{-}' in this context are swapped. + +@noindent +If the @t{-q} (quiet) option is specified, the hook function @t{chpwd} +and the functions in the array @t{$chpwd_functions} are not called, +and the new directory stack is not printed. This is useful for calls to +@t{pushd} that do not change the environment seen by an interactive user. + +@noindent +If the option @t{-q} is not specified and the shell option @t{PUSHD_SILENT} +is not set, the directory stack will be printed after a @t{pushd} is +performed. + +@noindent +The options @t{-s}, @t{-L} and @t{-P} have the same meanings as for the +@t{cd} builtin. + +@findex pushln +@item @t{pushln} [ @var{arg} ... ] +Equivalent to @t{print -nz}. + +@findex pwd +@pindex CHASE_LINKS, use of +@item @t{pwd} [ @t{-rLP} ] +Print the absolute pathname of the current working directory. +If the @t{-r} or the @t{-P} flag is specified, or the @t{CHASE_LINKS} +option is set and the @t{-L} flag is not given, the printed path will not +contain symbolic links. + +@findex r +@item @t{r} +Same as @t{fc -e -}. + +@findex read +@vindex IFS, use of + +@item @t{read }[ @t{-rszpqAclneE} ] [ @t{-t} [ @var{num} ] ] [ @t{-k} [ @var{num} ] ] [ @t{-d} @var{delim} ] +@itemx @t{@ @ @ @ @ }[ @t{-u} @var{n} ] [ [@var{name}][@t{?}@var{prompt}] ] [ @var{name} ... ] +@vindex REPLY, use of +@vindex reply, use of +Read one line and break it into fields using the characters +in @t{$IFS} as separators, except as noted below. +The first field is assigned to the first @var{name}, the second field +to the second @var{name}, etc., with leftover +fields assigned to the last @var{name}. +If @var{name} is omitted then +@t{REPLY} is used for scalars and @t{reply} for arrays. + +@noindent +@table @asis +@item @t{-r} +Raw mode: a `@t{\}' at the end of a line does not signify line +continuation and backslashes in the line don't quote the following +character and are not removed. + +@item @t{-s} +Don't echo back characters if reading from the terminal. + +@item @t{-q} +Read only one character from the terminal and set @var{name} to +`@t{y}' if this character was `@t{y}' or `@t{Y}' and to `@t{n}' otherwise. +With this flag set the return status is zero only if the character was +`@t{y}' or `@t{Y}'. This option may be used with a timeout (see @t{-t}); if +the read times out, or encounters end of file, status 2 is returned. Input is +read from the terminal unless one of @t{-u} or @t{-p} is present. This option +may also be used within zle widgets. + +@item @t{-k} [ @var{num} ] +Read only one (or @var{num}) characters. All are assigned to the first +@var{name}, without word splitting. This flag is ignored when @t{-q} is +present. Input is read from the terminal unless one of @t{-u} or @t{-p} +is present. This option may also be used within zle widgets. + +@noindent +Note that despite the mnemonic `key' this option does read full +characters, which may consist of multiple bytes if the option +@t{MULTIBYTE} is set. + +@item @t{-z} +Read one entry from the editor buffer stack and assign it to the first +@var{name}, without word splitting. Text is pushed onto the stack with +`@t{print -z}' or with @t{push-line} from the line editor (see +@ref{Zsh Line Editor}). This flag is ignored when the @t{-k} or @t{-q} flags are present. + +@item @t{-e} +@itemx @t{-E} +The input read is printed (echoed) to the standard output. If the @t{-e} +flag is used, no input is assigned to the parameters. + +@item @t{-A} +The first @var{name} is taken as the name of an array and all words are +assigned to it. + +@item @t{-c} +@itemx @t{-l} +These flags are allowed only if called inside a +function used for completion (specified with the @t{-K} flag to +@t{compctl}). If the @t{-c} flag is given, the words of the +current command are read. If the @t{-l} flag is given, the whole +line is assigned as a scalar. If both flags are present, @t{-l} +is used and @t{-c} is ignored. + +@item @t{-n} +Together with @t{-c}, the number of the word the cursor is on is +read. With @t{-l}, the index of the character the cursor is on is +read. Note that the command name is word number 1, not word 0, +and that when the cursor is at the end of the line, its character +index is the length of the line plus one. + +@item @t{-u} @var{n} +Input is read from file descriptor @var{n}. + +@item @t{-p} +Input is read from the coprocess. + +@item @t{-d} @var{delim} +Input is terminated by the first character of @var{delim} instead of +by newline. + +@item @t{-t} [ @var{num} ] +Test if input is available before attempting to read. If @var{num} +is present, it must begin with a digit and will be evaluated +to give a number of seconds, which may be a floating point number; +in this case the read times out if input is not available within this +time. If @var{num} is not present, it is taken to be zero, so that +@t{read} returns immediately if no input is available. +If no input is available, return status 1 and do not set any variables. + +This option is not available when reading from the editor buffer with +@t{-z}, when called from within completion with @t{-c} or @t{-l}, with +@t{-q} which clears the input queue before reading, or within zle where +other mechanisms should be used to test for input. + +Note that read does not attempt to alter the input processing mode. The +default mode is canonical input, in which an entire line is read at a time, +so usually `@t{read -t}' will not read anything until an entire line has +been typed. However, when reading from the terminal with @t{-k} +input is processed one key at a time; in this case, only availability of +the first character is tested, so that e.g. `@t{read -t -k 2}' can still +block on the second character. Use two instances of `@t{read -t -k}' if +this is not what is wanted. + +@end table + +@noindent +If the first argument contains a `@t{?}', the remainder of this +word is used as a @var{prompt} on standard error when the shell +is interactive. + +@noindent +The value (exit status) of @t{read} is 1 when an end-of-file is +encountered, or when @t{-c} or @t{-l} is present and the command is +not called from a @t{compctl} function, or as described for @t{-q}. +Otherwise the value is 0. + +@noindent +The behavior of some combinations of the @t{-k}, @t{-p}, @t{-q}, @t{-u} +and @t{-z} flags is undefined. Presently @t{-q} cancels all the others, +@t{-p} cancels @t{-u}, @t{-k} cancels @t{-z}, and otherwise @t{-z} +cancels both @t{-p} and @t{-u}. + +@noindent +The @t{-c} or @t{-l} flags cancel any and all of @t{-kpquz}. + +@cindex parameters, marking readonly +@item @t{readonly} +Same as @t{typeset -r}. With the @t{POSIX_BUILTINS} option set, same +as @t{typeset -gr}. + +@findex rehash +@item @t{rehash} +Same as @t{hash -r}. + +@findex return +@cindex functions, returning from +@item @t{return} [ @var{n} ] +Causes a shell function or `@t{.}' script to return to +the invoking script with the return status specified by +an arithmetic expression @var{n}. +For example, the following prints `@t{42}': + +@noindent +@example +() @{ integer foo=40; return "foo + 2" @} +echo $? +@end example + +@noindent +If @var{n} +is omitted, the return status is that of the last command +executed. + +@noindent +If @t{return} was executed from a trap in a @t{TRAP}@var{NAL} function, +the effect is different for zero and non-zero return status. With zero +status (or after an implicit return at the end of the trap), the shell +will return to whatever it was previously processing; with a non-zero +status, the shell will behave as interrupted except that the return +status of the trap is retained. Note that the numeric value of the signal +which caused the trap is passed as the first argument, so the statement +`@t{return "128+$1"}' will return the same status as if the signal +had not been trapped. + +@item @t{sched} +See @ref{The zsh/sched Module}. + +@findex set +@cindex parameters, listing +@cindex parameters, positional +@cindex parameters, setting array +@cindex array parameters, setting +@pindex KSH_ARRAYS, use of + +@item @t{set }[ @{@t{+}|@t{-}@}@var{options} | @{@t{+}|@t{-}@}@t{o} [ @var{option_name} ] ] ... [ @{@t{+}|@t{-}@}@t{A} [ @var{name} ] ] +@itemx @t{@ @ @ @ }[ @var{arg} ... ] +Set the options for the shell and/or set the positional parameters, or +declare and set an array. If the @t{-s} option is given, it causes the +specified arguments to be sorted before assigning them to the positional +parameters (or to the array @var{name} if @t{-A} is used). With @t{+s} +sort arguments in descending order. For the meaning of the other flags, see +@ref{Options}. Flags may be specified by name using the @t{-o} option. If no option +name is supplied with @t{-o}, the current option states are printed: see +the description of @t{setopt} below for more information on the format. +With @t{+o} they are printed in a form that can be used as input +to the shell. + +@noindent +If the @t{-A} flag is specified, @var{name} is set to an array containing +the given @var{arg}s; if no @var{name} is specified, all arrays are printed +together with their values. + +@noindent +If @t{+A} is used and @var{name} is an array, the +given arguments will replace the initial elements of that array; if no +@var{name} is specified, all arrays are printed without their values. + +@noindent +The behaviour of arguments after @t{-A} @var{name} or @t{+A} @var{name} +depends on whether the option @t{KSH_ARRAYS} is set. If it is not set, all +arguments following @var{name} are treated as values for the array, +regardless of their form. If the option is set, normal option processing +continues at that point; only regular arguments are treated as values for +the array. This means that + +@noindent +@example +set -A array -x -- foo +@end example + +@noindent +sets @t{array} to `@t{-x -}@t{- foo}' if @t{KSH_ARRAYS} is not set, but sets +the array to @t{foo} and turns on the option `@t{-x}' if it is set. + +@noindent +If the @t{-A} flag is not present, but there are arguments beyond the +options, the positional parameters are set. If the option list (if any) +is terminated by `@t{-}@t{-}', and there are no further arguments, the +positional parameters will be unset. + +@noindent +If no arguments and no `@t{-}@t{-}' are given, then the names and values of +all parameters are printed on the standard output. If the only argument is +`@t{+}', the names of all parameters are printed. + +@noindent +For historical reasons, `@t{set -}' is treated as `@t{set +xv}' +and `@t{set -} @var{args}' as `@t{set +xv --} @var{args}' when in +any other emulation mode than zsh's native mode. + +@item @t{setcap} +See @ref{The zsh/cap Module}. + +@findex setopt +@cindex options, setting +@item @t{setopt} [ @{@t{+}|@t{-}@}@var{options} | @{@t{+}|@t{-}@}@t{o} @var{option_name} ] [ @t{-m} ] [ @var{name} ... ] +Set the options for the shell. All options specified either +with flags or by name are set. + +@noindent +If no arguments are supplied, the names of all options currently set are +printed. The form is chosen so as to minimize the differences from the +default options for the current emulation (the default emulation being +native @t{zsh}, shown as @t{<Z>} in +@ref{Description of Options}). +Options that are on by default for the emulation are +shown with the prefix @t{no} only if they are off, while other options are +shown without the prefix @t{no} and only if they are on. In addition to +options changed from the default state by the user, any options activated +automatically by the shell (for example, @t{SHIN_STDIN} or @t{INTERACTIVE}) +will be shown in the list. The format is further modified by the option +@t{KSH_OPTION_PRINT}, however the rationale for choosing options with +or without the @t{no} prefix remains the same in this case. + +@noindent +If the @t{-m} flag is given the arguments are taken as patterns +(which should be quoted to protect them from filename expansion), and all +options with names matching these patterns are set. + +@noindent +Note that a bad option name does not cause execution of subsequent shell +code to be aborted; this is behaviour is different from that of `@t{set +-o}'. This is because @t{set} is regarded as a special builtin by the +POSIX standard, but @t{setopt} is not. + +@findex shift +@cindex parameters, positional +@item @t{shift} [ @t{-p} ] [ @var{n} ] [ @var{name} ... ] +The positional parameters @t{$@{}@var{n}+1@t{@}} ... are renamed +to @t{$1} ..., where @var{n} is an arithmetic expression that +defaults to 1. +If any @var{name}s are given then the arrays with these names are +shifted instead of the positional parameters. + +@noindent +If the option @t{-p} is given arguments are instead removed (popped) +from the end rather than the start of the array. + +@findex source +@item @t{source} @var{file} [ @var{arg} ... ] +Same as `@t{.}', except that the current directory is always searched and +is always searched first, before directories in @t{$path}. + +@item @t{stat} +See @ref{The zsh/stat Module}. + +@findex suspend +@cindex shell, suspending +@cindex suspending the shell +@item @t{suspend} [ @t{-f} ] +Suspend the execution of the shell (send it a @t{SIGTSTP}) +until it receives a @t{SIGCONT}. +Unless the @t{-f} option is given, this will refuse to suspend a login shell. + +@findex test +@item @t{test} [ @var{arg} ... ] +@itemx @t{[} [ @var{arg} ... ] @t{]} +Like the system version of @t{test}. Added for compatibility; +use conditional expressions instead (see @ref{Conditional Expressions}). +The main differences between the conditional expression syntax and the +@t{test} and @t{[} builtins are: these commands are not handled +syntactically, so for example an empty variable expansion may cause an +argument to be omitted; syntax errors cause status 2 to be returned instead +of a shell error; and arithmetic operators expect integer arguments rather +than arithmetic expressions. + +@noindent +The command attempts to implement POSIX and its extensions where these +are specified. Unfortunately there are intrinsic ambiguities in +the syntax; in particular there is no distinction between test operators +and strings that resemble them. The standard attempts to resolve these +for small numbers of arguments (up to four); for five or more arguments +compatibility cannot be relied on. Users are urged wherever possible to +use the `@t{[[}' test syntax which does not have these ambiguities. + +@findex times +@cindex shell, timing +@cindex timing the shell +@item @t{times} +Print the accumulated user and system times for the shell +and for processes run from the shell. + +@findex trap +@cindex signals, trapping +@cindex trapping signals +@item @t{trap} [ @var{arg} ] [ @var{sig} ... ] +@var{arg} is a series of commands (usually quoted to protect it from +immediate evaluation by the shell) to be read and executed when the shell +receives any of the signals specified by one or more @var{sig} args. +Each @var{sig} can be given as a number, +or as the name of a signal either with or without the string @t{SIG} +in front (e.g. 1, HUP, and SIGHUP are all the same signal). + +@noindent +If @var{arg} is `@t{-}', then the specified signals are reset to their +defaults, or, if no @var{sig} args are present, all traps are reset. + +@noindent +If @var{arg} is an empty string, then the specified signals +are ignored by the shell (and by the commands it invokes). + +@noindent +If @var{arg} is omitted but one or more @var{sig} args are provided (i.e. +the first argument is a valid signal number or name), the effect is the +same as if @var{arg} had been specified as `@t{-}'. + +@noindent +The @t{trap} command with no arguments prints a list of commands +associated with each signal. + +@noindent +If @var{sig} is @t{ZERR} then @var{arg} will be executed +after each command with a nonzero exit status. @t{ERR} is an alias +for @t{ZERR} on systems that have no @t{SIGERR} signal (this is the +usual case). + +@noindent +If @var{sig} is @t{DEBUG} then @var{arg} will be executed +before each command if the option @t{DEBUG_BEFORE_CMD} is set +(as it is by default), else after each command. Here, a `command' is +what is described as a `sublist' in the shell grammar, see +@ref{Simple Commands & Pipelines}. +If @t{DEBUG_BEFORE_CMD} is set various additional features are available. +First, it is possible to skip the next command by setting the option +@t{ERR_EXIT}; see the description of the @t{ERR_EXIT} option in +@ref{Description of Options}. Also, the shell parameter +@t{ZSH_DEBUG_CMD} is set to the string corresponding to the command +to be executed following the trap. Note that this string is reconstructed +from the internal format and may not be formatted the same way as the +original text. The parameter is unset after the trap is executed. + +@noindent +If @var{sig} is @t{0} or @t{EXIT} +and the @t{trap} statement is executed inside the body of a function, +then the command @var{arg} is executed after the function completes. +The value of @t{$?} at the start of execution is the exit status of the +shell or the return status of the function exiting. +If @var{sig} is @t{0} or @t{EXIT} +and the @t{trap} statement is not executed inside the body of a function, +then the command @var{arg} is executed when the shell terminates; the +trap runs before any @t{zshexit} hook functions. + +@noindent +@t{ZERR}, @t{DEBUG}, and @t{EXIT} traps are not executed inside other +traps. @t{ZERR} and @t{DEBUG} traps are kept within subshells, while +other traps are reset. + +@noindent +Note that traps defined with the @t{trap} builtin are slightly different +from those defined as `@t{TRAP}@var{NAL} () @{ ... @}', as the latter have +their own function environment (line numbers, local variables, etc.) while +the former use the environment of the command in which they were called. +For example, + +@noindent +@example +trap 'print $LINENO' DEBUG +@end example + +@noindent +will print the line number of a command executed after it has run, while + +@noindent +@example +TRAPDEBUG() @{ print $LINENO; @} +@end example + +@noindent +will always print the number zero. + +@noindent +Alternative signal names are allowed as described under @t{kill} above. +Defining a trap under either name causes any trap under an alternative +name to be removed. However, it is recommended that for consistency +users stick exclusively to one name or another. + +@findex true +@cindex doing nothing, successfully +@item @t{true} [ @var{arg} ... ] +Do nothing and return an exit status of 0. + +@findex ttyctl +@cindex tty, freezing +@item @t{ttyctl} [ @t{-fu} ] +The @t{-f} option freezes the tty (i.e. terminal or terminal emulator), and +@t{-u} unfreezes it. +When the tty is frozen, no changes made to the tty settings by +external programs will be honored by the shell, except for changes in the +size of the screen; the shell will +simply reset the settings to their previous values as soon as each +command exits or is suspended. Thus, @t{stty} and similar programs have +no effect when the tty is frozen. Freezing the tty does not cause +the current state to be remembered: instead, it causes future changes +to the state to be blocked. + +@noindent +Without options it reports whether the terminal is frozen or not. + +@noindent +Note that, regardless of whether the tty is frozen or not, the +shell needs to change the settings when the line editor starts, so +unfreezing the tty does not guarantee settings made on the +command line are preserved. Strings of commands run between +editing the command line will see a consistent tty state. +See also the shell variable @t{STTY} for a means of initialising +the tty before running external commands and/or freezing the tty +around a single command. + +@findex type +@item @t{type} [ @t{-wfpamsS} ] @var{name} ... +Equivalent to @t{whence -v}. + +@findex typeset +@cindex parameters, setting +@cindex parameters, declaring + +@item @t{typeset }[ @{@t{+}|@t{-}@}@t{AHUaghlmrtux} ] [ @{@t{+}|@t{-}@}@t{EFLRZip} [ @var{n} ] ] +@itemx @t{@ @ @ @ @ @ @ @ }[ @t{+} ] [ @var{name}[@t{=}@var{value}] ... ] +@itemx @t{typeset }@t{-T} [ @{@t{+}|@t{-}@}@t{Uglrux} ] [ @{@t{+}|@t{-}@}@t{LRZp} [ @var{n} ] ] +@itemx @t{@ @ @ @ @ @ @ @ }[ @t{+} | @var{SCALAR}[@t{=}@var{value}] @var{array}[@t{=(}@var{value} ...@t{)}] [ @var{sep} ] ] +@itemx @t{typeset} @t{-f} [ @{@t{+}|@t{-}@}@t{TUkmtuz} ] [ @t{+} ] [ @var{name} ... ] +Set or display attributes and values for shell parameters. + +@noindent +Except as noted below for control flags that change the behavior, +a parameter is created for each @var{name} that does not already refer +to one. When inside a function, a new parameter is created for every +@var{name} (even those that already exist), and is unset again when the +function completes. See +@ref{Local Parameters}. The same rules apply to special shell parameters, which +retain their special attributes when made local. + +@noindent +For each @var{name}@t{=}@var{value} assignment, the parameter +@var{name} is set to @var{value}. If the assignment is omitted and @var{name} +does @emph{not} refer to an existing parameter, a new parameter is intialized +to empty string, zero, or empty array (as appropriate), @emph{unless} the +shell option @t{TYPESET_TO_UNSET} is set. When that option is set, +the parameter attributes are recorded but the parameter remains unset. + +@noindent +If the shell option @t{TYPESET_SILENT} is not set, for each remaining +@var{name} that refers to a parameter that is already set, the name and +value of the parameter are printed in the form of an assignment. +Nothing is printed for newly-created parameters, or when any attribute +flags listed below are given along with the @var{name}. Using +`@t{+}' instead of minus to introduce an attribute turns it off. + +@noindent +If no @var{name} is present, the names and values of all parameters are +printed. In this case the attribute flags restrict the display to only +those parameters that have the specified attributes, and using `@t{+}' +rather than `@t{-}' to introduce the flag suppresses printing of the values +of parameters when there is no parameter name. + +@noindent +All forms of the command handle scalar assignment. Array assignment is +possible if any of the reserved words @t{declare}, @t{export}, @t{float}, +@t{integer}, @t{local}, @t{readonly} or @t{typeset} is matched when the +line is parsed (N.B. not when it is executed). In this case the arguments +are parsed as assignments, except that the `@t{+=}' syntax and the +@t{GLOB_ASSIGN} option are not supported, and scalar values after @t{=} +are @emph{not} split further into words, even if expanded (regardless of the +setting of the @t{KSH_TYPESET} option; this option is obsolete). + +@noindent +Examples of the differences between command and reserved word parsing: + +@noindent +@example +# Reserved word parsing +typeset svar=$(echo one word) avar=(several words) +@end example + +@noindent +The above creates a scalar parameter @t{svar} and an array +parameter @t{avar} as if the assignments had been + +@noindent +@example +svar="one word" +avar=(several words) +@end example + +@noindent +On the other hand: + +@noindent +@example +# Normal builtin interface +builtin typeset svar=$(echo two words) +@end example + +@noindent +The @t{builtin} keyword causes the above to use the standard builtin +interface to @t{typeset} in which argument parsing is performed in the same +way as for other commands. This example creates a scalar @t{svar} +containing the value @t{two} and another scalar parameter @t{words} with +no value. An array value in this case would either cause an error or be +treated as an obscure set of glob qualifiers. + +@noindent +Arbitrary arguments are allowed if they take the form of assignments +after command line expansion; however, these only perform scalar +assignment: + +@noindent +@example +var='svar=val' +typeset $var +@end example + +@noindent +The above sets the scalar parameter @t{svar} to the value @t{val}. +Parentheses around the value within @t{var} would not cause array +assignment as they will be treated as ordinary characters when @t{$var} +is substituted. Any non-trivial expansion in the name part of the +assignment causes the argument to be treated in this fashion: + +@noindent +@example +typeset @{var1,var2,var3@}=name +@end example + +@noindent +The above syntax is valid, and has the expected effect of setting the +three parameters to the same value, but the command line is parsed as +a set of three normal command line arguments to @t{typeset} after +expansion. Hence it is not possible to assign to multiple arrays by +this means. + +@noindent +Note that each interface to any of the commands may be disabled +separately. For example, `@t{disable -r typeset}' disables the reserved +word interface to @t{typeset}, exposing the builtin interface, while +`@t{disable typeset}' disables the builtin. Note that disabling the +reserved word interface for @t{typeset} may cause problems with the +output of `@t{typeset -p}', which assumes the reserved word interface is +available in order to restore array and associative array values. + +@noindent +Unlike parameter assignment statements, @t{typeset}'s exit status on an +assignment that involves a command substitution does not reflect the exit +status of the command substitution. Therefore, to test for an error in +a command substitution, separate the declaration of the parameter from its +initialization: + +@noindent +@example +# WRONG +typeset var1=$(exit 1) || echo "Trouble with var1" + +# RIGHT +typeset var1 && var1=$(exit 1) || echo "Trouble with var1" + +@end example + +@noindent +To initialize a parameter @var{param} to a command output and mark it readonly, +use @t{typeset -r }@var{param} or @t{readonly }@var{param} after the parameter +assignment statement. + +@noindent +If no attribute flags are given, and either no @var{name} arguments are +present or the flag @t{+m} is used, then each parameter name printed is +preceded by a list of the attributes of that parameter (@t{array}, +@t{association}, @t{exported}, @t{float}, @t{integer}, @t{readonly}, +or @t{undefined} for autoloaded parameters not yet loaded). If @t{+m} is +used with attribute flags, and all those flags are introduced with +@t{+}, the matching parameter names are printed but their values +are not. + +@noindent +The following control flags change the behavior of @t{typeset}: + +@noindent +@table @asis +@item @t{+} +If `@t{+}' appears by itself in a separate word as the last option, +then the names of all parameters (functions with @t{-f}) are printed, but +the values (function bodies) are not. No @var{name} arguments may appear, +and it is an error for any other options to follow `@t{+}'. The +effect of `@t{+}' is as if all attribute flags which precede it were +given with a `@t{+}' prefix. For example, `@t{typeset -U +}' is +equivalent to `@t{typeset +U}' and displays the names of all arrays having +the uniqueness attribute, whereas `@t{typeset -f -U +}' displays the +names of all autoloadable functions. If @t{+} is the only option, +then type information (array, readonly, etc.) is also printed for each +parameter, in the same manner as `@t{typeset +m "*"}'. + +@item @t{-g} +The @t{-g} (global) means that any resulting parameter will not be +restricted to local scope. Note that this does not necessarily mean that +the parameter will be global, as the flag will apply to any existing +parameter (even if unset) from an enclosing function. This flag does not +affect the parameter after creation, hence it has no effect when listing +existing parameters, nor does the flag @t{+g} have any effect except in +combination with @t{-m} (see below). + +@item @t{-m} +If the @t{-m} flag is given the @var{name} arguments are taken as patterns +(use quoting to prevent these from being interpreted as file patterns). +With no attribute flags, all parameters (or functions with the @t{-f} +flag) with matching names are printed (the shell option @t{TYPESET_SILENT} +is not used in this case). + +@noindent +If the @t{+g} flag is combined with @t{-m}, a new local parameter is +created for every matching parameter that is not already local. Otherwise +@t{-m} applies all other flags or assignments to the existing parameters. + +@noindent +Except when assignments are made with @var{name}@t{=}@var{value}, using +@t{+m} forces the matching parameters and their attributes to be printed, +even inside a function. Note that @t{-m} is ignored if no patterns are +given, so `@t{typeset -m}' displays attributes but `@t{typeset -a +m}' +does not. + +@item @t{-p} [ @var{n} ] +If the @t{-p} option is given, parameters and values are printed in the +form of a typeset command with an assignment, regardless of other flags +and options. Note that the @t{-H} flag on parameters is respected; no +value will be shown for these parameters. + +@noindent +@t{-p} may be followed by an optional integer argument. Currently +only the value @t{1} is supported. In this case arrays and associative +arrays are printed with newlines between indented elements for +readability. + +@item @t{-T} [ @var{scalar}[@t{=}@var{value}] @var{array}[@t{=(}@var{value} ...@t{)}] [ @var{sep} ] ] +This flag has a different meaning when used with @t{-f}; see below. +Otherwise the @t{-T} option requires zero, two, or three arguments to be +present. With no arguments, the list of parameters created in this +fashion is shown. With two or three arguments, the first two are the name +of a scalar and of an array parameter (in that order) that will be tied +together in the manner of @t{$PATH} and @t{$path}. The optional third +argument is a single-character separator which will be used to join the +elements of the array to form the scalar; if absent, a colon is used, as +with @t{$PATH}. Only the first character of the separator is significant; +any remaining characters are ignored. Multibyte characters are not +yet supported. + +@noindent +Only one of the scalar and array parameters may be assigned an initial +value (the restrictions on assignment forms described above also apply). + +@noindent +Both the scalar and the array may be manipulated as normal. If one is +unset, the other will automatically be unset too. There is no way of +untying the variables without unsetting them, nor of converting the type +of one of them with another @t{typeset} command; @t{+T} does not work, +assigning an array to @var{scalar} is an error, and assigning a scalar to +@var{array} sets it to be a single-element array. + +@noindent +Note that both `@t{typeset -xT ...}' and `@t{export -T ...}' work, but +only the scalar will be marked for export. Setting the value using the +scalar version causes a split on all separators (which cannot be quoted). +It is possible to apply @t{-T} to two previously tied variables but with a +different separator character, in which case the variables remain joined +as before but the separator is changed. + +@noindent +When an existing scalar is tied to a new array, the value of the scalar +is preserved but no attribute other than export will be preserved. + +@end table + +@noindent +Attribute flags that transform the final value (@t{-L}, @t{-R}, @t{-Z}, +@t{-l}, @t{-u}) are only applied to the expanded value at the point +of a parameter expansion expression using `@t{$}'. They are not applied +when a parameter is retrieved internally by the shell for any purpose. + +@noindent +The following attribute flags may be specified: + +@noindent +@table @asis +@item @t{-A} +The names refer to associative array parameters; see +@ref{Array Parameters}. + +@item @t{-L} [ @var{n} ] +Left justify and remove leading blanks from the value when the parameter +is expanded. +If @var{n} is nonzero, it defines the width of the field. +If @var{n} is zero, the width is determined by the width of the value of +the first assignment. In the case of numeric parameters, the length of the +complete value assigned to the parameter is used to determine the width, +not the value that would be output. + +@noindent +The width is the count of characters, which may be multibyte characters +if the @t{MULTIBYTE} option is in effect. Note that the screen +width of the character is not taken into account; if this is required, +use padding with parameter expansion flags +@t{$@{(ml}@var{...}@t{)}@var{...}@t{@}} as described in +`Parameter Expansion Flags' in +@ref{Parameter Expansion}. + +@noindent +When the parameter is expanded, it is filled on the right with +blanks or truncated if necessary to fit the field. +Note truncation can lead to unexpected results with numeric parameters. +Leading zeros are removed if the @t{-Z} flag is also set. + +@item @t{-R} [ @var{n} ] +Similar to @t{-L}, except that right justification is used; +when the parameter is expanded, the field is left filled with +blanks or truncated from the end. May not be combined with the @t{-Z} +flag. + +@item @t{-U} +For arrays (but not for associative arrays), keep only the first +occurrence of each duplicated value. This may also be set for tied +parameters (see @t{-T}) or colon-separated special parameters like +@t{PATH} or @t{FIGNORE}, etc. Note the flag takes effect on assignment, +and the type of the variable being assigned to is determinative; for +variables with shared values it is therefore recommended to set the flag +for all interfaces, e.g. `@t{typeset -U PATH path}'. + +@noindent +This flag has a different meaning when used with @t{-f}; see below. + +@item @t{-Z} [ @var{n} ] +Specially handled if set along with the @t{-L} flag. +Otherwise, similar to @t{-R}, except that leading zeros are used for +padding instead of blanks if the first non-blank character is a digit. +Numeric parameters are specially handled: they are always eligible +for padding with zeroes, and the zeroes are inserted at an appropriate +place in the output. + +@item @t{-a} +The names refer to array parameters. An array parameter may be +created this way, but it may be assigned to in the @t{typeset} +statement only if the reserved word form of @t{typeset} is enabled +(as it is by default). When displaying, both normal and associative +arrays are shown. + +@item @t{-f} +The names refer to functions rather than parameters. No assignments +can be made, and the only other valid flags are @t{-t}, @t{-T}, @t{-k}, +@t{-u}, @t{-U} and @t{-z}. The flag @t{-t} turns on execution tracing +for this function; the flag @t{-T} does the same, but turns off tracing +for any named (not anonymous) function called from the present one, +unless that function also +has the @t{-t} or @t{-T} flag. The @t{-u} and @t{-U} flags cause the +function to be marked for autoloading; @t{-U} also causes alias +expansion to be suppressed when the function is loaded. See the +description of the `@t{autoload}' builtin for details. + +@noindent +Note that the builtin @t{functions} provides the same basic capabilities +as @t{typeset -f} but gives access to a few extra options; @t{autoload} +gives further additional options for the case @t{typeset -fu} and +@t{typeset -fU}. + +@item @t{-h} +Hide: only useful for special parameters (those marked `<S>' in the table in +@ref{Parameters Set By The Shell}), and for local parameters with the same name as a special parameter, +though harmless for others. A special parameter with this attribute will +not retain its special effect when made local. Thus after `@t{typeset -h +PATH}', a function containing `@t{typeset PATH}' will create an ordinary +local parameter without the usual behaviour of @t{PATH}. Alternatively, +the local parameter may itself be given this attribute; hence inside a +function `@t{typeset -h PATH}' creates an ordinary local parameter and the +special @t{PATH} parameter is not altered in any way. It is also possible +to create a local parameter using `@t{typeset +h }@var{special}', where the +local copy of @var{special} will retain its special properties regardless of +having the @t{-h} attribute. Global special parameters loaded from shell +modules (currently those in @t{zsh/mapfile} and @t{zsh/parameter}) are +automatically given the @t{-h} attribute to avoid name clashes. + +@item @t{-H} +Hide value: specifies that @t{typeset} will not display the value of the +parameter when listing parameters; the display for such parameters is +always as if the `@t{+}' flag had been given. Use of the parameter is +in other respects normal, and the option does not apply if the parameter is +specified by name, or by pattern with the @t{-m} option. This is on by +default for the parameters in the @t{zsh/parameter} and @t{zsh/mapfile} +modules. Note, however, that unlike the @t{-h} flag this is also useful +for non-special parameters. + +@item @t{-i} [ @var{n} ] +Use an internal integer representation. If @var{n} is nonzero it +defines the output arithmetic base, otherwise it is determined by the +first assignment. Bases from 2 to 36 inclusive are allowed. + +@item @t{-E} [ @var{n} ] +Use an internal double-precision floating point representation. On output +the variable will be converted to scientific notation. If @var{n} is +nonzero it defines the number of significant figures to display; the +default is ten. + +@item @t{-F} [ @var{n} ] +Use an internal double-precision floating point representation. On output +the variable will be converted to fixed-point decimal notation. If @var{n} +is nonzero it defines the number of digits to display after the decimal +point; the default is ten. + +@item @t{-l} +Convert the result to lower case whenever the parameter is expanded. +The value is @emph{not} converted when assigned. + +@item @t{-r} +The given @var{name}s are marked readonly. Note that if @var{name} is a +special parameter, the readonly attribute can be turned on, but cannot then +be turned off. + +@noindent +If the @t{POSIX_BUILTINS} option is set, the readonly attribute is +more restrictive: unset variables can be marked readonly and cannot then +be set; furthermore, the readonly attribute cannot be removed from any +variable. + +@noindent +It is still possible to change other attributes of the variable though, +some of which like @t{-U} or @t{-Z} would affect the value. More generally, +the readonly attribute should not be relied on as a security mechanism. + +@noindent +Note that in zsh (like in pdksh but unlike most other shells) it is +still possible to create a local variable of the same name as this is +considered a different variable (though this variable, too, can be marked +readonly). Special variables that have been made readonly retain their value +and readonly attribute when made local. + +@item @t{-t} +Tags the named parameters. Tags have no special meaning to the shell. +This flag has a different meaning when used with @t{-f}; see above. + +@item @t{-u} +Convert the result to upper case whenever the parameter is expanded. +The value is @emph{not} converted when assigned. +This flag has a different meaning when used with @t{-f}; see above. + +@item @t{-x} +Mark for automatic export to the environment of subsequently +executed commands. If the option @t{GLOBAL_EXPORT} is set, this implies +the option @t{-g}, unless @t{+g} is also explicitly given; in other words +the parameter is not made local to the enclosing function. This is for +compatibility with previous versions of zsh. + +@end table + +@findex ulimit +@cindex resource limits +@cindex limits, resource +@item @t{ulimit} [ @t{-HSa} ] [ @{ @t{-bcdfiklmnpqrsTtvwx} | @t{-N} @var{resource} @} [ @var{limit} ] ... ] +Set or display resource limits of the shell and the processes started by +the shell. The value of @var{limit} can be a number in the unit specified +below or one of the values `@t{unlimited}', which removes the limit on the +resource, or `@t{hard}', which uses the current value of the hard limit on +the resource. + +@noindent +By default, only soft limits are manipulated. If the @t{-H} flag +is given use hard limits instead of soft limits. If the @t{-S} flag is given +together with the @t{-H} flag set both hard and soft limits. + +@noindent +If no options are used, the file size limit (@t{-f}) is assumed. + +@noindent +If @var{limit} is omitted the current value of the specified resources are +printed. When more than one resource value is printed, the limit name and +unit is printed before each value. + +@noindent +When looping over multiple resources, the shell will abort immediately if +it detects a badly formed argument. However, if it fails to set a limit +for some other reason it will continue trying to set the remaining limits. + +@noindent +Not all the following resources are supported on all systems. Running +@t{ulimit -a} will show which are supported. + +@noindent +@table @asis +@item @t{-a} +Lists all of the current resource limits. +@item @t{-b} +Socket buffer size in bytes (N.B. not kilobytes) +@item @t{-c} +512-byte blocks on the size of core dumps. +@item @t{-d} +Kilobytes on the size of the data segment. +@item @t{-f} +512-byte blocks on the size of files written. +@item @t{-i} +The number of pending signals. +@item @t{-k} +The number of kqueues allocated. +@item @t{-l} +Kilobytes on the size of locked-in memory. +@item @t{-m} +Kilobytes on the size of physical memory. +@item @t{-n} +open file descriptors. +@item @t{-p} +The number of pseudo-terminals. +@item @t{-q} +Bytes in POSIX message queues. +@item @t{-r} +Maximum real time priority. On some systems where this +is not available, such as NetBSD, this has the same effect as @t{-T} +for compatibility with @t{sh}. +@item @t{-s} +Kilobytes on the size of the stack. +@item @t{-T} +The number of simultaneous threads available to the user. +@item @t{-t} +CPU seconds to be used. +@item @t{-u} +The number of processes available to the user. +@item @t{-v} +Kilobytes on the size of virtual memory. On some systems this +refers to the limit called `address space'. +@item @t{-w} +Kilobytes on the size of swapped out memory. +@item @t{-x} +The number of locks on files. +@end table + +@noindent +A resource may also be specified by integer in the form `@t{-N} +@var{resource}', where @var{resource} corresponds to the integer defined for +the resource by the operating system. This may be used to set the limits +for resources known to the shell which do not correspond to option letters. +Such limits will be shown by number in the output of `@t{ulimit -a}'. + +@noindent +The number may alternatively be out of the range of limits compiled into +the shell. The shell will try to read or write the limit anyway, and +will report an error if this fails. + +@findex umask +@cindex umask +@item @t{umask} [ @t{-S} ] [ @var{mask} ] +The umask is set to @var{mask}. @var{mask} can be either +an octal number or a symbolic value as described in the chmod(1) man page. +If @var{mask} is omitted, the current value is printed. The @t{-S} +option causes the mask to be printed as a symbolic value. Otherwise, +the mask is printed as an octal number. Note that in +the symbolic form the permissions you specify are those which are to be +allowed (not denied) to the users specified. + +@cindex aliases, removing +@item @t{unalias} [ @t{-ams} ] @var{name} ... +Removes aliases. This command works the same as @t{unhash -a}, except that +the @t{-a} option removes all regular or global aliases, or with @t{-s} +all suffix aliases: in this case no @var{name} arguments may appear. The +options @t{-m} (remove by pattern) and @t{-s} without @t{-a} (remove +listed suffix aliases) behave as for @t{unhash -a}. Note that +the meaning of @t{-a} is different between @t{unalias} and @t{unhash}. + +@cindex functions, removing +@findex unfunction +@item @t{unfunction} +Same as @t{unhash -f}. + +@findex unhash +@item @t{unhash} [ @t{-adfms} ] @var{name} ... +Remove the element named @var{name} from an internal hash table. The +default is remove elements from the command hash table. The @t{-a} +option causes @t{unhash} to remove regular or global aliases; note +when removing a global aliases that the argument must be quoted to prevent +it from being expanded before being passed to the command. +The @t{-s} option causes @t{unhash} to remove suffix aliases. +The @t{-f} option causes +@t{unhash} to remove shell functions. The @t{-d} options causes +@t{unhash} to remove named directories. If the @t{-m} flag is given +the arguments are taken as patterns (should be quoted) and all elements +of the corresponding hash table with matching names will be removed. + +@findex unlimit +@cindex resource limits +@cindex limits, resource +@item @t{unlimit} [ @t{-hs} ] @var{resource} ... +The resource limit for each @var{resource} is set to the hard limit. +If the @t{-h} flag is given and the shell has appropriate privileges, +the hard resource limit for each @var{resource} is removed. +The resources of the shell process are only changed if the @t{-s} +flag is given. + +@noindent +The @t{unlimit} command is not made available by default when the +shell starts in a mode emulating another shell. It can be made available +with the command `@t{zmodload -F zsh/rlimits b:unlimit}'. + +@findex unset +@cindex parameters, unsetting +@item @t{unset} [ @t{-fmv} ] @var{name} ... +Each named parameter is unset. +Local parameters remain local even if unset; they appear unset within scope, +but the previous value will still reappear when the scope ends. + +@noindent +Individual elements of associative array parameters may be unset by using +subscript syntax on @var{name}, which should be quoted (or the entire command +prefixed with @t{noglob}) to protect the subscript from filename generation. + +@noindent +If the @t{-m} flag is specified the arguments are taken as patterns (should +be quoted) and all parameters with matching names are unset. Note that this +cannot be used when unsetting associative array elements, as the subscript +will be treated as part of the pattern. + +@noindent +The @t{-v} flag specifies that @var{name} refers to parameters. This is the +default behaviour. + +@noindent +@t{unset -f} is equivalent to @t{unfunction}. + +@findex unsetopt +@cindex options, unsetting +@item @t{unsetopt} [ @{@t{+}|@t{-}@}@var{options} | @{@t{+}|@t{-}@}@t{o} @var{option_name} ] [ @var{name} ... ] +Unset the options for the shell. All options specified either +with flags or by name are unset. If no arguments are supplied, +the names of all options currently unset are printed. +If the @t{-m} flag is given the arguments are taken as patterns +(which should be quoted to preserve them from being interpreted as glob +patterns), and all options with names matching these patterns are unset. + +@item @t{vared} +See @ref{Zle Builtins}. + +@findex wait +@cindex waiting for jobs +@cindex jobs, waiting for +@item @t{wait} [ @var{job} ... ] +Wait for the specified jobs or processes. If @var{job} is not given +then all currently active child processes are waited for. +Each @var{job} can be either a job specification or the process ID +of a job in the job table. +The exit status from this command is that of the job waited for. +If @var{job} represents an unknown job or process ID, a warning is printed +(unless the @t{POSIX_BUILTINS} option is set) and the exit status is 127. + +@noindent +It is possible to wait for recent processes (specified by process ID, +not by job) that were running in the background even if the process has +exited. Typically the process ID will be recorded by capturing the +value of the variable @t{$!} immediately after the process has been +started. There is a limit on the number of process IDs remembered by +the shell; this is given by the value of the system configuration +parameter @t{CHILD_MAX}. When this limit is reached, older process IDs +are discarded, least recently started processes first. + +@noindent +Note there is no protection against the process ID wrapping, i.e. if the +wait is not executed soon enough there is a chance the process waited +for is the wrong one. A conflict implies both process IDs have been +generated by the shell, as other processes are not recorded, and that +the user is potentially interested in both, so this problem is intrinsic +to process IDs. + +@findex whence +@item @t{whence} [ @t{-vcwfpamsS} ] [ @t{-x} @var{num} ] @var{name} ... +For each @var{name}, indicate how it would be interpreted if used as a +command name. + +@noindent +If @var{name} is not an alias, built-in command, external command, shell +function, hashed command, or a reserved word, the exit status shall be +non-zero, and --- if @t{-v}, @t{-c}, or @t{-w} was passed --- a message +will be written to standard output. (This is different from other shells that +write that message to standard error.) + +@noindent +@t{whence} is most useful when @var{name} is only the last path component +of a command, i.e. does not include a `@t{/}'; in particular, pattern +matching only succeeds if just the non-directory component of the command is +passed. + +@noindent +@table @asis +@item @t{-v} +Produce a more verbose report. + +@item @t{-c} +Print the results in a @cite{csh}-like format. +This takes precedence over @t{-v}. + +@item @t{-w} +For each @var{name}, print `@var{name}@t{:} @var{word}' where @var{word} +is one of @t{alias}, @t{builtin}, @t{command}, @t{function}, +@t{hashed}, @t{reserved} or @t{none}, according as @var{name} +corresponds to an alias, a built-in command, an external command, a +shell function, a command defined with the @t{hash} builtin, a +reserved word, or is not recognised. This takes precedence over +@t{-v} and @t{-c}. + +@item @t{-f} +Causes the contents of a shell function to be +displayed, which would otherwise not happen unless the @t{-c} +flag were used. + +@item @t{-p} +Do a path search for @var{name} +even if it is an alias, reserved word, shell function or builtin. + +@item @t{-a} +Do a search for all occurrences of @var{name} +throughout the command path. +Normally only the first occurrence is printed. + +@item @t{-m} +The arguments are taken as patterns (pattern characters should be +quoted), and the information is displayed for each command matching one +of these patterns. + +@item @t{-s} +If a pathname contains symlinks, print the symlink-free pathname as well. + +@item @t{-S} +As @t{-s}, but if the pathname had to be resolved by following +multiple symlinks, the intermediate steps are printed, too. The +symlink resolved at each step might be anywhere in the path. + +@item @t{-x} @var{num} +Expand tabs when outputting shell functions using the @t{-c} option. +This has the same effect as the @t{-x} option to the @t{functions} +builtin. + +@end table + +@findex where +@item @t{where} [ @t{-wpmsS} ] [ @t{-x} @var{num} ] @var{name} ... +Equivalent to @t{whence -ca}. + +@findex which +@item @t{which} [ @t{-wpamsS} ] [ @t{-x} @var{num} ] @var{name} ... +Equivalent to @t{whence -c}. + +@findex zcompile +@cindex .zwc files, creation +@cindex compilation +@item @t{zcompile} [ @t{-U} ] [ @t{-z} | @t{-k} ] [ @t{-R} | @t{-M} ] @var{file} [ @var{name} ... ] +@itemx @t{zcompile} @t{-ca} [ @t{-m} ] [ @t{-R} | @t{-M} ] @var{file} [ @var{name} ... ] +@itemx @t{zcompile -t} @var{file} [ @var{name} ... ] +This builtin command can be used to compile functions or scripts, +storing the compiled form in a file, and to examine files containing +the compiled form. This allows faster autoloading of functions and +sourcing of scripts by avoiding parsing of the text when the files +are read. + +@noindent +The first form (without the @t{-c}, @t{-a} or @t{-t} options) creates a +compiled file. If only the @var{file} argument is given, the +output file has the name `@var{file}@t{.zwc}' and will be placed in +the same directory as the @var{file}. The shell will load the compiled +file instead of the normal function file when the function +is autoloaded; see +@ref{Functions} +for a description of how autoloaded functions are searched. The +extension @t{.zwc} stands for `zsh word code'. + +@noindent +@vindex fpath, with zcompile +If there is at least one @var{name} argument, all the named files +are compiled into the output @var{file} given as the first argument. If +@var{file} does not end in @t{.zwc}, this extension is automatically +appended. Files containing multiple compiled functions are called `digest' +files, and are intended to be used as elements of the @t{FPATH}/@t{fpath} +special array. + +@noindent +The second form, with the @t{-c} or @t{-a} options, writes the compiled +definitions for all the named functions into @var{file}. For @t{-c}, the +names must be functions currently defined in the shell, not those marked +for autoloading. Undefined functions that are marked for autoloading +may be written by using the @t{-a} option, in which case the @t{fpath} +is searched and the contents of the definition files for those +functions, if found, are compiled into @var{file}. If both @t{-c} and +@t{-a} are given, names of both defined functions and functions marked +for autoloading may be given. In either case, the functions in files +written with the @t{-c} or @t{-a} option will be autoloaded as if the +@t{KSH_AUTOLOAD} option were unset. + +@noindent +The reason for handling loaded and not-yet-loaded functions with +different options is that some definition files for autoloading define +multiple functions, including the function with the same name as the +file, and, at the end, call that function. In such cases the output of +`@t{zcompile -c}' does not include the additional functions defined in +the file, and any other initialization code in the file is lost. Using +`@t{zcompile -a}' captures all this extra information. + +@noindent +If the @t{-m} option is combined with @t{-c} or @t{-a}, +the @var{name}s are used as patterns and all functions whose names +match one of these patterns will be written. If no @var{name} is given, +the definitions of all functions currently defined or marked as +autoloaded will be written. + +@noindent +Note the second form cannot be used for compiling functions that +include redirections as part of the definition rather than within +the body of the function; for example + +@noindent +@example +fn1() @{ @{ ... @} >~/logfile @} +@end example + +@noindent +can be compiled but + +@noindent +@example +fn1() @{ ... @} >~/logfile +@end example + +@noindent +cannot. It is possible to use the first form of @t{zcompile} to compile +autoloadable functions that include the full function definition instead +of just the body of the function. + +@noindent +The third form, with the @t{-t} option, examines an existing +compiled file. Without further arguments, the names of the original +files compiled into it are listed. The first line of output shows +the version of the shell which compiled the file and how the file +will be used (i.e. by reading it directly or by mapping it into memory). +With arguments, nothing is output and the return status is set to zero if +definitions for @emph{all} @var{name}s were found in the compiled +file, and non-zero if the definition for at least one @var{name} was not +found. + +@noindent +Other options: + +@noindent +@table @asis +@item @t{-U} +Aliases are not expanded when compiling the @var{name}d files. + +@item @t{-R} +When the compiled file is read, its contents are copied into the +shell's memory, rather than memory-mapped (see @t{-M}). This +happens automatically on systems that do not support memory mapping. + +@noindent +When compiling scripts instead of autoloadable functions, it is +often desirable to use this option; otherwise the whole file, including the +code to define functions which have already been defined, will +remain mapped, consequently wasting memory. + +@item @t{-M} +The compiled file is mapped into the shell's memory when read. This +is done in such a way that multiple instances of the shell running +on the same host will share this mapped file. If neither @t{-R} nor +@t{-M} is given, the @t{zcompile} builtin decides what to do based +on the size of the compiled file. + +@item @t{-k} +@itemx @t{-z} +These options are used when the compiled file contains functions which +are to be autoloaded. If @t{-z} is given, the +function will be autoloaded as if the @t{KSH_AUTOLOAD} option is +@emph{not} set, even if it is set at the time the compiled file is +read, while if the @t{-k} is given, the function will be loaded as if +@t{KSH_AUTOLOAD} @emph{is} set. These options also take precedence over +any @t{-k} or @t{-z} options specified to the @t{autoload} builtin. If +neither of these options is given, the function will be loaded as +determined by the setting of the @t{KSH_AUTOLOAD} option at the time +the compiled file is read. + +These options may also appear as many times as necessary between the listed +@var{name}s to specify the loading style of all following functions, up to +the next @t{-k} or @t{-z}. + +@end table + +@noindent +The created file always contains two versions of the compiled +format, one for big-endian machines and one for small-endian +machines. The upshot of this is that the compiled file is machine +independent and if it is read or mapped, only one half of the file +is actually used (and mapped). + + +@item @t{zformat} +See @ref{The zsh/zutil Module}. + +@item @t{zftp} +See @ref{The zsh/zftp Module}. + +@item @t{zle} +See @ref{Zle Builtins}. + +@findex zmodload +@cindex modules, loading +@cindex loading modules +@item @t{zmodload} [ @t{-dL} ] [ @t{-s} ] [ ... ] +@itemx @t{zmodload -F} [ @t{-alLme} @t{-P} @var{param} ] @var{module} [ [@t{+-}]@var{feature} ... ] +@itemx @t{zmodload -e} [ @t{-A} ] [ ... ] +@itemx @t{zmodload} [ @t{-a} [ @t{-bcpf} [ @t{-I} ] ] ] [ @t{-iL} ] ... +@itemx @t{zmodload} @t{-u} [ @t{-abcdpf} [ @t{-I} ] ] [ @t{-iL} ] ... +@itemx @t{zmodload} @t{-A} [ @t{-L} ] [ @var{modalias}[@t{=}@var{module}] ... ] +@itemx @t{zmodload} @t{-R} @var{modalias} ... +Performs operations relating to zsh's loadable modules. +Loading of modules while the shell is running (`dynamical loading') is not +available on all operating systems, or on all installations on a particular +operating system, although the @t{zmodload} command itself is always +available and can be used to manipulate modules built into versions of the +shell executable without dynamical loading. + +@noindent +Without arguments the names of all currently loaded binary modules are +printed. The @t{-L} option causes this list to be in the form of a +series of @t{zmodload} commands. Forms with arguments are: + +@noindent +@table @asis +@item @t{zmodload} [ @t{-is} ] @var{name} ... +@itemx @t{zmodload} @t{-u} [ @t{-i} ] @var{name} ... +In the simplest case, @t{zmodload} loads a binary module. The module must +be in a file with a name consisting of the specified @var{name} followed by +a standard suffix, usually `@t{.so}' (`@t{.sl}' on HPUX). +If the module to be loaded is already loaded the duplicate module is +ignored. If @t{zmodload} detects an inconsistency, such as an +invalid module name or circular dependency list, the current code block is +aborted. If it is available, the module is loaded if necessary, while if it +is not available, non-zero status is silently returned. The option +@t{-i} is accepted for compatibility but has no effect. + +@noindent +The @var{name}d module is searched for in the same way a command is, using +@t{$module_path} instead of @t{$path}. However, the path search is +performed even when the module name contains a `@t{/}', which it usually does. +There is no way to prevent the path search. + +@noindent +If the module supports features (see below), @t{zmodload} tries to +enable all features when loading a module. If the module was successfully +loaded but not all features could be enabled, @t{zmodload} returns status 2. + +@noindent +If the option @t{-s} is given, no error is printed if the module was not +available (though other errors indicating a problem with the module are +printed). The return status indicates if the module was loaded. This +is appropriate if the caller considers the module optional. + +@noindent +With @t{-u}, @t{zmodload} unloads modules. The same @var{name} +must be given that was given when the module was loaded, but it is not +necessary for the module to exist in the file system. +The @t{-i} option suppresses the error if the module is already +unloaded (or was never loaded). + +@noindent +Each module has a boot and a cleanup function. The module +will not be loaded if its boot function fails. Similarly a module +can only be unloaded if its cleanup function runs successfully. + +@item @t{zmodload -F} [ @t{-almLe} @t{-P} @var{param} ] @var{module} [ [@t{+-}]@var{feature} ... ] +@t{zmodload -F} allows more selective control over the features provided +by modules. With no options apart from @t{-F}, the module named +@var{module} is loaded, if it was not already loaded, and the list of +@var{feature}s is set to the required state. If no +@var{feature}s are specified, the module is loaded, if it was not already +loaded, but the state of features is unchanged. Each feature +may be preceded by a @t{+} to turn the feature on, or @t{-} to turn it +off; the @t{+} is assumed if neither character is present. +Any feature not explicitly mentioned is left in its current state; +if the module was not previously loaded this means any such features will +remain disabled. The return status is zero if all features were +set, 1 if the module failed to load, and 2 if some features could +not be set (for example, a parameter couldn't be added because there +was a different parameter of the same name) but the module was loaded. + +@noindent +The standard features are builtins, conditions, parameters and math +functions; these are indicated by the prefix `@t{b:}', `@t{c:}' +(`@t{C:}' for an infix condition), `@t{p:}' and `@t{f:}', respectively, +followed by the name that the corresponding feature would have in the +shell. For example, `@t{b:strftime}' indicates a builtin named +@t{strftime} and @t{p:EPOCHSECONDS} indicates a parameter named +@t{EPOCHSECONDS}. The module may provide other (`abstract') features of +its own as indicated by its documentation; these have no prefix. + +@noindent +With @t{-l} or @t{-L}, features provided by the module are listed. With +@t{-l} alone, a list of features together with their states is shown, one +feature per line. With @t{-L} alone, a @t{zmodload -F} command that would +cause enabled features of the module to be turned on is shown. With +@t{-lL}, a @t{zmodload -F} command that would cause all the features to be +set to their current state is shown. If one of these combinations is given +with the option @t{-P} @var{param} then the parameter @var{param} is set to an +array of features, either features together with their state or (if +@t{-L} alone is given) enabled features. + +@noindent +With the option @t{-L} the module name may be omitted; then a list +of all enabled features for all modules providing features is printed +in the form of @t{zmodload -F} commands. If @t{-l} is also given, +the state of both enabled and disabled features is output in that form. + +@noindent +A set of features may be provided together with @t{-l} or @t{-L} and a +module name; in that case only the state of those features is +considered. Each feature may be preceded by @t{+} or @t{-} but the +character has no effect. If no set of features is provided, all +features are considered. + +@noindent +With @t{-e}, the command first tests that the module is loaded; +if it is not, status 1 is returned. If the module is loaded, +the list of features given as an argument is examined. Any feature +given with no prefix is simply tested to see if the module provides it; +any feature given with a prefix @t{+} or @t{-} is tested to +see if is provided and in the given state. If the tests on all features +in the list succeed, status 0 is returned, else status 1. + +@noindent +With @t{-m}, each entry in the given list of features is taken +as a pattern to be matched against the list of features provided +by the module. An initial @t{+} or @t{-} must be given explicitly. +This may not be combined with the @t{-a} option as autoloads must +be specified explicitly. + +@noindent +With @t{-a}, the given list of features is marked for autoload from +the specified module, which may not yet be loaded. An optional @t{+} +may appear before the feature name. If the feature is prefixed with +@t{-}, any existing autoload is removed. The options @t{-l} and @t{-L} +may be used to list autoloads. Autoloading is specific to individual +features; when the module is loaded only the requested feature is +enabled. Autoload requests are preserved if the module is +subsequently unloaded until an explicit `@t{zmodload -Fa} @var{module} +@t{-}@var{feature}' is issued. It is not an error to request an autoload +for a feature of a module that is already loaded. + +@noindent +When the module is loaded each autoload is checked against the features +actually provided by the module; if the feature is not provided the +autoload request is deleted. A warning message is output; if the +module is being loaded to provide a different feature, and that autoload +is successful, there is no effect on the status of the current command. +If the module is already loaded at the time when @t{zmodload -Fa} is +run, an error message is printed and status 1 returned. + +@noindent +@t{zmodload -Fa} can be used with the @t{-l}, @t{-L}, @t{-e} and +@t{-P} options for listing and testing the existence of autoloadable +features. In this case @t{-l} is ignored if @t{-L} is specified. +@t{zmodload -FaL} with no module name lists autoloads for all modules. + +@noindent +Note that only standard features as described above can be autoloaded; +other features require the module to be loaded before enabling. + +@item @t{zmodload} @t{-d} [ @t{-L} ] [ @var{name} ] +@itemx @t{zmodload} @t{-d} @var{name} @var{dep} ... +@itemx @t{zmodload} @t{-ud} @var{name} [ @var{dep} ... ] +The @t{-d} option can be used to specify module dependencies. The modules +named in the second and subsequent arguments will be loaded before the +module named in the first argument. + +@noindent +With @t{-d} and one argument, all dependencies for that module are listed. +With @t{-d} and no arguments, all module dependencies are listed. This +listing is by default in a Makefile-like format. The @t{-L} option +changes this format to a list of @t{zmodload -d} commands. + +@noindent +If @t{-d} and @t{-u} are both used, dependencies are removed. If only one +argument is given, all dependencies for that module are removed. + +@item @t{zmodload} @t{-ab} [ @t{-L} ] +@itemx @t{zmodload} @t{-ab} [ @t{-i} ] @var{name} [ @var{builtin} ... ] +@itemx @t{zmodload} @t{-ub} [ @t{-i} ] @var{builtin} ... +The @t{-ab} option defines autoloaded builtins. It defines the specified +@var{builtin}s. When any of those builtins is called, the module specified +in the first argument is loaded and all its features are enabled (for +selective control of features use `@t{zmodload -F -a}' as described +above). If only the @var{name} is given, one builtin is defined, with +the same name as the module. @t{-i} suppresses the error if the builtin +is already defined or autoloaded, but not if another builtin of the +same name is already defined. + +@noindent +With @t{-ab} and no arguments, all autoloaded builtins are listed, with the +module name (if different) shown in parentheses after the builtin name. +The @t{-L} option changes this format to a list of @t{zmodload -a} +commands. + +@noindent +If @t{-b} is used together with the @t{-u} option, it removes builtins +previously defined with @t{-ab}. This is only possible if the builtin is +not yet loaded. @t{-i} suppresses the error if the builtin is already +removed (or never existed). + +@noindent +Autoload requests are retained if the module is subsequently unloaded +until an explicit `@t{zmodload -ub} @var{builtin}' is issued. + +@item @t{zmodload} @t{-ac} [ @t{-IL} ] +@itemx @t{zmodload} @t{-ac} [ @t{-iI} ] @var{name} [ @var{cond} ... ] +@itemx @t{zmodload} @t{-uc} [ @t{-iI} ] @var{cond} ... +The @t{-ac} option is used to define autoloaded condition codes. The +@var{cond} strings give the names of the conditions defined by the +module. The optional @t{-I} option is used to define infix condition +names. Without this option prefix condition names are defined. + +@noindent +If given no condition names, all defined names are listed (as a series of +@t{zmodload} commands if the @t{-L} option is given). + +@noindent +The @t{-uc} option removes definitions for autoloaded conditions. + +@item @t{zmodload} @t{-ap} [ @t{-L} ] +@itemx @t{zmodload} @t{-ap} [ @t{-i} ] @var{name} [ @var{parameter} ... ] +@itemx @t{zmodload} @t{-up} [ @t{-i} ] @var{parameter} ... +The @t{-p} option is like the @t{-b} and @t{-c} options, but makes +@t{zmodload} work on autoloaded parameters instead. + +@item @t{zmodload} @t{-af} [ @t{-L} ] +@itemx @t{zmodload} @t{-af} [ @t{-i} ] @var{name} [ @var{function} ... ] +@itemx @t{zmodload} @t{-uf} [ @t{-i} ] @var{function} ... +The @t{-f} option is like the @t{-b}, @t{-p}, and @t{-c} options, but +makes @t{zmodload} work on autoloaded math functions instead. + +@item @t{zmodload} @t{-a} [ @t{-L} ] +@itemx @t{zmodload} @t{-a} [ @t{-i} ] @var{name} [ @var{builtin} ... ] +@itemx @t{zmodload} @t{-ua} [ @t{-i} ] @var{builtin} ... +Equivalent to @t{-ab} and @t{-ub}. + +@item @t{zmodload -e} [ @t{-A} ] [ @var{string} ... ] +The @t{-e} option without arguments lists all loaded modules; if the @t{-A} +option is also given, module aliases corresponding to loaded modules are +also shown. If arguments are provided, nothing is printed; +the return status is set to zero if all @var{string}s given as arguments +are names of loaded modules and to one if at least on @var{string} is not +the name of a loaded module. This can be used to test for the +availability of things implemented by modules. In this case, any +aliases are automatically resolved and the @t{-A} flag is not used. + +@item @t{zmodload} @t{-A} [ @t{-L} ] [ @var{modalias}[@t{=}@var{module}] ... ] +For each argument, if both @var{modalias} and @var{module} are given, +define @var{modalias} to be an alias for the module @var{module}. +If the module @var{modalias} is ever subsequently requested, either via a +call to @t{zmodload} or implicitly, the shell will attempt to load +@var{module} instead. If @var{module} is not given, show the definition of +@var{modalias}. If no arguments are given, list all defined module aliases. +When listing, if the @t{-L} flag was also given, list the definition as a +@t{zmodload} command to recreate the alias. + +@noindent +The existence of aliases for modules is completely independent of whether +the name resolved is actually loaded as a module: while the alias exists, +loading and unloading the module under any alias has exactly the same +effect as using the resolved name, and does not affect the connection +between the alias and the resolved name which can be removed either by +@t{zmodload -R} or by redefining the alias. Chains of aliases (i.e. where +the first resolved name is itself an alias) are valid so long as these are +not circular. As the aliases take the same format as module names, they +may include path separators: in this case, there is no requirement for any +part of the path named to exist as the alias will be resolved first. For +example, `@t{any/old/alias}' is always a valid alias. + +@noindent +Dependencies added to aliased modules are actually added to the resolved +module; these remain if the alias is removed. It is valid to create an +alias whose name is one of the standard shell modules and which resolves to +a different module. However, if a module has dependencies, it +will not be possible to use the module name as an alias as the module will +already be marked as a loadable module in its own right. + +@noindent +Apart from the above, aliases can be used in the @t{zmodload} command +anywhere module names are required. However, aliases will not be +shown in lists of loaded modules with a bare `@t{zmodload}'. + +@item @t{zmodload} @t{-R} @var{modalias} ... +For each @var{modalias} argument that was previously defined as a module +alias via @t{zmodload -A}, delete the alias. If any was not defined, an +error is caused and the remainder of the line is ignored. + +@end table + +@noindent +Note that @t{zsh} makes no distinction between modules that were linked +into the shell and modules that are loaded dynamically. In both cases +this builtin command has to be used to make available the builtins and +other things defined by modules (unless the module is autoloaded on +these definitions). This is true even for systems that don't support +dynamic loading of modules. + +@item @t{zparseopts} +See @ref{The zsh/zutil Module}. + +@item @t{zprof} +See @ref{The zsh/zprof Module}. + +@item @t{zpty} +See @ref{The zsh/zpty Module}. + +@item @t{zregexparse} +See @ref{The zsh/zutil Module}. + +@item @t{zsocket} +See @ref{The zsh/net/socket Module}. + +@item @t{zstyle} +See @ref{The zsh/zutil Module}. + +@item @t{ztcp} +See @ref{The zsh/net/tcp Module}. + +@end table +@c (avoiding a yodl bug) +@c Yodl file: Zsh/zle.yo +@node Zsh Line Editor, Completion Widgets, Shell Builtin Commands, Top + +@chapter Zsh Line Editor +@noindent +@cindex line editor +@cindex editor, line +@cindex ZLE + +@section Description +@noindent +@pindex ZLE, use of +If the @t{ZLE} option is set (which it is by default in interactive shells) +and the shell input is attached to the terminal, the user +is able to edit command lines. + +@noindent +There are two display modes. The first, multiline mode, is the +default. It only works if the @t{TERM} parameter is set to a valid +terminal type that can move the cursor up. The second, single line +mode, is used if @t{TERM} is invalid or incapable of moving the +cursor up, or if the @t{SINGLE_LINE_ZLE} option is set. +@pindex SINGLE_LINE_ZLE, use of +@cindex ksh, editor mode +@cindex editor ksh style +This mode +is similar to @cite{ksh}, and uses no termcap sequences. If @t{TERM} is +"emacs", the @t{ZLE} option will be unset by default. + +@noindent +@vindex BAUD, use of +@vindex COLUMNS, use of +@vindex LINES, use of +The parameters @t{BAUD}, @t{COLUMNS}, and @t{LINES} are also used by the +line editor. See +@ref{Parameters Used By The Shell}. + +@noindent +@vindex zle_highlight, use of +The parameter @t{zle_highlight} is also used by the line editor; see +@ref{Character Highlighting}. Highlighting +of special characters and the region between the cursor and the +mark (as set with @t{set-mark-command} in Emacs mode, or by @t{visual-mode} +in Vi mode) is enabled +by default; consult this reference for more information. Irascible +conservatives will wish to know that all highlighting may be disabled by +the following setting: + +@noindent +@example +zle_highlight=(none) +@end example + +@noindent +In many places, references are made to the @t{numeric argument}. This can +by default be entered in emacs mode by holding the alt key and typing +a number, or pressing escape before each digit, and in vi command mode +by typing the number before entering a command. Generally the numeric +argument causes the next command entered to be repeated the specified +number of times, unless otherwise noted below; this is implemented +by the @t{digit-argument} widget. See also +@ref{Arguments}for some other ways the numeric argument can be modified. + +@noindent +@menu +* Keymaps:: +* Zle Builtins:: +* Zle Widgets:: +* User-Defined Widgets:: +* Standard Widgets:: +* Character Highlighting:: +@end menu + +@noindent +@node Keymaps, Zle Builtins, , Zsh Line Editor + +@section Keymaps +@noindent +@cindex keymaps +@cindex key bindings +@cindex bindings, key +A keymap in ZLE contains a set of bindings between key sequences +and ZLE commands. The empty key sequence cannot be bound. + +@noindent +There can be any number of keymaps at any time, and each keymap has one +or more names. If all of a keymap's names are deleted, it disappears. +@findex bindkey, use of +@t{bindkey} can be used to manipulate keymap names. + +@noindent +Initially, there are eight keymaps: + +@noindent +@table @asis +@item @t{emacs} +EMACS emulation +@item @t{viins} +vi emulation - insert mode +@item @t{vicmd} +vi emulation - command mode +@item @t{viopp} +vi emulation - operator pending +@item @t{visual} +vi emulation - selection active +@item @t{isearch} +incremental search mode +@item @t{command} +read a command name +@item @t{.safe} +fallback keymap +@end table + +@noindent +The `@t{.safe}' keymap is special. It can never be altered, and the name +can never be removed. However, it can be linked to other names, which can +be removed. In the future other special keymaps may be added; users should +avoid using names beginning with `@t{.}' for their own keymaps. + +@noindent +@vindex VISUAL +@vindex EDITOR +In addition to these names, either `@t{emacs}' or `@t{viins}' is +also linked to the name `@t{main}'. If one of the @t{VISUAL} or +@t{EDITOR} environment variables contain the string `@t{vi}' when the shell +starts up then it will be `@t{viins}', otherwise it will be `@t{emacs}'. +@t{bindkey}'s @t{-e} and @t{-v} +options provide a convenient way to override this default choice. + +@noindent +When the editor starts up, it will select the `@t{main}' keymap. +If that keymap doesn't exist, it will use `@t{.safe}' instead. + +@noindent +In the `@t{.safe}' keymap, each single key is bound to @t{self-insert}, +except for ^J (line feed) and ^M (return) which are bound to @t{accept-line}. +This is deliberately not pleasant to use; if you are using it, it +means you deleted the main keymap, and you should put it back. + +@noindent + +@subsection Reading Commands +@noindent +When ZLE is reading a command from the terminal, it may read a sequence +that is bound to some command and is also a prefix of a longer bound string. +In this case ZLE will wait a certain time to see if more characters +are typed, and if not (or they don't match any longer string) it will +execute the binding. This timeout is defined by the @t{KEYTIMEOUT} parameter; +its default is 0.4 sec. There is no timeout if the prefix string is not +itself bound to a command. + +@noindent +The key timeout is also applied when ZLE is reading the bytes from a +multibyte character string when it is in the appropriate mode. (This +requires that the shell was compiled with multibyte mode enabled; typically +also the locale has characters with the UTF-8 encoding, although any +multibyte encoding known to the operating system is supported.) If the +second or a subsequent byte is not read within the timeout period, the +shell acts as if @t{?} were typed and resets the input state. + +@noindent +As well as ZLE commands, key sequences can be bound to other strings, by using +`@t{bindkey -s}'. +When such a sequence is read, the replacement string is pushed back as input, +and the command reading process starts again using these fake keystrokes. +This input can itself invoke further replacement strings, but in order to +detect loops the process will be stopped if there are twenty such replacements +without a real command being read. + +@noindent +A key sequence typed by the user can be turned into a command name for use +in user-defined widgets with the @t{read-command} widget, described in +@ref{Miscellaneous} below. + +@noindent + +@subsection Local Keymaps +@noindent +@cindex local keymaps +While for normal editing a single keymap is used exclusively, in many +modes a local keymap allows for some keys to be customised. For example, +in an incremental search mode, a binding in the @t{isearch} keymap will +override a binding in the @t{main} keymap but all keys that are not +overridden can still be used. + +@noindent +If a key sequence is defined in a local keymap, it will hide a key +sequence in the global keymap that is a prefix of that sequence. An +example of this occurs with the binding of @t{iw} in @t{viopp} as this +hides the binding of @t{i} in @t{vicmd}. However, a longer sequence in +the global keymap that shares the same prefix can still apply so for +example the binding of @t{^Xa} in the global keymap will be unaffected +by the binding of @t{^Xb} in the local keymap. + +@noindent +@node Zle Builtins, Zle Widgets, Keymaps, Zsh Line Editor + +@section Zle Builtins +@noindent +@cindex zle, builtin commands +The ZLE module contains three related builtin commands. The @t{bindkey} +command manipulates keymaps and key bindings; the @t{vared} command invokes +ZLE on the value of a shell parameter; and the @t{zle} command manipulates +editing widgets and allows command line access to ZLE commands from within +shell functions. + +@noindent +@table @asis +@findex bindkey +@cindex keys, rebinding +@cindex rebinding keys +@cindex keys, binding +@cindex binding keys +@cindex keymaps +@item @t{bindkey} [ @var{options} ] @t{-l} [ @t{-L} ] [ @var{keymap} ... ] +@itemx @t{bindkey} [ @var{options} ] @t{-d} +@itemx @t{bindkey} [ @var{options} ] @t{-D} @var{keymap} ... +@itemx @t{bindkey} [ @var{options} ] @t{-A} @var{old-keymap new-keymap} +@itemx @t{bindkey} [ @var{options} ] @t{-N} @var{new-keymap} [ @var{old-keymap} ] +@itemx @t{bindkey} [ @var{options} ] @t{-m} +@itemx @t{bindkey} [ @var{options} ] @t{-r} @var{in-string} ... +@itemx @t{bindkey} [ @var{options} ] @t{-s} @var{in-string out-string} ... +@itemx @t{bindkey} [ @var{options} ] @var{in-string command} ... +@itemx @t{bindkey} [ @var{options} ] [ @var{in-string} ] +@t{bindkey}'s options can be divided into three categories: keymap +selection for the current command, operation selection, and others. The +keymap selection options are: + +@noindent +@table @asis +@item @t{-e} +Selects keymap `@t{emacs}' for any operations by the current command, +and also links `@t{emacs}' to `@t{main}' so that it is selected by +default the next time the editor starts. + +@item @t{-v} +Selects keymap `@t{viins}' for any operations by the current command, +and also links `@t{viins}' to `@t{main}' so that it is selected by default +the next time the editor starts. + +@item @t{-a} +Selects keymap `@t{vicmd}' for any operations by the current command. + +@item @t{-M} @var{keymap} +The @var{keymap} specifies a keymap name that is selected for any +operations by the current command. + +@end table + +@noindent +If a keymap selection is required and none of the options above are used, the +`@t{main}' keymap is used. Some operations do not permit a keymap to be +selected, namely: + +@noindent +@table @asis +@item @t{-l} +List all existing keymap names; if any arguments are given, list just +those keymaps. + +@noindent +If the @t{-L} option is also used, list in the form of @t{bindkey} +commands to create or link the keymaps. `@t{bindkey -lL +main}' shows which keymap is linked to `@t{main}', if any, and hence if +the standard emacs or vi emulation is in effect. This option does +not show the @t{.safe} keymap because it cannot be created in that +fashion; however, neither is `@t{bindkey -lL .safe}' reported as an +error, it simply outputs nothing. + +@item @t{-d} +Delete all existing keymaps and reset to the default state. + +@item @t{-D} @var{keymap} ... +Delete the named @var{keymap}s. + +@item @t{-A} @var{old-keymap new-keymap} +Make the @var{new-keymap} name an alias for @var{old-keymap}, so that +both names refer to the same keymap. The names have equal standing; +if either is deleted, the other remains. If there is already a keymap +with the @var{new-keymap} name, it is deleted. + +@item @t{-N} @var{new-keymap} [ @var{old-keymap} ] +Create a new keymap, named @var{new-keymap}. If a keymap already has that +name, it is deleted. If an @var{old-keymap} name is given, the new keymap +is initialized to be a duplicate of it, otherwise the new keymap will +be empty. + +@end table + +@noindent +To use a newly created keymap, it should be linked to @t{main}. Hence +the sequence of commands to create and use a new keymap `@t{mymap}' +initialized from the @t{emacs} keymap (which remains unchanged) is: + +@noindent +@example +bindkey -N mymap emacs +bindkey -A mymap main +@end example + +@noindent +Note that while `@t{bindkey -A} @var{newmap} @t{main}' will work when +@var{newmap} is @t{emacs} or @t{viins}, it will not work for @t{vicmd}, as +switching from vi insert to command mode becomes impossible. + +@noindent +The following operations act on the `@t{main}' keymap if no keymap +selection option was given: + +@noindent +@table @asis +@item @t{-m} +Add the built-in set of meta-key bindings to the selected keymap. +Only keys that are unbound or bound to @t{self-insert} are affected. + +@item @t{-r} @var{in-string} ... +Unbind the specified @var{in-string}s in the selected keymap. +This is exactly equivalent to binding the strings to @t{undefined-key}. + +@noindent +When @t{-R} is also used, interpret the @var{in-string}s as ranges. + +@noindent +When @t{-p} is also used, the @var{in-string}s specify prefixes. Any +binding that has the given @var{in-string} as a prefix, not including the +binding for the @var{in-string} itself, if any, will be removed. For +example, + +@noindent +@example +bindkey -rpM viins '^[' +@end example + +@noindent +will remove all bindings in the vi-insert keymap beginning with an escape +character (probably cursor keys), but leave the binding for the escape +character itself (probably @t{vi-cmd-mode}). This is incompatible with the +option @t{-R}. + +@item @t{-s} @var{in-string out-string} ... +Bind each @var{in-string} to each @var{out-string}. +When @var{in-string} is typed, @var{out-string} will be +pushed back and treated as input to the line editor. +When @t{-R} is also used, interpret the @var{in-string}s as ranges. + +@noindent +Note that both @var{in-string} and @var{out-string} are subject to the same +form of interpretation, as described below. + +@item @var{in-string command} ... +Bind each @var{in-string} to each @var{command}. +When @t{-R} is used, interpret the @var{in-string}s as ranges. + +@item [ @var{in-string} ] +List key bindings. If an @var{in-string} is specified, the binding of +that string in the selected keymap is displayed. Otherwise, all key +bindings in the selected keymap are displayed. (As a special case, +if the @t{-e} or @t{-v} option is used alone, the keymap is @emph{not} +displayed - the implicit linking of keymaps is the only thing that +happens.) + +@noindent +When the option @t{-p} is used, the @var{in-string} must be present. +The listing shows all bindings which have the given key sequence as a +prefix, not including any bindings for the key sequence itself. + +@noindent +When the @t{-L} option is used, the list is in the form of @t{bindkey} +commands to create the key bindings. + +@end table + +@noindent +When the @t{-R} option is used as noted above, a valid range consists of +two characters, with an optional `@t{-}' between them. All characters +between the two specified, inclusive, are bound as specified. + +@noindent +For either @var{in-string} or @var{out-string}, the following +escape sequences are recognised: + +@noindent +@table @asis +@item @t{\a} +bell character +@item @t{\b} +backspace +@item @t{\e}, @t{\E} +escape +@item @t{\f} +form feed +@item @t{\n} +linefeed (newline) +@item @t{\r} +carriage return +@item @t{\t} +horizontal tab +@item @t{\v} +vertical tab +@item @t{\}@var{NNN} +character code in octal +@item @t{\x}@var{NN} +character code in hexadecimal +@item @t{\u}@var{NNNN} +unicode character code in hexadecimal +@item @t{\U}@var{NNNNNNNN} +unicode character code in hexadecimal +@item @t{\M}[@t{-}]@var{X} +character with meta bit set +@item @t{\C}[@t{-}]@var{X} +control character +@item @t{^}@var{X} +control character +@end table + +@noindent +In all other cases, `@t{\}' escapes the following character. Delete is +written as `@t{^?}'. Note that `@t{\M^?}' and `@t{^\M?}' are not the same, +and that (unlike emacs), the bindings `@t{\M-}@var{X}' and `@t{\e}@var{X}' +are entirely distinct, although they are initialized to the same bindings +by `@t{bindkey -m}'. + +@findex vared +@cindex parameters, editing +@cindex editing parameters + +@item @t{vared }[ @t{-Aacghe} ] [ @t{-p} @var{prompt} ] [ @t{-r} @var{rprompt} ] +@itemx @t{@ @ @ @ @ @ }[ @t{-M} @var{main-keymap} ] [ @t{-m} @var{vicmd-keymap} ] +@itemx @t{@ @ @ @ @ @ }[ @t{-i} @var{init-widget} ] [ @t{-f} @var{finish-widget} ] +@itemx @t{@ @ @ @ @ @ }[ @t{-t} @var{tty} ] @var{name} +The value of the parameter @var{name} is loaded into the edit +buffer, and the line editor is invoked. When the editor exits, +@var{name} is set to the string value returned by the editor. +When the @t{-c} flag is given, the parameter is created if it doesn't +already exist. The @t{-a} flag may be given with @t{-c} to create +an array parameter, or the @t{-A} flag to create an associative array. +If the type of an existing parameter does not match the type to be +created, the parameter is unset and recreated. The @t{-g} flag may +be given to suppress warnings from the @t{WARN_CREATE_GLOBAL} +and @t{WARN_NESTED_VAR} options. + +@noindent +If an array or array slice is being edited, separator characters as defined +in @t{$IFS} will be shown quoted with a backslash, as will backslashes +themselves. Conversely, when the edited text is split into an array, a +backslash quotes an immediately following separator character or backslash; +no other special handling of backslashes, or any handling of quotes, is +performed. + +@noindent +Individual elements of existing array or associative array parameters +may be edited by using subscript syntax on @var{name}. New elements are +created automatically, even without @t{-c}. + +@noindent +If the @t{-p} flag is given, the following string will be taken as +the prompt to display at the left. If the @t{-r} flag is given, +the following string gives the prompt to display at the right. If the +@t{-h} flag is specified, the history can be accessed from ZLE. If the +@t{-e} flag is given, typing @t{^D} (Control-D) on an empty line +causes @t{vared} to exit immediately with a non-zero return value. + +@noindent +The @t{-M} option gives a keymap to link to the @t{main} keymap during +editing, and the @t{-m} option gives a keymap to link to the @t{vicmd} +keymap during editing. For vi-style editing, this allows a pair of keymaps +to override @t{viins} and @t{vicmd}. For emacs-style editing, only @t{-M} +is normally needed but the @t{-m} option may still be used. On exit, the +previous keymaps will be restored. + +@noindent +@t{Vared} calls the usual `@t{zle-line-init}' and `@t{zle-line-finish}' +hooks before and after it takes control. Using the @t{-i} and @t{-f} +options, it is possible to replace these with other custom widgets. + +@noindent +If `@t{-t} @var{tty}' is given, @var{tty} is the name of a terminal device +to be used instead of the default @t{/dev/tty}. If @var{tty} does not +refer to a terminal an error is reported. + +@findex zle +@cindex widgets, rebinding +@cindex rebinding widgets +@cindex widgets, binding +@cindex binding widgets +@cindex widgets, invoking +@cindex invoking widgets +@cindex widgets, calling +@cindex calling widgets +@cindex widgets, defining +@cindex defining widgets +@item @t{zle} +@itemx @t{zle} @t{-l} [ @t{-L} | @t{-a} ] [ @var{string} ... ] +@itemx @t{zle} @t{-D} @var{widget} ... +@itemx @t{zle} @t{-A} @var{old-widget} @var{new-widget} +@itemx @t{zle} @t{-N} @var{widget} [ @var{function} ] +@itemx @t{zle} @t{-f} @var{flag} [ @var{flag}... ] +@itemx @t{zle} @t{-C} @var{widget} @var{completion-widget} @var{function} +@itemx @t{zle} @t{-R} [ @t{-c} ] [ @var{display-string} ] [ @var{string} ... ] +@itemx @t{zle} @t{-M} @var{string} +@itemx @t{zle} @t{-U} @var{string} +@itemx @t{zle} @t{-K} @var{keymap} +@itemx @t{zle} @t{-F} [ @t{-L} | @t{-w} ] [ @var{fd} [ @var{handler} ] ] +@itemx @t{zle} @t{-I} +@itemx @t{zle} @t{-T} [ @t{tc} @var{function} | @t{-r} @t{tc} | @t{-L} ] +@itemx @t{zle} @var{widget} [ @t{-n} @var{num} ] [ @t{-f} @var{flag} ] [ @t{-Nw} ] [ @t{-K} @var{keymap} ] @var{args} ... +The @t{zle} builtin performs a number of different actions concerning +ZLE. + +@noindent +With no options and no arguments, only the return status will be +set. It is zero if ZLE is currently active and widgets could be +invoked using this builtin command and non-zero otherwise. +Note that even if non-zero status is returned, zle may still be active as +part of the completion system; this does not allow direct calls to ZLE +widgets. + +@noindent +Otherwise, which operation it performs depends on its options: + +@noindent +@table @asis +@item @t{-l} [ @t{-L} | @t{-a} ] [ @var{string} ] +List all existing user-defined widgets. If the @t{-L} +option is used, list in the form of @t{zle} +commands to create the widgets. + +@noindent +When combined with the @t{-a} option, all widget names are listed, +including the builtin ones. In this case the @t{-L} option is ignored. + +@noindent +If at least one @var{string} is given, and @t{-a} is present or @t{-L} is +not used, nothing will be printed. The return status will be zero if +all @var{string}s are names of existing widgets and non-zero if at least one +@var{string} is not a name of a defined widget. If @t{-a} is also +present, all widget names are used for the comparison including builtin +widgets, else only user-defined widgets are used. + +@noindent +If at least one @var{string} is present and the @t{-L} option is used, +user-defined widgets matching any @var{string} are listed in the form of +@t{zle} commands to create the widgets. + +@item @t{-D} @var{widget} ... +Delete the named @var{widget}s. + +@item @t{-A} @var{old-widget} @var{new-widget} +Make the @var{new-widget} name an alias for @var{old-widget}, so that +both names refer to the same widget. The names have equal standing; +if either is deleted, the other remains. If there is already a widget +with the @var{new-widget} name, it is deleted. + +@item @t{-N} @var{widget} [ @var{function} ] +Create a user-defined widget. If there is already a widget with the +specified name, it is overwritten. When the new +widget is invoked from within the editor, the specified shell @var{function} +is called. If no function name is specified, it defaults to +the same name as the widget. For further information, see +@ref{Zle Widgets}. + +@item @t{-f} @var{flag} [ @var{flag}... ] +Set various flags on the running widget. Possible values for @var{flag} are: + +@noindent +@t{yank} for indicating that the widget has yanked text into the buffer. +If the widget is wrapping an existing internal widget, no further +action is necessary, but if it has inserted the text manually, then it +should also take care to set @t{YANK_START} and @t{YANK_END} correctly. +@t{yankbefore} does the same but is used when the yanked text appears +after the cursor. + +@noindent +@t{kill} for indicating that text has been killed into the cutbuffer. +When repeatedly invoking a kill widget, text is appended to the cutbuffer +instead of replacing it, but when wrapping such widgets, it is necessary +to call `@t{zle -f kill}' to retain this effect. + +@noindent +@t{vichange} for indicating that the widget represents a vi change that +can be repeated as a whole with `@t{vi-repeat-change}'. The flag should be set +early in the function before inspecting the value of @t{NUMERIC} or invoking +other widgets. This has no effect for a widget invoked from insert mode. If +insert mode is active when the widget finishes, the change extends until next +returning to command mode. + +@cindex completion widgets, creating +@item @t{-C} @var{widget} @var{completion-widget} @var{function} +Create a user-defined completion widget named @var{widget}. The +completion widget will behave like the built-in completion-widget +whose name is given as @var{completion-widget}. To generate the +completions, the shell function @var{function} will be called. +For further information, see +@ref{Completion Widgets}. + +@item @t{-R} [ @t{-c} ] [ @var{display-string} ] [ @var{string} ... ] +Redisplay the command line. If a @var{display-string} is +given and not empty, this is shown in the status line (immediately +below the line being edited). + +@noindent +If the optional @var{string}s are given they are listed below the +prompt in the same way as completion lists are printed. If no +@var{string}s are given but the @t{-c} option is used such a list is +cleared. + +@noindent +Note that immediately after returning from running widgets, the command line +will be redisplayed and the strings displayed will be erased. Therefore, this +option is only useful for widgets that do not exit immediately after using it. + +@noindent +This command can safely be called outside user defined widgets; if zle is +active, the display will be refreshed, while if zle is not active, the +command has no effect. In this case there will usually be no other +arguments. + +@noindent +The status is zero if zle was active, else one. + +@item @t{-M} @var{string} +As with the @t{-R} option, the @var{string} will be displayed below the +command line; unlike the @t{-R} option, the string will not be put into +the status line but will instead be printed normally below the +prompt. This means that the @var{string} will still be displayed after +the widget returns (until it is overwritten by subsequent commands). + +@item @t{-U} @var{string} +This pushes the characters in the @var{string} onto the input stack of +ZLE. After the widget currently executed finishes ZLE will behave as +if the characters in the @var{string} were typed by the user. + +@noindent +As ZLE uses a stack, if this option is used repeatedly +the last string pushed onto the stack will be processed first. However, +the characters in each @var{string} will be processed in the order in which +they appear in the string. + +@item @t{-K} @var{keymap} +Selects the keymap named @var{keymap}. An error message will be displayed if +there is no such keymap. + +@noindent +This keymap selection affects the interpretation of following keystrokes +within this invocation of ZLE. Any following invocation (e.g., the next +command line) will start as usual with the `@t{main}' keymap selected. + +@item @t{-F} [ @t{-L} | @t{-w} ] [ @var{fd} [ @var{handler} ] ] +Only available if your system supports one of the `poll' or `select' system +calls; most modern systems do. + +@noindent +Installs @var{handler} (the name of a shell function) to handle input from +file descriptor @var{fd}. Installing a handler for an @var{fd} which is +already handled causes the existing handler to be replaced. Any number of +handlers for any number of readable file descriptors may be installed. +Note that zle makes no attempt to check whether this @var{fd} is actually +readable when installing the handler. The user must make their own +arrangements for handling the file descriptor when zle is not active. + +@noindent +When zle is attempting to read data, it will examine both the terminal and +the list of handled @var{fd}'s. If data becomes available on a handled +@var{fd}, zle calls @var{handler} with the fd which is ready for reading +as the first argument. Under normal circumstances this is the only +argument, but if an error was detected, a second argument provides +details: `@t{hup}' for a disconnect, `@t{nval}' for a closed or otherwise +invalid descriptor, or `@t{err}' for any other condition. Systems that +support only the `select' system call always use `@t{err}'. + +@noindent +If the option @t{-w} is also given, the @var{handler} is instead a line +editor widget, typically a shell function made into a widget using +`@t{zle -N}'. In that case @var{handler} can use all the facilities of zle +to update the current editing line. Note, however, that as handling @var{fd} +takes place at a low level changes to the display will not automatically +appear; the widget should call `@t{zle -R}' to force redisplay. As of this +writing, widget handlers only support a single argument and thus are never +passed a string for error state, so widgets must be prepared to test the +descriptor themselves. + +@noindent +If either type of handler produces output to the terminal, it should call +`@t{zle -I}' before doing so (see below). Handlers should not attempt to +read from the terminal. + +@noindent +If no @var{handler} is given, but an @var{fd} is present, any handler for +that @var{fd} is removed. If there is none, an error message is printed +and status 1 is returned. + +@noindent +If no arguments are given, or the @t{-L} option is supplied, a list of +handlers is printed in a form which can be stored for later execution. + +@noindent +An @var{fd} (but not a @var{handler}) may optionally be given with the @t{-L} +option; in this case, the function will list the handler if any, else +silently return status 1. + +@noindent +Note that this feature should be used with care. Activity on one of the +@var{fd}'s which is not properly handled can cause the terminal to become +unusable. Removing an @var{fd} handler from within a signal trap may cause +unpredictable behavior. + +@noindent +Here is a simple example of using this feature. A connection to a remote +TCP port is created using the ztcp command; see +@ref{The zsh/net/tcp Module}. Then a handler is installed +which simply prints out any data which arrives on this connection. Note +that `select' will indicate that the file descriptor needs handling +if the remote side has closed the connection; we handle that by testing +for a failed read. + +@noindent +@example +if ztcp pwspc 2811; then + tcpfd=$REPLY + handler() @{ + zle -I + local line + if ! read -r line <&$1; then + # select marks this fd if we reach EOF, + # so handle this specially. + print "[Read on fd $1 failed, removing.]" >&2 + zle -F $1 + return 1 + fi + print -r - $line + @} + zle -F $tcpfd handler +fi +@end example + +@item @t{-I} +Unusually, this option is most useful outside ordinary widget functions, +though it may be used within if normal output to the terminal is required. +It invalidates the current zle display in preparation for output; typically +this will be from a trap function. It has no effect if zle is not +active. When a trap exits, the shell checks to see if the display needs +restoring, hence the following will print output in such a way as not to +disturb the line being edited: + +@noindent +@example +TRAPUSR1() @{ + # Invalidate zle display + [[ -o zle ]] && zle -I + # Show output + print Hello +@} +@end example + +@noindent +In general, the trap function may need to test whether zle is active before +using this method (as shown in the example), since the @t{zsh/zle} module +may not even be loaded; if it is not, the command can be skipped. + +@noindent +It is possible to call `@t{zle -I}' several times before control is +returned to the editor; the display will only be invalidated the first time +to minimise disruption. + +@noindent +Note that there are normally better ways of manipulating the display from +within zle widgets; see, for example, `@t{zle -R}' above. + +@noindent +The returned status is zero if zle was invalidated, even though +this may have been by a previous call to `@t{zle -I}' or by a system +notification. To test if a zle widget may be called at this point, execute +@t{zle} with no arguments and examine the return status. + +@item @t{-T} +This is used to add, list or remove internal transformations on the +processing performed by the line editor. It is typically used only for +debugging or testing and is therefore of little interest to the general +user. + +@noindent +`@t{zle -T} @var{transformation} @var{func}' specifies that the +given @var{transformation} (see below) is effected by shell function +@var{func}. + +@noindent +`@t{zle -Tr} @var{transformation}' removes the given @var{transformation} +if it was present (it is not an error if none was). + +@noindent +`@t{zle -TL}' can be used to list all transformations currently in +operation. + +@noindent +Currently the only transformation is @t{tc}. This is used instead +of outputting termcap codes to the terminal. When the transformation is +in operation the shell function is passed the termcap code that would be +output as its first argument; if the operation required a numeric +argument, that is passed as a second argument. The function should set +the shell variable @t{REPLY} to the transformed termcap code. Typically +this is used to produce some simply formatted version of the code and +optional argument for debugging or testing. Note that this +transformation is not applied to other non-printing characters such as +carriage returns and newlines. + +@item @var{widget} [ @t{-n} @var{num} ] [ @t{-f} @var{flag} ] [ @t{-Nw} ] [ @t{-K} @var{keymap} ] @var{args} ... +Invoke the specified @var{widget}. This can only be done when ZLE is +active; normally this will be within a user-defined widget. + +@noindent +With the options @t{-n} and @t{-N}, the current numeric argument will be +saved and then restored after the call to @var{widget}; `@t{-n} @var{num}' +sets the numeric argument temporarily to @var{num}, while `@t{-N}' sets it +to the default, i.e. as if there were none. + +@noindent +With the option @t{-K}, @var{keymap} will be used as the current keymap +during the execution of the widget. The previous keymap will be +restored when the widget exits. + +@noindent +Normally, calling a widget in this way does not set the special +parameter @t{WIDGET} and related parameters, so that the environment +appears as if the top-level widget called by the user were still +active. With the option @t{-w}, @t{WIDGET} and related parameters are set +to reflect the widget being executed by the @t{zle} call. + +@noindent +Normally, when @var{widget} returns the special parameter @t{LASTWIDGET} will +point to it. This can be inhibited by passing the option @t{-f nolast}. + +@noindent +Any further arguments will be passed to the widget; note that as +standard argument handling is performed, any general argument list +should be preceded by @t{-}@t{-}. If it is a shell +function, these are passed down as positional parameters; for builtin +widgets it is up to the widget in question what it does with them. +Currently arguments are only handled by the incremental-search commands, +the @t{history-search-forward} and @t{-backward} and the corresponding +functions prefixed by @t{vi-}, and by @t{universal-argument}. No error is +flagged if the command does not use the arguments, or only uses some of +them. + +@noindent +The return status reflects the success or failure of the operation carried +out by the widget, or if it is a user-defined widget the return status of +the shell function. + +@noindent +A non-zero return status causes the shell to beep when the widget exits, +unless the @t{BEEP} options was unset or the widget was called via the +@t{zle} command. Thus if a user defined widget requires an immediate beep, +it should call the @t{beep} widget directly. + +@end table + +@end table + +@noindent +@node Zle Widgets, User-Defined Widgets, Zle Builtins, Zsh Line Editor + +@section Zle Widgets +@noindent +@cindex widgets +All actions in the editor are performed by `widgets'. A widget's job is +simply to perform some small action. The ZLE commands that key sequences +in keymaps are bound to are in fact widgets. Widgets can be user-defined +or built in. + +@noindent +The standard widgets built into ZLE are listed in +@ref{Standard Widgets}. +Other built-in widgets can be defined by other modules (see +@ref{Zsh Modules}). Each built-in widget has two names: its normal canonical name, and the +same name preceded by a `@t{.}'. The `@t{.}' name is special: it can't be +rebound to a different widget. This makes the widget available even when +its usual name has been redefined. + +@noindent +User-defined widgets are defined using `@t{zle -N}', and implemented +as shell functions. When the widget is executed, the corresponding +shell function is executed, and can perform editing (or other) actions. +It is recommended that user-defined widgets should not have names +starting with `@t{.}'. + +@noindent +@node User-Defined Widgets, Standard Widgets, Zle Widgets, Zsh Line Editor + +@section User-Defined Widgets +@noindent +@cindex widgets, user-defined +User-defined widgets, being implemented as shell functions, +can execute any normal shell command. They can also run other widgets +(whether built-in or user-defined) using the @t{zle} builtin command. The +standard input of the function is redirected from /dev/null to prevent +external commands from unintentionally blocking ZLE by reading from the +terminal, but @t{read -k} or @t{read -q} can be used to read characters. +Finally, they can examine and edit the ZLE buffer being edited by reading +and setting the special parameters described below. + +@noindent +@cindex parameters, editor +@cindex parameters, zle +These special parameters are always available in widget functions, but +are not in any way special outside ZLE. If they have some normal value +outside ZLE, that value is temporarily inaccessible, but will return +when the widget function exits. These special parameters in fact have +local scope, like parameters created in a function using @t{local}. + +@noindent +Inside completion widgets and traps called while ZLE is active, these +parameters are available read-only. + +@noindent +Note that the parameters appear as local to any ZLE widget in +which they appear. Hence if it is desired to override them this needs +to be done within a nested function: + +@noindent +@example +widget-function() @{ + # $WIDGET here refers to the special variable + # that is local inside widget-function + () @{ + # This anonymous nested function allows WIDGET + # to be used as a local variable. The -h + # removes the special status of the variable. + local -h WIDGET + @} +@} +@end example + +@noindent +@table @asis +@vindex BUFFER +@item @t{BUFFER} (scalar) +The entire contents of the edit buffer. If it is written to, the +cursor remains at the same offset, unless that would put it outside the +buffer. + +@vindex BUFFERLINES +@item @t{BUFFERLINES} (integer) +The number of screen lines needed for the edit buffer currently +displayed on screen (i.e. without any changes to the preceding +parameters done after the last redisplay); read-only. + +@vindex CONTEXT +@item @t{CONTEXT} (scalar) +The context in which zle was called to read a line; read-only. One of +the values: + +@noindent +@table @asis +@item @t{start} +The start of a command line (at prompt @t{PS1}). + +@item @t{cont} +A continuation to a command line (at prompt @t{PS2}). + +@item @t{select} +In a @t{select} loop (at prompt @t{PS3}). + +@item @t{vared} +Editing a variable in @t{vared}. + +@end table + +@vindex CURSOR +@item @t{CURSOR} (integer) +The offset of the cursor, within the edit buffer. This is in the range +0 to @t{$#BUFFER}, and is by definition equal to @t{$#LBUFFER}. +Attempts to move the cursor outside the buffer will result in the +cursor being moved to the appropriate end of the buffer. + +@vindex CUTBUFFER +@item @t{CUTBUFFER} (scalar) +The last item cut using one of the `@t{kill-}' commands; the string +which the next yank would insert in the line. Later entries in +the kill ring are in the array @t{killring}. Note that the +command `@t{zle copy-region-as-kill} @var{string}' can be used to +set the text of the cut buffer from a shell function and cycle the kill +ring in the same way as interactively killing text. + +@vindex HISTNO +@item @t{HISTNO} (integer) +The current history number. Setting this has the same effect as +moving up or down in the history to the corresponding history line. +An attempt to set it is ignored if the line is not stored in the +history. Note this is not the same as the parameter @t{HISTCMD}, +which always gives the number of the history line being added to the main +shell's history. @t{HISTNO} refers to the line being retrieved within +zle. + +@vindex ISEARCHMATCH_ACTIVE +@vindex ISEARCHMATCH_START +@vindex ISEARCHMATCH_END +@item @t{ISEARCHMATCH_ACTIVE} (integer) +@itemx @t{ISEARCHMATCH_START} (integer) +@itemx @t{ISEARCHMATCH_END} (integer) +@t{ISEARCHMATCH_ACTIVE} indicates whether a part of the @t{BUFFER} is +currently matched by an incremental search pattern. @t{ISEARCHMATCH_START} +and @t{ISEARCHMATCH_END} give the location of the matched part and are +in the same units as @t{CURSOR}. They are only valid for reading +when @t{ISEARCHMATCH_ACTIVE} is non-zero. + +@noindent +All parameters are read-only. + +@vindex KEYMAP +@item @t{KEYMAP} (scalar) +The name of the currently selected keymap; read-only. + +@vindex KEYS +@item @t{KEYS} (scalar) +The keys typed to invoke this widget, as a literal string; read-only. + +@vindex KEYS_QUEUED_COUNT +@item @t{KEYS_QUEUED_COUNT} (integer) +The number of bytes pushed back to the input queue and therefore +available for reading immediately before any I/O is done; read-only. +See also @t{PENDING}; the two values are distinct. + +@vindex killring +@item @t{killring} (array) +The array of previously killed items, with the most recently killed first. +This gives the items that would be retrieved by a @t{yank-pop} in the +same order. Note, however, that the most recently killed item is in +@t{$CUTBUFFER}; @t{$killring} shows the array of previous entries. + +@noindent +The default size for the kill ring is eight, however the length may be +changed by normal array operations. Any empty string in the kill ring is +ignored by the @t{yank-pop} command, hence the size of the array +effectively sets the maximum length of the kill ring, while the number of +non-zero strings gives the current length, both as seen by the user at the +command line. + +@vindex LASTABORTEDSEARCH +@item @t{LASTABORTEDSEARCH} (scalar) +The last search string used by an interactive search that was +aborted by the user (status 3 returned by the search widget). + +@vindex LASTSEARCH +@item @t{LASTSEARCH} (scalar) +The last search string used by an interactive search; read-only. +This is set even if the search failed (status 0, 1 or 2 returned +by the search widget), but not if it was aborted by the user. + +@vindex LASTWIDGET +@item @t{LASTWIDGET} (scalar) +The name of the last widget that was executed; read-only. + +@vindex LBUFFER +@item @t{LBUFFER} (scalar) +The part of the buffer that lies to the left of the cursor position. +If it is assigned to, only that part of the buffer is replaced, and the +cursor remains between the new @t{$LBUFFER} and the old @t{$RBUFFER}. + +@vindex MARK +@item @t{MARK} (integer) +Like @t{CURSOR}, but for the mark. With vi-mode operators that wait for +a movement command to select a region of text, setting @t{MARK} allows +the selection to extend in both directions from the initial cursor +position. + +@vindex NUMERIC +@item @t{NUMERIC} (integer) +The numeric argument. If no numeric argument was given, this parameter +is unset. When this is set inside a widget function, builtin widgets +called with the @t{zle} builtin command will use the value +assigned. If it is unset inside a widget function, builtin widgets +called behave as if no numeric argument was given. + +@vindex PENDING +@item @t{PENDING} (integer) +The number of bytes pending for input, i.e. the number of bytes which have +already been typed and can immediately be read. On systems where the shell +is not able to get this information, this parameter will always have a +value of zero. Read-only. See also @t{KEYS_QUEUED_COUNT}; the two +values are distinct. + +@vindex PREBUFFER +@item @t{PREBUFFER} (scalar) +In a multi-line input at the secondary prompt, this read-only parameter +contains the contents of the lines before the one the cursor is +currently in. + +@vindex PREDISPLAY +@item @t{PREDISPLAY} (scalar) +Text to be displayed before the start of the editable text buffer. This +does not have to be a complete line; to display a complete line, a newline +must be appended explicitly. The text is reset on each new invocation +(but not recursive invocation) of zle. + +@vindex POSTDISPLAY +@item @t{POSTDISPLAY} (scalar) +Text to be displayed after the end of the editable text buffer. This +does not have to be a complete line; to display a complete line, a newline +must be prepended explicitly. The text is reset on each new invocation +(but not recursive invocation) of zle. + +@vindex RBUFFER +@item @t{RBUFFER} (scalar) +The part of the buffer that lies to the right of the cursor position. +If it is assigned to, only that part of the buffer is replaced, and the +cursor remains between the old @t{$LBUFFER} and the new @t{$RBUFFER}. + +@vindex REGION_ACTIVE +@item @t{REGION_ACTIVE} (integer) +Indicates if the region is currently active. It can be assigned 0 or 1 +to deactivate and activate the region respectively. A value of 2 +activates the region in line-wise mode with the highlighted text +extending for whole lines only; see +@ref{Character Highlighting}. + +@vindex region_highlight +@item @t{region_highlight} (array) +Each element of this array may be set to a string that describes +highlighting for an arbitrary region of the command line that will +take effect the next time the command line is redisplayed. Highlighting +of the non-editable parts of the command line in @t{PREDISPLAY} +and @t{POSTDISPLAY} are possible, but note that the @t{P} flag +is needed for character indexing to include @t{PREDISPLAY}. + +@noindent +Each string consists of the following whitespace-separated parts: + +@noindent +@itemize @bullet + +@item +Optionally, a `@t{P}' to signify that the start and end offset that +follow include any string set by the @t{PREDISPLAY} special parameter; +this is needed if the predisplay string itself is to be highlighted. +Whitespace between the `@t{P}' and the start offset is optional. +@item +A start offset in the same units as @t{CURSOR}. +@item +An end offset in the same units as @t{CURSOR}. +@item +A highlight specification in the same format as +used for contexts in the parameter @t{zle_highlight}, see +@ref{Character Highlighting}; +for example, @t{standout} or @t{fg=red,bold}. +@item +Optionally, a string of the form `@t{memo=}@var{token}'. +The @var{token} consists of everything between the `@t{=}' and the next +whitespace, comma, NUL, or the end of the string. +The @var{token} is preserved verbatim but not parsed in any way. + +@noindent +Plugins may use this to identify array elements they have added: for example, +a plugin might set @var{token} to its (the plugin's) name and then use +`@t{region_highlight=( $@{region_highlight:#*memo=}@var{token}@t{@} )}' +in order to remove array elements it have added. + +@noindent +(This example uses the `@t{$@{}@var{name}@t{:#}@var{pattern}@t{@}}' array-grepping +syntax described in +@ref{Parameter Expansion}.) +@end itemize + +@noindent +For example, + +@noindent +@example +region_highlight=("P0 20 bold memo=foobar") +@end example + +@noindent +specifies that the first twenty characters of the text including +any predisplay string should be highlighted in bold. + +@noindent +Note that the effect of @t{region_highlight} is not saved and disappears +as soon as the line is accepted. + +@noindent +Note that zsh 5.8 and older do not support the `@t{memo=}@var{token}' field +and may misparse the third (highlight specification) field when a memo +is given. + + +@noindent +The final highlighting on the command line depends on both @t{region_highlight} +and @t{zle_highlight}; see +@ref{Character Highlighting} for details. + +@vindex registers +@item @t{registers} (associative array) +The contents of each of the vi register buffers. These are +typically set using @t{vi-set-buffer} followed by a delete, change or +yank command. + +@vindex SUFFIX_ACTIVE +@vindex SUFFIX_START +@vindex SUFFIX_END +@item @t{SUFFIX_ACTIVE} (integer) +@itemx @t{SUFFIX_START} (integer) +@itemx @t{SUFFIX_END} (integer) +@t{SUFFIX_ACTIVE} indicates whether an auto-removable completion suffix +is currently active. @t{SUFFIX_START} and @t{SUFFIX_END} give the +location of the suffix and are in the same units as @t{CURSOR}. They are +only valid for reading when @t{SUFFIX_ACTIVE} is non-zero. + +@noindent +All parameters are read-only. + +@vindex UNDO_CHANGE_NO +@item @t{UNDO_CHANGE_NO} (integer) +A number representing the state of the undo history. The only use +of this is passing as an argument to the @t{undo} widget in order to +undo back to the recorded point. Read-only. + +@vindex UNDO_LIMIT_NO +@item @t{UNDO_LIMIT_NO} (integer) +A number corresponding to an existing change in the undo history; +compare @t{UNDO_CHANGE_NO}. If this is set to a value greater +than zero, the @t{undo} command will not allow the line to +be undone beyond the given change number. It is still possible +to use `@t{zle undo} @var{change}' in a widget to undo beyond +that point; in that case, it will not be possible to undo at +all until @t{UNDO_LIMIT_NO} is reduced. Set to 0 to disable the limit. + +@noindent +A typical use of this variable in a widget function is as follows (note +the additional function scope is required): + +@noindent +@example +() @{ + local UNDO_LIMIT_NO=$UNDO_CHANGE_NO + # Perform some form of recursive edit. +@} +@end example + +@vindex WIDGET +@item @t{WIDGET} (scalar) +The name of the widget currently being executed; read-only. + +@vindex WIDGETFUNC +@item @t{WIDGETFUNC} (scalar) +The name of the shell function that implements a widget defined with +either @t{zle -N} or @t{zle -C}. In the former case, this is the second +argument to the @t{zle -N} command that defined the widget, or +the first argument if there was no second argument. In the latter case +this is the third argument to the @t{zle -C} command that defined the +widget. Read-only. + +@vindex WIDGETSTYLE +@item @t{WIDGETSTYLE} (scalar) +Describes the implementation behind the completion widget currently being +executed; the second argument that followed @t{zle -C} when the widget was +defined. This is the name of a builtin completion widget. For widgets +defined with @t{zle -N} this is set to the empty string. Read-only. + +@vindex YANK_ACTIVE +@vindex YANK_START +@vindex YANK_END +@item @t{YANK_ACTIVE} (integer) +@itemx @t{YANK_START} (integer) +@itemx @t{YANK_END} (integer) +@t{YANK_ACTIVE} indicates whether text has just been yanked (pasted) +into the buffer. @t{YANK_START} and @t{YANK_END} give the location of +the pasted text and are in the same units as @t{CURSOR}. They are only +valid for reading when @t{YANK_ACTIVE} is non-zero. They can also be +assigned by widgets that insert text in a yank-like fashion, for example +wrappers of @t{bracketed-paste}. See also @t{zle -f}. + +@noindent +@t{YANK_ACTIVE} is read-only. + +@vindex ZLE_RECURSIVE +@item @t{ZLE_RECURSIVE} (integer) +Usually zero, but incremented inside any instance of +@t{recursive-edit}. Hence indicates the current recursion level. + +@noindent +@t{ZLE_RECURSIVE} is read-only. + +@vindex ZLE_STATE +@item @t{ZLE_STATE} (scalar) +Contains a set of space-separated words that describe the current @t{zle} +state. + +@noindent +Currently, the states shown are the insert mode as set by the +@t{overwrite-mode} or @t{vi-replace} widgets and whether history commands +will visit imported entries as controlled by the set-local-history widget. +The string contains `@t{insert}' if characters to be inserted on the +command line move existing characters to the right or `@t{overwrite}' +if characters to be inserted overwrite existing characters. It contains +`@t{localhistory}' if only local history commands will be visited or +`@t{globalhistory}' if imported history commands will also be visited. + +@noindent +The substrings are sorted in alphabetical order so that if you want to +test for two specific substrings in a future-proof way, you can do match +by doing: + +@noindent +@example +if [[ $ZLE_STATE == *globalhistory*insert* ]]; then ...; fi +@end example + +@end table + +@noindent + +@subsection Special Widgets +@noindent + +@noindent +There are a few user-defined widgets which are special to the shell. +If they do not exist, no special action is taken. The environment +provided is identical to that for any other editing widget. + +@noindent +@table @asis +@tindex zle-isearch-exit +@item @t{zle-isearch-exit} +Executed at the end of incremental search at the point where the isearch +prompt is removed from the display. See @t{zle-isearch-update} for +an example. + +@tindex zle-isearch-update +@item @t{zle-isearch-update} +Executed within incremental search when the display is about to be +redrawn. Additional output below the incremental search prompt can be +generated by using `@t{zle -M}' within the widget. For example, + +@noindent +@example +zle-isearch-update() @{ zle -M "Line $HISTNO"; @} +zle -N zle-isearch-update +@end example + +@noindent +Note the line output by `@t{zle -M}' is not deleted on exit from +incremental search. This can be done from a @t{zle-isearch-exit} +widget: + +@noindent +@example +zle-isearch-exit() @{ zle -M ""; @} +zle -N zle-isearch-exit +@end example + +@tindex zle-line-pre-redraw +@item @t{zle-line-pre-redraw} +Executed whenever the input line is about to be redrawn, providing an +opportunity to update the region_highlight array. + +@tindex zle-line-init +@item @t{zle-line-init} +Executed every time the line editor is started to read a new line +of input. The following example puts the line editor into vi command +mode when it starts up. + +@noindent +@example +zle-line-init() @{ zle -K vicmd; @} +zle -N zle-line-init +@end example + +@noindent +(The command inside the function sets the keymap directly; it is +equivalent to @t{zle vi-cmd-mode}.) + +@tindex zle-line-finish +@item @t{zle-line-finish} +This is similar to @t{zle-line-init} but is executed every time the +line editor has finished reading a line of input. + +@tindex zle-history-line-set +@item @t{zle-history-line-set} +Executed when the history line changes. + +@tindex zle-keymap-select +@item @t{zle-keymap-select} +Executed every time the keymap changes, i.e. the special parameter +@t{KEYMAP} is set to a different value, while the line editor is active. +Initialising the keymap when the line editor starts does not cause the +widget to be called. + +@noindent +The value @t{$KEYMAP} within the function reflects the new keymap. The +old keymap is passed as the sole argument. + +@noindent +This can be used for detecting switches between the vi command +(@t{vicmd}) and insert (usually @t{main}) keymaps. + +@end table + +@noindent +@node Standard Widgets, Character Highlighting, User-Defined Widgets, Zsh Line Editor + +@section Standard Widgets +@noindent +@cindex widgets, standard +The following is a list of all the standard widgets, +and their default bindings in emacs mode, +vi command mode and vi insert mode +(the `@t{emacs}', `@t{vicmd}' and `@t{viins}' keymaps, respectively). + +@noindent +Note that cursor keys are bound to movement keys in all three keymaps; +the shell assumes that the cursor keys send the key sequences reported +by the terminal-handling library (termcap or terminfo). The key sequences +shown in the list are those based on the VT100, common on many modern +terminals, but in fact these are not necessarily bound. In the case of the +@t{viins} keymap, the initial escape character of the sequences serves also +to return to the @t{vicmd} keymap: whether this happens is determined by +the @t{KEYTIMEOUT} parameter, see @ref{Parameters}. +@menu +* Movement:: +* History Control:: +* Modifying Text:: +* Arguments:: +* Completion:: +* Miscellaneous:: +* Text Objects:: +@end menu +@node Movement, History Control, , Standard Widgets + +@subsection Movement +@noindent +@table @asis +@tindex vi-backward-blank-word +@item @t{vi-backward-blank-word} (unbound) (@t{B}) (unbound) +Move backward one word, where a word is defined as a series of +non-blank characters. + +@tindex vi-backward-blank-word-end +@item @t{vi-backward-blank-word-end} (unbound) (@t{gE}) (unbound) +Move to the end of the previous word, where a word is defined as a +series of non-blank characters. + +@tindex backward-char +@item @t{backward-char} (@t{^B ESC-[D}) (unbound) (unbound) +Move backward one character. + +@tindex vi-backward-char +@item @t{vi-backward-char} (unbound) (@t{^H h ^?}) (@t{ESC-[D}) +Move backward one character, without changing lines. + +@tindex backward-word +@item @t{backward-word} (@t{ESC-B ESC-b}) (unbound) (unbound) +Move to the beginning of the previous word. + +@tindex emacs-backward-word +@item @t{emacs-backward-word} +Move to the beginning of the previous word. + +@tindex vi-backward-word +@item @t{vi-backward-word} (unbound) (@t{b}) (unbound) +Move to the beginning of the previous word, vi-style. + +@tindex vi-backward-word-end +@item @t{vi-backward-word-end} (unbound) (@t{ge}) (unbound) +Move to the end of the previous word, vi-style. + +@tindex beginning-of-line +@item @t{beginning-of-line} (@t{^A}) (unbound) (unbound) +Move to the beginning of the line. If already at the beginning +of the line, move to the beginning of the previous line, if any. + +@tindex vi-beginning-of-line +@item @t{vi-beginning-of-line} +Move to the beginning of the line, without changing lines. + +@tindex down-line +@item @t{down-line} (unbound) (unbound) (unbound) +Move down a line in the buffer. + +@tindex end-of-line +@item @t{end-of-line} (@t{^E}) (unbound) (unbound) +Move to the end of the line. If already at the end +of the line, move to the end of the next line, if any. + +@tindex vi-end-of-line +@item @t{vi-end-of-line} (unbound) (@t{$}) (unbound) +Move to the end of the line. +If an argument is given to this command, the cursor will be moved to +the end of the line (argument - 1) lines down. + +@tindex vi-forward-blank-word +@item @t{vi-forward-blank-word} (unbound) (@t{W}) (unbound) +Move forward one word, where a word is defined as a series of +non-blank characters. + +@tindex vi-forward-blank-word-end +@item @t{vi-forward-blank-word-end} (unbound) (@t{E}) (unbound) +Move to the end of the current word, or, if at the end of the current word, +to the end of the next word, +where a word is defined as a series of non-blank characters. + +@tindex forward-char +@item @t{forward-char} (@t{^F ESC-[C}) (unbound) (unbound) +Move forward one character. + +@tindex vi-forward-char +@item @t{vi-forward-char} (unbound) (@t{space l}) (@t{ESC-[C}) +Move forward one character. + +@tindex vi-find-next-char +@item @t{vi-find-next-char} (@t{^X^F}) (@t{f}) (unbound) +Read a character from the keyboard, and move to +the next occurrence of it in the line. + +@tindex vi-find-next-char-skip +@item @t{vi-find-next-char-skip} (unbound) (@t{t}) (unbound) +Read a character from the keyboard, and move to +the position just before the next occurrence of it in the line. + +@tindex vi-find-prev-char +@item @t{vi-find-prev-char} (unbound) (@t{F}) (unbound) +Read a character from the keyboard, and move to +the previous occurrence of it in the line. + +@tindex vi-find-prev-char-skip +@item @t{vi-find-prev-char-skip} (unbound) (@t{T}) (unbound) +Read a character from the keyboard, and move to +the position just after the previous occurrence of it in the line. + +@tindex vi-first-non-blank +@item @t{vi-first-non-blank} (unbound) (@t{^}) (unbound) +Move to the first non-blank character in the line. + +@tindex vi-forward-word +@item @t{vi-forward-word} (unbound) (@t{w}) (unbound) +Move forward one word, vi-style. + +@tindex forward-word +@item @t{forward-word} (@t{ESC-F ESC-f}) (unbound) (unbound) +Move to the beginning of the next word. +The editor's idea of a word is specified with the @t{WORDCHARS} +parameter. + +@tindex emacs-forward-word +@item @t{emacs-forward-word} +Move to the end of the next word. + +@tindex vi-forward-word-end +@item @t{vi-forward-word-end} (unbound) (@t{e}) (unbound) +Move to the end of the next word. + +@tindex vi-goto-column +@item @t{vi-goto-column} (@t{ESC-|}) (@t{|}) (unbound) +Move to the column specified by the numeric argument. + +@tindex vi-goto-mark +@item @t{vi-goto-mark} (unbound) (@t{`}) (unbound) +Move to the specified mark. + +@tindex vi-goto-mark-line +@item @t{vi-goto-mark-line} (unbound) (@t{'}) (unbound) +Move to beginning of the line containing the specified mark. + +@tindex vi-repeat-find +@item @t{vi-repeat-find} (unbound) (@t{;}) (unbound) +Repeat the last @t{vi-find} command. + +@tindex vi-rev-repeat-find +@item @t{vi-rev-repeat-find} (unbound) (@t{,}) (unbound) +Repeat the last @t{vi-find} command in the opposite direction. + +@tindex up-line +@item @t{up-line} (unbound) (unbound) (unbound) +Move up a line in the buffer. + +@end table +@node History Control, Modifying Text, Movement, Standard Widgets + +@subsection History Control +@noindent +@table @asis +@tindex beginning-of-buffer-or-history +@item @t{beginning-of-buffer-or-history} (@t{ESC-<}) (@t{gg}) (unbound) +Move to the beginning of the buffer, or if already there, +move to the first event in the history list. + +@tindex beginning-of-line-hist +@item @t{beginning-of-line-hist} +Move to the beginning of the line. If already at the +beginning of the buffer, move to the previous history line. + +@tindex beginning-of-history +@item @t{beginning-of-history} +Move to the first event in the history list. + +@tindex down-line-or-history +@item @t{down-line-or-history} (@t{^N ESC-[B}) (@t{j}) (@t{ESC-[B}) +Move down a line in the buffer, or if already at the bottom line, +move to the next event in the history list. + +@tindex vi-down-line-or-history +@item @t{vi-down-line-or-history} (unbound) (@t{+}) (unbound) +Move down a line in the buffer, or if already at the bottom line, +move to the next event in the history list. +Then move to the first non-blank character on the line. + +@tindex down-line-or-search +@item @t{down-line-or-search} +Move down a line in the buffer, or if already at the bottom line, +search forward in the history for a line beginning with the first +word in the buffer. + +@noindent +If called from a function by the @t{zle} command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. + +@tindex down-history +@item @t{down-history} (unbound) (@t{^N}) (unbound) +Move to the next event in the history list. + +@tindex history-beginning-search-backward +@item @t{history-beginning-search-backward} +Search backward in the history for a line beginning with the current +line up to the cursor. +This leaves the cursor in its original position. + +@tindex end-of-buffer-or-history +@item @t{end-of-buffer-or-history} (@t{ESC->}) (unbound) (unbound) +Move to the end of the buffer, or if already there, +move to the last event in the history list. + +@tindex end-of-line-hist +@item @t{end-of-line-hist} +Move to the end of the line. If already at the end of +the buffer, move to the next history line. + +@tindex end-of-history +@item @t{end-of-history} +Move to the last event in the history list. + +@tindex vi-fetch-history +@item @t{vi-fetch-history} (unbound) (@t{G}) (unbound) +Fetch the history line specified by the numeric argument. +This defaults to the current history line +(i.e. the one that isn't history yet). + +@tindex history-incremental-search-backward +@item @t{history-incremental-search-backward} (@t{^R ^Xr}) (unbound) (unbound) +Search backward incrementally for a specified string. The search is +case-insensitive if the search string does not have uppercase letters and no +numeric argument was given. The string may begin with `@t{^}' to anchor the +search to the beginning of the line. When called from a user-defined +function returns the following statuses: 0, if the search succeeded; +1, if the search failed; 2, if the search term was a bad pattern; +3, if the search was aborted by the @t{send-break} command. + +@noindent +A restricted set of editing functions +is available in the mini-buffer. Keys are looked up in the special +@t{isearch} keymap, and if not found there in the main keymap (note +that by default the @t{isearch} keymap is empty). +An interrupt signal, as defined by the stty +setting, will stop the search and go back to the original line. An undefined +key will have the same effect. Note that the following always +perform the same task within incremental searches and cannot be +replaced by user defined widgets, nor can the set of functions +be extended. The supported functions are: + +@noindent +@table @asis +@item @t{accept-and-hold} +@itemx @t{accept-and-infer-next-history} +@itemx @t{accept-line} +@itemx @t{accept-line-and-down-history} +Perform the usual function after exiting incremental search. +The command line displayed is executed. + +@item @t{backward-delete-char} +@itemx @t{vi-backward-delete-char} +Back up one place in the search history. If the search has been +repeated this does not immediately erase a character in the +minibuffer. + +@item @t{accept-search} +Exit incremental search, retaining the command line but performing no +further action. Note that this function is not bound by default +and has no effect outside incremental search. + +@item @t{backward-delete-word} +@itemx @t{backward-kill-word} +@itemx @t{vi-backward-kill-word} +Back up one character in the minibuffer; if multiple searches +have been performed since the character was inserted the search +history is rewound to the point just before the character was +entered. Hence this has the effect of repeating +@t{backward-delete-char}. + +@item @t{clear-screen} +Clear the screen, remaining in incremental search mode. + +@item @t{history-incremental-search-backward} +Find the next occurrence of the contents of the mini-buffer. If the +mini-buffer is empty, the most recent previously used search string is +reinstated. + +@item @t{history-incremental-search-forward} +Invert the sense of the search. + +@item @t{magic-space} +Inserts a non-magical space. + +@item @t{quoted-insert} +@itemx @t{vi-quoted-insert} +Quote the character to insert into the minibuffer. + +@item @t{redisplay} +Redisplay the command line, remaining in incremental search mode. + +@item @t{vi-cmd-mode} +Select the `@t{vicmd}' keymap; +the `@t{main}' keymap (insert mode) will be selected initially. + +@noindent +In addition, the modifications that were made while in vi insert mode are +merged to form a single undo event. + +@item @t{vi-repeat-search} +@itemx @t{vi-rev-repeat-search} +Repeat the search. The direction of the search is indicated in the +mini-buffer. + +@end table + +@noindent +Any character that is not bound to one of the above functions, or +@t{self-insert} or @t{self-insert-unmeta}, will cause the mode to be +exited. The character is then looked up and executed in the keymap in +effect at that point. + +@noindent +When called from a widget function by the @t{zle} command, the incremental +search commands can take a string argument. This will be treated as a +string of keys, as for arguments to the @t{bindkey} command, and used as +initial input for the command. Any characters in the string which are +unused by the incremental search will be silently ignored. For example, + +@noindent +@example +zle history-incremental-search-backward forceps +@end example + +@noindent +will search backwards for @t{forceps}, leaving the minibuffer containing +the string `@t{forceps}'. + +@tindex history-incremental-search-forward +@item @t{history-incremental-search-forward} (@t{^S ^Xs}) (unbound) (unbound) +Search forward incrementally for a specified string. The search is +case-insensitive if the search string does not have uppercase letters and no +numeric argument was given. The string may begin with `@t{^}' to anchor the +search to the beginning of the line. The functions available in the +mini-buffer are the same as for @t{history-incremental-search-backward}. + +@tindex history-incremental-pattern-search-backward +@tindex history-incremental-pattern-search-forward +@item @t{history-incremental-pattern-search-backward} +@itemx @t{history-incremental-pattern-search-forward} +These widgets behave similarly to the corresponding widgets with +no @t{-pattern}, but the search string typed by the user is treated +as a pattern, respecting the current settings of the various options +affecting pattern matching. See +@ref{Filename Generation} for a description of patterns. +If no numeric argument was given lowercase letters in the search +string may match uppercase letters in the history. The string may begin +with `@t{^}' to anchor the search to the beginning of the line. + +@noindent +The prompt changes to indicate an invalid pattern; this may simply +indicate the pattern is not yet complete. + +@noindent +Note that only non-overlapping matches are reported, so an expression +with wildcards may return fewer matches on a line than are visible +by inspection. + +@tindex history-search-backward +@item @t{history-search-backward} (@t{ESC-P ESC-p}) (unbound) (unbound) +Search backward in the history for a line beginning with the first +word in the buffer. + +@noindent +If called from a function by the @t{zle} command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. + +@tindex vi-history-search-backward +@item @t{vi-history-search-backward} (unbound) (@t{/}) (unbound) +Search backward in the history for a specified string. +The string may begin with `@t{^}' to anchor the search to the +beginning of the line. + +@noindent +A restricted set of editing functions is available in +the mini-buffer. An interrupt signal, as defined by the stty setting, will +stop the search. +The functions available in the mini-buffer are: +@t{accept-line}, +@t{backward-delete-char}, +@t{vi-backward-delete-char}, +@t{backward-kill-word}, +@t{vi-backward-kill-word}, +@t{clear-screen}, +@t{redisplay}, +@t{quoted-insert} +and +@t{vi-quoted-insert}. + +@noindent +@t{vi-cmd-mode} is treated the same as accept-line, and +@t{magic-space} is treated as a space. +Any other character that is not bound to self-insert or +self-insert-unmeta will beep and be ignored. If the function is called from vi +command mode, the bindings of the current insert mode will be used. + +@noindent +If called from a function by the @t{zle} command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. + +@tindex history-search-forward +@item @t{history-search-forward} (@t{ESC-N ESC-n}) (unbound) (unbound) +Search forward in the history for a line beginning with the first +word in the buffer. + +@noindent +If called from a function by the @t{zle} command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. + +@tindex vi-history-search-forward +@item @t{vi-history-search-forward} (unbound) (@t{?}) (unbound) +Search forward in the history for a specified string. +The string may begin with `@t{^}' to anchor the search to the +beginning of the line. The functions available in the mini-buffer are the same +as for @t{vi-history-search-backward}. Argument handling is also the same +as for that command. + +@tindex infer-next-history +@item @t{infer-next-history} (@t{^X^N}) (unbound) (unbound) +Search in the history list for a line matching the current one and +fetch the event following it. + +@tindex insert-last-word +@item @t{insert-last-word} (@t{ESC-_ ESC-.}) (unbound) (unbound) +Insert the last word from the previous history event at the +cursor position. If a positive numeric argument is given, +insert that word from the end of the previous history event. +If the argument is zero or negative insert that word from the +left (zero inserts the previous command word). Repeating this command +replaces the word just inserted with the last word from the +history event prior to the one just used; numeric arguments can be used in +the same way to pick a word from that event. + +@noindent +When called from a shell function invoked from a user-defined widget, the +command can take one to three arguments. The first argument specifies a +history offset which applies to successive calls to this widget: if it is -1, +the default behaviour is used, while if it is 1, successive calls will move +forwards through the history. The value 0 can be used to indicate that the +history line examined by the previous execution of the command will be +reexamined. Note that negative numbers should be preceded by a +`@t{-}@t{-}' argument to avoid confusing them with options. + +@noindent +If two arguments are given, the second specifies the word on the command +line in normal array index notation (as a more natural alternative to the +numeric argument). Hence 1 is the first word, and -1 (the default) is the +last word. + +@noindent +If a third argument is given, its value is ignored, but it is used to +signify that the history offset is relative to the current history line, +rather than the one remembered after the previous invocations of +@t{insert-last-word}. + +@noindent +For example, the default behaviour of the command corresponds to + +@noindent +@example +zle insert-last-word -- -1 -1 +@end example + +@noindent +while the command + +@noindent +@example +zle insert-last-word -- -1 1 - +@end example + +@noindent +always copies the first word of the line in the history immediately before +the line being edited. This has the side effect that later invocations of +the widget will be relative to that line. + +@tindex vi-repeat-search +@item @t{vi-repeat-search} (unbound) (@t{n}) (unbound) +Repeat the last vi history search. + +@tindex vi-rev-repeat-search +@item @t{vi-rev-repeat-search} (unbound) (@t{N}) (unbound) +Repeat the last vi history search, but in reverse. + +@tindex up-line-or-history +@item @t{up-line-or-history} (@t{^P ESC-[A}) (@t{k}) (@t{ESC-[A}) +Move up a line in the buffer, or if already at the top line, +move to the previous event in the history list. + +@tindex vi-up-line-or-history +@item @t{vi-up-line-or-history} (unbound) (@t{-}) (unbound) +Move up a line in the buffer, or if already at the top line, +move to the previous event in the history list. +Then move to the first non-blank character on the line. + +@tindex up-line-or-search +@item @t{up-line-or-search} +Move up a line in the buffer, or if already at the top line, +search backward in the history for a line beginning with the +first word in the buffer. + +@noindent +If called from a function by the @t{zle} command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer. + +@tindex up-history +@item @t{up-history} (unbound) (@t{^P}) (unbound) +Move to the previous event in the history list. + +@tindex history-beginning-search-forward +@item @t{history-beginning-search-forward} +Search forward in the history for a line beginning with the current +line up to the cursor. +This leaves the cursor in its original position. + +@tindex set-local-history +@item @t{set-local-history} +By default, history movement commands visit the imported lines as well as +the local lines. This widget lets you toggle this on and off, or set it with +the numeric argument. Zero for both local and imported lines and nonzero for +only local lines. + +@end table +@node Modifying Text, Arguments, History Control, Standard Widgets + +@subsection Modifying Text +@noindent +@table @asis +@tindex vi-add-eol +@item @t{vi-add-eol} (unbound) (@t{A}) (unbound) +Move to the end of the line and enter insert mode. + +@tindex vi-add-next +@item @t{vi-add-next} (unbound) (@t{a}) (unbound) +Enter insert mode after the current cursor position, without changing lines. + +@tindex backward-delete-char +@item @t{backward-delete-char} (@t{^H ^?}) (unbound) (unbound) +Delete the character behind the cursor. + +@tindex vi-backward-delete-char +@item @t{vi-backward-delete-char} (unbound) (@t{X}) (@t{^H}) +Delete the character behind the cursor, without changing lines. +If in insert mode, this won't delete past the point where insert mode was +last entered. + +@tindex backward-delete-word +@item @t{backward-delete-word} +Delete the word behind the cursor. + +@tindex backward-kill-line +@item @t{backward-kill-line} +Kill from the beginning of the line to the cursor position. + +@tindex backward-kill-word +@item @t{backward-kill-word} (@t{^W ESC-^H ESC-^?}) (unbound) (unbound) +Kill the word behind the cursor. + +@tindex vi-backward-kill-word +@item @t{vi-backward-kill-word} (unbound) (unbound) (@t{^W}) +Kill the word behind the cursor, without going past the point where insert +mode was last entered. + +@tindex capitalize-word +@item @t{capitalize-word} (@t{ESC-C ESC-c}) (unbound) (unbound) +Capitalize the current word and move past it. + +@tindex vi-change +@item @t{vi-change} (unbound) (@t{c}) (unbound) +Read a movement command from the keyboard, and kill +from the cursor position to the endpoint of the movement. +Then enter insert mode. +If the command is @t{vi-change}, change the current line. + +@noindent +For compatibility with vi, if the command is @t{vi-forward-word} +or @t{vi-forward-blank-word}, the whitespace after the word is not +included. If you prefer the more consistent behaviour with the +whitespace included use the following key binding: + +@noindent +@example +bindkey -a -s cw dwi +@end example + +@tindex vi-change-eol +@item @t{vi-change-eol} (unbound) (@t{C}) (unbound) +Kill to the end of the line and enter insert mode. + +@tindex vi-change-whole-line +@item @t{vi-change-whole-line} (unbound) (@t{S}) (unbound) +Kill the current line and enter insert mode. + +@tindex copy-region-as-kill +@item @t{copy-region-as-kill} (@t{ESC-W ESC-w}) (unbound) (unbound) +Copy the area from the cursor to the mark to the kill buffer. + +@noindent +If called from a ZLE widget function in the form `@t{zle +copy-region-as-kill} @var{string}' then @var{string} will be taken as the +text to copy to the kill buffer. The cursor, the mark and the text on the +command line are not used in this case. + +@tindex copy-prev-word +@item @t{copy-prev-word} (@t{ESC-^_}) (unbound) (unbound) +Duplicate the word to the left of the cursor. + +@tindex copy-prev-shell-word +@item @t{copy-prev-shell-word} +Like @t{copy-prev-word}, but the word is found by using shell parsing, +whereas @t{copy-prev-word} looks for blanks. This makes a difference +when the word is quoted and contains spaces. + +@tindex vi-delete +@item @t{vi-delete} (unbound) (@t{d}) (unbound) +Read a movement command from the keyboard, and kill +from the cursor position to the endpoint of the movement. +If the command is @t{vi-delete}, kill the current line. + +@tindex delete-char +@item @t{delete-char} +Delete the character under the cursor. + +@tindex vi-delete-char +@item @t{vi-delete-char} (unbound) (@t{x}) (unbound) +Delete the character under the cursor, +without going past the end of the line. + +@tindex delete-word +@item @t{delete-word} +Delete the current word. + +@tindex down-case-word +@item @t{down-case-word} (@t{ESC-L ESC-l}) (unbound) (unbound) +Convert the current word to all lowercase and move past it. + +@tindex vi-down-case +@item @t{vi-down-case} (unbound) (@t{gu}) (unbound) +Read a movement command from the keyboard, and convert all characters +from the cursor position to the endpoint of the movement to lowercase. +If the movement command is @t{vi-down-case}, swap the case of all +characters on the current line. + +@tindex kill-word +@item @t{kill-word} (@t{ESC-D ESC-d}) (unbound) (unbound) +Kill the current word. + +@tindex gosmacs-transpose-chars +@item @t{gosmacs-transpose-chars} +Exchange the two characters behind the cursor. + +@tindex vi-indent +@item @t{vi-indent} (unbound) (@t{>}) (unbound) +Indent a number of lines. + +@tindex vi-insert +@item @t{vi-insert} (unbound) (@t{i}) (unbound) +Enter insert mode. + +@tindex vi-insert-bol +@item @t{vi-insert-bol} (unbound) (@t{I}) (unbound) +Move to the first non-blank character on the line and enter insert mode. + +@tindex vi-join +@item @t{vi-join} (@t{^X^J}) (@t{J}) (unbound) +Join the current line with the next one. + +@tindex kill-line +@item @t{kill-line} (@t{^K}) (unbound) (unbound) +Kill from the cursor to the end of the line. +If already on the end of the line, kill the newline character. + +@tindex vi-kill-line +@item @t{vi-kill-line} (unbound) (unbound) (@t{^U}) +Kill from the cursor back to wherever insert mode was last entered. + +@tindex vi-kill-eol +@item @t{vi-kill-eol} (unbound) (@t{D}) (unbound) +Kill from the cursor to the end of the line. + +@tindex kill-region +@item @t{kill-region} +Kill from the cursor to the mark. + +@tindex kill-buffer +@item @t{kill-buffer} (@t{^X^K}) (unbound) (unbound) +Kill the entire buffer. + +@tindex kill-whole-line +@item @t{kill-whole-line} (@t{^U}) (unbound) (unbound) +Kill the current line. + +@tindex vi-match-bracket +@item @t{vi-match-bracket} (@t{^X^B}) (@t{%}) (unbound) +Move to the bracket character (one of @t{@{@}}, @t{()} or @t{[]}) that +matches the one under the cursor. +If the cursor is not on a bracket character, move forward without going +past the end of the line to find one, and then go to the matching bracket. + +@tindex vi-open-line-above +@item @t{vi-open-line-above} (unbound) (@t{O}) (unbound) +Open a line above the cursor and enter insert mode. + +@tindex vi-open-line-below +@item @t{vi-open-line-below} (unbound) (@t{o}) (unbound) +Open a line below the cursor and enter insert mode. + +@tindex vi-oper-swap-case +@item @t{vi-oper-swap-case} (unbound) (@t{g~}) (unbound) +Read a movement command from the keyboard, and swap +the case of all characters +from the cursor position to the endpoint of the movement. +If the movement command is @t{vi-oper-swap-case}, +swap the case of all characters on the current line. + +@tindex overwrite-mode +@item @t{overwrite-mode} (@t{^X^O}) (unbound) (unbound) +Toggle between overwrite mode and insert mode. + +@tindex vi-put-before +@item @t{vi-put-before} (unbound) (@t{P}) (unbound) +Insert the contents of the kill buffer before the cursor. +If the kill buffer contains a sequence of lines (as opposed to characters), +paste it above the current line. + +@tindex vi-put-after +@item @t{vi-put-after} (unbound) (@t{p}) (unbound) +Insert the contents of the kill buffer after the cursor. +If the kill buffer contains a sequence of lines (as opposed to characters), +paste it below the current line. + +@tindex put-replace-selection +@item @t{put-replace-selection} (unbound) (unbound) (unbound) +Replace the contents of the current region or selection with the +contents of the kill buffer. If the kill buffer contains a sequence of +lines (as opposed to characters), the current line will be split by the +pasted lines. + +@tindex quoted-insert +@item @t{quoted-insert} (@t{^V}) (unbound) (unbound) +Insert the next character typed into the buffer literally. +An interrupt character will not be inserted. + +@tindex vi-quoted-insert +@item @t{vi-quoted-insert} (unbound) (unbound) (@t{^Q ^V}) +Display a `@t{^}' at the cursor position, and +insert the next character typed into the buffer literally. +An interrupt character will not be inserted. + +@tindex quote-line +@item @t{quote-line} (@t{ESC-'}) (unbound) (unbound) +Quote the current line; that is, put a `@t{'}' character at the +beginning and the end, and convert all `@t{'}' characters +to `@t{'\@value{dsq}}'. + +@tindex quote-region +@item @t{quote-region} (@t{ESC-"}) (unbound) (unbound) +Quote the region from the cursor to the mark. + +@tindex vi-replace +@item @t{vi-replace} (unbound) (@t{R}) (unbound) +Enter overwrite mode. + +@tindex vi-repeat-change +@item @t{vi-repeat-change} (unbound) (@t{.}) (unbound) +Repeat the last vi mode text modification. +If a count was used with the modification, it is remembered. +If a count is given to this command, it overrides the remembered count, +and is remembered for future uses of this command. +The cut buffer specification is similarly remembered. + +@tindex vi-replace-chars +@item @t{vi-replace-chars} (unbound) (@t{r}) (unbound) +Replace the character under the cursor with a character +read from the keyboard. + +@tindex self-insert +@item @t{self-insert} (printable characters) (unbound) (printable characters and some control characters) +Insert a character into the buffer at the cursor position. + +@tindex self-insert-unmeta +@item @t{self-insert-unmeta} (@t{ESC-^I ESC-^J ESC-^M}) (unbound) (unbound) +Insert a character into the buffer after stripping the meta bit +and converting ^M to ^J. + +@tindex vi-substitute +@item @t{vi-substitute} (unbound) (@t{s}) (unbound) +Substitute the next character(s). + +@tindex vi-swap-case +@item @t{vi-swap-case} (unbound) (@t{~}) (unbound) +Swap the case of the character under the cursor and move past it. + +@tindex transpose-chars +@item @t{transpose-chars} (@t{^T}) (unbound) (unbound) +Exchange the two characters to the left of the +cursor if at end of line, else exchange the +character under the cursor with the character +to the left. + +@tindex transpose-words +@item @t{transpose-words} (@t{ESC-T ESC-t}) (unbound) (unbound) +Exchange the current word with the one before it. + +@noindent +With a positive numeric argument @emph{N}, the word around the cursor, or +following it if the cursor is between words, is transposed with the +preceding @emph{N} words. The cursor is put at the end of the resulting +group of words. + +@noindent +With a negative numeric argument @emph{-N}, the effect is the same as using +a positive argument @emph{N} except that the original cursor position is +retained, regardless of how the words are rearranged. + +@tindex vi-unindent +@item @t{vi-unindent} (unbound) (@t{<}) (unbound) +Unindent a number of lines. + +@tindex vi-up-case +@item @t{vi-up-case} (unbound) (@t{gU}) (unbound) +Read a movement command from the keyboard, and convert all characters +from the cursor position to the endpoint of the movement to lowercase. +If the movement command is @t{vi-up-case}, swap the case of all +characters on the current line. + +@tindex up-case-word +@item @t{up-case-word} (@t{ESC-U ESC-u}) (unbound) (unbound) +Convert the current word to all caps and move past it. + +@tindex yank +@item @t{yank} (@t{^Y}) (unbound) (unbound) +Insert the contents of the kill buffer at the cursor position. + +@tindex yank-pop +@item @t{yank-pop} (@t{ESC-y}) (unbound) (unbound) +Remove the text just yanked, rotate the kill-ring (the history of +previously killed text) and yank the new top. Only works following +@t{yank}, @t{vi-put-before}, @t{vi-put-after} or @t{yank-pop}. + +@tindex vi-yank +@item @t{vi-yank} (unbound) (@t{y}) (unbound) +Read a movement command from the keyboard, and copy the region +from the cursor position to the endpoint of the movement +into the kill buffer. +If the command is @t{vi-yank}, copy the current line. + +@tindex vi-yank-whole-line +@item @t{vi-yank-whole-line} (unbound) (@t{Y}) (unbound) +Copy the current line into the kill buffer. + +@tindex vi-yank-eol +@item @t{vi-yank-eol} +Copy the region from the cursor position to the end of the line +into the kill buffer. +Arguably, this is what Y should do in vi, but it isn't what it actually does. + +@end table +@node Arguments, Completion, Modifying Text, Standard Widgets + +@subsection Arguments +@noindent +@table @asis +@tindex digit-argument +@item @t{digit-argument} (@t{ESC-0}..@t{ESC-9}) (@t{1}-@t{9}) (unbound) +Start a new numeric argument, or add to the current one. +See also @t{vi-digit-or-beginning-of-line}. This only works if bound to a +key sequence ending in a decimal digit. + +@noindent +Inside a widget function, a call to this function treats the last key of +the key sequence which called the widget as the digit. + +@tindex neg-argument +@item @t{neg-argument} (@t{ESC-}@t{-}) (unbound) (unbound) +Changes the sign of the following argument. + +@tindex universal-argument +@item @t{universal-argument} +Multiply the argument of the next command by 4. Alternatively, if +this command is followed by an integer (positive or negative), use +that as the argument for the next command. Thus digits cannot be +repeated using this command. For example, if this command occurs +twice, followed immediately by @t{forward-char}, move forward sixteen +spaces; if instead it is followed by @t{-2}, then @t{forward-char}, +move backward two spaces. + +@noindent +Inside a widget function, if passed an argument, i.e. `@t{zle +universal-argument} @var{num}', the numeric argument will be set to +@var{num}; this is equivalent to `@t{NUMERIC=}@var{num}'. + +@tindex argument-base +@item @t{argument-base} +Use the existing numeric argument as a numeric base, which must be in the +range 2 to 36 inclusive. Subsequent use of @t{digit-argument} and +@t{universal-argument} will input a new numeric argument in the given base. +The usual hexadecimal convention is used: the letter @t{a} or @t{A} +corresponds to 10, and so on. Arguments in bases requiring digits from 10 +upwards are more conveniently input with @t{universal-argument}, since +@t{ESC-a} etc. are not usually bound to @t{digit-argument}. + +@noindent +The function can be used with a command argument inside a user-defined +widget. The following code sets the base to 16 and lets the user input a +hexadecimal argument until a key out of the digit range is typed: + +@noindent +@example +zle argument-base 16 +zle universal-argument +@end example + +@end table +@node Completion, Miscellaneous, Arguments, Standard Widgets + +@subsection Completion +@noindent +@table @asis +@tindex accept-and-menu-complete +@item @t{accept-and-menu-complete} +In a menu completion, insert the current completion into the buffer, +and advance to the next possible completion. + +@tindex complete-word +@item @t{complete-word} +Attempt completion on the current word. + +@tindex delete-char-or-list +@item @t{delete-char-or-list} (@t{^D}) (unbound) (unbound) +Delete the character under the cursor. If the cursor +is at the end of the line, list possible completions for the +current word. + +@tindex expand-cmd-path +@item @t{expand-cmd-path} +Expand the current command to its full pathname. + +@tindex expand-or-complete +@item @t{expand-or-complete} (@t{TAB}) (unbound) (@t{TAB}) +Attempt shell expansion on the current word. +If that fails, +attempt completion. + +@tindex expand-or-complete-prefix +@item @t{expand-or-complete-prefix} +Attempt shell expansion on the current word up to cursor. + +@tindex expand-history +@item @t{expand-history} (@t{ESC-space ESC-!}) (unbound) (unbound) +Perform history expansion on the edit buffer. + +@tindex expand-word +@item @t{expand-word} (@t{^X*}) (unbound) (unbound) +Attempt shell expansion on the current word. + +@tindex list-choices +@item @t{list-choices} (@t{ESC-^D}) (@t{^D =}) (@t{^D}) +List possible completions for the current word. + +@tindex list-expand +@item @t{list-expand} (@t{^Xg ^XG}) (@t{^G}) (@t{^G}) +List the expansion of the current word. + +@tindex magic-space +@item @t{magic-space} +Perform history expansion and insert a space into the +buffer. This is intended to be bound to space. + +@tindex menu-complete +@pindex MENU_COMPLETE, use of +@item @t{menu-complete} +Like @t{complete-word}, except that menu completion is used. +See the @t{MENU_COMPLETE} option. + +@tindex menu-expand-or-complete +@item @t{menu-expand-or-complete} +Like @t{expand-or-complete}, except that menu completion is used. + +@tindex reverse-menu-complete +@item @t{reverse-menu-complete} +Perform menu completion, like @t{menu-complete}, except that if +a menu completion is already in progress, move to the @emph{previous} +completion rather than the next. + +@tindex end-of-list +@item @t{end-of-list} +When a previous completion displayed a list below the prompt, this +widget can be used to move the prompt below the list. + +@end table +@node Miscellaneous, Text Objects, Completion, Standard Widgets + +@subsection Miscellaneous +@noindent +@table @asis +@tindex accept-and-hold +@item @t{accept-and-hold} (@t{ESC-A ESC-a}) (unbound) (unbound) +Push the contents of the buffer on the buffer stack +and execute it. + +@tindex accept-and-infer-next-history +@item @t{accept-and-infer-next-history} +Execute the contents of the buffer. +Then search the history list for a line matching the current one +and push the event following onto the buffer stack. + +@tindex accept-line +@item @t{accept-line} (@t{^J ^M}) (@t{^J ^M}) (@t{^J ^M}) +Finish editing the buffer. Normally this causes the buffer to be +executed as a shell command. + +@tindex accept-line-and-down-history +@item @t{accept-line-and-down-history} (@t{^O}) (unbound) (unbound) +Execute the current line, and push the next history +event on the buffer stack. + +@tindex auto-suffix-remove +@item @t{auto-suffix-remove} +If the previous action added a suffix (space, slash, etc.) to the word on +the command line, remove it. Otherwise do nothing. Removing the suffix +ends any active menu completion or menu selection. + +@noindent +This widget is intended to be called from user-defined widgets to enforce +a desired suffix-removal behavior. + +@tindex auto-suffix-retain +@item @t{auto-suffix-retain} +If the previous action added a suffix (space, slash, etc.) to the word on +the command line, force it to be preserved. Otherwise do nothing. +Retaining the suffix ends any active menu completion or menu selection. + +@noindent +This widget is intended to be called from user-defined widgets to enforce +a desired suffix-preservation behavior. + +@tindex beep +@item @t{beep} +Beep, unless the @t{BEEP} option is unset. + +@tindex bracketed-paste +@item @t{bracketed-paste} (@t{^[[200~}) (@t{^[[200~}) (@t{^[[200~}) +This widget is invoked when text is pasted to the terminal emulator. It +is not intended to be bound to actual keys but instead to the special +sequence generated by the terminal emulator when text is pasted. + +@noindent +When invoked interactively, the pasted text is inserted to the buffer +and placed in the cutbuffer. +If a numeric argument is given, shell quoting will be applied to the +pasted text before it is inserted. + +@noindent +When a named buffer is specified with @t{vi-set-buffer} (@t{"x}), +the pasted text is stored in that named buffer but not inserted. + +@noindent +When called from a widget function as `@t{bracketed-paste} @var{name}`, the +pasted text is assigned to the variable @var{name} and no other processing is +done. + +@noindent +See also the @t{zle_bracketed_paste} parameter. + +@tindex vi-cmd-mode +@item @t{vi-cmd-mode} (@t{^X^V}) (unbound) (@t{^[}) +Enter command mode; that is, select the `@t{vicmd}' keymap. +Yes, this is bound by default in emacs mode. + +@tindex vi-caps-lock-panic +@item @t{vi-caps-lock-panic} +Hang until any lowercase key is pressed. +This is for vi users without the mental capacity to keep +track of their caps lock key (like the author). + +@tindex clear-screen +@item @t{clear-screen} (@t{^L ESC-^L}) (@t{^L}) (@t{^L}) +Clear the screen and redraw the prompt. + +@tindex deactivate-region +@item @t{deactivate-region} +Make the current region inactive. This disables vim-style visual +selection mode if it is active. + +@tindex describe-key-briefly +@item @t{describe-key-briefly} +Reads a key sequence, then prints the function bound to that sequence. + +@tindex exchange-point-and-mark +@item @t{exchange-point-and-mark} (@t{^X^X}) (unbound) (unbound) +Exchange the cursor position (point) with the position of the mark. +Unless a negative numeric argument is given, the region between +point and mark is activated so that it can be highlighted. +If a zero numeric argument is given, the region is activated but +point and mark are not swapped. + +@tindex execute-named-cmd +@item @t{execute-named-cmd} (@t{ESC-x}) (@t{:}) (unbound) +Read the name of an editor command and execute it. Aliasing this +widget with `@t{zle -A}' or replacing it with `@t{zle -N}' has no +effect when interpreting key bindings, but `@t{zle execute-named-cmd}' +will invoke such an alias or replacement. + +@noindent +A restricted set of editing functions is available in the +mini-buffer. Keys are looked up in the special +@t{command} keymap, and if not found there in the main keymap. +An interrupt signal, as defined by the stty setting, will +abort the function. Note that the following always +perform the same task within the @t{executed-named-cmd} environment and +cannot be replaced by user defined widgets, nor can the set of functions +be extended. The allowed functions are: +@t{backward-delete-char}, +@t{vi-backward-delete-char}, +@t{clear-screen}, +@t{redisplay}, +@t{quoted-insert}, +@t{vi-quoted-insert}, +@t{backward-kill-word}, +@t{vi-backward-kill-word}, +@t{kill-whole-line}, +@t{vi-kill-line}, +@t{backward-kill-line}, +@t{list-choices}, +@t{delete-char-or-list}, +@t{complete-word}, +@t{accept-line}, +@t{expand-or-complete} and +@t{expand-or-complete-prefix}. + +@noindent +@t{kill-region} kills the last word, +and vi-cmd-mode is treated the same as accept-line. +The space and tab characters, if not bound to one of +these functions, will complete the name and then list the +possibilities if the @t{AUTO_LIST} option is set. +Any other character that is not bound to @t{self-insert} or +@t{self-insert-unmeta} will beep and be ignored. +The bindings of the current insert mode will be used. + +@noindent +Currently this command may not be redefined or called by name. + +@tindex execute-last-named-cmd +@item @t{execute-last-named-cmd} (@t{ESC-z}) (unbound) (unbound) +Redo the last function executed with @t{execute-named-cmd}. + +@noindent +Like @t{execute-named-cmd}, this command may not be redefined, +but it may be called by name. + +@tindex get-line +@item @t{get-line} (@t{ESC-G ESC-g}) (unbound) (unbound) +Pop the top line off the buffer stack and insert it at the +cursor position. + +@tindex pound-insert +@item @t{pound-insert} (unbound) (@t{#}) (unbound) +If there is no # character at the beginning of the buffer, +add one to the beginning of each line. +If there is one, remove a # from each line that has one. +In either case, accept the current line. +The @t{INTERACTIVE_COMMENTS} option must be set +for this to have any usefulness. + +@tindex vi-pound-insert +@item @t{vi-pound-insert} +If there is no # character at the beginning of the current line, +add one. If there is one, remove it. +The @t{INTERACTIVE_COMMENTS} option must be set +for this to have any usefulness. + +@tindex push-input +@item @t{push-input} +Push the entire current multiline construct onto the buffer stack and +return to the top-level (@t{PS1}) prompt. +If the current parser construct is only a single line, this is exactly +like @t{push-line}. +Next time the editor starts up or is popped with @t{get-line}, the +construct will be popped off the top of the buffer stack and loaded +into the editing buffer. + +@tindex push-line +@item @t{push-line} (@t{^Q ESC-Q ESC-q}) (unbound) (unbound) +Push the current buffer onto the buffer stack and clear +the buffer. +Next time the editor starts up, the buffer will be popped +off the top of the buffer stack and loaded into the editing +buffer. + +@tindex push-line-or-edit +@item @t{push-line-or-edit} +At the top-level (@t{PS1}) prompt, equivalent to @t{push-line}. +At a secondary (@t{PS2}) prompt, move the entire current multiline +construct into the editor buffer. +The latter is equivalent to @t{push-input} followed by @t{get-line}. + +@tindex read-command +@item @t{read-command} +Only useful from a user-defined widget. A keystroke is read just as in +normal operation, but instead of the command being executed the name +of the command that would be executed is stored in the shell parameter +@t{REPLY}. This can be used as the argument of a future @t{zle} +command. If the key sequence is not bound, status 1 is returned; +typically, however, @t{REPLY} is set to @t{undefined-key} to indicate +a useless key sequence. + +@tindex recursive-edit +@item @t{recursive-edit} +Only useful from a user-defined widget. At this point in the function, +the editor regains control until one of the standard widgets which would +normally cause zle to exit (typically an @t{accept-line} caused by +hitting the return key) is executed. Instead, control returns to the +user-defined widget. The status returned is non-zero if the return was +caused by an error, but the function still continues executing and hence +may tidy up. This makes it safe for the user-defined widget to alter +the command line or key bindings temporarily. + +@noindent +The following widget, @t{caps-lock}, serves as an example. + +@noindent +@example +self-insert-ucase() @{ + LBUFFER+=$@{(U)KEYS[-1]@} +@} + +integer stat + +zle -N self-insert self-insert-ucase +zle -A caps-lock save-caps-lock +zle -A accept-line caps-lock + +zle recursive-edit +stat=$? + +zle -A .self-insert self-insert +zle -A save-caps-lock caps-lock +zle -D save-caps-lock + +(( stat )) && zle send-break + +return $stat +@end example + +@noindent +This causes typed letters to be inserted capitalised until either +@t{accept-line} (i.e. typically the return key) is typed or the +@t{caps-lock} widget is invoked again; the later is handled by saving +the old definition of @t{caps-lock} as @t{save-caps-lock} and then +rebinding it to invoke @t{accept-line}. Note that an error from the +recursive edit is detected as a non-zero return status and propagated by +using the @t{send-break} widget. + +@tindex redisplay +@item @t{redisplay} (unbound) (@t{^R}) (@t{^R}) +Redisplays the edit buffer. + +@tindex reset-prompt +@item @t{reset-prompt} (unbound) (unbound) (unbound) +Force the prompts on both the left and right of the screen to be +re-expanded, then redisplay the edit buffer. This +reflects changes both to the prompt variables themselves and changes +in the expansion of the values (for example, changes in time or +directory, or changes to the value of variables referred to by the +prompt). + +@noindent +Otherwise, the prompt is only expanded each time zle starts, and +when the display has been interrupted by output from another part of the +shell (such as a job notification) which causes the command line to be +reprinted. + +@noindent +@t{reset-prompt} doesn't alter the special parameter @t{LASTWIDGET}. + +@noindent + +@tindex send-break +@item @t{send-break} (@t{^G ESC-^G}) (unbound) (unbound) +Abort the current editor function, e.g. @t{execute-named-command}, or the +editor itself, e.g. if you are in @t{vared}. Otherwise abort the parsing of +the current line; in this case the aborted line is available in the shell +variable @t{ZLE_LINE_ABORTED}. If the editor is aborted from within +@t{vared}, the variable @t{ZLE_VARED_ABORTED} is set. + +@tindex run-help +@item @t{run-help} (@t{ESC-H ESC-h}) (unbound) (unbound) +Push the buffer onto the buffer stack, and execute the +command `@t{run-help} @var{cmd}', where @var{cmd} is the current +command. @t{run-help} is normally aliased to @t{man}. + +@tindex vi-set-buffer +@item @t{vi-set-buffer} (unbound) (@t{"}) (unbound) +Specify a buffer to be used in the following command. +There are 37 buffers that can be specified: +the 26 `named' buffers @t{"a} to @t{"z}, the `yank' buffer @t{"0}, +the nine `queued' buffers @t{"1} to @t{"9} and the `black hole' buffer +@t{"_}. The named buffers can also be specified as @t{"A} to @t{"Z}. + +@noindent +When a buffer is specified for a cut, change or yank command, the text +concerned replaces the previous contents of the specified buffer. If +a named buffer is specified using a capital, the newly cut text is +appended to the buffer instead of overwriting it. When using the @t{"_} +buffer, nothing happens. This can be useful for deleting text without +affecting any buffers. + +@noindent +If no buffer is specified for a cut or change command, @t{"1} is used, and +the contents of @t{"1} to @t{"8} are each shifted along one buffer; +the contents of @t{"9} is lost. If no buffer is specified for a yank +command, @t{"0} is used. Finally, a paste command without a specified +buffer will paste the text from the most recent command regardless of any +buffer that might have been used with that command. + +@noindent +When called from a widget function by the @t{zle} command, the buffer +can optionally be specified with an argument. For example, + +@noindent +@example +zle vi-set-buffer A +@end example + +@tindex vi-set-mark +@item @t{vi-set-mark} (unbound) (@t{m}) (unbound) +Set the specified mark at the cursor position. + +@tindex set-mark-command +@item @t{set-mark-command} (@t{^@@}) (unbound) (unbound) +Set the mark at the cursor position. If called with a negative +numeric argument, do not set the mark but deactivate the region so that +it is no longer highlighted (it is still usable for other purposes). +Otherwise the region is marked as active. + +@tindex spell-word +@item @t{spell-word} (@t{ESC-$ ESC-S ESC-s}) (unbound) (unbound) +Attempt spelling correction on the current word. + +@tindex split-undo +@item @t{split-undo} +Breaks the undo sequence at the current change. This is useful in vi mode as +changes made in insert mode are coalesced on entering command mode. Similarly, +@t{undo} will normally revert as one all the changes made by a user-defined +widget. + +@tindex undefined-key +@item @t{undefined-key} +This command is executed when a key sequence that is not bound to any +command is typed. By default it beeps. + +@tindex undo +@item @t{undo} (@t{^_ ^Xu ^X^U}) (@t{u}) (unbound) +Incrementally undo the last text modification. When called from a +user-defined widget, takes an optional argument indicating a previous state +of the undo history as returned by the @t{UNDO_CHANGE_NO} variable; +modifications are undone until that state is reached, subject to +any limit imposed by the @t{UNDO_LIMIT_NO} variable. + +@noindent +Note that when invoked from vi command mode, the full prior change made in +insert mode is reverted, the changes having been merged when command mode was +selected. + +@tindex redo +@item @t{redo} (unbound) (@t{^R}) (unbound) +Incrementally redo undone text modifications. + +@tindex vi-undo-change +@item @t{vi-undo-change} (unbound) (unbound) (unbound) +Undo the last text modification. +If repeated, redo the modification. + +@tindex visual-mode +@item @t{visual-mode} (unbound) (@t{v}) (unbound) +Toggle vim-style visual selection mode. If line-wise visual mode is +currently enabled then it is changed to being character-wise. If used +following an operator, it forces the subsequent movement command to be +treated as a character-wise movement. + +@tindex visual-line-mode +@item @t{visual-line-mode} (unbound) (@t{V}) (unbound) +Toggle vim-style line-wise visual selection mode. If character-wise +visual mode is currently enabled then it is changed to being line-wise. If used +following an operator, it forces the subsequent movement command to be +treated as a line-wise movement. + +@tindex what-cursor-position +@item @t{what-cursor-position} (@t{^X=}) (@t{ga}) (unbound) +Print the character under the cursor, its code as an octal, decimal and +hexadecimal number, the current cursor position within the buffer and the +column of the cursor in the current line. + +@tindex where-is +@item @t{where-is} +Read the name of an editor command and print the listing of key +sequences that invoke the specified command. +A restricted set of editing functions is available in the +mini-buffer. Keys are looked up in the special +@t{command} keymap, and if not found there in the main keymap. + +@tindex which-command +@item @t{which-command} (@t{ESC-?}) (unbound) (unbound) +Push the buffer onto the buffer stack, and execute the +command `@t{which-command} @var{cmd}'. where @var{cmd} is the current +command. @t{which-command} is normally aliased to @t{whence}. + +@tindex vi-digit-or-beginning-of-line +@item @t{vi-digit-or-beginning-of-line} (unbound) (@t{0}) (unbound) +If the last command executed was a digit as part of an argument, +continue the argument. Otherwise, execute vi-beginning-of-line. + +@end table +@node Text Objects, , Miscellaneous, Standard Widgets + +@subsection Text Objects +@noindent +@cindex text objects +Text objects are commands that can be used to select a block of text +according to some criteria. They are a feature of the vim text editor +and so are primarily intended for use with vi operators or from visual +selection mode. However, they can also be used from vi-insert or emacs +mode. Key bindings listed below apply to the @t{viopp} and @t{visual} +keymaps. + +@noindent +@table @asis +@tindex select-a-blank-word +@item @t{select-a-blank-word} (@t{aW}) +Select a word including adjacent blanks, where a word is defined as a +series of non-blank characters. With a numeric argument, multiple words +will be selected. + +@tindex select-a-shell-word +@item @t{select-a-shell-word} (@t{aa}) +Select the current command argument applying the normal rules for +quoting. + +@tindex select-a-word +@item @t{select-a-word} (@t{aw}) +Select a word including adjacent blanks, using the normal vi-style word +definition. With a numeric argument, multiple words will be selected. + +@tindex select-in-blank-word +@item @t{select-in-blank-word} (@t{iW}) +Select a word, where a word is defined as a series of non-blank +characters. With a numeric argument, multiple words will be selected. + +@tindex select-in-shell-word +@item @t{select-in-shell-word} (@t{ia}) +Select the current command argument applying the normal rules for +quoting. If the argument begins and ends with matching quote characters, +these are not included in the selection. + +@tindex select-in-word +@item @t{select-in-word} (@t{iw}) +Select a word, using the normal vi-style word definition. With a numeric +argument, multiple words will be selected. + +@end table + +@noindent +@node Character Highlighting, , Standard Widgets, Zsh Line Editor + +@section Character Highlighting +@noindent + +@noindent +@vindex zle_highlight, setting +The line editor has the ability to highlight characters or regions +of the line that have a particular significance. This is controlled +by the array parameter @t{zle_highlight}, if it has been set by the user. + +@noindent +If the parameter contains the single entry @t{none} all highlighting +is turned off. Note the parameter is still expected to be an array. + +@noindent +Otherwise each entry of the array should consist of a word indicating a +context for highlighting, then a colon, then a comma-separated list of +the types of highlighting to apply in that context. + +@noindent +The contexts available for highlighting are the following: + +@noindent +@table @asis +@cindex region, highlighting +@cindex highlighting, region +@item @t{default} +Any text within the command line not affected by any other highlighting. +Text outside the editable area of the command line is not affected. + +@item @t{isearch} +When one of the incremental history search widgets is active, the +area of the command line matched by the search string or pattern. + +@item @t{region} +The currently selected text. In emacs terminology, this is referred to as +the region and is bounded by the cursor (point) and the mark. The region +is only highlighted if it is active, which is the case after the mark +is modified with @t{set-mark-command} or @t{exchange-point-and-mark}. +Note that whether or not the region is active has no effect on its +use within emacs style widgets, it simply determines whether it is +highlighted. In vi mode, the region corresponds to selected text in +visual mode. + +@cindex special characters, highlighting +@cindex highlighting, special characters +@item @t{special} +Individual characters that have no direct printable +representation but are shown in a special manner by the line editor. +These characters are described below. + +@cindex completion removable suffix, highlighting +@cindex suffix, highlighting removable, in completion +@cindex removable suffix, highlighting in completion +@item @t{suffix} +This context is used in completion for characters that are +marked as suffixes that will be removed if the completion ends +at that point, the most obvious example being a slash (@t{/}) after +a directory name. Note that suffix removal is configurable; the +circumstances under which the suffix will be removed may differ +for different completions. + +@item @t{paste} +Following a command to paste text, the characters that were inserted. + +@end table + +@noindent +When @t{region_highlight} is set, the contexts that describe a region --- +@t{isearch}, @t{region}, @t{suffix}, and @t{paste} --- +are applied first, then @t{region_highlight} is applied, then the remaining +@t{zle_highlight} contexts are applied. If a particular character is +affected by multiple specifications, the last specification wins. + +@noindent +@t{zle_highlight} may contain additional fields for controlling how +terminal sequences to change colours are output. Each of the following is +followed by a colon and a string in the same form as for key bindings. +This will not be necessary for the vast majority of terminals as the +defaults shown in parentheses are widely used. + +@noindent +@table @asis +@cindex escape sequences, terminal, for highlighting +@cindex terminal escape sequences for highlighting +@item @t{fg_start_code} (@t{\e[3}) +The start of the escape sequence for the foreground colour. +This is followed by one to three ASCII digits representing the colour. +Only used for palette colors, i.e. not 24-bit colors specified via a +color triplet. + +@item @t{fg_default_code} (@t{9}) +The number to use instead of the colour to reset the default foreground +colour. + +@item @t{fg_end_code} (@t{m}) +The end of the escape sequence for the foreground colour. + +@item @t{bg_start_code} (@t{\e[4}) +The start of the escape sequence for the background colour. +See @t{fg_start_code} above. + +@item @t{bg_default_code} (@t{9}) +The number to use instead of the colour to reset the default +background colour. + +@item @t{bg_end_code} (@t{m}) +The end of the escape sequence for the background colour. + +@end table + +@noindent +The available types of highlighting are the following. Note that +not all types of highlighting are available on all terminals: + +@noindent +@table @asis +@item @t{none} +No highlighting is applied to the given context. It is not useful for +this to appear with other types of highlighting; it is used to override +a default. + +@item @t{fg=}@var{colour} +The foreground colour should be set to @var{colour}, a decimal integer, +the name of one of the eight most widely-supported colours or as a +`@t{#}' followed by an RGB triplet in hexadecimal format. + +@noindent +Not all terminals support this and, of those that do, not all provide +facilities to test the support, hence the user should decide based on the +terminal type. Most terminals support the colours @t{black}, @t{red}, +@t{green}, @t{yellow}, @t{blue}, @t{magenta}, @t{cyan} and @t{white}, +which can be set by name. In addition. @t{default} may be used to +set the terminal's default foreground colour. Abbreviations are allowed; +@t{b} or @t{bl} selects black. Some terminals may generate additional +colours if the @t{bold} attribute is also present. + +@noindent +On recent terminals and on systems with an up-to-date terminal database the +number of colours supported may be tested by the command `@t{echotc +Co}'; if this succeeds, it indicates a limit on the number of colours which +will be enforced by the line editor. The number of colours is in any case +limited to 256 (i.e. the range 0 to 255). + +@noindent +Some modern terminal emulators have support for 24-bit true colour (16 +million colours). In this case, the hex triplet format can be used. This +consists of a `@t{#}' followed by either a three or six digit hexadecimal +number describing the red, green and blue components of the colour. Hex +triplets can also be used with 88 and 256 colour terminals via the +@t{zsh/nearcolor} module (see @ref{The zsh/nearcolor Module}). + +@noindent +Colour is also known as color. + +@item @t{bg=}@var{colour} +The background colour should be set to @var{colour}. +This works similarly to the foreground colour, except the background is +not usually affected by the bold attribute. + +@item @t{bold} +The characters in the given context are shown in a bold font. +Not all terminals distinguish bold fonts. + +@item @t{standout} +The characters in the given context are shown in the terminal's standout +mode. The actual effect is specific to the terminal; on many terminals it +is inverse video. On some such terminals, where the cursor does not blink +it appears with standout mode negated, making it less than clear where +the cursor actually is. On such terminals one of the other effects +may be preferable for highlighting the region and matched search string. + +@item @t{underline} +The characters in the given context are shown underlined. Some +terminals show the foreground in a different colour instead; in this +case whitespace will not be highlighted. + +@end table + +@noindent +The characters described above as `special' are as follows. The +formatting described here is used irrespective of whether the characters +are highlighted: + +@noindent +@table @asis +@item ASCII control characters +Control characters in the ASCII range are shown as +`@t{^}' followed by the base character. + +@item Unprintable multibyte characters +This item applies to control characters not in the ASCII range, +plus other characters as follows. If the @t{MULTIBYTE} option is in +effect, multibyte characters not in the ASCII character set that are +reported as having zero width are treated as combining characters when the +option @t{COMBINING_CHARS} is on. If the option is off, or if a character +appears where a combining character is not valid, the character +is treated as unprintable. + +@noindent +Unprintable multibyte characters are shown as a hexadecimal number between +angle brackets. The number is the code point of the character in the wide +character set; this may or may not be Unicode, depending on the operating +system. + +@item Invalid multibyte characters +If the @t{MULTIBYTE} option is in effect, any sequence of one or more +bytes that does not form a valid character in the current character +set is treated as a series of bytes each shown as a special character. +This case can be distinguished from other unprintable characters +as the bytes are represented as two hexadecimal digits between angle +brackets, as distinct from the four or eight digits that are used for +unprintable characters that are nonetheless valid in the current +character set. + +@noindent +Not all systems support this: for it to work, the system's representation of +wide characters must be code values from the Universal Character Set, +as defined by IS0 10646 (also known as Unicode). + +@item Wrapped double-width characters +When a double-width character appears in the final column of a line, it +is instead shown on the next line. The empty space left in the original +position is highlighted as a special character. + +@end table + +@noindent +If @t{zle_highlight} is not set or no value applies to a particular +context, the defaults applied are equivalent to + +@noindent +@example +zle_highlight=(region:standout special:standout +suffix:bold isearch:underline paste:standout) +@end example + +@noindent +i.e. both the region and special characters are shown in standout mode. + +@noindent +Within widgets, arbitrary regions may be highlighted by setting the +special array parameter @t{region_highlight}; see +@ref{Zle Widgets}. + +@noindent +@c (avoiding a yodl bug) +@c Yodl file: Zsh/compwid.yo +@node Completion Widgets, Completion System, Zsh Line Editor, Top + +@chapter Completion Widgets +@noindent +@cindex completion, widgets +@cindex completion, programmable +@cindex completion, controlling + +@section Description +@noindent +The shell's programmable completion mechanism can be manipulated in two +ways; here the low-level features supporting the newer, function-based +mechanism are defined. A complete set of shell functions based on these +features is described in +the next chapter, @ref{Completion System}, +and users with no interest in adding to that system (or, potentially, +writing their own --- see dictionary entry for `hubris') should skip +the current section. The older system based on the @t{compctl} builtin +command is described in +@ref{Completion Using compctl}. + +@noindent +Completion widgets are defined by the @t{-C} option to the @t{zle} +builtin command provided by the @t{zsh/zle} module (see +@ref{The zsh/zle Module}). For example, + +@noindent +@example +zle -C complete expand-or-complete completer +@end example + +@noindent +defines a widget named `@t{complete}'. The second argument is the name +of any of the builtin widgets that handle completions: +@t{complete-word}, @t{expand-or-complete}, +@t{expand-or-complete-prefix}, @t{menu-complete}, +@t{menu-expand-or-complete}, @t{reverse-menu-complete}, +@t{list-choices}, or @t{delete-char-or-list}. Note that this will still +work even if the widget in question has been re-bound. + +@noindent +When this newly defined widget is bound to a key +using the @t{bindkey} builtin command defined in the @t{zsh/zle} module +(@ref{Zsh Line Editor}), typing that key will call the shell function `@t{completer}'. This +function is responsible for generating completion matches using the +builtins described below. As with other ZLE widgets, the function is +called with its standard input closed. + +@noindent +Once the function returns, the completion code takes over control again +and treats the matches in the same manner as the specified builtin +widget, in this case @t{expand-or-complete}. + +@noindent +@menu +* Completion Special Parameters:: +* Completion Builtin Commands:: +* Completion Condition Codes:: +* Completion Matching Control:: +* Completion Widget Example:: +@end menu + +@noindent +@node Completion Special Parameters, Completion Builtin Commands, , Completion Widgets + +@section Completion Special Parameters +@noindent + +@noindent +The parameters @t{ZLE_REMOVE_SUFFIX_CHARS} and @t{ZLE_SPACE_SUFFIX_CHARS} +are used by the completion mechanism, but are not special. See +@ref{Parameters Used By The Shell}. + +@noindent +Inside completion widgets, and any functions called from them, some +parameters have special meaning; outside these functions they are not +special to the shell in any way. These parameters are used to pass +information between the completion code and the completion widget. Some of +the builtin commands and the condition codes use or change the current +values of these parameters. Any existing values will be hidden during +execution of completion widgets; except for @t{compstate}, the parameters +are reset on each function exit (including nested function calls from +within the completion widget) to the values they had when the function was +entered. + +@noindent +@table @asis +@vindex CURRENT +@item @t{CURRENT} +This is the number of the current word, i.e. the word the cursor is +currently on in the @t{words} array. Note that this value is only +correct if the @t{ksharrays} option is not set. + +@vindex IPREFIX +@item @t{IPREFIX} +Initially this will be set to the empty string. This parameter functions +like @t{PREFIX}; it contains a string which precedes the one in @t{PREFIX} +and is not considered part of the list of matches. Typically, a string is +transferred from the beginning of @t{PREFIX} to the end of @t{IPREFIX}, for +example: + +@noindent +@example +IPREFIX=$@{PREFIX%%\=*@}= +PREFIX=$@{PREFIX#*=@} +@end example + +@noindent +causes the part of the prefix up to and including the first equal sign not +to be treated as part of a matched string. This can be done automatically +by the @t{compset} builtin, see below. + +@vindex ISUFFIX +@item @t{ISUFFIX} +As @t{IPREFIX}, but for a suffix that should not be considered part +of the matches; note that the @t{ISUFFIX} string follows the @t{SUFFIX} +string. + +@vindex PREFIX +@item @t{PREFIX} +Initially this will be set to the part of the current word from the +beginning of the word up to the position of the cursor; it may be altered +to give a common prefix for all matches. + +@vindex QIPREFIX +@item @t{QIPREFIX} +This parameter is read-only and contains the quoted string up to the +word being completed. E.g. when completing `@t{"foo}', this parameter +contains the double quote. If the @t{-q} option of @t{compset} is used +(see below), and the original string was `@t{"foo bar}' with the +cursor on the `@t{bar}', this parameter contains `@t{"foo }'. + +@vindex QISUFFIX +@item @t{QISUFFIX} +Like @t{QIPREFIX}, but containing the suffix. + +@vindex SUFFIX +@item @t{SUFFIX} +Initially this will be set to the part of the current word from the +cursor position to the end; it may be altered to give a common suffix for +all matches. It is most useful when the option @t{COMPLETE_IN_WORD} is +set, as otherwise the whole word on the command line is treated as a +prefix. + +@vindex compstate +@cindex completion widgets, examining and setting state in +@item @t{compstate} +This is an associative array with various keys and values that the +completion code uses to exchange information with the completion widget. +The keys are: + +@noindent +@table @asis +@vindex all_quotes, compstate +@item @t{all_quotes} +The @t{-q} option of the @t{compset} builtin command (see below) +allows a quoted string to be broken into separate words; if the cursor is +on one of those words, that word will be completed, possibly invoking +`@t{compset -q}' recursively. With this key it is possible to test the +types of quoted strings which are currently broken into parts in this +fashion. Its value contains one character for each quoting level. The +characters are a single quote or a double quote for strings quoted with +these characters, a dollars sign for strings quoted with +@t{$'}@var{...}@t{'} and a backslash for strings not starting with a +quote character. The first character in the value always corresponds to the +innermost quoting level. + +@vindex context, compstate +@item @t{context} +This will be set by the completion code to the overall context +in which completion is attempted. Possible values are: + +@noindent +@table @asis +@item @t{array_value} +when completing inside the value of an array parameter assignment; in +this case the @t{words} array contains the words inside the parentheses. + +@item @t{brace_parameter} +when completing the name of a parameter in a parameter expansion beginning +with @t{$@{}. This context will also be set when completing parameter +flags following @t{$@{(}; the full command line argument is presented +and the handler must test the value to be completed to ascertain that +this is the case. + +@item @t{assign_parameter} +when completing the name of a parameter in a parameter assignment. + +@item @t{command} +when completing for a normal command (either in command position or for +an argument of the command). + +@item @t{condition} +when completing inside a `@t{[[}...@t{]]}' conditional expression; in +this case the @t{words} array contains only the words inside the +conditional expression. + +@item @t{math} +when completing in a mathematical environment such as a +`@t{((}...@t{))}' construct. + +@item @t{parameter} +when completing the name of a parameter in a parameter expansion beginning +with @t{$} but not @t{$@{}. + +@item @t{redirect} +when completing after a redirection operator. + +@item @t{subscript} +when completing inside a parameter subscript. + +@item @t{value} +when completing the value of a parameter assignment. + +@end table + +@vindex exact, compstate +@item @t{exact} +Controls the behaviour when the @t{REC_EXACT} option is set. It will be +set to @t{accept} if an exact match would be accepted, and will be unset +otherwise. + +@noindent +If it was set when at least one match equal to the string on the line +was generated, the match is accepted. + +@vindex exact_string, compstate +@item @t{exact_string} +The string of an exact match if one was found, otherwise unset. + +@vindex ignored, compstate +@item @t{ignored} +The number of completions that were ignored because they matched one of the +patterns given with the @t{-F} option to the @t{compadd} builtin +command. + +@vindex insert, compstate +@item @t{insert} +This controls the manner in which a match is inserted into the command +line. On entry to the widget function, if it is unset the command line is +not to be changed; if set to @t{unambiguous}, any prefix common to all +matches is to be inserted; if set to @t{automenu-unambiguous}, the +common prefix is to be inserted and the next invocation of the +completion code may start menu completion (due to the @t{AUTO_MENU} +option being set); if set to @t{menu} or @t{automenu} menu completion +will be started for the matches currently generated (in the +latter case this will happen because the @t{AUTO_MENU} is set). The +value may also contain the string `@t{tab}' when the completion code +would normally not really do completion, but only insert the TAB +character. + +@noindent +On exit it may be set to any of the values above (where setting it to +the empty string is the same as unsetting it), or to a number, in which +case the match whose number is given will be inserted into the command line. +Negative numbers count backward from the last match (with `@t{-1}' +selecting the last match) and out-of-range values are wrapped +around, so that a value of zero selects the last match and a value +one more than the maximum selects the first. Unless the value of this +key ends in a space, the match is inserted as in a menu completion, +i.e. without automatically appending a space. + +@noindent +Both @t{menu} and @t{automenu} may also specify the number of the +match to insert, given after a colon. For example, `@t{menu:2}' says +to start menu completion, beginning with the second match. + +@noindent +Note that a value containing the substring `@t{tab}' makes the +matches generated be ignored and only the TAB be inserted. + +@noindent +Finally, it may also be set to @t{all}, which makes all matches +generated be inserted into the line. + +@vindex insert_positions, compstate +@item @t{insert_positions} +When the completion system inserts an unambiguous string into the +line, there may be multiple places where characters are missing or +where the character inserted differs from at least one match. The +value of this key contains a colon separated list of all these +positions, as indexes into the command line. + +@vindex last_prompt, compstate +@item @t{last_prompt} +If this is set to a non-empty string for every match added, the +completion code will move the cursor back to the previous prompt after +the list of completions has been displayed. Initially this is set or +unset according to the @t{ALWAYS_LAST_PROMPT} option. + +@vindex list, compstate +@item @t{list} +This controls whether or how the list of matches will be displayed. If it +is unset or empty they will never be listed; if its value begins with +@t{list}, they will always be listed; if it begins with @t{autolist} +or @t{ambiguous}, they will be listed when the @t{AUTO_LIST} or +@t{LIST_AMBIGUOUS} options respectively would normally cause them to +be. + +@noindent +If the substring @t{force} appears in the value, this makes the +list be shown even if there is only one match. Normally, the list +would be shown only if there are at least two matches. + +@noindent +The value contains the substring @t{packed} if the @t{LIST_PACKED} +option is set. If this substring is given for all matches added to a +group, this group will show the @t{LIST_PACKED} behavior. The same is +done for the @t{LIST_ROWS_FIRST} option with the substring @t{rows}. + +@noindent +Finally, if the value contains the string @t{explanations}, only the +explanation strings, if any, will be listed and if it contains +@t{messages}, only the messages (added with the @t{-x} option of +@t{compadd}) will be listed. If it contains both @t{explanations} and +@t{messages} both kinds of explanation strings will be listed. It +will be set appropriately on entry to a completion widget and may be +changed there. + +@vindex list_lines, compstate +@item @t{list_lines} +This gives the number of lines that are needed to display the full +list of completions. Note that to calculate the total number of lines +to display you need to add the number of lines needed for the command +line to this value, this is available as the value of the @t{BUFFERLINES} +special parameter. + +@vindex list_max, compstate +@item @t{list_max} +Initially this is set to the value of the @t{LISTMAX} parameter. +It may be set to any other value; when the widget exits this value +will be used in the same way as the value of @t{LISTMAX}. + +@vindex nmatches, compstate +@item @t{nmatches} +The number of matches added by the completion code so far. + +@vindex old_insert, compstate +@item @t{old_insert} +On entry to the widget this will be set to the number of the match of +an old list of completions that is currently inserted into the command +line. If no match has been inserted, this is unset. + +@noindent +As with @t{old_list}, the value of this key will only be used if it is the +string @t{keep}. If it was set to this value by the widget and there was an +old match inserted into the command line, this match will be kept and if +the value of the @t{insert} key specifies that another match should be +inserted, this will be inserted after the old one. + +@vindex old_list, compstate +@item @t{old_list} +This is set to @t{yes} if there is still a valid list of completions +from a previous completion at the time the widget is invoked. This will +usually be the case if and only if the previous editing operation was a +completion widget or one of the builtin completion functions. If there is a +valid list and it is also currently shown on the screen, the value of this +key is @t{shown}. + +@noindent +After the widget has exited the value of this key is only used if it +was set to @t{keep}. In this case the completion code will continue +to use this old list. If the widget generated new matches, they will +not be used. + +@vindex parameter, compstate +@item @t{parameter} +The name of the parameter when completing in a subscript or in the +value of a parameter assignment. + +@vindex pattern_insert, compstate +@item @t{pattern_insert} +Normally this is set to @t{menu}, which specifies that menu completion will +be used whenever a set of matches was generated using @t{pattern_match} +(see below). If +it is set to any other non-empty string by the user and menu completion is +not selected by other option settings, the code will instead insert any +common prefix for the generated matches as with normal completion. + +@vindex pattern_match, compstate +@item @t{pattern_match} +Locally controls the behaviour given by the @t{GLOB_COMPLETE} option. +Initially it is set to `@t{*}' if and only if the option is set. +The completion widget may set it to this value, to an empty string +(which has the same effect as unsetting it), or to any +other non-empty string. If it is non-empty, unquoted metacharacters on the +command line will be treated as patterns; if it is `@t{*}', then +additionally a wildcard `@t{*}' is assumed at the cursor position; if +it is empty or unset, metacharacters will be treated literally. + +@noindent +Note that the match specifications given to the @t{compadd} builtin +command are not used if this is set to a non-empty string. + +@vindex quote, compstate +@item @t{quote} +When completing inside quotes, this contains the quotation character +(i.e. either a single quote, a double quote, or a backtick). Otherwise it +is unset. + +@vindex quoting, compstate +@item @t{quoting} +When completing inside single quotes, this is set to the string +@t{single}; inside double quotes, the string +@t{double}; inside backticks, the string @t{backtick}. +Otherwise it is unset. + +@vindex redirect, compstate +@item @t{redirect} +The redirection operator when completing in a redirection position, +i.e. one of @t{<}, @t{>}, etc. + +@vindex restore, compstate +@item @t{restore} +This is set to @t{auto} before a function is entered, which forces the +special parameters mentioned above (@t{words}, @t{CURRENT}, @t{PREFIX}, +@t{IPREFIX}, @t{SUFFIX}, and @t{ISUFFIX}) to be restored to their +previous values when the function exits. If a function unsets it or +sets it to any other string, they will not be restored. + +@vindex to_end, compstate +@item @t{to_end} +Specifies the occasions on which the cursor is moved to the end of a string +when a match is inserted. On entry to a widget function, it may be +@t{single} if this will happen when a single unambiguous match was inserted +or @t{match} if it will happen any time a match is inserted (for example, +by menu completion; this is likely to be the effect of the @t{ALWAYS_TO_END} +option). + +@noindent +On exit, it may be set to @t{single} as above. It may also be set to +@t{always}, or to the empty string or unset; in those cases the cursor will +be moved to the end of the string always or never respectively. Any +other string is treated as @t{match}. + +@vindex unambiguous, compstate +@item @t{unambiguous} +This key is read-only and will always be set to the common (unambiguous) +prefix the completion code has generated for all matches added so far. + +@vindex unambiguous_cursor, compstate +@item @t{unambiguous_cursor} +This gives the position the cursor would be placed at if the +common prefix in the @t{unambiguous} key were inserted, relative to +the value of that key. The cursor would be placed before the character +whose index is given by this key. + +@vindex unambiguous_positions, compstate +@item @t{unambiguous_positions} +This contains all positions where characters in the unambiguous string +are missing or where the character inserted differs from at least one +of the matches. The positions are given as indexes into the string +given by the value of the @t{unambiguous} key. + +@vindex vared, compstate +@item @t{vared} +If completion is called while editing a line using the @t{vared} +builtin, the value of this key is set to the name of the parameter +given as an argument to @t{vared}. This key is only set while a @t{vared} +command is active. + +@end table + +@vindex words +@item @t{words} +This array contains the words present on the command line currently being +edited. + +@end table + +@noindent +@node Completion Builtin Commands, Completion Condition Codes, Completion Special Parameters, Completion Widgets + +@section Completion Builtin Commands +@noindent +@table @asis +@findex compadd +@cindex completion widgets, adding specified matches + +@item @t{compadd }[ @t{-akqQfenUl12C} ] [ @t{-F} @var{array} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-P} @var{prefix} ] [ @t{-S} @var{suffix} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-p} @var{hidden-prefix} ] [ @t{-s} @var{hidden-suffix} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-i} @var{ignored-prefix} ] [ @t{-I} @var{ignored-suffix} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-W} @var{file-prefix} ] [ @t{-d} @var{array} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-J} @var{group-name} ] [ @t{-X} @var{explanation} ] [ @t{-x} @var{message} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-V} @var{group-name} ] [ @t{-o} [ @var{order} ] ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-r} @var{remove-chars} ] [ @t{-R} @var{remove-func} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-D} @var{array} ] [ @t{-O} @var{array} ] [ @t{-A} @var{array} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-E} @var{number} ] +@itemx @t{@ @ @ @ @ @ @ @ }[@t{-M} @var{match-spec} ] [ @t{-}@t{-} ] [ @var{completions} ... ] + +@noindent +This builtin command can be used to add matches directly and control +all the information the completion code stores with each possible +completion. The return status is zero if at least one match was added and +non-zero if no matches were added. + +@noindent +The completion code breaks each match into seven fields in the order: + +@noindent +@quotation +@var{<ipre><apre><hpre><body><hsuf><asuf><isuf>} +@end quotation + +@noindent +The first field +is an ignored prefix taken from the command line, the contents of the +@t{IPREFIX} parameter plus the string given with the @t{-i} +option. With the @t{-U} option, only the string from the @t{-i} +option is used. The field @var{<apre>} is an optional prefix string +given with the @t{-P} option. The @var{<hpre>} field is a string +that is considered part of the match but that should not be shown when +listing completions, given with the @t{-p} option; for example, +functions that do filename generation might specify +a common path prefix this way. @var{<body>} is the part of the match that +should appear in the list of matches shown to the user. +The suffixes @var{<hsuf>}, +@var{<asuf>} and @var{<isuf>} correspond to the prefixes @var{<hpre>}, +@var{<apre>} and @var{<ipre>} and are given by the options @t{-s}, @t{-S} and +@t{-I}, respectively. + +@noindent +The supported flags are: + +@noindent +@table @asis +@item @t{-P} @var{prefix} +This gives a string to be inserted before each match. The +string given is not considered as part of the match and any shell +metacharacters in it will not be quoted when the string is inserted. + +@item @t{-S} @var{suffix} +Like @t{-P}, but gives a string to be inserted after each match. + +@item @t{-p} @var{hidden-prefix} +This gives a string that should be inserted before each +match but that should not appear in the list of matches. Unless the +@t{-U} option is given, this string must be matched as part of the string +on the command line. + +@item @t{-s} @var{hidden-suffix} +Like `@t{-p}', but gives a string to insert after each match. + +@item @t{-i} @var{ignored-prefix} +This gives a string to insert just before any +string given with the `@t{-P}' option. Without `@t{-P}' the string is +inserted before the string given with `@t{-p}' or directly before each +match. + +@item @t{-I} @var{ignored-suffix} +Like @t{-i}, but gives an ignored suffix. + +@item @t{-a} +With this flag the @var{completions} are taken as names of arrays and the +actual completions are their values. If only some elements of the +arrays are needed, the @var{completions} may also contain subscripts, as in +`@t{foo[2,-1]}'. + +@item @t{-k} +With this flag the @var{completions} are taken as names of associative arrays +and the actual completions are their keys. As for @t{-a}, the +@var{words} may also contain subscripts, as in `@t{foo[(R)*bar*]}'. + +@item @t{-d} @var{array} +This adds per-completion display strings. The @var{array} should contain one +element per @var{completion} given. The completion code will then display the +first element instead of the first @var{completion}, and so on. The +@var{array} may be given as the name of an array parameter or directly +as a space-separated list of words in parentheses. + +@noindent +If there are fewer display strings than @var{completions}, the leftover +@var{completions} will be displayed unchanged and if there are more display +strings than @var{completions}, the leftover display strings will be silently +ignored. + +@item @t{-l} +This option only has an effect if used together with the @t{-d} +option. If it is given, the display strings are listed one per line, +not arrayed in columns. + +@item @t{-o} [ @var{order} ] +This controls the order in which matches are sorted. @var{order} is a +comma-separated list comprising the following possible values. These values +can be abbreviated to their initial two or three characters. Note that the +order forms part of the group name space so matches with different orderings +will not be in the same group. + +@noindent +@table @asis +@item @t{match} +If given, the order of the output is determined by the match strings; +otherwise it is determined by the display strings (i.e. the strings given +by the @t{-d} option). This is the default if `@t{-o}' is specified but +the @var{order} argument is omitted. + +@item @t{nosort} +This specifies that the @var{completions} +are pre-sorted and their order should be +preserved. This value only makes sense alone and cannot be combined with any +others. + +@item @t{numeric} +If the matches include numbers, sort them numerically rather than +lexicographically. + +@item @t{reverse} +Arrange the matches backwards by reversing the sort ordering. + +@end table + +@item @t{-J} @var{group-name} +Gives the name of the group that the matches should be stored in. + +@item @t{-V} @var{group-name} +Like @t{-J} but naming an unsorted group. This option is identical to +the combination of @t{-J} and @t{-o nosort}. + +@item @t{-1} +If given together with the @t{-V} option, makes +only consecutive duplicates in the group be removed. If combined with +the @t{-J} option, this has no visible effect. Note that groups +with and without this flag are in different name spaces. + +@item @t{-2} +If given together with the @t{-J} or @t{-V} option, makes all +duplicates be kept. Again, groups with and without this flag are in +different name spaces. + +@item @t{-X} @var{explanation} +The @var{explanation} string will be printed with the list of matches, +above the group currently selected. + +@noindent +Within the @var{explanation}, the following sequences may be used to +specify output attributes +(see @ref{Prompt Expansion}): +`@t{%B}', `@t{%S}', `@t{%U}', `@t{%F}', `@t{%K}' and their lower case +counterparts, as well as `@t{%@{}...@t{%@}}'. `@t{%F}', `@t{%K}' and +`@t{%@{}...@t{%@}}' take arguments in the same form as prompt +expansion. (Note that the sequence `@t{%G}' is not available; an +argument to `@t{%@{}' should be used instead.) The sequence `@t{%%}' +produces a literal `@t{%}'. + +@noindent +These sequences are most often employed by users when customising the +@t{format} style +(see +@ref{Completion System}), +but they must also be taken into account when writing completion +functions, as passing descriptions with unescaped `@t{%}' characters +to utility functions such as @t{_arguments} and @t{_message} may +produce unexpected results. If arbitrary text is to be passed in a +description, it can be escaped using e.g. @t{$@{my_str//\%/%%@}}. + +@item @t{-x} @var{message} +Like @t{-X}, but the @var{message} will be printed even if there are no +matches in the group. + +@item @t{-q} +The suffix given with @t{-S} will be automatically removed if +the next character typed is a blank or does not insert anything, or if +the suffix consists of only one character and the next character typed +is the same character. + +@item @t{-r} @var{remove-chars} +This is a more versatile form of the @t{-q} option. +The suffix given with @t{-S} or the slash automatically added after +completing directories will be automatically removed if +the next character typed inserts one of the characters given in the +@var{remove-chars}. This string is parsed as a characters class and +understands the backslash sequences used by the @t{print} command. For +example, `@t{-r "a-z\t"}' removes the suffix if the next character typed +inserts a lower case character or a TAB, and `@t{-r "^0-9"}' removes the +suffix if the next character typed inserts anything but a digit. One extra +backslash sequence is understood in this string: `@t{\-}' stands for +all characters that insert nothing. Thus `@t{-S "=" -q}' is the same +as `@t{-S "=" -r "= \t\n\-"}'. + +@noindent +This option may also be used without the @t{-S} option; then any +automatically added space will be removed when one of the characters in the +list is typed. + +@item @t{-R} @var{remove-func} +This is another form of the @t{-r} option. When a match +has been accepted and a suffix has been inserted, the function +@var{remove-func} will be called after the next character typed. It is +passed the length of the suffix as an argument and can use the special +parameters available in ordinary (non-completion) zle widgets (see +@ref{Zsh Line Editor}) to analyse and modify the command line. + +@item @t{-f} +If this flag is given, all of the matches built from the @var{completions} are +marked as being the names of files. They are not required to be actual +filenames, but if they are, and the option @t{LIST_TYPES} is set, the +characters describing the types of the files in the completion lists will +be shown. This also forces a slash to be added when the name of a +directory is completed. + +@item @t{-e} +This flag can be used to tell the completion code that the matches +added are parameter names for a parameter expansion. This will make +the @t{AUTO_PARAM_SLASH} and @t{AUTO_PARAM_KEYS} options be used for +the matches. + +@item @t{-W} @var{file-prefix} +This string is a pathname that will be prepended to each match together +with any prefix specified by the @t{-p} option to form a complete filename +for testing. Hence it is only useful if combined with the @t{-f} flag, as +the tests will not otherwise be performed. + +@item @t{-F} @var{array} +Specifies an array containing patterns. @var{completions} that match one of +these patterns are ignored, that is, not considered to be matches. + +@noindent +The @var{array} may be the name of an array parameter or a list of +literal patterns enclosed in parentheses and quoted, as in `@t{-F "(*?.o +*?.h)"}'. If the name of an array is given, the elements of the array are +taken as the patterns. + +@item @t{-Q} +This flag instructs the completion +code not to quote any metacharacters in the matches when inserting them +into the command line. + +@item @t{-M} @var{match-spec} +This gives local match specifications as described below in +@ref{Completion Matching Control}. This option may be given more than once. +In this case all @var{match-spec}s given are concatenated with spaces +between them to form the specification string to use. +Note that they will only be used if the @t{-U} option is not given. + +@item @t{-n} +Specifies that matching @var{completions} are to be added to the set of +matches, but are not to be listed to the user. + +@item @t{-U} +If this flag is given, all @var{completions} are added +to the set of matches and no matching +will be done by the completion code. Normally this is used in +functions that do the matching themselves. + +@item @t{-O} @var{array} +If this option is given, the @var{completions} are @emph{not} added to the set of +matches. Instead, matching is done as usual and all of the +@var{completions} that match +will be stored in the array parameter whose name is given as @var{array}. + +@item @t{-A} @var{array} +As the @t{-O} option, except that instead of those of the @var{completions} +which +match being stored in @var{array}, the strings generated internally by the +completion code are stored. For example, +with a match specification of `@t{-M "L:|no="}', a current word of `@t{nof}' +and @var{completions} of `@t{foo}', this +option stores the string `@t{nofoo}' in the array, whereas the @t{-O} +option stores the `@t{foo}' originally given. + +@item @t{-D} @var{array} +As with @t{-O}, the @var{completions} are not added to the set of matches. +Instead, whenever the @var{n}th @var{completion} does not +match, the @var{n}th element of the @var{array} is removed. Elements +for which the corresponding @var{completion} matches are retained. +This option can be used more than once to remove elements from multiple +arrays. + +@item @t{-C} +This option adds a special match which expands to all other matches +when inserted into the line, even those that are added after this +option is used. Together with the @t{-d} option it is possible to +specify a string that should be displayed in the list for this special +match. If no string is given, it will be shown as a string containing +the strings that would be inserted for the other matches, truncated to +the width of the screen. + +@item @t{-E} @var{number} +This option adds @var{number} empty matches after matching @var{completions} have +been added. An empty match takes up space in completion listings but +will never be inserted in the line and can't be selected with menu +completion or menu selection. This makes empty matches only useful to +format completion lists and to make explanatory string be shown in +completion lists (since empty matches can be given display strings +with the @t{-d} option). And because all but one empty string would +otherwise be removed, this option implies the @t{-V} and @t{-2} +options (even if an explicit @t{-J} option is given). This can be +important to note as it affects the name space into which matches are +added. + +@item @t{-} +@itemx @t{-}@t{-} +This flag ends the list of flags and options. All arguments after it +will be taken as the @var{completions} even if they begin with +hyphens. + +@end table + +@noindent +Except for the @t{-M} flag, if any of these flags is given more than +once, the first one (and its argument) will be used. + +@findex compset +@cindex completion widgets, modifying special parameters +@item @t{compset -p} @var{number} +@itemx @t{compset -P} [ @var{number} ] @var{pattern} +@itemx @t{compset -s} @var{number} +@itemx @t{compset -S} [ @var{number} ] @var{pattern} +@itemx @t{compset -n} @var{begin} [ @var{end} ] +@itemx @t{compset -N} @var{beg-pat} [ @var{end-pat} ] +@itemx @t{compset -q} +This command simplifies modification of the special parameters, +while its return status allows tests on them to be carried out. + +@noindent +The options are: + +@noindent +@table @asis +@item @t{-p} @var{number} +If the value of the @t{PREFIX} parameter is at least @var{number} +characters long, the first @var{number} characters are removed from it and +appended to the contents of the @t{IPREFIX} parameter. + +@item @t{-P} [ @var{number} ] @var{pattern} +If the value of the @t{PREFIX} parameter begins with anything that +matches the @var{pattern}, the matched portion is removed from +@t{PREFIX} and appended to @t{IPREFIX}. + +@noindent +Without the optional @var{number}, the longest match is taken, but +if @var{number} is given, anything up to the @var{number}th match is +moved. If the @var{number} is negative, the @var{number}th longest +match is moved. For example, if @t{PREFIX} contains the string +`@t{a=b=c}', then @t{compset -P '*\='} will move the string `@t{a=b=}' +into the @t{IPREFIX} parameter, but @t{compset -P 1 '*\='} will move only +the string `@t{a=}'. + +@item @t{-s} @var{number} +As @t{-p}, but transfer the last @var{number} characters from the +value of @t{SUFFIX} to the front of the value of @t{ISUFFIX}. + +@item @t{-S} [ @var{number} ] @var{pattern} +As @t{-P}, but match the last portion of @t{SUFFIX} and transfer the +matched portion to the front of the value of @t{ISUFFIX}. + +@item @t{-n} @var{begin} [ @var{end} ] +If the current word position as specified by the parameter @t{CURRENT} +is greater than or equal to @var{begin}, anything up to the +@var{begin}th word is removed from the @t{words} array and the value +of the parameter @t{CURRENT} is decremented by @var{begin}. + +@noindent +If the optional @var{end} is given, the modification is done only if +the current word position is also less than or equal to @var{end}. In +this case, the words from position @var{end} onwards are also removed from +the @t{words} array. + +@noindent +Both @var{begin} and @var{end} may be negative to count backwards +from the last element of the @t{words} array. + +@item @t{-N} @var{beg-pat} [ @var{end-pat} ] +If one of the elements of the @t{words} array before the one at the +index given by the value of the parameter @t{CURRENT} matches the +pattern @var{beg-pat}, all elements up to and including the matching one are +removed from the @t{words} array and the value of @t{CURRENT} is changed to +point to the same word in the changed array. + +@noindent +If the optional pattern @var{end-pat} is also given, and there is an +element in the @t{words} array matching this pattern, the parameters +are modified only if the index of this word is higher than the one +given by the @t{CURRENT} parameter (so that the matching word has +to be after the cursor). In this case, the words starting with the one +matching @t{end-pat} are also removed from the @t{words} +array. If @t{words} contains no word matching @var{end-pat}, the +testing and modification is performed as if it were not given. + +@item @t{-q} +The word +currently being completed is split on spaces into separate words, +respecting the usual shell quoting conventions. The +resulting words are stored in the @t{words} array, and @t{CURRENT}, +@t{PREFIX}, @t{SUFFIX}, @t{QIPREFIX}, and @t{QISUFFIX} are modified to +reflect the word part that is completed. + +@end table + +@noindent +In all the above cases the return status is zero if the test succeeded +and the parameters were modified and non-zero otherwise. This allows +one to use this builtin in tests such as: + +@noindent +@example +if compset -P '*\='; then ... +@end example + +@noindent +This forces anything up to and including the last equal sign to be +ignored by the completion code. + +@item @t{compcall} [ @t{-TD} ] +This allows the use of completions defined with the @t{compctl} builtin +from within completion widgets. The list of matches will be generated as +if one of the non-widget completion functions (@t{complete-word}, etc.) +had been called, except that only @t{compctl}s given for specific commands +are used. To force the code to try completions defined with the @t{-T} +option of @t{compctl} and/or the default completion (whether defined by +@t{compctl -D} or the builtin default) in the appropriate places, the +@t{-T} and/or @t{-D} flags can be passed to @t{compcall}. + +@noindent +The return status can be used to test if a matching @t{compctl} +definition was found. It is non-zero if a @t{compctl} was found and +zero otherwise. + +@noindent +Note that this builtin is defined by the @t{zsh/compctl} module. + +@end table + +@noindent +@node Completion Condition Codes, Completion Matching Control, Completion Builtin Commands, Completion Widgets + +@section Completion Condition Codes +@noindent +@cindex completion widgets, condition codes + +@noindent +The following additional condition codes for use within the @t{[[} @var{...} @t{]]} +construct are available in completion widgets. These work on the special +parameters. All of these tests can also be performed by the @t{compset} +builtin, but in the case of the condition codes the contents of the special +parameters are not modified. + +@noindent +@table @asis +@item @t{-prefix} [ @var{number} ] @var{pattern} +true if the test for the @t{-P} option of @t{compset} would succeed. + +@item @t{-suffix} [ @var{number} ] @var{pattern} +true if the test for the @t{-S} option of @t{compset} would succeed. + +@item @t{-after} @var{beg-pat} +true if the test of the @t{-N} option with only the @var{beg-pat} given +would succeed. + +@item @t{-between} @var{beg-pat end-pat} +true if the test for the @t{-N} option with both patterns would succeed. + +@end table + +@noindent +@node Completion Matching Control, Completion Widget Example, Completion Condition Codes, Completion Widgets + +@section Completion Matching Control +@noindent + +@noindent +When the user invokes completion, the current @emph{word} on the command line +(that is, the word the cursor is currently on) is used to generate a @emph{match +pattern}. Only those @emph{completions} that match the pattern are offered to the +user as @emph{matches}. + +@noindent +The default match pattern is generated from the current word by either + +@noindent +@itemize @bullet + +@item +appending a `@t{*}' (matching any number of characters in a completion) +@emph{or,} +@item +if the shell option @t{COMPLETE_IN_WORD} is set, inserting a `@t{*}' at the +cursor position. +@end itemize + +@noindent +This narrow pattern can be broadened selectively by passing a @emph{match +specification} to the @t{compadd} builtin command through its @t{-M} option +(see +@ref{Completion Builtin Commands}). A match specification consists of one or more @var{matchers} separated by +whitespace. Matchers in a match specification are applied one at a time, from +left to right. Once all matchers have been applied, completions are compared +to the final match pattern and non-matching ones are discarded. + +@noindent +@itemize @bullet + +@item +Note that the @t{-M} option is ignored if the current word contains a glob +pattern and the shell option @t{GLOB_COMPLETE} is set or if the +@t{pattern_match} key of the special associative array @t{compstate} is set to +a non-empty value (see +@ref{Completion Special Parameters}). +@item +Users of the @ref{Completion System} should generally not use the @t{-M} option directly, but rather use the +@t{matcher-list} and @t{matcher} styles (see the subsection @emph{Standard Styles} +in +@ref{Completion System Configuration}). +@end itemize + +@noindent +Each matcher consists of + +@noindent +@itemize @bullet + +@item +a case-sensitive letter +@item +a `@t{:}', +@item +one or more patterns separated by pipes (`@t{|}'), +@item +an equals sign (`@t{=}'), and +@item +another pattern. +@end itemize + +@noindent +The patterns before the `@t{=}' are used to match substrings of the current +word. For each matched substring, the corresponding part of the match pattern +is broadened with the pattern after the `@t{=}', by means of a logical @t{OR}. + +@noindent +Each pattern in a matcher cosists of either + +@noindent +@itemize @bullet + +@item +the empty string or +@item +a sequence of + +@noindent +@itemize @bullet + +@item +literal characters (which may be quoted with a `@t{\}'), +@item +question marks (`@t{?}'), +@item +bracket expressions (`@t{[...]}'; see the subsection @emph{Glob Operators} in +@ref{Filename Generation}), and/or +@item +brace expressions (see below). +@end itemize + +@end itemize + +@noindent +Other shell patterns are not allowed. + +@noindent +A brace expression, like a bracket expression, consists of a list of + +@noindent +@itemize @bullet + +@item +literal characters, +@item +ranges (`@t{0-9}'), and/or +@item +character classes (`@t{[:}@var{name}@t{:]}'). +@end itemize + +@noindent +However, they differ from each other as follows: + +@noindent +@itemize @bullet + +@item +A brace expression is delimited by a pair of braces (`@t{@{...@}}'). +@item +Brace expressions do not support negations. That is, an initial +`@t{!}' or `@t{^}' has no special meaning and will be interpreted as a literal +character. +@item +When a character in the current word matches the @var{n}th pattern in a brace +expression, the corresponding part of the match pattern is broadened only with +the @var{n}th pattern of the brace expression on the other side of the `@t{=}', +if there is one; if there is no brace expression on the other side, then this +pattern is the empty string. However, if either brace expression has more +elements than the other, then the excess entries are simply ignored. When +comparing indexes, each literal character or character class counts as one +element, but each range is instead expanded to the full list of literal +characters it represents. Additionally, if on @emph{both} sides of the +`@t{=}', the @var{n}th pattern is `@t{[:upper:]}' or `@t{[:lower:]}', then these +are expanded as ranges, too. +@end itemize + +@noindent +Note that, although the matching system does not yet handle multibyte +characters, this is likely to be a future extension. Hence, using +`@t{[:upper:]}' and `@t{[:lower:]}' is recommended over +`@t{A-Z}' and `@t{a-z}'. + +@noindent +Below are the different forms of matchers supported. Each @emph{uppercase} form +behaves exactly like its lowercase counterpart, but adds an additional step +@emph{after} the match pattern has filtered out non-matching completions: Each of +a match's substrings that was matched by a subpattern from an uppercase matcher +is replaced with the corresponding substring of the current word. However, +patterns from @emph{lowercase} matchers have higher weight: If a substring of the +current word was matched by patterns from both a lowercase and an uppercase +matcher, then the lowercase matcher's pattern wins and the corresponding part +of the match is not modified. + +@noindent +Unless indicated otherwise, each example listed assumes @t{COMPLETE_IN_WORD} to +be unset (as it is by default). + +@noindent +@table @asis +@item @t{m:}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{M:}@var{word-pat}@t{=}@var{match-pat} + +@noindent +For each substring of the current word that matches @var{word-pat}, broaden the +corresponding part of the match pattern to additionally match @var{match-pat}. + +@noindent +@table @asis +@item Examples: + +@noindent +@t{m:@{[:lower:]@}=@{[:upper:]@}} lets any lower case character in the current word +be completed to itself or its uppercase counterpart. So, the completions +`@t{foo}', `@t{FOO}' and `@t{Foo}' will are be considered matches for the word +`@t{fo}'. + +@noindent +@t{M:_=} inserts every underscore from the current word into each match, in the +same relative position, determined by matching the substrings around it. So, +given a completion `@t{foo}', the word `@t{f_o}' will be completed to the match +`@t{f_oo}', even though the latter was not present as a completion. + +@end table + +@item @t{b:}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{B:}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{e:}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{E:}@var{word-pat}@t{=}@var{match-pat} + +@noindent +For each consecutive substring at the @t{b:}eginning or @t{e:}nd of the current +word that matches @var{word-pat}, broaden the corresponding part of the match +pattern to additionally match @var{match-pat}. + +@noindent +@table @asis +@item Examples: + +@noindent +`@t{b:-=+}' lets any number of minuses at the start of the current word be +completed to a minus or a plus. + +@noindent +`@t{B:0=}' adds all zeroes at the beginning of the current word to the +beginning of each match. + +@end table + +@item @t{l:}@t{|}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{L:}@t{|}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{R:}@var{word-pat}@t{|}@t{=}@var{match-pat} +@itemx @t{r:}@var{word-pat}@t{|}@t{=}@var{match-pat} + +@noindent +If there is a substring at the @t{l:}eft or @t{r:}ight edge of the current word +that matches @var{word-pat}, then broaden the corresponding part of the match +pattern to additionally match @var{match-pat}. + +@noindent +For each @t{l:}, @t{L:}, @t{r:} and @t{R:} matcher (including the ones below), +the pattern @var{match-pat} may also be a `@t{*}'. This matches any number of +characters in a completion. + +@noindent +@table @asis +@item Examples: + +@noindent +`@t{r:|=*}' appends a `@t{*}' to the match pattern, even when +@t{COMPLETE_IN_WORD} is set and the cursor is not at the end of the current +word. + +@noindent +If the current word starts with a minus, then `@t{L:|-=}' will prepend it to +each match. + +@end table + +@item @t{l:}@var{anchor}@t{|}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{L:}@var{anchor}@t{|}@var{word-pat}@t{=}@var{match-pat} +@itemx @t{r:}@var{word-pat}@t{|}@var{anchor}@t{=}@var{match-pat} +@itemx @t{R:}@var{word-pat}@t{|}@var{anchor}@t{=}@var{match-pat} + +@noindent +For each substring of the current word that matches @var{word-pat} and has on +its @t{l:}eft or @t{r:}ight another substring matching @var{anchor}, broaden the +corresponding part of the match pattern to additionally match @var{match-pat}. + +@noindent +Note that these matchers (and the ones below) modify only what is matched by +@var{word-pat}; they do not change the matching behavior of what is matched by +@var{anchor} (or @var{coanchor}; see the matchers below). Thus, unless its +corresponding part of the match pattern has been modified, the anchor in the +current word has to match literally in each completion, just like any other +substring of the current word. + +@noindent +If a matcher includes at least one anchor (which includes the matchers with two +anchors, below), then @var{match-pat} may also be `@t{*}' or `@t{**}'. `@t{*}' +can match any part of a completion that does not contain any substrings +matching @var{anchor}, whereas a `@t{**}' can match any part of a completion, +period. (Note that this is different from the behavior of `@t{*}' in the +anchorless forms of `@t{l:}' and `@t{r:}' and and also different from `@t{*}' +and `@t{**}' in glob expressions.) + +@noindent +@table @asis +@item Examples: + +@noindent +`@t{r:|.=*}' makes the completion `@t{comp.sources.unix}' a match for the word +`@t{..u}' --- but @emph{not} for the word `@t{.u}'. + +@noindent +Given a completion `@t{-}@t{-foo}', the matcher `@t{L:--|no-=}' will complete +the word `@t{-}@t{-no-}' to the match `@t{-}@t{-no-foo}'. + +@end table + +@item @t{l:}@var{anchor}@t{||}@var{coanchor}@t{=}@var{match-pat} +@itemx @t{L:}@var{anchor}@t{||}@var{coanchor}@t{=}@var{match-pat} +@itemx @t{r:}@var{coanchor}@t{||}@var{anchor}@t{=}@var{match-pat} +@itemx @t{R:}@var{coanchor}@t{||}@var{anchor}@t{=}@var{match-pat} + +@noindent +For any two consecutive substrings of the current word that match @var{anchor} +and @var{coanchor}, in the order given, insert the pattern @var{match-pat} +between their corresponding parts in the match pattern. + +@noindent +Note that, unlike @var{anchor}, the pattern @var{coanchor} does not change what +`@t{*}' can match. + +@noindent +@table @asis +@item Examples: + +@noindent +`@t{r:?||[[:upper:]]=*}' will complete the current word `@t{fB}' to +`@t{fooBar}', but it will not complete it to `@t{fooHooBar}' (because `@t{*}' +here cannot match anything that includes a match for `@t{[[:upper:]]}), nor +will it complete `@t{B}' to `@t{fooBar}' (because there is no character in the +current word to match @var{coanchor}). + +@noindent +Given the current word `@t{pass.n}' and a completion `@t{pass.byname}', the +matcher `@t{L:.||[[:alpha:]]=by}' will produce the match `@t{pass.name}'. + +@end table + +@item @t{x:} + +@noindent +Ignore this matcher and all matchers to its right. + +@noindent +This matcher is used to mark the end of a match specification. In a single +standalone list of matchers, this has no use, but where match specifications +are concatenated, as is often the case when using the +@ref{Completion System}, it can allow one match specification to override another. + +@end table + +@noindent +@node Completion Widget Example, , Completion Matching Control, Completion Widgets + +@section Completion Widget Example +@noindent +@cindex completion widgets, example + +@noindent +The first step is to define the widget: + +@noindent +@example +zle -C complete complete-word complete-files +@end example + +@noindent +Then the widget can be bound to a key using the @t{bindkey} builtin +command: + +@noindent +@example +bindkey '^X\t' complete +@end example + +@noindent +After that the shell function @t{complete-files} will be invoked +after typing control-X and TAB. The function should then generate the +matches, e.g.: + +@noindent +@example +complete-files () @{ compadd - * @} +@end example + +@noindent +This function will complete files in the current directory matching the +current word. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/compsys.yo +@node Completion System, Completion Using compctl, Completion Widgets, Top + +@chapter Completion System +@noindent +@cindex completion system +@cindex completion, programmable +@cindex completion, controlling + +@section Description +@noindent + +@noindent +This describes the shell code for the `new' completion system, referred +to as @t{compsys}. It is written in shell functions based on the +features described in +the previous chapter, @ref{Completion Widgets}. + +@noindent +The features are contextual, sensitive to the point at which completion is +started. Many completions are already provided. +For this reason, a user can perform a great many tasks without +knowing any details beyond how to initialize the system, which is +described +in @ref{Initialization}. + +@noindent +The context that decides what completion is to be performed may be +@itemize @bullet + +@item +an argument or option position: these describe the position on the +command line at which completion is requested. For example `first argument +to rmdir, the word being completed names a directory'; + +@item +a special context, denoting an element in the shell's syntax. For example +`a word in command position' or `an array subscript'. + +@end itemize + +@noindent +A full context specification contains other elements, as we shall describe. + +@noindent +Besides commands names and contexts, the system employs two more +concepts, @emph{styles} and @emph{tags}. These provide ways for the user +to configure the system's behaviour. + +@noindent +Tags play a dual role. They serve as a classification system for +the matches, typically indicating a class of object that the user +may need to distinguish. For example, when completing arguments of the +@t{ls} command the user may prefer to try @t{files} before @t{directories}, +so both of these are tags. They also appear as the rightmost +element in a context specification. + +@noindent +Styles modify various operations of the completion system, such as +output formatting, but also what kinds of completers are used (and in +what order), or which tags are examined. Styles may accept arguments +and are manipulated using the @t{zstyle} command described in +@ref{The zsh/zutil Module}. + +@noindent +In summary, tags describe @emph{what} the completion objects are, and style +@t{how} they are to be completed. At various points of execution, the +completion system checks what styles and/or tags are defined for the +current context, and uses that to modify its behavior. The full +description of context handling, which determines how tags and other +elements of the context influence the behaviour of styles, is described +in @ref{Completion System Configuration}. + +@noindent +When a completion is requested, a dispatcher function is called; +see the description of @t{_main_complete} in the list of control functions +below. This dispatcher decides which function should +be called to produce the completions, and calls it. The result is +passed to one or more @emph{completers}, functions that implement +individual completion strategies: simple completion, error correction, +completion with error correction, menu selection, etc. + +@noindent +More generally, the shell functions contained in the completion system are +of two types: +@itemize @bullet + +@item +those beginning `@t{comp}' are to be called directly; there are only +a few of these; + +@item +those beginning `@t{_}' are called by the +completion code. The shell functions of this set, which implement +completion behaviour and may be bound to keystrokes, are referred to +as `widgets'. These proliferate as new completions are required. + +@end itemize + +@noindent +@menu +* Initialization:: +* Completion System Configuration:: +* Control Functions:: +* Bindable Commands:: +* Completion Functions:: +* Completion Directories:: +* Completion System Variables:: +@end menu + +@noindent +@node Initialization, Completion System Configuration, , Completion System + +@section Initialization +@noindent +@findex compinstall +@cindex completion system, installing + +@noindent +If the system was installed completely, it should be enough to +call the shell function @t{compinit} from your initialization file; see the +next section. However, the function @t{compinstall} can be run by a user +to configure various aspects of the completion system. + +@noindent +Usually, @t{compinstall} will insert code into @t{.zshrc}, although if +that is not writable it will save it in another file and tell you that +file's location. Note that it is up to you to make sure that the lines +added to @t{.zshrc} are actually run; you may, for example, need to move +them to an earlier place in the file if @t{.zshrc} usually returns early. +So long as you keep them all together (including the comment lines at the +start and finish), you can rerun @t{compinstall} and it will correctly +locate and modify these lines. Note, however, that any code you add to +this section by hand is likely to be lost if you rerun @t{compinstall}, +although lines using the command `@t{zstyle}' should be gracefully handled. + +@noindent +The new code will take effect next time you start the shell, or run +@t{.zshrc} by hand; there is also an option to make them take effect +immediately. However, if @t{compinstall} has removed definitions, you will +need to restart the shell to see the changes. + +@noindent +To run @t{compinstall} you will need to make sure it is in a directory +mentioned in your @t{fpath} parameter, which should already be the case if +zsh was properly configured as long as your startup files do not remove the +appropriate directories from @t{fpath}. Then it must be autoloaded +(`@t{autoload -U compinstall}' is recommended). You can abort the +installation any time you are being prompted for information, and your +@t{.zshrc} will not be altered at all; changes only take place right at the +end, where you are specifically asked for confirmation. + +@noindent + +@subsection Use of compinit +@noindent +@findex compinit +@cindex completion system, initializing + +@noindent +This section describes the use of @t{compinit} to initialize completion for +the current session when called directly; if you have run +@t{compinstall} it will be called automatically from your @t{.zshrc}. + +@noindent +To initialize the system, the function @t{compinit} should be in a +directory mentioned in the @t{fpath} parameter, and should be autoloaded +(`@t{autoload -U compinit}' is recommended), and then run simply as +`@t{compinit}'. This will define a +few utility functions, arrange for all the necessary shell functions to be +autoloaded, and will then re-define all widgets that do completion to use the +new system. If you use the @t{menu-select} widget, which is part of the +@t{zsh/complist} module, you should make sure that that module is loaded +before the call to @t{compinit} so that that widget is also +re-defined. If completion styles (see below) are set up to perform +expansion as well as completion by default, and the TAB key is bound to +@t{expand-or-complete}, @t{compinit} will rebind it to @t{complete-word}; +this is necessary to use the correct form of expansion. + +@noindent +Should you need to use the original completion commands, you can still +bind keys to the old widgets by putting a `@t{.}' in front of the +widget name, e.g. `@t{.expand-or-complete}'. + +@noindent +To speed up the running of @t{compinit}, it can be made to produce a dumped +configuration that will be read in on future invocations; this is the +default, but can be turned off by calling @t{compinit} with the +option @t{-D}. The dumped file is @t{.zcompdump} in the same +directory as the startup files (i.e. @t{$ZDOTDIR} or @t{$HOME}); +alternatively, an explicit file name can be given by `@t{compinit -d} +@var{dumpfile}'. The next invocation of @t{compinit} will read the dumped +file instead of performing a full initialization. + +@noindent +If the number of completion files changes, @t{compinit} will recognise this +and produce a new dump file. However, if the name of a function or the +arguments in the first line of a @t{#compdef} function (as described below) +change, it is easiest to delete the dump file by hand so that +@t{compinit} will re-create it the next time it is run. The check +performed to see if there are new functions can be omitted by giving +the option @t{-C}. In this case the dump file will only be created if +there isn't one already. + +@noindent +The dumping is actually done by another function, @t{compdump}, but you +will only need to run this yourself if you change the configuration +(e.g. using @t{compdef}) and then want to dump the new one. The name of +the old dumped file will be remembered for this purpose. + +@noindent +If the parameter @t{_compdir} is set, @t{compinit} uses it as a directory +where completion functions can be found; this is only necessary if they are +not already in the function search path. + +@noindent +For security reasons @t{compinit} also checks if the completion system +would use files not owned by root or by the current user, or files in +directories that are world- or group-writable or that are not owned by +root or by the current user. If such files or directories are found, +@t{compinit} will ask if the completion system should really be used. To +avoid these tests and make all files found be used without asking, use the +option @t{-u}, and to make @t{compinit} silently ignore all insecure files +and directories use the option @t{-i}. This security check is skipped +entirely when the @t{-C} option is given, provided the dumpfile exists. + +@noindent +@findex compaudit +The security check can be retried at any time by running the function +@t{compaudit}. This is the same check used by @t{compinit}, but when it +is executed directly any changes to @t{fpath} are made local to the +function so they do not persist. The directories to be checked may be +passed as arguments; if none are given, @t{compaudit} uses @t{fpath} and +@t{_compdir} to find completion system directories, adding missing ones +to @t{fpath} as necessary. To force a check of exactly the directories +currently named in @t{fpath}, set @t{_compdir} to an empty string before +calling @t{compaudit} or @t{compinit}. + +@noindent +@findex bashcompinit +The function @t{bashcompinit} provides compatibility with bash's programmable +completion system. When run it will define the functions, @t{compgen} and +@t{complete} which correspond to the bash builtins with the same names. +It will then be possible to use completion specifications and functions +written for bash. + +@noindent + +@subsection Autoloaded files +@noindent +@cindex completion system, autoloaded functions + +@noindent +The convention for autoloaded functions used in completion is that they +start with an underscore; as already mentioned, the @t{fpath/FPATH} +parameter must contain the directory in which they are stored. If @t{zsh} +was properly installed on your system, then @t{fpath/FPATH} automatically +contains the required directories for the standard functions. + +@noindent +For incomplete installations, if @t{compinit} does not find enough files +beginning with an underscore (fewer than twenty) in the search path, it +will try to find more by adding the directory @t{_compdir} to the search +path. If that directory has a subdirectory named @t{Base}, all +subdirectories will be added to the path. Furthermore, if the subdirectory +@t{Base} has a subdirectory named @t{Core}, @t{compinit} will add all +subdirectories of the subdirectories to the path: this allows +the functions to be in the same format as in the @t{zsh} source +distribution. + +@noindent +@cindex compdef, use of by compinit +When @t{compinit} is run, it searches all such files accessible via +@t{fpath/FPATH} and reads the first line of each of them. This line should +contain one of the tags described below. Files whose first line does not +start with one of these tags are not considered to be part of the +completion system and will not be treated specially. + +@noindent +The tags are: + +@noindent +@table @asis +@item @t{#compdef} @var{name} ... [ @t{-}@{@t{p}|@t{P}@} @var{pattern} ... [ @t{-N} @var{name} ... ] ] +The file will be made autoloadable and the function defined +in it will be called when completing @var{name}s, each of which is +either the name of a command whose arguments are to be completed or one of +a number of special contexts in the form @t{-}@var{context}@t{-} described +below. + +@noindent +Each @var{name} may also be of the form `@var{cmd}@t{=}@var{service}'. +When completing the command @var{cmd}, the function typically behaves as +if the command (or special context) @var{service} was being completed +instead. This provides a way of altering the behaviour of functions +that can perform many different completions. It is implemented +by setting the parameter @t{$service} when calling the function; +the function may choose to interpret this how it wishes, and simpler +functions will probably ignore it. + +@noindent +If the @t{#compdef} line contains one of the options @t{-p} or @t{-P}, +the words following are taken to be patterns. The function will be +called when completion is attempted for a command or context that matches +one of the patterns. The options @t{-p} and @t{-P} are used to specify +patterns to be tried before or after other completions respectively. +Hence @t{-P} may be used to specify default actions. + +@noindent +The option @t{-N} is used after a list following @t{-p} or @t{-P}; it +specifies that remaining words no longer define patterns. It is +possible to toggle between the three options as many times as necessary. + +@item @t{#compdef -k} @var{style key-sequence} ... +This option creates a widget behaving like the +builtin widget @var{style} and binds it to the given @var{key-sequence}s, +if any. The @var{style} must be one of the builtin widgets that perform +completion, namely @t{complete-word}, @t{delete-char-or-list}, +@t{expand-or-complete}, @t{expand-or-complete-prefix}, @t{list-choices}, +@t{menu-complete}, @t{menu-expand-or-complete}, or +@t{reverse-menu-complete}. If the @t{zsh/complist} module is loaded (see +@ref{The zsh/complist Module}) the widget @t{menu-select} is also available. + +@noindent +When one of the @var{key-sequence}s is typed, the function in the file will +be invoked to generate the matches. Note that a key will not be re-bound +if it already was (that is, was bound to something other than +@t{undefined-key}). The widget created has the same name as the file and +can be bound to any other keys using @t{bindkey} as usual. + +@item @t{#compdef -K} @var{widget-name} @var{style} @var{key-sequence} [ @var{name} @var{style} @var{seq} ... ] +This is similar to @t{-k} except that only one @var{key-sequence} +argument may be given for each @var{widget-name} @var{style} pair. +However, the entire set of three arguments may be repeated with a +different set of arguments. Note in particular that the +@var{widget-name} must be distinct in each set. If it does not begin with +`@t{_}' this will be added. The @var{widget-name} should not clash with +the name of any existing widget: names based on the name of the function +are most useful. For example, + +@noindent +@example +#compdef -K _foo_complete complete-word "^X^C" \ + _foo_list list-choices "^X^D" +@end example + +@noindent +(all on one line) defines a widget @t{_foo_complete} for completion, bound +to `@t{^X^C}', and a widget @t{_foo_list} for listing, bound to `@t{^X^D}'. + +@item @t{#autoload} [ @var{options} ] +Functions with the @t{#autoload} tag are marked for autoloading but +are not otherwise treated specially. Typically they are to be called +from within one of the completion functions. Any @var{options} supplied +will be passed to the @t{autoload} builtin; a typical use is @t{+X} to +force the function to be loaded immediately. Note that the @t{-U} and +@t{-z} flags are always added implicitly. + +@end table + +@noindent +The @t{#} is part of the tag name and no white space is allowed after it. +The @t{#compdef} tags use the @t{compdef} function described below; the +main difference is that the name of the function is supplied implicitly. + +@noindent +The special contexts for which completion functions can be defined are: + +@noindent +@table @asis +@kindex -array-value-, completion context +@item @t{-array-value-} +The right hand side of an array-assignment +(`@var{name}@t{=(}@var{...}@t{)}') + +@kindex -assign-parameter-, completion context +@item @t{-assign-parameter-} +The name of a parameter in an assignment, i.e. on the left hand side of +an `@t{=}' + +@kindex -brace-parameter-, completion context +@item @t{-brace-parameter-} +The name of a parameter expansion within braces (`@t{$@{}@var{...}@t{@}}') + +@kindex -command-, completion context +@item @t{-command-} +A word in command position + +@kindex -condition-, completion context +@item @t{-condition-} +A word inside a condition (`@t{[[}@var{...}@t{]]}') + +@kindex -default-, completion context +@item @t{-default-} +Any word for which no other completion is defined + +@kindex -equal-, completion context +@item @t{-equal-} +A word beginning with an equals sign + +@kindex -first-, completion context +@item @t{-first-} +This is tried before any other completion function. The function called +may set the @t{_compskip} parameter to one of various values: +@t{all}: no further completion is attempted; a string +containing the substring @t{patterns}: no pattern completion functions +will be called; a string containing @t{default}: the +function for the `@t{-default-}' context will not be called, but +functions defined for commands will be. + +@kindex -math-, completion context +@item @t{-math-} +Inside mathematical contexts, such as +`@t{((}@var{...}@t{))}' + +@kindex -parameter-, completion context +@item @t{-parameter-} +The name of a parameter expansion (`@t{$}@var{...}') + +@kindex -redirect-, completion context +@item @t{-redirect-} +The word after a redirection operator. + +@kindex -subscript-, completion context +@item @t{-subscript-} +The contents of a parameter subscript. + +@kindex -tilde-, completion context +@item @t{-tilde-} +After an initial tilde (`@t{~}'), but before the first slash +in the word. + +@kindex -value-, completion context +@item @t{-value-} +On the right hand side of an assignment. + +@end table + +@noindent +Default implementations are supplied for each of these +contexts. In most cases the context @t{-}@var{context}@t{-} is +implemented by a corresponding function @t{_}@var{context}, for example +the context `@t{-tilde-}' and the function `@t{_tilde}'). + +@noindent +The contexts @t{-redirect-} and @t{-value-} allow extra context-specific +information. (Internally, this is handled by the functions for each +context calling the function @t{_dispatch}.) The extra +information is added separated by commas. + +@noindent +For the @t{-redirect-} context, the extra information is in the form +`@t{-redirect-,}@var{op}@t{,}@var{command}', where @var{op} is the +redirection operator and @var{command} is the name of the command on +the line. If there is no command on the line yet, the @var{command} +field will be empty. + +@noindent +For the @t{-value-} context, the form is +`@t{-value-,}@var{name}@t{,}@var{command}', where @var{name} is the name of +the parameter on the left hand side of the assignment. +In the case of elements of an associative array, for +example `@t{assoc=(key <TAB>}', @var{name} is expanded to +`@var{name}@t{-}@var{key}'. In certain special contexts, such as +completing after `@t{make CFLAGS=}', the @var{command} part gives the +name of the command, here @t{make}; otherwise it is empty. + +@noindent +It is not necessary to define fully specific completions as the +functions provided will try to generate completions by progressively +replacing the elements with `@t{-default-}'. For example, when +completing after `@t{foo=<TAB>}', @t{_value} will try the names +`@t{-value-,foo,}' (note the empty @var{command} part), +`@t{-value-,foo,-default-}' and`@t{-value-,-default-,-default-}', in +that order, until it finds a function to handle the context. + +@noindent +As an example: + +@noindent +@example +compdef '_files -g "*.log"' '-redirect-,2>,-default-' +@end example + +@noindent +completes files matching `@t{*.log}' after `@t{2> <TAB>}' for any +command with no more specific handler defined. + +@noindent +Also: + +@noindent +@example +compdef _foo -value-,-default-,-default- +@end example + +@noindent +specifies that @t{_foo} provides completions for the values of +parameters for which no special function has been defined. This is +usually handled by the function @t{_value} itself. + +@noindent +The same lookup rules are used when looking up styles (as described +below); for example + +@noindent +@example +zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log' +@end example + +@noindent +is another way to make completion after `@t{2> <TAB>}' complete files +matching `@t{*.log}'. + +@noindent + +@subsection Functions +@noindent + +@noindent +The following function is defined by @t{compinit} and may be called +directly. + +@noindent +@findex compdef +@cindex completion system, adding definitions +@table @asis + +@item @t{compdef} [ @t{-ane} ] @var{function name} ... [ @t{-}@{@t{p}|@t{P}@} @var{pattern} ... [ @t{-N} @var{name} ...]] +@itemx @t{compdef -d} @var{name} ... +@itemx @t{compdef -k} [ @t{-an} ] @var{function style key-sequence} [ @var{key-sequence} ... ] +@itemx @t{compdef -K} [ @t{-an} ] @var{function name style key-seq} [ @var{name style seq} ... ] +The first form defines the @var{function} to call for completion in the +given contexts as described for the @t{#compdef} tag above. + +@noindent +Alternatively, all the arguments may have the form +`@var{cmd}@t{=}@var{service}'. Here @var{service} should already have been +defined by `@var{cmd1}@t{=}@var{service}' lines in @t{#compdef} files, as +described above. The argument for @var{cmd} will be completed in the +same way as @var{service}. + +@noindent +The @var{function} argument may alternatively be a string containing +almost any shell code. If the string contains an equal sign, the above +will take precedence. The option @t{-e} may be used to specify the first +argument is to be evaluated as shell code even if it contains an equal +sign. The string will be executed using the @t{eval} builtin command to +generate completions. This provides a way of avoiding having to define +a new completion function. For example, to complete files ending in +`@t{.h}' as arguments to the command @t{foo}: + +@noindent +@example +compdef '_files -g "*.h"' foo +@end example + +@noindent +The option @t{-n} prevents any completions already defined for the +command or context from being overwritten. + +@noindent +The option @t{-d} deletes any completion defined for the command or +contexts listed. + +@noindent +The @var{name}s may also contain @t{-p}, @t{-P} and @t{-N} options as +described for the @t{#compdef} tag. The effect on the argument list is +identical, switching between definitions of patterns tried initially, +patterns tried finally, and normal commands and contexts. + +@noindent +The parameter @t{$_compskip} may be set by any function defined for a +pattern context. If it is set to a value containing the substring +`@t{patterns}' none of the pattern-functions will be called; if it is +set to a value containing the substring `@t{all}', no other function +will be called. Setting @t{$_compskip} in this manner is of particular +utility when using the @t{-p} option, as otherwise the dispatcher will +move on to additional functions (likely the default one) after calling +the pattern-context one, which can mangle the display of completion +possibilities if not handled properly. + +@noindent +The form with @t{-k} defines a widget with the same name as the @var{function} +that will be called for each of the @var{key-sequence}s; this is like the +@t{#compdef -k} tag. The function should generate the completions needed +and will otherwise behave like the builtin widget whose name is given as +the @var{style} argument. The widgets usable for this are: +@t{complete-word}, @t{delete-char-or-list}, @t{expand-or-complete}, +@t{expand-or-complete-prefix}, @t{list-choices}, @t{menu-complete}, +@t{menu-expand-or-complete}, and @t{reverse-menu-complete}, as well as +@t{menu-select} if the @t{zsh/complist} module is loaded. The option @t{-n} +prevents the key being bound if it is already to bound to something other +than @t{undefined-key}. + +@noindent +The form with @t{-K} is similar and defines multiple widgets based on the +same @var{function}, each of which requires the set of three arguments +@var{name}, @var{style} and @var{key-seq}uence, where the latter two are as +for @t{-k} and the first must be a unique widget name beginning with an +underscore. + +@noindent +Wherever applicable, the @t{-a} option makes the @var{function} +autoloadable, equivalent to @t{autoload -U }@var{function}. + +@end table + +@noindent +The function @t{compdef} can be used to associate existing completion +functions with new commands. For example, + +@noindent +@example +compdef _pids foo +@end example + +@noindent +uses the function @t{_pids} to complete process IDs for the command @t{foo}. + +@noindent +Note also the @t{_gnu_generic} function described below, which can be +used to complete options for commands that understand the +`@t{-}@t{-help}' option. + +@noindent +@node Completion System Configuration, Control Functions, Initialization, Completion System + +@section Completion System Configuration +@noindent +@cindex completion system, configuration + +@noindent +This section gives a short overview of how the completion system works, +and then more detail on how users can configure how and when matches are +generated. + +@noindent + +@subsection Overview +@noindent + +@noindent +When completion is attempted somewhere on the command line the +completion system begins building the context. The context represents +everything that the shell knows about the meaning of the command line +and the significance of the cursor position. This takes account of a +number of things including the command word (such as `@t{grep}' or +`@t{zsh}') and options to which the current word may be an argument +(such as the `@t{-o}' option to @t{zsh} which takes a shell option as an +argument). + +@noindent +The context starts out very generic ("we are beginning a completion") +and becomes more specific as more is learned ("the current word is in a +position that is usually a command name" or "the current word might be a +variable name" and so on). Therefore the context will vary during the +same call to the completion system. + +@noindent +This context information is condensed into a string consisting of multiple +fields separated by colons, referred to simply as `the context' in the +remainder of the documentation. Note that a user of the completion system +rarely needs to compose a context string, unless for example a new +function is being written to perform completion for a new command. What a +user may need to do is compose a @emph{style} pattern, which is matched +against a context when needed to look up context-sensitive options that +configure the completion system. + +@noindent +The next few paragraphs explain how a context is composed within the +completion function suite. Following that is discussion of how @emph{styles} +are defined. Styles determine such things as how the matches are +generated, similarly to shell options but with much more control. They +are defined with the @t{zstyle} builtin command (@ref{The zsh/zutil Module}). + +@noindent +The context string always consists of a fixed set of fields, separated +by colons and with a leading colon before the first. Fields which are +not yet known are left empty, but the surrounding colons appear anyway. +The fields are always in the order +@t{:completion:}@var{function}@t{:}@var{completer}@t{:}@var{command}@t{:}@var{argument}@t{:}@var{tag}. These have the following meaning: + +@noindent +@itemize @bullet + +@item +The literal string @t{completion}, saying that this style is used by +the completion system. This distinguishes the context from those used +by, for example, zle widgets and ZFTP functions. + +@item +The @var{function}, if completion is called from a named widget rather +than through the normal completion system. Typically this is blank, but +it is set by special widgets such as @t{predict-on} and the various +functions in the @t{Widget} directory of the distribution to the name of +that function, often in an abbreviated form. + +@item +The @var{completer} currently active, the name of the function without the +leading underscore and with other underscores converted to hyphens. A +`completer' is in overall control of how completion is to be performed; +`@t{complete}' is the simplest, but other completers exist to perform +related tasks such as correction, or to modify the behaviour of a later +completer. See +@ref{Control Functions} +for more information. + +@item +The @var{command} or a special @t{-}@var{context}@t{-}, just at it appears +following the @t{#compdef} tag or the @t{compdef} function. Completion +functions for commands that have sub-commands usually modify this field +to contain the name of the command followed by a minus sign and the +sub-command. For example, the completion function for the @t{cvs} +command sets this field to @t{cvs-add} when completing arguments to +the @t{add} subcommand. + +@item +The @var{argument}; this indicates which command line or option argument +we are completing. For command arguments this generally takes the form +@t{argument-}@var{n}, where @var{n} is the number of the argument, +and for arguments to options the form @t{option-}@var{opt}@t{-}@var{n} +where @var{n} is the number of the argument to option @var{opt}. However, +this is only the case if the command line is parsed with standard +UNIX-style options and arguments, so many completions do not set this. + +@item +The @var{tag}. As described previously, tags are used to discriminate between +the types of matches a completion function can generate in a certain context. +Any completion function may use any tag name it likes, but a list of the +more common ones is given below. + +@end itemize + +@noindent +The context is gradually put together as the functions are executed, starting +with the main entry point, which adds @t{:completion:} and the @var{function} +element if necessary. The completer then adds the @var{completer} element. +The contextual completion adds the @var{command} and @var{argument} options. +Finally, the @var{tag} is added when the types of completion are known. +For example, the context name + +@noindent +@example +@t{:completion::complete:dvips:option-o-1:files} +@end example + +@noindent +says that normal completion was attempted as the first argument to the +option @t{-o} of the command @t{dvips}: + +@noindent +@example +@t{dvips -o ...} +@end example + +@noindent +and the completion function will generate filenames. + +@noindent +Usually completion will be tried for all possible tags in an order given +by the completion function. However, this can be altered by using the +@t{tag-order} style. Completion is then restricted to the list of given +tags in the given order. + +@noindent +The @t{_complete_help} bindable command shows all the contexts and tags +available for completion at a particular point. This provides an easy +way of finding information for @t{tag-order} and other styles. It is +described in +@ref{Bindable Commands}. + +@noindent +When looking up styles the completion system uses full context names, +including the tag. Looking up the value of a style therefore consists of +two things: the context, which is matched to the most specific (best +fitting) pattern, and the name of the style itself, which must be +matched exactly. The following examples demonstrate that patterns +may be loosely defined for styles that apply broadly, or as tightly +defined as desired for styles that apply in narrower circumstances. + +@noindent +For example, many completion functions can generate matches in a +simple and a verbose form and use the @t{verbose} style to decide +which form should be used. To make all such functions use the verbose form, +put + +@noindent +@example +zstyle ':completion:*' verbose yes +@end example + +@noindent +in a startup file (probably @t{.zshrc}). +This gives the @t{verbose} style the value @t{yes} in every +context inside the completion system, unless that context has a more +specific definition. It is best to avoid giving the pattern as `@t{*}' +in case the style has some meaning outside the completion system. + +@noindent +Many such general purpose styles can be configured simply by using the +@t{compinstall} function. + +@noindent +A more specific example of the use of the @t{verbose} style is by the +completion for the @t{kill} builtin. If the style is set, the builtin +lists full job texts and process command lines; otherwise it shows the +bare job numbers and PIDs. To turn the style off for this use only: + +@noindent +@example +zstyle ':completion:*:*:kill:*:*' verbose no +@end example + +@noindent +For even more control, the style can use one of the tags `@t{jobs}' or +`@t{processes}'. To turn off verbose display only for jobs: + +@noindent +@example +zstyle ':completion:*:*:kill:*:jobs' verbose no +@end example + +@noindent +The @t{-e} option to @t{zstyle} even allows completion function code to +appear as the argument to a style; this requires some understanding of +the internals of completion functions (see +@ref{Completion Widgets})). For example, + +@noindent +@example +@t{zstyle -e ':completion:*' hosts 'reply=($myhosts)'} +@end example + +@noindent +This forces the value of the @t{hosts} style to be read from the +variable @t{myhosts} each time a host name is needed; this is useful +if the value of @t{myhosts} can change dynamically. +For another useful example, see the example in the description of the +@t{file-list} style below. This form can be +slow and should be avoided for commonly examined styles such +as @t{menu} and @t{list-rows-first}. + +@noindent +Note that the order in which styles are @emph{defined} does not matter; the +style mechanism uses the most specific possible match for a particular +style to determine the set of values. Strings are +preferred over patterns (for example, `@t{:completion::complete:::foo}' is +more specific than `@t{:completion::complete:::*'}), and longer patterns are +preferred over the pattern `@t{*}'. See +@ref{The zsh/zutil Module} +for details. + +@noindent +Context patterns that use something other than a wildcard (@t{*}) to match the +middle parts of the context --- the @var{completer}, @var{command}, and +@var{argument} in +@t{:completion:}@var{function}@t{:}@var{completer}@t{:}@var{command}@t{:}@var{argument}@t{:}@var{tag} +--- should include all six colons (@t{:}) explicitly. Without this, +a pattern such as @t{:completion:*:foo:*} could match @t{foo} against a +component other than the intended one (for example, against @var{completer} when +a match against @var{command} was intended). + +@noindent +Style names like those of tags are arbitrary and depend on the completion +function. However, the following two sections list some of the most +common tags and styles. + +@noindent + +@subsection Standard Tags +@noindent +@cindex completion system, tags + +@noindent +Some of the following are only used when looking up particular styles +and do not refer to a type of match. + +@noindent +@table @asis +@kindex accounts, completion tag +@item @t{accounts} +used to look up the @t{users-hosts} style + +@kindex all-expansions, completion tag +@item @t{all-expansions} +used by the @t{_expand} completer when adding the single string containing +all possible expansions + +@kindex all-files, completion tag +@item @t{all-files} +for the names of all files (as distinct from a particular subset, see the +@t{globbed-files} tag). + +@kindex arguments, completion tag +@item @t{arguments} +for arguments to a command + +@kindex arrays, completion tag +@item @t{arrays} +for names of array parameters + +@kindex association-keys, completion tag +@item @t{association-keys} +for keys of associative arrays; used when completing inside a +subscript to a parameter of this type + +@kindex bookmarks, completion tag +@item @t{bookmarks} +when completing bookmarks (e.g. for URLs and the @t{zftp} function suite) + +@kindex builtins, completion tag +@item @t{builtins} +for names of builtin commands + +@kindex characters, completion tag +@item @t{characters} +for single characters in arguments of commands such as @t{stty}. Also used +when completing character classes after an opening bracket + +@kindex colormapids, completion tag +@item @t{colormapids} +for X colormap ids + +@kindex colors, completion tag +@item @t{colors} +for color names + +@kindex commands, completion tag +@item @t{commands} +for names of external commands. Also used by complex commands such as +@t{cvs} when completing names subcommands. + +@kindex contexts, completion tag +@item @t{contexts} +for contexts in arguments to the @t{zstyle} builtin command + +@kindex corrections, completion tag +@item @t{corrections} +used by the @t{_approximate} and @t{_correct} completers for possible +corrections + +@kindex cursors, completion tag +@item @t{cursors} +for cursor names used by X programs + +@kindex default, completion tag +@item @t{default} +used in some contexts to provide a way of supplying a default when more +specific tags are also valid. Note that this tag is +used when only the @var{function} field of the context name is set + +@kindex descriptions, completion tag +@item @t{descriptions} +used when looking up the value of the @t{format} style to generate +descriptions for types of matches + +@kindex devices, completion tag +@item @t{devices} +for names of device special files + +@kindex directories, completion tag +@item @t{directories} +for names of directories --- @t{local-directories} is used instead +when completing arguments of @t{cd} and related builtin commands when +the @t{cdpath} array is set + +@kindex directory-stack, completion tag +@item @t{directory-stack} +for entries in the directory stack + +@kindex displays, completion tag +@item @t{displays} +for X display names + +@kindex domains, completion tag +@item @t{domains} +for network domains + +@kindex email-*, completion tag +@item @t{email-}@var{plugin} +for email addresses from the `@t{_email-}@var{plugin}' backend of @t{_email_addresses} + +@kindex expansions, completion tag +@item @t{expansions} +used by the @t{_expand} completer for individual words (as opposed to +the complete set of expansions) resulting from the expansion of a word +on the command line + +@kindex extensions, completion tag +@item @t{extensions} +for X server extensions + +@kindex file-descriptors, completion tag +@item @t{file-descriptors} +for numbers of open file descriptors + +@kindex files, completion tag +@item @t{files} +the generic file-matching tag used by functions completing filenames + +@kindex fonts, completion tag +@item @t{fonts} +for X font names + +@kindex fstypes, completion tag +@item @t{fstypes} +for file system types (e.g. for the @t{mount} command) + +@kindex functions, completion tag +@item @t{functions} +names of functions --- normally shell functions, although certain +commands may understand other kinds of function + +@kindex globbed-files, completion tag +@item @t{globbed-files} +for filenames when the name has been generated by pattern matching + +@kindex groups, completion tag +@item @t{groups} +for names of user groups + +@kindex history-words, completion tag +@item @t{history-words} +for words from the history + +@kindex hosts, completion tag +@item @t{hosts} +for hostnames + +@kindex indexes, completion tag +@item @t{indexes} +for array indexes + +@kindex interfaces, completion tag +@item @t{interfaces} +for network interfaces + +@kindex jobs, completion tag +@item @t{jobs} +for jobs (as listed by the `@t{jobs}' builtin) + +@kindex keymaps, completion tag +@item @t{keymaps} +for names of zsh keymaps + +@kindex keysyms, completion tag +@item @t{keysyms} +for names of X keysyms + +@kindex libraries, completion tag +@item @t{libraries} +for names of system libraries + +@kindex limits, completion tag +@item @t{limits} +for system limits + +@kindex local-directories, completion tag +@item @t{local-directories} +for names of directories that are subdirectories of the current working +directory when completing arguments of @t{cd} and related builtin +commands (compare @t{path-directories}) --- when the @t{cdpath} +array is unset, @t{directories} is used instead + +@kindex mailboxes, completion tag +@item @t{mailboxes} +for e-mail folders + +@kindex manuals, completion tag +@item @t{manuals} +for names of manual pages + +@kindex maps, completion tag +@item @t{maps} +for map names (e.g. NIS maps) + +@kindex messages, completion tag +@item @t{messages} +used to look up the @t{format} style for messages + +@kindex modifiers, completion tag +@item @t{modifiers} +for names of X modifiers + +@kindex modules, completion tag +@item @t{modules} +for modules (e.g. @t{zsh} modules) + +@kindex my-accounts, completion tag +@item @t{my-accounts} +used to look up the @t{users-hosts} style + +@kindex named-directories, completion tag +@item @t{named-directories} +for named directories (you wouldn't have guessed that, would you?) + +@kindex names, completion tag +@item @t{names} +for all kinds of names + +@kindex newsgroups, completion tag +@item @t{newsgroups} +for USENET groups + +@kindex nicknames, completion tag +@item @t{nicknames} +for nicknames of NIS maps + +@kindex options, completion tag +@item @t{options} +for command options + +@kindex original, completion tag +@item @t{original} +used by the @t{_approximate}, @t{_correct} and @t{_expand} completers when +offering the original string as a match + +@kindex other-accounts, completion tag +@item @t{other-accounts} +used to look up the @t{users-hosts} style + +@kindex packages, completion tag +@item @t{packages} +for packages (e.g. @t{rpm} or installed @t{Debian} packages) + +@kindex parameters, completion tag +@item @t{parameters} +for names of parameters + +@kindex path-directories, completion tag +@item @t{path-directories} +for names of directories found by searching the @t{cdpath} array when +completing arguments of @t{cd} and related builtin commands (compare +@t{local-directories}) + +@kindex paths, completion tag +@item @t{paths} +used to look up the values of the @t{expand}, @t{ambiguous} and +@t{special-dirs} styles + +@kindex pods, completion tag +@item @t{pods} +for perl pods (documentation files) + +@kindex ports, completion tag +@item @t{ports} +for communication ports + +@kindex prefixes, completion tag +@item @t{prefixes} +for prefixes (like those of a URL) + +@kindex printers, completion tag +@item @t{printers} +for print queue names + +@kindex processes, completion tag +@item @t{processes} +for process identifiers + +@kindex processes-names, completion tag +@item @t{processes-names} +used to look up the @t{command} style when generating the names of +processes for @t{killall} + +@kindex sequences, completion tag +@item @t{sequences} +for sequences (e.g. @t{mh} sequences) + +@kindex sessions, completion tag +@item @t{sessions} +for sessions in the @t{zftp} function suite + +@kindex signals, completion tag +@item @t{signals} +for signal names + +@kindex strings, completion tag +@item @t{strings} +for strings (e.g. the replacement strings for the @t{cd} builtin +command) + +@kindex styles, completion tag +@item @t{styles} +for styles used by the zstyle builtin command + +@kindex suffixes, completion tag +@item @t{suffixes} +for filename extensions + +@kindex tags, completion tag +@item @t{tags} +for tags (e.g. @t{rpm} tags) + +@kindex targets, completion tag +@item @t{targets} +for makefile targets + +@kindex time-zones, completion tag +@item @t{time-zones} +for time zones (e.g. when setting the @t{TZ} parameter) + +@kindex types, completion tag +@item @t{types} +for types of whatever (e.g. address types for the @t{xhost} command) + +@kindex urls, completion tag +@item @t{urls} +used to look up the @t{urls} and @t{local} styles when completing URLs + +@kindex users, completion tag +@item @t{users} +for usernames + +@kindex values, completion tag +@item @t{values} +for one of a set of values in certain lists + +@kindex variant, completion tag +@item @t{variant} +used by @t{_pick_variant} to look up the command to run when determining +what program is installed for a particular command name. + +@kindex visuals, completion tag +@item @t{visuals} +for X visuals + +@kindex warnings, completion tag +@item @t{warnings} +used to look up the @t{format} style for warnings + +@kindex widgets, completion tag +@item @t{widgets} +for zsh widget names + +@kindex windows, completion tag +@item @t{windows} +for IDs of X windows + +@kindex zsh-options, completion tag +@item @t{zsh-options} +for shell options + +@end table + +@noindent + +@subsection Standard Styles +@noindent +@cindex completion system, styles + +@noindent +Note that the values of several of these styles represent boolean +values. Any of the strings `@t{true}', `@t{on}', +`@t{yes}', and `@t{1}' can be used for the value `true' and +any of the strings `@t{false}', `@t{off}', `@t{no}', and `@t{0}' for +the value `false'. The behavior for any other value is undefined +except where explicitly mentioned. The default value may +be either `true' or `false' if the style is not set. + +@noindent +Some of these styles are tested first for every possible tag +corresponding to a type of match, and if no style was found, for the +@t{default} tag. The most notable styles of this type are @t{menu}, +@t{list-colors} and styles controlling completion listing such as +@t{list-packed} and @t{last-prompt}. When tested for the @t{default} +tag, only the @var{function} field of the context will be set so that +a style using the @t{default} tag will normally be defined along the lines of: + +@noindent +@example +zstyle ':completion:*:default' menu ... +@end example + +@noindent +@table @asis +@kindex accept-exact, completion style +@item @t{accept-exact} +This is tested for the @t{default} tag in addition to the tags valid for +the current context. If it is set to `true' and any of the trial +matches is the same as the string on the command line, this match will +immediately be accepted (even if it would otherwise be considered +ambiguous). + +@noindent +When completing pathnames (where the tag used is `@t{paths}') +this style accepts any number of patterns as the value in addition to +the boolean values. Pathnames matching one of these +patterns will be accepted immediately even if the command line contains +some more partially typed pathname components and these match no file +under the directory accepted. + +@noindent +This style is also used by the @t{_expand} completer to decide if +words beginning with a tilde or parameter expansion should be +expanded. For example, if there are parameters +@t{foo} and @t{foobar}, the string `@t{$foo}' will only be expanded if +@t{accept-exact} is set to `true'; otherwise the completion system will +be allowed to complete @t{$foo} to @t{$foobar}. If the style is set to +`@t{continue}', @t{_expand} will add the expansion as a match and the completion +system will also be allowed to continue. + +@kindex accept-exact-dirs, completion style +@item @t{accept-exact-dirs} +This is used by filename completion. Unlike @t{accept-exact} it is +a boolean. By default, filename completion examines all components +of a path to see if there are completions of that component, even if +the component matches an existing directory. For example, when +completion after @t{/usr/bin/}, the function examines possible +completions to @t{/usr}. + +@noindent +When this style is `true', any prefix of a path that matches an existing +directory is accepted without any attempt to complete it further. +Hence, in the given example, the path @t{/usr/bin/} is accepted +immediately and completion tried in that directory. + +@noindent +This style is also useful when completing after directories that +magically appear when referenced, such as ZFS @t{.zfs} directories +or NetApp @t{.snapshot} directories. When the style is set the +shell does not check for the existence of the directory within the +parent directory. + +@noindent +If you wish to inhibit this behaviour entirely, set the @t{path-completion} +style (see below) to `false'. + +@kindex add-space, completion style +@item @t{add-space} +This style is used by the @t{_expand} completer. If it is `true' (the +default), a space will be inserted after all words resulting from the +expansion, or a slash in the case of directory names. If the value +is `@t{file}', the completer will only add a space +to names of existing files. Either a boolean `true' or the value +`@t{file}' may be combined with `@t{subst}', in which case the completer +will not add a space to words generated from the expansion of a +substitution of the form `@t{$(}@var{...}@t{)}' or `@t{$@{}@var{...}@t{@}}'. + +@noindent +The @t{_prefix} completer uses this style as a simple boolean value +to decide if a space should be inserted before the suffix. + +@kindex ambiguous, completion style +@item @t{ambiguous} +This applies when completing non-final components of filename paths, in +other words those with a trailing slash. If it is set, the cursor is +left after the first ambiguous component, even if menu completion is in +use. The style is always tested with the @t{paths} tag. + +@kindex assign-list, completion style +@item @t{assign-list} +When completing after an equals sign that is being treated as an +assignment, the completion system normally completes only one filename. +In some cases the value may be a list of filenames separated by colons, +as with @t{PATH} and similar parameters. This style can be set to a +list of patterns matching the names of such parameters. + +@noindent +The default is to complete lists when the word on the line already +contains a colon. + +@kindex auto-description, completion style +@item @t{auto-description} +If set, this style's value will be used as the description for options that +are not described by the completion functions, but that have exactly +one argument. The sequence `@t{%d}' in the value will be replaced by +the description for this argument. Depending on personal preferences, +it may be useful to set this style to something like `@t{specify: %d}'. +Note that this may not work for some commands. + +@kindex avoid-completer, completion style +@item @t{avoid-completer} +This is used by the @t{_all_matches} completer to decide if the string +consisting of all matches should be added to the list currently being +generated. Its value is a list of names of completers. If any of +these is the name of the completer that generated the matches in this +completion, the string will not be added. + +@noindent +The default value for this style is `@t{_expand _old_list _correct +_approximate}', i.e. it contains the completers for which a string +with all matches will almost never be wanted. + +@kindex cache-path, completion style +@item @t{cache-path} +This style defines the path where any cache files containing dumped +completion data are stored. It defaults to `@t{$ZDOTDIR/.zcompcache}', or +`@t{$HOME/.zcompcache}' if @t{$ZDOTDIR} is not defined. The completion +cache will not be used unless the @t{use-cache} style is set. + +@kindex cache-policy, completion style +@item @t{cache-policy} +This style defines the function that will be used to determine whether +a cache needs rebuilding. See the section on the @t{_cache_invalid} +function below. + +@kindex call-command, completion style +@item @t{call-command} +This style is used in the function for commands such as @t{make} and +@t{ant} where calling the command directly to generate matches suffers +problems such as being slow or, as in the case of @t{make} can +potentially cause actions in the makefile to be executed. If it is set +to `true' the command is called to generate matches. The default value +of this style is `false'. + +@kindex command, completion style +@item @t{command} +In many places, completion functions need to call external commands to +generate the list of completions. This style can be used to override the +command that is called in some such cases. The elements of the value are +joined with spaces to form a command line to execute. The value can also +start with a hyphen, in which case the usual command will be added to the +end; this is most useful for putting `@t{builtin}' or `@t{command}' in +front to make sure the appropriate version of a command is called, for +example to avoid calling a shell function with the same name as an external +command. + +@noindent +As an example, the completion function for process IDs uses this +style with the @t{processes} tag to generate the IDs to complete and +the list of processes to display (if the @t{verbose} style is `true'). +The list produced by the command should look like the output of the +@t{ps} command. The first line is not displayed, but is searched for +the string `@t{PID}' (or `@t{pid}') to find the position of the +process IDs in the following lines. If the line does not contain +`@t{PID}', the first numbers in each of the other lines are taken as the +process IDs to complete. + +@noindent +Note that the completion function generally has to call the specified +command for each attempt to generate the completion list. Hence +care should be taken to specify only commands that take a short +time to run, and in particular to avoid any that may never terminate. + +@kindex command-path, completion style +@item @t{command-path} +This is a list of directories to search for commands to complete. The +default for this style is the value of the special parameter @t{path}. + +@kindex commands, completion style +@item @t{commands} +This is used by the function completing sub-commands for the system +initialisation scripts (residing in @t{/etc/init.d} or somewhere not +too far away from that). Its values give the default commands to +complete for those commands for which the completion function isn't +able to find them out automatically. The default for this style are +the two strings `@t{start}' and `@t{stop}'. + +@kindex complete, completion style +@item @t{complete} +This is used by the @t{_expand_alias} function when invoked as a +bindable command. If set to `true' and the word on the command +line is not the name of an alias, matching alias names will be +completed. + +@kindex complete-options, completion style +@item @t{complete-options} +This is used by the completer for @t{cd}, @t{chdir} and @t{pushd}. +For these commands a @t{-} is used to introduce a directory stack entry +and completion of these is far more common than completing options. +Hence unless the value of this style is `true' options will not be +completed, even after an initial @t{-}. If it is `true', options will +be completed after an initial @t{-} unless there is a preceding +@t{-}@t{-} on the command line. + +@kindex completer, completion style +@item @t{completer} +The strings given as the value of this style provide the names of the +completer functions to use. The available completer functions are +described in +@ref{Control Functions}. + +@noindent +Each string may be either the name of a completer function or a string +of the form `@var{function}@t{:}@var{name}'. In the first case the +@var{completer} field of the context will contain the name of the +completer without the leading underscore and with all other +underscores replaced by hyphens. In the second case the +@var{function} is the name of the completer to call, but the context +will contain the user-defined @var{name} in the @var{completer} field of +the context. If the @var{name} starts with a hyphen, the string for the +context will be build from the name of the completer function as in +the first case with the @var{name} appended to it. For example: + +@noindent +@example +zstyle ':completion:*' completer _complete _complete:-foo +@end example + +@noindent +Here, completion will call the @t{_complete} completer twice, once +using `@t{complete}' and once using `@t{complete-foo}' in the +@var{completer} field of the context. Normally, using the same +completer more than once only makes sense when used with the +`@var{functions}@t{:}@var{name}' form, because otherwise the context +name will be the same in all calls to the completer; possible +exceptions to this rule are the @t{_ignored} and @t{_prefix} +completers. + +@noindent +The default value for this style is `@t{_complete _ignored}': +only completion will be done, first using the @t{ignored-patterns} style +and the @t{$fignore} array and then without ignoring matches. + +@kindex condition, completion style +@item @t{condition} +This style is used by the @t{_list} completer function to decide if +insertion of matches should be delayed unconditionally. The default is +`true'. + +@kindex delimiters, completion style +@item @t{delimiters} +This style is used when adding a delimiter for use with history +modifiers or glob qualifiers that have delimited arguments. It is +an array of preferred delimiters to add. Non-special characters are +preferred as the completion system may otherwise become confused. +The default list is @t{:}, @t{+}, @t{/}, @t{-}, @t{%}. The list +may be empty to force a delimiter to be typed. + +@kindex disabled, completion style +@item @t{disabled} +If this is set to `true', the @t{_expand_alias} completer and bindable +command will try to expand disabled aliases, too. The default is +`false'. + +@kindex domains, completion style +@item @t{domains} +A list of names of network domains for completion. +If this is not set, domain names will be taken from +the file @t{/etc/resolv.conf}. + +@kindex environ, completion style +@item @t{environ} +The environ style is used when completing for `@t{sudo}'. It is set to an +array of `@var{VAR}@t{=}@var{value}' assignments to be exported into the +local environment before the completion for the target command is invoked. +@example +zstyle ':completion:*:sudo::' environ \ + PATH="/sbin:/usr/sbin:$PATH" HOME="/root" +@end example + +@kindex expand, completion style +@item @t{expand} +This style is used when completing strings consisting of multiple +parts, such as path names. + +@noindent +If one of its values is the string `@t{prefix}', the partially typed +word from the line will be expanded as far as possible even if trailing +parts cannot be completed. + +@noindent +If one of its values is the string `@t{suffix}', matching names for +components after the first ambiguous one will also be added. This means +that the resulting string is the longest unambiguous string possible. +However, menu completion can be used to cycle through all matches. + +@kindex extra-verbose, completion style +@item @t{extra-verbose} +If set, the completion listing is more verbose at the cost of +a probable decrease in completion speed. Completion performance +will suffer if this style is set to `true'. + +@kindex fake, completion style +@item @t{fake} +This style may be set for any completion context. It +specifies additional strings that will always be completed in that +context. The form of each string is `@var{value}@t{:}@var{description}'; +the colon and description may be omitted, but any literal colons in +@var{value} must be quoted with a backslash. Any @var{description} +provided is shown alongside the value in completion listings. + +@noindent +It is important to use a sufficiently restrictive context when specifying +fake strings. Note that the styles @t{fake-files} and @t{fake-parameters} +provide additional features when completing files or parameters. + +@kindex fake-always, completion style +@item @t{fake-always} +This works identically to the @t{fake} style except that +the @t{ignored-patterns} style is not applied to it. This makes it +possible to override a set of matches completely by setting the +ignored patterns to `@t{*}'. + +@noindent +The following shows a way of supplementing any tag with arbitrary data, but +having it behave for display purposes like a separate tag. In this example +we use the features of the @t{tag-order} style to divide the +@t{named-directories} tag into two when performing completion with +the standard completer @t{complete} for arguments of @t{cd}. The tag +@t{named-directories-normal} behaves as normal, but the tag +@t{named-directories-mine} contains a fixed set of directories. +This has the effect of adding the match group `@t{extra directories}' with +the given completions. + +@noindent +@example +zstyle ':completion::complete:cd:*' tag-order \ + 'named-directories:-mine:extra\ directories + named-directories:-normal:named\ directories *' +zstyle ':completion::complete:cd:*:named-directories-mine' \ + fake-always mydir1 mydir2 +zstyle ':completion::complete:cd:*:named-directories-mine' \ + ignored-patterns '*' +@end example + +@kindex fake-files, completion style +@item @t{fake-files} +This style is used when completing files and looked up +without a tag. Its values are of the form +`@var{dir}@t{:}@var{names...}'. This will add the @var{names} (strings +separated by spaces) as +possible matches when completing in the directory @var{dir}, even if no +such files really exist. The dir may be a pattern; pattern characters +or colons in @var{dir} should be quoted with a backslash to be treated +literally. + +@noindent +This can be useful on systems that support special file systems whose +top-level pathnames can not be listed or generated with glob patterns +(but see @t{accept-exact-dirs} for a more general way of dealing +with this problem). It can also be used for directories for which one +does not have read permission. + +@noindent +The pattern form can be used to add a certain `magic' entry +to all directories on a particular file system. + +@kindex fake-parameters, completion style +@item @t{fake-parameters} +This is used by the completion function for parameter names. +Its values are names of parameters that might not yet be +set but should be completed nonetheless. Each name may also be +followed by a colon and a string specifying the type of the parameter +(like `@t{scalar}', `@t{array}' or `@t{integer}'). If the type is +given, the name will only be completed if parameters of that type are +required in the particular context. Names for which no type is +specified will always be completed. + +@kindex file-list, completion style +@item @t{file-list} +This style controls whether files completed using the standard builtin +mechanism are to be listed with a long list similar to @t{ls -l}. +Note that this feature uses the shell module +@t{zsh/stat} for file information; this loads the builtin @t{stat} +which will replace any external @t{stat} executable. To avoid +this the following code can be included in an initialization file: + +@noindent +@example +zmodload -i zsh/stat +disable stat +@end example + +@noindent +The style may either be set to a `true' value (or `@t{all}'), or +one of the values `@t{insert}' or `@t{list}', indicating that files +are to be listed in long format in all circumstances, or when +attempting to insert a file name, or when listing file names +without attempting to insert one. + +@noindent +More generally, the value may be an array of any of the above values, +optionally followed by @t{=}@var{num}. If @var{num} is present it +gives the maximum number of matches for which long listing style +will be used. For example, + +@noindent +@example +zstyle ':completion:*' file-list list=20 insert=10 +@end example + +@noindent +specifies that long format will be used when listing up to 20 files +or inserting a file with up to 10 matches (assuming a listing +is to be shown at all, for example on an ambiguous completion), else short +format will be used. + +@noindent +@example +zstyle -e ':completion:*' file-list \ + '(( $@{+NUMERIC@} )) && reply=(true)' +@end example + +@noindent +specifies that long format will be used any time a numeric argument is +supplied, else short format. + +@kindex file-patterns, completion style +@item @t{file-patterns} +This is used by the standard function for completing filenames, +@t{_files}. If the style is unset up to three tags are offered, +`@t{globbed-files}',`@t{directories}' and `@t{all-files}', depending on +the types of files expected by the caller of @t{_files}. The first two +(`@t{globbed-files}' and `@t{directories}') are normally offered +together to make it easier to complete files in sub-directories. + +@noindent +The @t{file-patterns} style provides alternatives to the default tags, +which are not used. Its value consists of elements of the form +`@var{pattern}@t{:}@var{tag}'; each string may contain any number of +such specifications separated by spaces. + +@noindent +The @var{pattern} is a pattern that is to be used to generate filenames. +Any occurrence of the sequence `@t{%p}' is replaced by any +pattern(s) +passed by the function calling @t{_files}. Colons in the pattern must +be preceded by a backslash to make them distinguishable from the colon +before the @var{tag}. If more than one pattern is needed, the patterns +can be given inside braces, separated by commas. + +@noindent +The @var{tag}s of all strings in the value will be offered by @t{_files} +and used when looking up other styles. Any @var{tag}s in the same +word will be offered at the same time and before later words. +If no `@t{:}@var{tag}' is given the `@t{files}' tag will be used. + +@noindent +The @var{tag} may also be followed by an optional second colon and a +description, which will be used for the `@t{%d}' in the value of +the @t{format} style (if that is set) instead of the default +description supplied by the completion function. The inclusion +of a description also gives precedence to associated options such as +for completion grouping so it can be used where files should be +separated. + +@noindent +For example, to make the @t{rm} command first complete only names of +object files and then the names of all files if there is no matching +object file: + +@noindent +@example +zstyle ':completion:*:*:rm:*:*' file-patterns \ + '*.o:object-files' '%p:all-files' +@end example + +@noindent +To alter the default behaviour of file completion --- offer files +matching a pattern and directories on the first attempt, then all files +--- to offer only matching files on the first attempt, then directories, +and finally all files: + +@noindent +@example +zstyle ':completion:*' file-patterns \ + '%p:globbed-files' '*(-/):directories' '*:all-files' +@end example + +@noindent +This works even where there is no special pattern: @t{_files} matches +all files using the pattern `@t{*}' at the first step and stops when it +sees this pattern. Note also it will never try a pattern more than once +for a single completion attempt. + +@noindent +To separate directories into a separate group from the files but still +complete them at the first attempt, a description needs to be given. +Note that directories need to be explicitly excluded from the +globbed-files because `@t{*}' will match directories. For grouping, it +is also necessary to set the @t{group-name} style. + +@noindent +@example +zstyle ':completion:*' file-patterns \ + '%p(^-/):globbed-files *(-/):directories:location' +@end example + +@noindent +During the execution of completion functions, the @t{EXTENDED_GLOB} +option is in effect, so the characters `@t{#}', `@t{~}' and `@t{^}' have +special meanings in the patterns. + +@kindex file-sort, completion style +@item @t{file-sort} +The standard filename completion function uses this style without a tag +to determine in which order the names should be listed; menu completion +will cycle through them in the same order. The possible +values are: `@t{size}' to sort by the size of the file; +`@t{links}' to sort by the number of links to the file; +`@t{modification}' (or `@t{time}' or `@t{date}') to sort by the last +modification time; `@t{access}' to sort by the last access time; and +`@t{inode}' (or `@t{change}') to sort by the last inode change +time. If the style is set to any other value, or is unset, files will be +sorted alphabetically by name. If the value contains the string +`@t{reverse}', sorting is done in the opposite order. If the value +contains the string `@t{follow}', timestamps are associated with the +targets of symbolic links; the default is to use the timestamps +of the links themselves. + +@kindex file-split-chars, completion style +@item @t{file-split-chars} +A set of characters that will cause @emph{all} file completions for +the given context to be split at the point where any of the characters +occurs. A typical use is to set the style to @t{:}; then everything +up to and including the last @t{:} in the string so far is ignored when +completing files. As this is quite heavy-handed, it is usually +preferable to update completion functions for contexts where this +behaviour is useful. + +@kindex filter, completion style +@item @t{filter} +The @t{ldap} plugin of email address completion (see @t{_email_addresses}) uses +this style to specify +the attributes to match against when filtering entries. So for example, if +the style is set to `@t{sn}', matching is done against surnames. Standard +LDAP filtering is used so normal completion matching is bypassed. If this +style is not set, the LDAP plugin is skipped. You may also need to set the +@t{command} style to specify how to connect to your LDAP server. + +@kindex force-list, completion style +@item @t{force-list} +This forces a list of completions to be shown at any point where listing is +done, even in cases where the list would usually be suppressed. +For example, normally the list is only shown if +there are at least two different matches. By setting this style to +`@t{always}', the list will always be shown, even if there is only a +single match that will immediately be accepted. The style may also +be set to a number. In this case the list will be shown if there are +at least that many matches, even if they would all insert the same +string. + +@noindent +This style is tested for the default tag as well as for each tag valid +for the current completion. Hence the listing can be forced only for +certain types of match. + +@kindex format, completion style +@item @t{format} +If this is set for the @t{descriptions} tag, its value is used as a +string to display above matches in completion lists. The sequence +`@t{%d}' in this string will be replaced with a short description of +what these matches are. This string may also contain the output +attribute sequences understood by @t{compadd -X} +(see +@ref{Completion Widgets}). + +@noindent +The style is tested with each tag valid for the current completion +before it is tested for the @t{descriptions} tag. Hence different format +strings can be defined for different types of match. + +@noindent +Note also that some completer functions define additional +`@t{%}'-sequences. These are described for the completer functions that +make use of them. + +@noindent +Some completion functions display messages that may be customised by +setting this style for the @t{messages} tag. Here, the `@t{%d}' is +replaced with a message given by the completion function. + +@noindent +Finally, the format string is looked up with the @t{warnings} tag, +for use when no matches could be generated at all. In this case the +`@t{%d}' is replaced with the descriptions for the matches that were +expected separated by spaces. The sequence `@t{%D}' is replaced with +the same descriptions separated by newlines. + +@noindent +It is possible to use printf-style field width specifiers with `@t{%d}' +and similar escape sequences. This is handled by the @t{zformat} +builtin command from the @t{zsh/zutil} module, see +@ref{The zsh/zutil Module}. + +@kindex gain-privileges, completion style +@item @t{gain-privileges} +If set to @t{true}, this style enables the use of commands like @t{sudo} +or @t{doas} to gain extra privileges when retrieving information for +completion. This is only done when a command such as @t{sudo} appears on +the command-line. To force the use of, e.g. @t{sudo} or to override any +prefix that might be added due to @t{gain-privileges}, the @t{command} +style can be used with a value that begins with a hyphen. + +@kindex glob, completion style +@item @t{glob} +This is used by the @t{_expand} completer. If +it is set to `true' (the default), globbing will be attempted on the +words resulting from a previous substitution (see the @t{substitute} +style) or else the original string from the line. + +@kindex global, completion style +@item @t{global} +If this is set to `true' (the default), the @t{_expand_alias} +completer and bindable command will try to expand global aliases. + +@kindex group-name, completion style +@item @t{group-name} +The completion system can group different types of matches, which appear +in separate lists. This style can be used to give the names of groups +for particular tags. For example, in command position the completion +system generates names of builtin and external commands, names of +aliases, shell functions and parameters and reserved words as possible +completions. To have the external commands and shell functions listed +separately: + +@noindent +@example +zstyle ':completion:*:*:-command-:*:commands' \ + group-name commands +zstyle ':completion:*:*:-command-:*:functions' \ + group-name functions +@end example + +@noindent +As a consequence, any match with the same tag will be displayed in the +same group. + +@noindent +If the name given is the empty string the name of the tag for +the matches will be used as the name of the group. So, to have all +different types of matches displayed separately, one can just set: + +@noindent +@example +zstyle ':completion:*' group-name @value{dsq} +@end example + +@noindent +All matches for which no group name is defined will be put in a group +named @t{-default-}. + +@noindent +To display the group name in the output, see the @t{format} style (q.v.) +under the @t{descriptions} tag. + +@kindex group-order, completion style +@item @t{group-order} +This style is additional to the @t{group-name} style to specify the +order for display of the groups defined by that style (compare @t{tag-order}, +which determines which completions appear at all). The groups named +are shown in the given order; any other groups +are shown in the order defined by the completion function. + +@noindent +For example, to have names of builtin commands, shell functions and +external commands appear in that order when completing in command +position: + +@noindent +@example +zstyle ':completion:*:*:-command-:*:*' group-order \ + builtins functions commands +@end example + +@kindex groups, completion style +@item @t{groups} +A list of names of UNIX groups. If this is not set, +group names are taken from the YP database or the file `@t{/etc/group}'. + +@kindex hidden, completion style +@item @t{hidden} +If this is set to `true', matches for the given context +will not be listed, although +any description for the matches set with the @t{format} style will be +shown. If it is set to `@t{all}', not even the description will be +displayed. + +@noindent +Note that the matches will still be completed; they are just not shown +in the list. To avoid having matches considered as possible +completions at all, the @t{tag-order} style can be modified as described +below. + +@kindex hosts, completion style +@item @t{hosts} +A list of names of hosts that should be completed. If this is not set, +hostnames are taken from the file `@t{/etc/hosts}'. + +@kindex hosts-ports, completion style +@item @t{hosts-ports} +This style is used by commands that need or accept hostnames and +network ports. The strings in the value should be of the form +`@var{host}@t{:}@var{port}'. Valid ports are determined by the presence +of hostnames; multiple ports for the same host may appear. + +@kindex ignore-line, completion style +@item @t{ignore-line} +This is tested for each tag valid for the current completion. If +it is set to `true', none of the words that are already on the line +will be considered as possible completions. If it is set to +`@t{current}', the word the cursor is on will not be considered as a +possible completion. The value `@t{current-shown}' is similar but only +applies if the list of completions is currently shown on the screen. +Finally, if the style is set to `@t{other}', all words on the line except +for the current one will be excluded from the possible completions. + +@noindent +The values `@t{current}' and `@t{current-shown}' are a bit like the +opposite of the @t{accept-exact} style: only strings with +missing characters will be completed. + +@noindent +Note that you almost certainly don't want to set this to `true' or +`@t{other}' for a general +context such as `@t{:completion:*}'. This is because it would disallow +completion of, for example, options multiple times even if the command +in question accepts the option more than once. + +@kindex ignore-parents, completion style +@item @t{ignore-parents} +The style is tested without a tag by the function completing pathnames +in order to determine whether to ignore +the names of directories already mentioned in the current word, or the +name of the current working directory. The value must include one or both +of the following strings: + +@noindent +@table @asis +@item @t{parent} +The name of any directory whose path is already contained in the word on +the line is ignored. For example, when completing after @t{foo/../}, the +directory @t{foo} will not be considered a valid completion. + +@item @t{pwd} +The name of the current working directory will not be completed; hence, +for example, completion after @t{../} will not use the name of the current +directory. + +@end table + +@noindent +In addition, the value may include one or both of: + +@noindent +@table @asis +@item @t{..} +Ignore the specified directories only when the word on the line contains +the substring `@t{../}'. + +@item @t{directory} +Ignore the specified directories only when names of directories are +completed, not when completing names of files. + +@end table + +@noindent +Excluded values act in a similar fashion to values of the +@t{ignored-patterns} style, so they can be restored to consideration by +the @t{_ignored} completer. + +@kindex ignored-patterns, completion style +@item @t{ignored-patterns} +A list of patterns; any trial completion matching one of the patterns +will be excluded from consideration. The +@t{_ignored} completer can appear in the list of completers to +restore the ignored matches. This is a more configurable +version of the shell parameter @t{$fignore}. + +@noindent +Note that the +@t{EXTENDED_GLOB} option is set during the execution of completion +functions, so the characters `@t{#}', `@t{~}' and `@t{^}' have special +meanings in the patterns. + +@kindex insert, completion style +@item @t{insert} +This style is used by the @t{_all_matches} completer to decide whether to +insert the list of all matches unconditionally instead of adding the +list as another match. + +@kindex insert-ids, completion style +@item @t{insert-ids} +When completing process IDs, for example as arguments to the @t{kill} and +@t{wait} builtins the name of a +command may be converted to the appropriate process ID. A problem +arises when the process name typed is not unique. By default (or if this +style is set explicitly to `@t{menu}') the name will be converted +immediately to a set of possible IDs, and menu completion will be started +to cycle through them. + +@noindent +If the value of the style is `@t{single}', +the shell will wait until the user has typed enough to make the command +unique before converting the name to an ID; attempts at completion will +be unsuccessful until that point. If the value is any other +string, menu completion will be started when the string typed by the +user is longer than the common prefix to the corresponding IDs. + +@kindex insert-sections, completion style +@item @t{insert-sections} +This style is used with tags of the form `@t{manuals.}@var{X}' when +completing names of manual pages. If set and the @var{X} in the tag name matches +the section number of the page being completed, the section number is inserted +along with the page name. For example, given + +@noindent +@example +zstyle ':completion:*:manuals.*' insert-sections true +@end example + +@noindent +@t{man ssh_<TAB>} may be completed to @t{man 5 ssh_config}. + +@noindent +The value may also be set to one of `@t{prepend}', or `@t{suffix}'. +`@t{prepend}' behaves the same as `true' as in the above example, while +`@t{suffix}' would complete @t{man ssh_<TAB>} as @t{man ssh_config.5}. + +@noindent +This is especially useful in conjunction with @t{separate-sections}, as +it ensures that the page requested of @t{man} corresponds to the one +displayed in the completion listing when there are multiple pages with the +same name (e.g., @t{printf(1)} and @t{printf(3)}). + +@noindent +The default for this style is `false'. + +@kindex insert-tab, completion style +@item @t{insert-tab} +If this is set to `true', the completion system will +insert a TAB character (assuming that was used to start completion) instead +of performing completion when there is no non-blank character to the left +of the cursor. If it is set to `false', completion will be done even there. + +@noindent +The value may also contain the substrings `@t{pending}' or +`@t{pending=}@var{val}'. In this case, the typed character will be +inserted instead of starting completion when there is unprocessed input +pending. If a @var{val} is given, completion will not be done if there +are at least that many characters of unprocessed input. This is often +useful when pasting characters into a terminal. Note +however, that it relies on the @t{$PENDING} special parameter from the +@t{zsh/zle} module being set properly which is not guaranteed on all +platforms. + +@noindent +The default value of this style is `true' except for completion within +@t{vared} builtin command where it is `false'. + +@kindex insert-unambiguous, completion style +@item @t{insert-unambiguous} +This is used by the @t{_match} and @t{_approximate} completers. +These completers are often used with menu completion since the word typed +may bear little resemblance to the final completion. +However, if this style is `true', the completer will start menu +completion only if it could find no unambiguous initial string at +least as long as the original string typed by the user. + +@noindent +In the case of the @t{_approximate} completer, the completer +field in the context will already have been set to one of +@t{correct-}@var{num} or @t{approximate-}@var{num}, where @var{num} is the +number of errors that were accepted. + +@noindent +In the case of the @t{_match} completer, the style may also be set to +the string `@t{pattern}'. Then the pattern on the line is left +unchanged if it does not match unambiguously. + +@kindex keep-prefix, completion style +@item @t{keep-prefix} +This style is used by the @t{_expand} completer. If it is `true', the +completer will try to keep a prefix containing a tilde or parameter +expansion. Hence, for example, the string `@t{~/f*}' would be expanded to +`@t{~/foo}' instead of `@t{/home/user/foo}'. If the style is set to +`@t{changed}' (the default), the prefix will only be left unchanged if +there were other changes between the expanded words and the original +word from the command line. Any other value forces the prefix to be +expanded unconditionally. + +@noindent +The behaviour of @t{_expand} when this style is `true' is to cause @t{_expand} +to give up when a single expansion with the restored prefix is the same +as the original; hence any remaining completers may be called. + +@kindex known-hosts-files +@item @t{known-hosts-files} +This style should contain a list of files to search for host names and +(if the @t{use-ip} style is set) IP addresses in a format compatible with +ssh @t{known_hosts} files. If it is not set, the files +@t{/etc/ssh/ssh_known_hosts} and @t{~/.ssh/known_hosts} are used. + +@kindex last-prompt, completion style +@item @t{last-prompt} +This is a more flexible form of the @t{ALWAYS_LAST_PROMPT} option. +If it is `true', the completion system will try to return the cursor to +the previous command line after displaying a completion list. It is +tested for all tags valid for the current completion, then the +@t{default} tag. The cursor will be moved back to the +previous line if this style is `true' for all types of match. Note +that unlike the @t{ALWAYS_LAST_PROMPT} option this is independent of the +numeric argument. + +@kindex list, completion style +@item @t{list} +This style is used by the @t{_history_complete_word} bindable command. +If it is set to `true' it has no effect. If it is set to `false' +matches will not be listed. This overrides the setting of the options +controlling listing behaviour, in particular @t{AUTO_LIST}. The context +always starts with `@t{:completion:history-words}'. + +@kindex list-colors, completion style +@item @t{list-colors} +If the @t{zsh/complist} module is loaded, this style can be used to set +color specifications. This mechanism replaces the use of the +@t{ZLS_COLORS} and @t{ZLS_COLOURS} parameters described in +@ref{The zsh/complist Module}, but the syntax is the same. + +@noindent +If this style is set for the @t{default} tag, the strings in the value +are taken as specifications that are to be used everywhere. If it is +set for other tags, the specifications are used only for matches of +the type described by the tag. For this to work best, the @t{group-name} +style must be set to an empty string. + +@noindent +In addition to setting styles for specific tags, it is also possible to +use group names specified explicitly by the @t{group-name} tag together +with the `@t{(group)}' syntax allowed by the @t{ZLS_COLORS} and +@t{ZLS_COLOURS} parameters and simply using the @t{default} tag. + +@noindent +It is possible to use any color specifications already set up for the GNU +version of the @t{ls} command: + +@noindent +@example +zstyle ':completion:*:default' list-colors \ + $@{(s.:.)LS_COLORS@} +@end example + +@noindent +The default colors are the same as for the GNU @t{ls} command and can be +obtained by setting the style to an empty string (i.e. @t{@value{dsq}}). + +@kindex list-dirs-first, completion style +@item @t{list-dirs-first} +This is used by file completion and corresponds to a particular +setting of the @t{file-patterns} style. +If set, the default directories to be completed +are listed separately from and before completion for other files. + +@kindex list-grouped, completion style +@item @t{list-grouped} +If this style is `true' (the default), the completion system will try to +make certain completion listings more compact by grouping matches. +For example, options for commands that have the same description (shown +when the @t{verbose} style is set to `true') will appear as a single +entry. However, menu selection can be used to cycle through all the +matches. + +@kindex list-packed, completion style +@item @t{list-packed} +This is tested for each tag valid in the current context as well as the +@t{default} tag. If it is set to `true', the corresponding matches +appear in listings as if the @t{LIST_PACKED} option were set. If it is +set to `false', they are listed normally. + +@kindex list-prompt, completion style +@item @t{list-prompt} +If this style is set for the @t{default} tag, +completion lists that don't fit on the screen can be scrolled (see +@ref{The zsh/complist Module}). The value, if not the empty string, will be displayed after every +screenful and the shell will prompt for a key press; if the style is +set to the empty string, +a default prompt will be used. + +@noindent +The value may contain the escape sequences: +`@t{%l}' or `@t{%L}', which will be replaced by the number of the last line +displayed and the total number of lines; `@t{%m}' or `@t{%M}', +the number of the last match shown and the total number of +matches; and `@t{%p}' and `@t{%P}', `@t{Top}' +when at the beginning of the list, `@t{Bottom}' when at the end and the +position shown as a percentage of the total length otherwise. In each +case the form with the uppercase letter will be replaced by a string of fixed +width, padded to the right with spaces, while the lowercase form will +be replaced by a variable width string. As in other prompt strings, the +escape sequences `@t{%S}', `@t{%s}', `@t{%B}', `@t{%b}', `@t{%U}', +`@t{%u}' for entering and leaving the display modes +standout, bold and underline, and `@t{%F}', `@t{%f}', `@t{%K}', `@t{%k}' for +changing the foreground background colour, are also available, as is the form +`@t{%@{}...@t{%@}}' for enclosing escape sequences which display with zero +(or, with a numeric argument, some other) width. + +@noindent +After deleting this prompt the variable @t{LISTPROMPT} should be unset for +the removal to take effect. + +@kindex list-rows-first, completion style +@item @t{list-rows-first} +This style is tested in the same way as the @t{list-packed} style and +determines whether matches are to be listed in a rows-first fashion as +if the @t{LIST_ROWS_FIRST} option were set. + +@kindex list-separator, completion style +@item @t{list-separator} +The value of this style is used in completion listing to separate the +string to complete from a description when possible (e.g. when +completing options). It defaults to `@t{-}@t{-}' (two hyphens). + +@kindex list-suffixes, completion style +@item @t{list-suffixes} +This style is used by the function that completes filenames. If it is +`true', and completion is attempted on a string containing multiple partially +typed pathname components, all ambiguous components will be shown. +Otherwise, completion stops at the first ambiguous component. + +@kindex local, completion style +@item @t{local} +This is for use with functions that complete URLs for which the +corresponding files are available directly from the file system. +Its value should consist of three strings: a +hostname, the path to the default web pages for the server, and the +directory name used by a user placing web pages within their home +area. + +@noindent +For example: + +@noindent +@example +zstyle ':completion:*' local toast \ + /var/http/public/toast public_html +@end example + +@noindent +Completion after `@t{http://toast/stuff/}' will look for files in the +directory @t{/var/http/public/toast/stuff}, while completion after +`@t{http://toast/~yousir/}' will look for files in the directory +@t{~yousir/public_html}. + +@kindex mail-directory, completion style +@item @t{mail-directory} +If set, zsh will assume that mailbox files can be found in +the directory specified. It defaults to `@t{~/Mail}'. + +@kindex match-original, completion style +@item @t{match-original} +This is used by the @t{_match} completer. If it is set to +@t{only}, @t{_match} will try to generate matches without inserting a +`@t{*}' at the cursor position. If set to any other non-empty value, +it will first try to generate matches without inserting the `@t{*}' +and if that yields no matches, it will try again with the `@t{*}' +inserted. If it is unset or set to the empty string, matching will +only be performed with the `@t{*}' inserted. + +@kindex matcher, completion style +@item @t{matcher} +This style is tested separately for each tag valid in the current +context. Its value is placed before any match specifications given by the +@t{matcher-list} style so can override them via the use of an @t{x:} +specification. The value should be in the form described in +@ref{Completion Matching Control}. For examples of this, see the description of the @t{tag-order} style. + +@noindent +For notes comparing the use of this and the @t{matcher-list} style, see +under the description of the @t{tag-order} style. + +@kindex matcher-list, completion style +@item @t{matcher-list} +This style can be set to a list of match specifications that are to +be applied everywhere. Match specifications are described in +@ref{Completion Matching Control}. +The completion system will try them one after another for each completer +selected. For example, to try first simple completion and, if that +generates no matches, case-insensitive completion: + +@noindent +@example +zstyle ':completion:*' matcher-list @value{dsq} 'm:@{a-zA-Z@}=@{A-Za-z@}' +@end example + +@noindent +By default each specification replaces the previous one; however, if a +specification is prefixed with @t{+}, it is added to the existing list. +Hence it is possible to create increasingly general specifications +without repetition: + +@noindent +@example +zstyle ':completion:*' matcher-list \ + @value{dsq} '+m:@{a-z@}=@{A-Z@}' '+m:@{A-Z@}=@{a-z@}' +@end example + +@noindent +It is possible to create match specifications valid for particular +completers by using the third field of the context. This applies only +to completers that override the global matcher-list, which as of this +writing includes only @t{_prefix} and @t{_ignored}. For example, to +use the completers @t{_complete} and @t{_prefix} but allow +case-insensitive completion only with @t{_complete}: + +@noindent +@example +zstyle ':completion:*' completer _complete _prefix +zstyle ':completion:*:complete:*:*:*' matcher-list \ + @value{dsq} 'm:@{a-zA-Z@}=@{A-Za-z@}' +@end example + +@noindent +User-defined names, as explained for the @t{completer} style, are +available. This makes it possible to try the same completer more than +once with different match specifications each time. For example, to try +normal completion without a match specification, then normal completion +with case-insensitive matching, then correction, and finally +partial-word completion: + +@noindent +@example +zstyle ':completion:*' completer \ + _complete _correct _complete:foo +zstyle ':completion:*:complete:*:*:*' matcher-list \ + @value{dsq} 'm:@{a-zA-Z@}=@{A-Za-z@}' +zstyle ':completion:*:foo:*:*:*' matcher-list \ + 'm:@{a-zA-Z@}=@{A-Za-z@} r:|[-_./]=* r:|=*' +@end example + +@noindent +If the style is unset in any context no match specification is applied. +Note also that some completers such as @t{_correct} and @t{_approximate} +do not use the match specifications at all, though these completers will +only ever be called once even if the @t{matcher-list} contains more than +one element. + +@noindent +Where multiple specifications are useful, note that the @emph{entire} +completion is done for each element of @t{matcher-list}, which can +quickly reduce the shell's performance. As a rough rule of thumb, +one to three strings will give acceptable performance. On the other +hand, putting multiple space-separated values into the same string does +not have an appreciable impact on performance. + +@noindent +If there is no current matcher or it is empty, and the option +@t{NO_CASE_GLOB} is in effect, the matching for files is performed +case-insensitively in any case. However, any matcher must +explicitly specify case-insensitive matching if that is required. + +@noindent +For notes comparing the use of this and the @t{matcher} style, see +under the description of the @t{tag-order} style. + +@kindex max-errors, completion style +@item @t{max-errors} +This is used by the @t{_approximate} and @t{_correct} completer functions +to determine the maximum number of errors to allow. The completer will try +to generate completions by first allowing one error, then two errors, and +so on, until either a match or matches were found or the maximum number of +errors given by this style has been reached. + +@noindent +If the value for this style contains the string `@t{numeric}', the +completer function will take any numeric argument as the +maximum number of errors allowed. For example, with + +@noindent +@example +zstyle ':completion:*:approximate:::' max-errors 2 numeric +@end example + +@noindent +two errors are allowed if no numeric argument is given, but with +a numeric argument of six (as in `@t{ESC-6 TAB}'), up to six +errors are accepted. Hence with a value of `@t{0 numeric}', no correcting +completion will be attempted unless a numeric argument is given. + +@noindent +If the value contains the string `@t{not-numeric}', the completer +will @emph{not} try to generate corrected +completions when given a numeric argument, so in this case the number given +should be greater than zero. For example, `@t{2 not-numeric}' specifies that +correcting completion with two errors will usually be performed, but if a +numeric argument is given, correcting completion will not be +performed. + +@noindent +The default value for this style is `@t{2 numeric}'. + +@kindex max-matches-width, completion style +@item @t{max-matches-width} +This style is used to determine the trade off between the width of the +display used for matches and the width used for their descriptions when +the @t{verbose} style is in effect. The value gives the number of +display columns to reserve for the matches. The default is half the +width of the screen. + +@noindent +This has the most impact when several matches have the +same description and so will be grouped together. Increasing the style +will allow more matches to be grouped together; decreasing it will allow +more of the description to be visible. + +@kindex menu, completion style +@item @t{menu} +If this is `true' in the context of any of the tags defined +for the current completion menu completion will be used. The value for +a specific tag will take precedence over that for the `@t{default}' tag. + +@noindent +If none of the values found in this way is `true' but at least +one is set to `@t{auto}', the shell behaves as if the @t{AUTO_MENU} +option is set. + +@noindent +If one of the values is explicitly set to `false', menu +completion will be explicitly turned off, overriding the +@t{MENU_COMPLETE} option and other settings. + +@noindent +In the form `@t{yes=}@var{num}', where `@t{yes}' may be any of the +`true' values (`@t{yes}', `@t{true}', `@t{on}' and `@t{1}'), +menu completion will be turned on if there are at least @var{num} matches. +In the form `@t{yes=long}', menu completion will be turned on +if the list does not fit on the screen. This does not activate menu +completion if the widget normally only lists completions, but menu +completion can be activated in that case with the value `@t{yes=long-list}' +(Typically, the value `@t{select=long-list}' described later is more +useful as it provides control over scrolling.) + +@noindent +Similarly, with any of the `false' values (as in `@t{no=10}'), menu +completion will @emph{not} be used if there are @var{num} or more matches. + +@noindent +The value of this widget also controls menu selection, as implemented by +the @t{zsh/complist} module. The following values may appear either +alongside or instead of the values above. + +@noindent +If the value contains the string `@t{select}', menu selection +will be started unconditionally. + +@noindent +In the form `@t{select=}@var{num}', menu selection will only be started if +there are at least @var{num} matches. If the values for more than one +tag provide a number, the smallest number is taken. + +@noindent +Menu selection can be turned off explicitly by defining a value +containing the string`@t{no-select}'. + +@noindent +It is also possible to start menu selection only if the list of +matches does not fit on the screen by using the value +`@t{select=long}'. To start menu selection even if the current widget +only performs listing, use the value `@t{select=long-list}'. + +@noindent +To turn on menu completion or menu selection when there are a certain +number of matches @emph{or} the list of matches does not fit on the +screen, both of `@t{yes=}' and `@t{select=}' may be given twice, once +with a number and once with `@t{long}' or `@t{long-list}'. + +@noindent +Finally, it is possible to activate two special modes of menu selection. +The word `@t{interactive}' in the value causes interactive mode +to be entered immediately when menu selection is started; see +@ref{The zsh/complist Module} +for a description of interactive mode. Including the string +`@t{search}' does the same for incremental search mode. To select backward +incremental search, include the string `@t{search-backward}'. + +@kindex muttrc, completion style +@item @t{muttrc} +If set, gives the location of the mutt configuration file. It defaults +to `@t{~/.muttrc}'. + +@kindex numbers, completion style +@item @t{numbers} +This is used with the @t{jobs} tag. If it is `true', the shell will +complete job numbers instead of the shortest unambiguous prefix +of the job command text. If the value is a number, job numbers will +only be used if that many words from the job descriptions are required to +resolve ambiguities. For example, if the value is `@t{1}', strings will +only be used if all jobs differ in the first word on their command lines. + +@kindex old-list, completion style +@item @t{old-list} +This is used by the @t{_oldlist} completer. If it is set to `@t{always}', +then standard widgets which perform listing will retain the current list of +matches, however they were generated; this can be turned off explicitly +with the value `@t{never}', giving the behaviour without the @t{_oldlist} +completer. If the style is unset, or any other value, then the existing +list of completions is displayed if it is not already; otherwise, the +standard completion list is generated; this is the default behaviour of +@t{_oldlist}. However, if there is an old list and this style contains +the name of the completer function that generated the list, then the +old list will be used even if it was generated by a widget which does +not do listing. + +@noindent +For example, suppose you type @t{^Xc} to use the @t{_correct_word} +widget, which generates a list of corrections for the word under the +cursor. Usually, typing @t{^D} would generate a standard list of +completions for the word on the command line, and show that. With +@t{_oldlist}, it will instead show the list of corrections already +generated. + +@noindent +As another example consider the @t{_match} completer: with the +@t{insert-unambiguous} style set to `true' it inserts only a common prefix +string, if there is any. However, this may remove parts of the original +pattern, so that further completion could produce more matches than on the +first attempt. By using the @t{_oldlist} completer and setting this style +to @t{_match}, the list of matches generated on the first attempt will be +used again. + +@kindex old-matches, completion style +@item @t{old-matches} +This is used by the @t{_all_matches} completer to decide if an old +list of matches should be used if one exists. This is selected by one of +the `true' values or by the string `@t{only}'. If +the value is `@t{only}', @t{_all_matches} will only use an old list +and won't have any effect on the list of matches currently being +generated. + +@noindent +If this style is set it is generally unwise to call the @t{_all_matches} +completer unconditionally. One possible use is for either this style or +the @t{completer} style to be defined with the @t{-e} option to +@t{zstyle} to make the style conditional. + +@kindex old-menu, completion style +@item @t{old-menu} +This is used by the @t{_oldlist} completer. It controls how menu +completion behaves when a completion has already been inserted and the +user types a standard completion key such as @t{TAB}. The default +behaviour of @t{_oldlist} is that menu completion always continues +with the existing list of completions. If this style is set to +`false', however, a new completion is started if the old list was +generated by a different completion command; this is the behaviour without +the @t{_oldlist} completer. + +@noindent +For example, suppose you type @t{^Xc} to generate a list of corrections, +and menu completion is started in one of the usual ways. Usually, or with +this style set to `false', typing @t{TAB} at this point would start +trying to complete the line as it now appears. With @t{_oldlist}, it +instead continues to cycle through the list of corrections. + +@kindex original, completion style +@item @t{original} +This is used by the @t{_approximate} and @t{_correct} +completers to decide if the original string should be added as +a possible completion. Normally, this is done only if there are +at least two possible corrections, but if this style is set to `true', it +is always added. Note that the style will be examined with the +completer field in the context name set to @t{correct-}@var{num} or +@t{approximate-}@var{num}, where @var{num} is the number of errors that +were accepted. + +@kindex packageset, completion style +@item @t{packageset} +This style is used when completing arguments of the Debian `@t{dpkg}' +program. It contains an override for the default package set +for a given context. For example, + +@noindent +@example +zstyle ':completion:*:complete:dpkg:option--status-1:*' \ + packageset avail +@end example + +@noindent +causes available packages, rather than only installed packages, +to be completed for `@t{dpkg -}@t{-status}'. + +@kindex path, completion style +@item @t{path} +The function that completes color names uses this style with the +@t{colors} tag. The value should be the pathname of a file +containing color names in the format of an X11 @t{rgb.txt} file. If +the style is not set but this file is found in one of various standard +locations it will be used as the default. + +@kindex path-completion, completion style +@item @t{path-completion} +This is used by filename completion. By default, filename completion +examines all components of a path to see if there are completions of +that component. For example, @t{/u/b/z} can be completed to +@t{/usr/bin/zsh}. Explicitly setting this style to `false' inhibits this +behaviour for path components up to the @t{/} before the cursor; this +overrides the setting of @t{accept-exact-dirs}. + +@noindent +Even with the style set to `false', it is still possible to complete +multiple paths by setting the option @t{COMPLETE_IN_WORD} and moving the +cursor back to the first component in the path to be completed. For +example, @t{/u/b/z} can be completed to @t{/usr/bin/zsh} if the cursor is +after the @t{/u}. + +@kindex pine-directory, completion style +@item @t{pine-directory} +If set, specifies the directory containing PINE mailbox files. There +is no default, since recursively searching this directory is inconvenient +for anyone who doesn't use PINE. + +@kindex ports, completion style +@item @t{ports} +A list of Internet service names (network ports) to complete. If this is +not set, service names are taken from the file `@t{/etc/services}'. + +@kindex prefix-hidden, completion style +@item @t{prefix-hidden} +This is used for certain completions which share a common prefix, for +example command options beginning with dashes. If it is `true', the +prefix will not be shown in the list of matches. + +@noindent +The default value for this style is `false'. + +@kindex prefix-needed, completion style +@item @t{prefix-needed} +This style is also relevant for matches with a common prefix. If it is +set to `true' this common prefix must be typed by the user to generate +the matches. + +@noindent +The style is applicable to the @t{options}, @t{signals}, @t{jobs}, +@t{functions}, and @t{parameters} completion tags. + +@noindent +For command options, this means that the initial `@t{-}', `@t{+}', or +`@t{-}@t{-}' must be typed explicitly before option names will be +completed. + +@noindent +For signals, an initial `@t{-}' is required before signal names will +be completed. + +@noindent +For jobs, an initial `@t{%}' is required before job names will be +completed. + +@noindent +For function and parameter names, an initial `@t{_}' or `@t{.}' is +required before function or parameter names starting with those +characters will be completed. + +@noindent +The default value for this style is `false' for @t{function} and +@t{parameter} completions, and `true' otherwise. + +@kindex preserve-prefix, completion style +@item @t{preserve-prefix} +This style is used when completing path names. Its value should be a +pattern matching an initial prefix of the word to complete that should +be left unchanged under all circumstances. For example, on some Unices +an initial `@t{//}' (double slash) has a special meaning; setting +this style to the string `@t{//}' will preserve it. As another example, +setting this style to `@t{?:/}' under Cygwin would allow completion +after `@t{a:/...}' and so on. + +@kindex range, completion style +@item @t{range} +This is used by the @t{_history} completer and the +@t{_history_complete_word} bindable command to decide which words +should be completed. + +@noindent +If it is a single number, only the last @var{N} words from the history +will be completed. + +@noindent +If it is a range of the form `@var{max}@t{:}@var{slice}', +the last @var{slice} words will be completed; then if that +yields no matches, the @var{slice} words before those will be tried and +so on. This process stops either when at least one match has been +found, or @var{max} words have been tried. + +@noindent +The default is to complete all words from the history at once. + +@kindex recursive-files, completion style +@item @t{recursive-files} +If this style is set, its value is an array of patterns to be +tested against `@t{$PWD/}': note the trailing slash, which allows +directories in the pattern to be delimited unambiguously by including +slashes on both sides. If an ordinary file completion fails +and the word on the command line does not yet have a directory part to its +name, the style is retrieved using the same tag as for the completion +just attempted, then the elements tested against @t{$PWD/} in turn. +If one matches, then the shell reattempts completion by prepending the word +on the command line with each directory in the expansion of @t{**/*(/)} +in turn. Typically the elements of the style will be set to restrict +the number of directories beneath the current one to a manageable +number, for example `@t{*/.git/*}'. + +@noindent +For example, + +@noindent +@example +zstyle ':completion:*' recursive-files '*/zsh/*' +@end example + +@noindent +If the current directory is @t{/home/pws/zsh/Src}, then +@t{zle_tr<TAB>} can be completed to @t{Zle/zle_tricky.c}. + +@kindex regular, completion style +@item @t{regular} +This style is used by the @t{_expand_alias} completer and bindable +command. If set to `true' (the default), regular aliases will be +expanded but only in command position. If it is set to `false', +regular aliases will never be expanded. If it is set to `@t{always}', +regular aliases will be expanded even if not in command position. + +@kindex rehash, completion style +@item @t{rehash} +If this is set when completing external commands, the internal +list (hash) of commands will be updated for each search by issuing +the @t{rehash} command. There is a speed penalty for this which +is only likely to be noticeable when directories in the path have +slow file access. + +@kindex remote-access, completion style +@item @t{remote-access} +If set to `false', certain commands will be prevented from making +Internet connections to retrieve remote information. This includes the +completion for the @t{CVS} command. + +@noindent +It is not always possible to know if connections are in fact to a remote +site, so some may be prevented unnecessarily. + +@kindex remove-all-dups, completion style +@item @t{remove-all-dups} +The @t{_history_complete_word} bindable command and the @t{_history} +completer use this to decide if all duplicate matches should be +removed, rather than just consecutive duplicates. + +@kindex select-prompt, completion style +@item @t{select-prompt} +If this is set for the @t{default} tag, its +value will be displayed during menu selection (see the @t{menu} style +above) when the completion list does not fit on the screen as a +whole. The same escapes as for the @t{list-prompt} style are +understood, except that the numbers refer to the match or line the mark is +on. A default prompt is used when the value is the empty string. + +@kindex select-scroll, completion style +@item @t{select-scroll} +This style is tested for the @t{default} tag and determines how a +completion list is scrolled during a menu selection (see the @t{menu} +style above) when the completion list does not fit on the screen as a +whole. If the value is `@t{0}' (zero), the list is scrolled by +half-screenfuls; if it is a positive integer, the list is scrolled by the +given number of lines; if it is a negative number, the list is scrolled by a +screenful minus the absolute value of the given number of lines. +The default is to scroll by single lines. + +@kindex separate-sections, completion style +@item @t{separate-sections} +This style is used with the @t{manuals} tag when completing names of +manual pages. If it is `true', entries for different sections are +added separately using tag names of the form `@t{manuals.}@var{X}', +where @var{X} is the section number. When the @t{group-name} style is +also in effect, pages from different sections will appear separately. +This style is also used similarly with the @t{words} style when +completing words for the dict command. It allows words from different +dictionary databases to be added separately. See also @t{insert-sections}. + +@noindent +The default for this style is `false'. + +@kindex show-ambiguity, completion style +@item @t{show-ambiguity} +If the @t{zsh/complist} module is loaded, this style can be used to +highlight the first ambiguous character in completion lists. The +value is either a color indication such as those supported by the +@t{list-colors} style or, with a value of `true', a default of +underlining is selected. The highlighting is only applied if the +completion display strings correspond to the actual matches. + +@kindex show-completer, completion style +@item @t{show-completer} +Tested whenever a new completer is tried. If it is `true', the completion +system outputs a progress message in the listing area showing what +completer is being tried. The message will be overwritten by any output +when completions are found and is removed after completion is finished. + +@kindex single-ignored, completion style +@item @t{single-ignored} +This is used by the @t{_ignored} completer when there is only one match. +If its value is `@t{show}', the single match will be +displayed but not inserted. If the value is `@t{menu}', then the single +match and the original string are both added as matches and menu completion +is started, making it easy to select either of them. + +@kindex sort, completion style +@item @t{sort} +This allows the standard ordering of matches to be overridden. + +@noindent +If its value is `@t{true}' or `@t{false}', sorting is enabled or disabled. +Additionally the values associated with the `@t{-o}' option to @t{compadd} can +also be listed: @t{match}, @t{nosort}, @t{numeric}, @t{reverse}. If it is not +set for the context, the standard behaviour of the calling widget is used. + +@noindent +The style is tested first against the full context including the tag, and +if that fails to produce a value against the context without the tag. + +@noindent +In many cases where a calling widget explicitly selects a particular ordering +in lieu of the default, a value of `@t{true}' is not honoured. An example of +where this is not the case is for command history where the default of sorting +matches chronologically may be overridden by setting the style to `true'. + +@noindent +In the @t{_expand} completer, if it is set to +`true', the expansions generated will always be sorted. If it is set +to `@t{menu}', then the expansions are only sorted when they are offered +as single strings but not in the string containing all possible +expansions. + +@kindex special-dirs, completion style +@item @t{special-dirs} +Normally, the completion code will not produce the directory names +`@t{.}' and `@t{..}' as possible completions. If this style is set to +`true', it will add both `@t{.}' and `@t{..}' as possible completions; +if it is set to `@t{..}', only `@t{..}' will be added. + +@noindent +The following example sets @t{special-dirs} to `@t{..}' when the +current prefix is empty, is a single `@t{.}', or consists only of a path +beginning with `@t{../}'. Otherwise the value is `false'. + +@noindent +@example +zstyle -e ':completion:*' special-dirs \ + '[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)' +@end example + +@kindex squeeze-slashes, completion style +@item @t{squeeze-slashes} +If set to `true', sequences of slashes in filename paths (for example in +`@t{foo//bar}') will be treated as a single slash. This is the usual +behaviour of UNIX paths. However, by default the file completion +function behaves as if there were a `@t{*}' between the slashes. + +@kindex stop, completion style +@item @t{stop} +If set to `true', the @t{_history_complete_word} bindable +command will stop once when reaching the beginning or end of the +history. Invoking @t{_history_complete_word} will then wrap around to +the opposite end of the history. If this style is set to `false' (the +default), @t{_history_complete_word} will loop immediately as in a +menu completion. + +@kindex strip-comments, completion style +@item @t{strip-comments} +If set to `true', this style causes non-essential comment text to be +removed from completion matches. Currently it is only used when +completing e-mail addresses where it removes any display name from the +addresses, cutting them down to plain @var{user@@host} form. + +@kindex subst-globs-only, completion style +@item @t{subst-globs-only} +This is used by the @t{_expand} completer. If it is set to `true', +the expansion will only be used if it resulted from globbing; hence, +if expansions resulted from the use of the @t{substitute} style +described below, but these were not further changed by globbing, the +expansions will be rejected. + +@noindent +The default for this style is `false'. + +@kindex substitute, completion style +@item @t{substitute} +This boolean style controls whether the @t{_expand} completer will +first try to expand all substitutions in the string (such as +`@t{$(}@var{...}@t{)}' and `@t{$@{}@var{...}@t{@}}'). + +@noindent +The default is `true'. + +@kindex suffix, completion style +@item @t{suffix} +This is used by the @t{_expand} completer if the word starts with a +tilde or contains a parameter expansion. If it is set to `true', the +word will only be expanded if it doesn't have a suffix, i.e. if it is +something like `@t{~foo}' or `@t{$foo}' rather than `@t{~foo/}' or +`@t{$foo/bar}', unless that suffix itself contains characters eligible +for expansion. The default for this style is `true'. + +@kindex tag-order, completion style +@item @t{tag-order} +This provides a mechanism for sorting how the tags available in a +particular context will be used. + +@noindent +The values for the style are sets of space-separated lists of tags. +The tags in each value will be tried at the same time; if no match is +found, the next value is used. (See the @t{file-patterns} style for +an exception to this behavior.) + +@noindent +For example: + +@noindent +@example +zstyle ':completion:*:complete:-command-:*:*' tag-order \ + 'commands functions' +@end example + +@noindent +specifies that completion in command position first offers +external commands and shell functions. Remaining tags will be tried if +no completions are found. + +@noindent +In addition to tag names, each string in the value may take one of the +following forms: + +@noindent +@table @asis +@item @t{-} +If any value consists of only a hyphen, +then @emph{only} the tags specified in the other values are +generated. Normally all tags not explicitly selected are tried last +if the specified tags fail to generate any matches. This means +that a single value consisting only of a single hyphen +turns off completion. + +@item @t{!} @var{tags}... +A string starting with an exclamation mark +specifies names of tags that are @emph{not} to be used. The effect is +the same as if all other possible tags for the context had been +listed. + +@item @var{tag}@t{:}@var{label} ... +Here, @var{tag} is one of the standard tags and @var{label} is an +arbitrary name. Matches are generated as normal but the name @var{label} +is used in contexts instead of @var{tag}. This is not useful in words +starting with @t{!}. + +@noindent +If the @var{label} starts with a hyphen, the @var{tag} is prepended to the +@var{label} to form the name used for lookup. This can be +used to make the completion system try a certain tag more than once, +supplying different style settings for each attempt; see below for an +example. + +@item @var{tag}@t{:}@var{label}@t{:}@var{description} +As before, but @t{description} will replace the `@t{%d}' in +the value of the @t{format} style instead of the default description +supplied by the completion function. Spaces in the description must +be quoted with a backslash. A `@t{%d}' appearing +in @var{description} is replaced with the description given by the +completion function. + +@end table + +@noindent +In any of the forms above the tag may be a pattern or several +patterns in the form `@t{@{}@var{pat1}@t{,}@var{pat2...}@t{@}}'. In this +case all matching tags will be used except +for any given explicitly in the same string. + +@noindent +One use of these features is to try +one tag more than once, setting other styles differently on +each attempt, but still to use all the other tags without having to +repeat them all. For example, to make completion of function names in +command position ignore all the completion functions starting with an +underscore the first time completion is tried: + +@noindent +@example +zstyle ':completion:*:*:-command-:*:*' tag-order \ + 'functions:-non-comp *' functions +zstyle ':completion:*:functions-non-comp' \ + ignored-patterns '_*' +@end example + +@noindent +On the first attempt, all tags will be offered but the @t{functions} tag +will be replaced by @t{functions-non-comp}. The @t{ignored-patterns} style +is set for this tag to exclude functions starting with an underscore. +If there are no matches, the second value of the +@t{tag-order} style is used which completes functions using the default +tag, this time presumably including all function names. + +@noindent +The matches for one tag can be split into different groups. For example: + +@noindent +@example +zstyle ':completion:*' tag-order \ + 'options:-long:long\ options + options:-short:short\ options + options:-single-letter:single\ letter\ options' +zstyle ':completion:*:options-long' \ + ignored-patterns '[-+](|-|[^-]*)' +zstyle ':completion:*:options-short' \ + ignored-patterns '--*' '[-+]?' +zstyle ':completion:*:options-single-letter' \ + ignored-patterns '???*' +@end example + +@noindent +With the @t{group-names} style set, options beginning with +`@t{-}@t{-}', options beginning with a single `@t{-}' or `@t{+}' but +containing multiple characters, and single-letter options will be +displayed in separate groups with different descriptions. + +@noindent +Another use of patterns is to +try multiple match specifications one after another. The +@t{matcher-list} style offers something similar, but it is tested very +early in the completion system and hence can't be set for single +commands nor for more specific contexts. Here is how to +try normal completion without any match specification and, if that +generates no matches, try again with case-insensitive matching, restricting +the effect to arguments of the command @t{foo}: + +@noindent +@example +zstyle ':completion:*:*:foo:*:*' tag-order '*' '*:-case' +zstyle ':completion:*-case' matcher 'm:@{a-z@}=@{A-Z@}' +@end example + +@noindent +First, all the tags offered when completing after @t{foo} are tried using +the normal tag name. If that generates no matches, the second value of +@t{tag-order} is used, which tries all tags again except that this time +each has @t{-case} appended to its name for lookup of styles. Hence this +time the value for the @t{matcher} style from the second call to @t{zstyle} +in the example is used to make completion case-insensitive. + +@noindent +It is possible to use the @t{-e} option of the @t{zstyle} builtin +command to specify conditions for the use of particular tags. For +example: + +@noindent +@example +zstyle -e '*:-command-:*' tag-order ' + if [[ -n $PREFIX$SUFFIX ]]; then + reply=( ) + else + reply=( - ) + fi' +@end example + +@noindent +Completion in command position will be attempted only if the string +typed so far is not empty. This is tested using the @t{PREFIX} +special parameter; see +@ref{Completion Widgets} +for a description of parameters which are special inside completion widgets. +Setting @t{reply} to an empty array provides the default +behaviour of trying all tags at once; setting it to an +array containing only a hyphen disables the use of all tags and hence of +all completions. + +@noindent +If no @t{tag-order} style has been defined for a context, the strings +`@t{(|*-)argument-* (|*-)option-* values}' and `@t{options}' plus all +tags offered by the completion function will be used to provide a +sensible default behavior that causes arguments (whether normal command +arguments or arguments of options) to be completed before option names for +most commands. + +@kindex urls, completion style +@item @t{urls} +This is used together with the @t{urls} tag by +functions completing URLs. + +@noindent +If the value consists of more than one string, or if the only string +does not name a file or directory, the strings are used as the URLs to +complete. + +@noindent +If the value contains only one string which is the name of a normal +file the URLs are taken from that file (where the URLs may be +separated by white space or newlines). + +@noindent +Finally, if the only string in the value names a directory, the +directory hierarchy rooted at this directory gives the completions. The +top level directory should be the file access method, such as +`@t{http}', `@t{ftp}', `@t{bookmark}' and so on. In many cases the next +level of directories will be a filename. The directory hierarchy can +descend as deep as necessary. + +@noindent +For example, + +@noindent +@example +zstyle ':completion:*' urls ~/.urls +mkdir -p ~/.urls/ftp/ftp.zsh.org/pub + +@end example + +@noindent +allows completion of all the components of the URL +@t{ftp://ftp.zsh.org/pub} after suitable commands such as +`@t{netscape}' or `@t{lynx}'. Note, however, that access methods and +files are completed separately, so if the @t{hosts} style is set hosts +can be completed without reference to the @t{urls} style. + +@noindent +See the description in the function @t{_urls} itself +for more information (e.g. `@t{more $^fpath/_urls(N)}'). + +@kindex use-cache, completion style +@item @t{use-cache} +If this is set, the completion caching layer is activated for any completions +which use it (via the @t{_store_cache}, @t{_retrieve_cache}, and +@t{_cache_invalid} functions). The directory containing the cache +files can be changed with the @t{cache-path} style. + +@kindex use-compctl, completion style +@item @t{use-compctl} +If this style is set to a string @emph{not} equal to @t{false}, @t{0}, +@t{no}, and @t{off}, the completion system may use any completion +specifications defined with the @t{compctl} builtin command. If the +style is unset, this is done only if the @t{zsh/compctl} module +is loaded. The string may also contain the substring `@t{first}' to +use completions defined with `@t{compctl -T}', and the substring +`@t{default}' to use the completion defined with `@t{compctl -D}'. + +@noindent +Note that this is only intended to smooth the transition from +@t{compctl} to the new completion system and may disappear in the +future. + +@noindent +Note also that the definitions from @t{compctl} will only be used if +there is no specific completion function for the command in question. For +example, if there is a function @t{_foo} to complete arguments to the +command @t{foo}, @t{compctl} will never be invoked for @t{foo}. +However, the @t{compctl} version will be tried if @t{foo} only uses +default completion. + +@kindex use-ip, completion style +@item @t{use-ip} +By default, the function @t{_hosts} that completes host names strips +IP addresses from entries read from host databases such as NIS and +ssh files. If this style is `true', the corresponding IP addresses +can be completed as well. This style is not use in any context +where the @t{hosts} style is set; note also it must be set before +the cache of host names is generated (typically the first completion +attempt). + +@kindex users, completion style +@item @t{users} +This may be set to a list of usernames to be completed. +If it is not set all usernames will be completed. +Note that if it is set only that list of users will be completed; +this is because on some systems querying all users can take +a prohibitive amount of time. + +@kindex users-hosts, completion style +@item @t{users-hosts} +The values of this style should be of the form +`@var{user}@t{@@}@var{host}' or `@var{user}@t{:}@var{host}'. It is used for +commands that need pairs of +user- and hostnames. These commands will complete usernames from this +style (only), and will restrict subsequent hostname completion to hosts +paired with that user in one of the values of the style. + +@noindent +It is possible to group values for sets of commands which allow a remote +login, such as @t{rlogin} and @t{ssh}, by using the @t{my-accounts} tag. +Similarly, values for sets of commands which usually refer to the +accounts of other people, such as @t{talk} and @t{finger}, can be +grouped by using the @t{other-accounts} tag. More ambivalent commands +may use the @t{accounts} tag. + +@kindex users-hosts-ports, completion style +@item @t{users-hosts-ports} +Like @t{users-hosts} but used for commands like @t{telnet} and +containing strings of the form `@var{user}@t{@@}@var{host}@t{:}@var{port}'. + +@kindex verbose, completion style +@item @t{verbose} +If set, as it is by default, the completion listing is more verbose. +In particular many commands show descriptions for options if this +style is `true'. + +@kindex word, completion style +@item @t{word} +This is used by the @t{_list} completer, which prevents the insertion of +completions until a second completion attempt when the line has not +changed. The normal way of finding out if the line has changed is to +compare its entire contents between the two occasions. If this style is +`true', the comparison is instead performed only on the current word. +Hence if completion is performed on another word with the same contents, +completion will not be delayed. + +@end table + +@noindent +@node Control Functions, Bindable Commands, Completion System Configuration, Completion System + +@section Control Functions +@noindent +@cindex completion system, choosing completers + +@noindent +The initialization script @t{compinit} redefines all the widgets +which perform completion to call the supplied widget function +@t{_main_complete}. This function acts as a wrapper calling the +so-called `completer' functions that generate matches. If +@t{_main_complete} is called with arguments, these are taken as the +names of completer functions to be called in the order given. If no +arguments are given, the set of functions to try is taken from the +@t{completer} style. For example, to use normal completion and +correction if that doesn't generate any matches: + +@noindent +@example +zstyle ':completion:*' completer _complete _correct +@end example + +@noindent +after calling @t{compinit}. The default value for this style is +`@t{_complete _ignored}', i.e. normally only ordinary completion is tried, +first with the effect of the @t{ignored-patterns} style and then without +it. The @t{_main_complete} function uses the return status of the completer +functions to decide if other completers should be called. If the return +status is zero, no other completers are tried and the @t{_main_complete} +function returns. + +@noindent +If the first argument to @t{_main_complete} is a single hyphen, the +arguments will not be taken as names of completers. Instead, the +second argument gives a name to use in the @var{completer} field of the +context and the other arguments give a command name and arguments to +call to generate the matches. + +@noindent +The following completer functions are contained in the distribution, +although users may write their own. Note that in contexts the leading +underscore is stripped, for example basic completion is performed in the +context `@t{:completion::complete:}@var{...}'. + +@noindent +@cindex completion system, completers +@table @asis +@findex _all_matches +@item @t{_all_matches} +This completer can be used to add a string consisting of all other +matches. As it influences later completers it must appear as the first +completer in the list. The list of all matches is affected by the +@t{avoid-completer} and @t{old-matches} styles described above. + +@noindent +It may be useful to use the @t{_generic} function described below +to bind @t{_all_matches} to its own keystroke, for example: + +@noindent +@example +zle -C all-matches complete-word _generic +bindkey '^Xa' all-matches +zstyle ':completion:all-matches:*' old-matches only +zstyle ':completion:all-matches::::' completer _all_matches +@end example + +@noindent +Note that this does not generate completions by itself: first use +any of the standard ways of generating a list of completions, +then use @t{^Xa} to show all matches. It is possible instead to +add a standard completer to the list and request that the +list of all matches should be directly inserted: + +@noindent +@example +zstyle ':completion:all-matches::::' completer \ + _all_matches _complete +zstyle ':completion:all-matches:*' insert true +@end example + +@noindent +In this case the @t{old-matches} style should not be set. + +@findex _approximate +@item @t{_approximate} +This is similar to the basic @t{_complete} completer but allows the +completions to undergo corrections. The maximum number of errors can be +specified by the @t{max-errors} style; see the description of +approximate matching in +@ref{Filename Generation} +for how errors are counted. Normally this completer will only be tried +after the normal @t{_complete} completer: + +@noindent +@example +zstyle ':completion:*' completer _complete _approximate +@end example + +@noindent +This will give correcting completion if and only if +normal completion yields no possible completions. When +corrected completions are found, the completer will normally start +menu completion allowing you to cycle through these strings. + +@noindent +This completer uses the tags @t{corrections} and @t{original} when +generating the possible corrections and the original string. The +@t{format} style for the former may contain the additional sequences +`@t{%e}' and `@t{%o}' which will be replaced by the number of errors +accepted to generate the corrections and the original string, +respectively. + +@noindent +The completer progressively increases the number of errors allowed up to +the limit by the @t{max-errors} style, hence if a completion is found +with one error, no completions with two errors will be shown, and so on. +It modifies the completer name in the context to indicate the number of +errors being tried: on the first try the completer field contains +`@t{approximate-1}', on the second try `@t{approximate-2}', and so on. + +@noindent +When @t{_approximate} is called from another function, the number of +errors to accept may be passed with the @t{-a} option. The argument +is in the same format as the @t{max-errors} style, all in one string. + +@noindent +Note that this completer (and the @t{_correct} completer mentioned +below) can be quite expensive to call, especially when a large number +of errors are allowed. One way to avoid this is to set up the +@t{completer} style using the @t{-e} option to zstyle so that some +completers are only used when completion is attempted a second time on +the same string, e.g.: + +@noindent +@example +zstyle -e ':completion:*' completer ' + if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then + _last_try="$HISTNO$BUFFER$CURSOR" + reply=(_complete _match _prefix) + else + reply=(_ignored _correct _approximate) + fi' +@end example + +@noindent +This uses the @t{HISTNO} parameter and the @t{BUFFER} and @t{CURSOR} +special parameters that are available inside zle and completion +widgets to find out if the command line hasn't changed since the last +time completion was tried. Only then are the @t{_ignored}, +@t{_correct} and @t{_approximate} completers called. + +@findex _canonical_paths +@item @t{_canonical_paths} [ @t{-A} @var{var} ] [ @t{-N} ] [ @t{-MJV12nfX} ] @var{tag} @var{descr} [ @var{paths} ... ] +This completion function completes all paths given to it, and also tries to +offer completions which point to the same file as one of the paths given +(relative path when an absolute path is given, and vice versa; when @t{..}'s +are present in the word to be completed; and some paths got from symlinks). + +@noindent +@t{-A}, if specified, takes the paths from the array variable specified. Paths can +also be specified on the command line as shown above. @t{-N}, if specified, +prevents canonicalizing the paths given before using them for completion, in +case they are already so. The options @t{-M}, @t{-J}, @t{-V}, @t{-1}, @t{-2}, +@t{-n}, @t{-F}, @t{-X} are passed to @t{compadd}. + +@noindent +See @t{_description} for a description of @var{tag} and @var{descr}. + +@findex _cmdambivalent +@item @t{_cmdambivalent} +Completes the remaining positional arguments as an external command. +The external command and its arguments are completed as separate arguments +(in a manner appropriate for completing @t{/usr/bin/env}) +if there are two or more remaining positional arguments on the command line, +and as a quoted command string (in the manner of @t{system(...)}) otherwise. +See also @t{_cmdstring} and @t{_precommand}. + +@noindent +This function takes no arguments. + +@findex _cmdstring +@item @t{_cmdstring} +Completes an external command as a single argument, as for +@t{system(...)}. + +@findex _complete +@item @t{_complete} +This completer generates all possible completions in a context-sensitive +manner, i.e. using the settings defined with the @t{compdef} function +explained above and the current settings of all special parameters. +This gives the normal completion behaviour. + +@noindent +To complete arguments of commands, @t{_complete} uses the utility function +@t{_normal}, which is in turn responsible for finding the particular +function; it is described below. Various contexts of the form +@t{-}@var{context}@t{-} are handled specifically. These are all +mentioned above as possible arguments to the @t{#compdef} tag. + +@noindent +Before trying to find a function for a specific context, @t{_complete} +checks if the parameter `@t{compcontext}' is set. Setting +`@t{compcontext}' allows the usual completion dispatching to be +overridden which is useful in places such as a function that uses +@t{vared} for input. If it is set to an array, the elements are taken +to be the possible matches which will be completed using the tag +`@t{values}' and the description `@t{value}'. If it is set to an +associative array, the keys are used as the possible completions and +the values (if non-empty) are used as descriptions for the matches. If +`@t{compcontext}' is set to a string containing colons, it should be of +the form `@var{tag}@t{:}@var{descr}@t{:}@var{action}'. In this case the +@var{tag} and @var{descr} give the tag and description to use and the +@var{action} indicates what should be completed in one of the forms +accepted by the @t{_arguments} utility function described below. + +@noindent +Finally, if `@t{compcontext}' is set to a string without colons, the +value is taken as the name of the context to use and the function +defined for that context will be called. For this purpose, there is a +special context named @t{-command-line-} that completes whole command +lines (commands and their arguments). This is not used by the completion +system itself but is nonetheless handled when explicitly called. + +@findex _correct +@item @t{_correct} +Generate corrections, but not completions, for the current word; this is +similar to @t{_approximate} but will not allow any number of extra +characters at the cursor as that completer does. The effect is +similar to spell-checking. It is based on @t{_approximate}, but the +completer field in the context name is @t{correct}. + +@noindent +For example, with: + +@noindent +@example +zstyle ':completion:::::' completer \ + _complete _correct _approximate +zstyle ':completion:*:correct:::' max-errors 2 not-numeric +zstyle ':completion:*:approximate:::' max-errors 3 numeric +@end example + +@noindent +correction will accept up to two errors. If a numeric argument is +given, correction will not be performed, but correcting completion +will be, and will accept as many errors as given by the numeric +argument. Without a numeric argument, first correction and then +correcting completion will be tried, with the first one accepting two +errors and the second one accepting three errors. + +@noindent +When @t{_correct} is called as a function, the number of errors to accept +may be given following the @t{-a} option. The argument is in the same +form a values to the @t{accept} style, all in one string. + +@noindent +This completer function is intended to be used without the +@t{_approximate} completer or, as in the example, just before +it. Using it after the @t{_approximate} completer is useless since +@t{_approximate} will at least generate the corrected strings +generated by the @t{_correct} completer --- and probably more. + +@findex _expand +@item @t{_expand} +This completer function does not really perform completion, but instead +checks if the word on the command line is eligible for expansion and, +if it is, gives detailed control over how this expansion is done. For +this to happen, the completion system needs to be invoked with +@t{complete-word}, not @t{expand-or-complete} (the default binding for +@t{TAB}), as otherwise the string will be expanded by the shell's +internal mechanism before the completion system is started. +Note also this completer should be called before the @t{_complete} +completer function. + +@noindent +The tags used when generating expansions are @t{all-expansions} for the +string containing all possible expansions, @t{expansions} when adding +the possible expansions as single matches and @t{original} when adding +the original string from the line. The order in which these strings are +generated, if at all, can be controlled by the @t{group-order} and +@t{tag-order} styles, as usual. + +@noindent +The format string for @t{all-expansions} and for @t{expansions} may +contain the sequence `@t{%o}' which will be replaced by the original +string from the line. + +@noindent +The kind of expansion to be tried is controlled by the @t{substitute}, +@t{glob} and @t{subst-globs-only} styles. + +@noindent +It is also possible to call @t{_expand} as a function, in which case the +different modes may be selected with options: @t{-s} for +@t{substitute}, @t{-g} for @t{glob} and @t{-o} for @t{subst-globs-only}. + +@findex _expand_alias +@item @t{_expand_alias} +If the word the cursor is on is an alias, it is expanded and no other +completers are called. The types of aliases which are to be expanded can +be controlled with the styles @t{regular}, @t{global} and @t{disabled}. + +@noindent +This function is also a bindable command, see +@ref{Bindable Commands}. + +@findex _extensions +@item @t{_extensions} +If the cursor follows the string `@t{*.}', filename extensions are +completed. The extensions are taken from files in current directory or a +directory specified at the beginning of the current word. For exact matches, +completion continues to allow other completers such as @t{_expand} to +expand the pattern. The standard @t{add-space} and @t{prefix-hidden} +styles are observed. + +@findex _external_pwds +@item @t{_external_pwds} +Completes current directories of other zsh processes belonging to the +current user. + +@noindent +This is intended to be used via @t{_generic}, bound to a custom key +combination. Note that pattern matching is enabled so matching is +performed similar to how it works with the @t{_match} completer. + +@findex _history +@item @t{_history} +Complete words from the shell's command history. This completer +can be controlled by the @t{remove-all-dups}, and @t{sort} styles as for the +@t{_history_complete_word} bindable command, see +@ref{Bindable Commands} +and +@ref{Completion System Configuration}. + +@findex _ignored +@item @t{_ignored} +The @t{ignored-patterns} style can be set to a list of patterns which are +compared against possible completions; matching ones are removed. +With this completer those matches can be reinstated, as +if no @t{ignored-patterns} style were set. The completer actually +generates its own list of matches; which completers are invoked +is determined in the same way as for the @t{_prefix} completer. +The @t{single-ignored} style is also available as described above. + +@findex _list +@item @t{_list} +This completer allows the insertion of matches to be delayed until +completion is attempted a second time without the word on the line +being changed. On the first attempt, only the list of matches will be +shown. It is affected by the styles @t{condition} and @t{word}, see +@ref{Completion System Configuration}. + +@findex _match +@item @t{_match} +This completer is intended to be used after the @t{_complete} +completer. It behaves similarly but the string on the command line may +be a pattern to match against trial completions. This gives the effect +of the @t{GLOB_COMPLETE} option. + +@noindent +Normally completion will be performed by taking the pattern from the line, +inserting a `@t{*}' at the cursor position and comparing the resulting +pattern with the possible completions generated. This can be modified +with the @t{match-original} style described above. + +@noindent +The generated matches will be offered in a menu completion unless the +@t{insert-unambiguous} style is set to `true'; see the description above +for other options for this style. + +@noindent +Note that matcher specifications defined globally or used by the +completion functions (the styles @t{matcher-list} and @t{matcher}) will +not be used. + +@findex _menu +@item @t{_menu} +This completer was written as simple example function to show how menu +completion can be enabled in shell code. However, it has the notable +effect of disabling menu selection which can be useful with +@t{_generic} based widgets. It should be used as the first completer in +the list. Note that this is independent of the setting of the +@t{MENU_COMPLETE} option and does not work with the other menu +completion widgets such as @t{reverse-menu-complete}, or +@t{accept-and-menu-complete}. + +@findex _oldlist +@item @t{_oldlist} +This completer controls how the standard completion widgets behave +when there is an existing list of completions which may have been +generated by a special completion (i.e. a separately-bound completion +command). It allows the ordinary completion keys to continue to use the +list of completions thus generated, instead of producing a new list of +ordinary contextual completions. +It should appear in the list of completers before any of +the widgets which generate matches. It uses two styles: @t{old-list} and +@t{old-menu}, see +@ref{Completion System Configuration}. + +@findex _precommand +@item @t{_precommand} +Complete an external command in word-separated arguments, as for +@t{exec} and @t{/usr/bin/env}. + +@findex _prefix +@item @t{_prefix} +This completer can be used to try completion with the suffix (everything +after the cursor) ignored. In other words, the suffix will not be +considered to be part of the word to complete. The effect is similar +to the @t{expand-or-complete-prefix} command. + +@noindent +The @t{completer} style is used to decide which other completers are to +be called to generate matches. If this style is unset, the list of +completers set for the current context is used --- except, of course, the +@t{_prefix} completer itself. Furthermore, if this completer appears +more than once in the list of completers only those completers not +already tried by the last invocation of @t{_prefix} will be called. + +@noindent +For example, consider this global @t{completer} style: + +@noindent +@example +zstyle ':completion:*' completer \ + _complete _prefix _correct _prefix:foo +@end example + +@noindent +Here, the @t{_prefix} completer tries normal completion but ignoring the +suffix. If that doesn't generate any matches, and neither does +the call to the @t{_correct} completer after it, @t{_prefix} will +be called a second time and, now only trying correction with the +suffix ignored. On the second invocation the completer part of the +context appears as `@t{foo}'. + +@noindent +To use @t{_prefix} as the last resort and try only normal completion +when it is invoked: + +@noindent +@example +zstyle ':completion:*' completer _complete ... _prefix +zstyle ':completion::prefix:*' completer _complete +@end example + +@noindent +The @t{add-space} style is also respected. If it is set to `true' then +@t{_prefix} will insert a space between the matches generated (if any) +and the suffix. + +@noindent +Note that this completer is only useful if the +@t{COMPLETE_IN_WORD} option is set; otherwise, the cursor will +be moved to the end of the current word before the completion code is +called and hence there will be no suffix. + +@findex _user_expand +@item @t{_user_expand} +This completer behaves similarly to the @t{_expand} completer but +instead performs expansions defined by users. The styles @t{add-space} and +@t{sort} styles specific to the @t{_expand} completer are usable with +@t{_user_expand} in addition to other styles handled more generally by +the completion system. The tag @t{all-expansions} is also available. + +@noindent +The expansion depends on the array style @t{user-expand} being defined +for the current context; remember that the context for completers is less +specific than that for contextual completion as the full context has not +yet been determined. Elements of the array may have one of the following +forms: + +@noindent +@table @asis +@item @t{$}@var{hash} + +@var{hash} is the name of an associative array. Note this is not a full +parameter expression, merely a @t{$}, suitably quoted to prevent immediate +expansion, followed by the name of an associative array. If the trial +expansion word matches a key in @var{hash}, the resulting expansion is the +corresponding value. + +@item @var{_func} + +@var{_func} is the name of a shell function whose name must begin with +@t{_} but is not otherwise special to the completion system. The function +is called with the trial word as an argument. If the word is to be +expanded, the function should set the array @t{reply} to a list of +expansions. Optionally, it can set @t{REPLY} to a word that will +be used as a description for the set of expansions. +The return status of the function is irrelevant. + +@end table + +@end table + +@noindent +@node Bindable Commands, Completion Functions, Control Functions, Completion System + +@section Bindable Commands +@noindent +@cindex completion system, bindable commands + +@noindent +In addition to the context-dependent completions provided, which are +expected to work in an intuitively obvious way, there are a few widgets +implementing special behaviour which can be bound separately to keys. The +following is a list of these and their default bindings. + +@noindent +@table @asis +@findex _bash_completions +@item @t{_bash_completions} +This function is used by two widgets, @t{_bash_complete-word} and +@t{_bash_list-choices}. It exists to provide compatibility with +completion bindings in bash. The last character of the binding determines +what is completed: `@t{!}', command names; `@t{$}', environment variables; +`@t{@@}', host names; `@t{/}', file names; `@t{~}' user names. In bash, the +binding preceded by `@t{\e}' gives completion, and preceded by `@t{^X}' +lists options. As some of these bindings clash with standard zsh +bindings, only `@t{\e~}' and `@t{^X~}' are bound by default. To add the +rest, the following should be added to @t{.zshrc} after @t{compinit} has +been run: + +@noindent +@example +for key in '!' '$' '@@' '/' '~'; do + bindkey "\e$key" _bash_complete-word + bindkey "^X$key" _bash_list-choices +done +@end example + +@noindent +This includes the bindings for `@t{~}' in case they were already bound to +something else; the completion code does not override user bindings. + +@findex _correct_filename (^XC) +@item @t{_correct_filename} (@t{^XC}) +Correct the filename path at the cursor position. Allows up to six errors +in the name. Can also be called with an argument to correct +a filename path, independently of zle; the correction is printed on +standard output. + +@findex _correct_word (^Xc) +@item @t{_correct_word} (@t{^Xc}) +Performs correction of the current argument using the usual contextual +completions as possible choices. This stores the string +`@t{correct-word}' in the @var{function} field of the context name and +then calls the @t{_correct} completer. + +@findex _expand_alias (^Xa) +@item @t{_expand_alias} (@t{^Xa}) +This function can be used as a completer and as a bindable command. +It expands the word the cursor is on if it is an alias. The types of +alias expanded can be controlled with the styles @t{regular}, @t{global} +and @t{disabled}. + +@noindent +When used as a bindable command there is one additional feature that +can be selected by setting the @t{complete} style to `true'. In this +case, if the word is not the name of an alias, @t{_expand_alias} tries +to complete the word to a full alias name without expanding it. It +leaves the cursor directly after the completed word so that invoking +@t{_expand_alias} once more will expand the now-complete alias name. + +@findex _expand_word (^Xe) +@item @t{_expand_word} (@t{^Xe}) +Performs expansion on the current word: equivalent to the standard +@t{expand-word} command, but using the @t{_expand} completer. Before +calling it, the @var{function} field of the context is set to +`@t{expand-word}'. + +@findex _generic +@item @t{_generic} +This function is not defined as a widget and not bound by +default. However, it can be used to define a widget and will then +store the name of the widget in the @var{function} field of the context +and call the completion system. This allows custom completion widgets +with their own set of style settings to be defined easily. For example, +to define a widget that performs normal completion and starts +menu selection: + +@noindent +@example +zle -C foo complete-word _generic +bindkey '...' foo +zstyle ':completion:foo:*' menu yes select=1 +@end example + +@noindent +Note in particular that the @t{completer} style may be set for the context +in order to change the set of functions used to generate possible matches. +If @t{_generic} is called with arguments, those are passed through to +@t{_main_complete} as the list of completers in place of those defined by +the @t{completer} style. + +@findex _history_complete_word (\e/) +@item @t{_history_complete_word} (@t{\e/}) +Complete words from the shell's command history. This uses the +@t{list}, @t{remove-all-dups}, @t{sort}, and @t{stop} styles. + +@findex _most_recent_file (^Xm) +@item @t{_most_recent_file} (@t{^Xm}) +Complete the name of the most recently modified file matching the pattern +on the command line (which may be blank). If given a numeric argument +@var{N}, complete the @var{N}th most recently modified file. Note the +completion, if any, is always unique. + +@findex _next_tags (^Xn) +@item @t{_next_tags} (@t{^Xn}) +This command alters the set of matches used to that for the next tag, or +set of tags, either as given by the @t{tag-order} style or as set by +default; these matches would otherwise not be available. +Successive invocations of the command cycle through all possible sets of +tags. + +@findex _read_comp (^X^R) +@item @t{_read_comp} (@t{^X^R}) +Prompt the user for a string, and use that to perform completion on the +current word. There are two possibilities for the string. First, it can +be a set of words beginning `@t{_}', for example `@t{_files -/}', in which +case the function with any arguments will be called to generate the +completions. Unambiguous parts of the function name will be completed +automatically (normal completion is not available at this point) until a +space is typed. + +@noindent +Second, any other string will be passed as a set of arguments to +@t{compadd} and should hence be an expression specifying what should +be completed. + +@noindent +A very restricted set of editing commands is available when reading the +string: `@t{DEL}' and `@t{^H}' delete the last character; `@t{^U}' deletes +the line, and `@t{^C}' and `@t{^G}' abort the function, while `@t{RET}' +accepts the completion. Note the string is used verbatim as a command +line, so arguments must be quoted in accordance with standard shell rules. + +@noindent +Once a string has been read, the next call to @t{_read_comp} will use the +existing string instead of reading a new one. To force a new string to be +read, call @t{_read_comp} with a numeric argument. + +@findex _complete_debug (^X?) +@item @t{_complete_debug} (@t{^X?}) +This widget performs ordinary completion, but captures in a temporary file +a trace of the shell commands executed by the completion system. Each +completion attempt gets its own file. A command to view each of these +files is pushed onto the editor buffer stack. + +@findex _complete_help (^Xh) +@item @t{_complete_help} (@t{^Xh}) +This widget displays information about the context names, +the tags, and the completion functions used +when completing at the current cursor position. If given a numeric +argument other than @t{1} (as in `@t{ESC-2 ^Xh}'), then the styles +used and the contexts for which they are used will be shown, too. + +@noindent +Note that the information about styles may be incomplete; it depends on the +information available from the completion functions called, which in turn +is determined by the user's own styles and other settings. + +@findex _complete_help_generic +@item @t{_complete_help_generic} +Unlike other commands listed here, this must be created as a normal ZLE +widget rather than a completion widget (i.e. with @t{zle -N}). It +is used for generating help with a widget bound to the @t{_generic} +widget that is described above. + +@noindent +If this widget is created using the name of the function, as it is by +default, then when executed it will read a key sequence. This is expected +to be bound to a call to a completion function that uses the @t{_generic} +widget. That widget will be executed, and information provided in +the same format that the @t{_complete_help} widget displays for +contextual completion. + +@noindent +If the widget's name contains @t{debug}, for example if it is created +as `@t{zle -N _complete_debug_generic _complete_help_generic}', it +will read and execute the keystring for a generic widget as before, +but then generate debugging information as done by @t{_complete_debug} +for contextual completion. + +@noindent +If the widget's name contains @t{noread}, it will not read a keystring +but instead arrange that the next use of a generic widget run in +the same shell will have the effect as described above. + +@noindent +The widget works by setting the shell parameter +@t{ZSH_TRACE_GENERIC_WIDGET} which is read by @t{_generic}. Unsetting +the parameter cancels any pending effect of the @t{noread} form. + +@noindent +For example, after executing the following: + +@noindent +@example +zle -N _complete_debug_generic _complete_help_generic +bindkey '^x:' _complete_debug_generic +@end example + +@noindent +typing `@t{C-x :}' followed by the key sequence for a generic widget +will cause trace output for that widget to be saved to a file. + +@findex _complete_tag (^Xt) +@item @t{_complete_tag} (@t{^Xt}) +This widget completes symbol tags created by the @t{etags} or @t{ctags} +programmes (note there is no connection with the completion system's tags) +stored in a file @t{TAGS}, in the format used by @t{etags}, or @t{tags}, in the +format created by @t{ctags}. It will look back up the path hierarchy for +the first occurrence of either file; if both exist, the file @t{TAGS} is +preferred. You can specify the full path to a @t{TAGS} or @t{tags} file by +setting the parameter @t{$TAGSFILE} or @t{$tagsfile} respectively. +The corresponding completion tags used are @t{etags} and @t{vtags}, after +emacs and vi respectively. + +@end table + +@noindent +@node Completion Functions, Completion System Variables, Bindable Commands, Completion System + +@section Utility Functions +@noindent +@cindex completion system, utility functions + +@noindent +Descriptions follow for utility functions that may be +useful when writing completion functions. If functions are installed in +subdirectories, most of these reside in the +@t{Base} subdirectory. Like the example +functions for commands in the distribution, the utility functions +generating matches all follow the convention of returning status zero if they +generated completions and non-zero if no matching completions could be +added. + +@noindent +@table @asis +@findex _absolute_command_paths +@item @t{_absolute_command_paths} +This function completes external commands as absolute paths (unlike +@t{_command_names -e} which completes their basenames). It takes no +arguments. + +@findex _all_labels +@item @t{_all_labels} [ @t{-x} ] [ @t{-12VJ} ] @var{tag} @var{name} @var{descr} [ @var{command} @var{arg} ... ] +This is a convenient interface to the @t{_next_label} function below, +implementing the loop shown in the @t{_next_label} example. The +@var{command} and its arguments are called to generate the matches. The +options stored in the parameter @var{name} will automatically be inserted +into the @var{arg}s passed to the @var{command}. Normally, they are put +directly after the @var{command}, but if one of the @var{arg}s is a single +hyphen, they are inserted directly before that. If the hyphen is the last +argument, it will be removed from the argument list before the +@var{command} is called. This allows @t{_all_labels} to be used in almost all +cases where the matches can be generated by a single call to the +@t{compadd} builtin command or by a call to one of the utility functions. + +@noindent +For example: + +@noindent +@example +local expl +... +if _requested foo; then + ... + _all_labels foo expl '...' compadd ... - $matches +fi +@end example + +@noindent +Will complete the strings from the @t{matches} parameter, using +@t{compadd} with additional options which will take precedence over +those generated by @t{_all_labels}. + +@findex _alternative +@item @t{_alternative} [ @t{-O} @var{name} ] [ @t{-C} @var{name} ] @var{spec} ... +This function is useful in simple cases where multiple tags are available. +Essentially it implements a loop like the one described for the @t{_tags} +function below. + +@noindent +The tags to use and the action to perform if a tag is requested are +described using the @var{spec}s which are of the form: +`@var{tag}@t{:}@var{descr}@t{:}@var{action}'. The @var{tag}s are offered using +@t{_tags} and if the tag is requested, the @var{action} is executed with the +given description @var{descr}. The @var{action}s are those accepted +by the @t{_arguments} function (described below), with the following +exceptions: +@itemize @bullet + +@item +The `@t{->}@var{state}' and `@t{=}@var{...}' forms are not supported. + +@item +The `@t{((a\:bar b\:baz}@t{))}' form does not need +the colon to be escaped, since the @var{spec}s have no colon-separated fields +after the @var{action}. + +@end itemize + +@noindent +For example, the @var{action} may be a simple function call: + +@noindent +@example +_alternative \ + 'users:user:_users' \ + 'hosts:host:_hosts' +@end example + +@noindent +offers usernames and hostnames as possible matches, +generated by the @t{_users} and @t{_hosts} functions respectively. + +@noindent +Like @t{_arguments}, this function uses @t{_all_labels} to execute +the actions, which will loop over all sets of tags. Special handling is +only required if there is an additional valid tag, for example inside a +function called from @t{_alternative}. + +@noindent +The option `@t{-O} @var{name}' is used in the same way as by the +@t{_arguments} function. In other words, the elements of the @var{name} +array will be passed to @t{compadd} when executing an action. + +@noindent +Like @t{_tags} this function supports the @t{-C} option to give a +different name for the argument context field. + +@findex _arguments + +@item @t{_arguments }[ @t{-nswWCRS} ] [ @t{-A} @var{pat} ] [ @t{-O} @var{name} ] [ @t{-M} @var{matchspec} ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ @ }[ @t{:} ] @var{spec} ... +@itemx @t{_arguments }[ @var{opt} ... ] @t{-}@t{-} [ @t{-l} ] [ @t{-i} @var{pats} ] [ @t{-s} @var{pair} ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ @ }[ @var{helpspec} ...] +This function can be used to give a complete specification for completion +for a command whose arguments follow standard UNIX option and argument +conventions. + +@noindent +@emph{Options Overview} + +@noindent +Options to @t{_arguments} itself must be in separate words, i.e. @t{-s -w}, +not @t{-sw}. The options are followed by @var{spec}s that describe options and +arguments of the analyzed command. To avoid ambiguity, all +options to @t{_arguments} itself may be separated from the @var{spec} forms +by a single colon. + +@noindent +The `@t{-}@t{-}' +form is used to intuit @var{spec} forms from the help output of the command +being analyzed, and is described in detail below. The @var{opts} for the +`@t{-}@t{-}' form are otherwise the same options as the first form. Note +that `@t{-s}' following `@t{-}@t{-}' has a distinct meaning from `@t{-s}' +preceding `@t{-}@t{-}', and both may appear. + +@noindent +The option switches @t{-s}, @t{-S}, @t{-A}, @t{-w}, and @t{-W} affect how +@t{_arguments} parses the analyzed command line's options. These switches are +useful for commands with standard argument parsing. + +@noindent +The options of @t{_arguments} have the following meanings: + +@noindent +@table @asis +@item @t{-n} +With this option, @t{_arguments} sets the parameter @t{NORMARG} +to the position of the first normal argument in the @t{$words} array, +i.e. the position after the end of the options. If that argument +has not been reached, @t{NORMARG} is set to @t{-1}. The caller +should declare `@t{integer NORMARG}' if the @t{-n} option is passed; +otherwise the parameter is not used. + +@item @t{-s} +Enable @emph{option stacking} for single-letter options, whereby multiple +single-letter options may be combined into a single word. For example, +the two options `@t{-x}' and `@t{-y}' may be combined into +a single word `@t{-xy}'. By default, every word corresponds to a single +option name (`@t{-xy}' is a single option named `@t{xy}'). + +@noindent +Options beginning with a single hyphen or plus sign are eligible for stacking; +words beginning with two hyphens are not. + +@noindent +Note that @t{-s} after @t{-}@t{-} has a different meaning, which is documented +in the segment entitled `Deriving @var{spec} forms from the help output'. + +@item @t{-w} +In combination with @t{-s}, allow option stacking +even if one or more of the options take +arguments. For example, if @t{-x} takes an argument, with no +@t{-s}, `@t{-xy}' is considered as a single (unhandled) option; with +@t{-s}, @t{-xy} is an option with the argument `@t{y}'; with both @t{-s} +and @t{-w}, @t{-xy} is the option @t{-x} and the option @t{-y} with +arguments to @t{-x} (and to @t{-y}, if it takes arguments) still to come +in subsequent words. + +@item @t{-W} +This option takes @t{-w} a stage further: it is possible to +complete single-letter options even after an argument that occurs in the +same word. However, it depends on the action performed whether options +will really be completed at this point. For more control, use a +utility function like @t{_guard} as part of the action. + +@item @t{-C} +Modify the @t{curcontext} parameter for an action of the form `@t{->}@var{state}'. +This is discussed in detail below. + +@item @t{-R} +Return status 300 instead of zero when a @t{$state} is to +be handled, in the `@t{->}@var{string}' syntax. + +@item @t{-S} +Do not complete options after a `@t{-}@t{-}' appearing on the line, +and ignore the `@t{-}@t{-}'. For example, with @t{-S}, in the line + +@noindent +@example +foobar -x -- -y +@end example + +@noindent +the `@t{-x}' is considered an option, the `@t{-y}' is considered an +argument, and the `@t{-}@t{-}' is considered to be neither. + +@item @t{-A} @var{pat} +Do not complete options after the first non-option +argument on the line. @var{pat} is a pattern matching +all strings which are not to be taken as arguments. For example, to make +@t{_arguments} stop completing options after the first normal argument, but +ignoring all strings starting with a hyphen even if they are not described +by one of the @var{optspec}s, the form is `@t{-A "-*"}'. + +@item @t{-O} @var{name} +Pass the elements of the array @var{name} as arguments to functions called to +execute @var{action}s. +This is discussed in detail below. + +@item @t{-M} @var{matchspec} +Use the match specification @var{matchspec} for completing option names and values. +The default @var{matchspec} allows partial word completion after `@t{_}' and +`@t{-}', such as completing `@t{-f-b}' to `@t{-foo-bar}'. The default +@var{matchspec} is: +@example +@t{r:|[_-]=* r:|=*} +@end example + +@item @t{-0} +When populating values of the `@t{opt_args}' associative array, don't +backslash-escape colons and backslashes and use NUL rather than colon for +joining multiple values. This option is described in more detail below, under +the heading @emph{@var{spec}s: actions}. + +@end table + +@noindent +@emph{@var{spec}s: overview} + +@noindent +Each of the following forms is a @var{spec} describing individual sets of +options or arguments on the command line being analyzed. + +@noindent +@table @asis +@item @var{n}@t{:}@var{message}@t{:}@var{action} +@itemx @var{n}@t{::}@var{message}@t{:}@var{action} +This describes the @var{n}'th normal argument. The @var{message} will be +printed above the matches generated and the @var{action} indicates what can +be completed in this position (see below). If there are two colons +before the @var{message} the argument is optional. If the +@var{message} contains only white space, nothing will be printed above +the matches unless the action adds an explanation string itself. + +@item @t{:}@var{message}@t{:}@var{action} +@itemx @t{::}@var{message}@t{:}@var{action} +Similar, but describes the @emph{next} argument, whatever number that +happens to be. If all arguments are specified in this form in the +correct order the numbers are unnecessary. + +@item @t{*:}@var{message}@t{:}@var{action} +@itemx @t{*::}@var{message}@t{:}@var{action} +@itemx @t{*:::}@var{message}@t{:}@var{action} +This describes how arguments (usually non-option arguments, those not +beginning with @t{-} or @t{+}) are to be completed when neither +of the first two forms was provided. Any number of arguments can +be completed in this fashion. + +@noindent +With two colons before the @var{message}, the @t{words} special array and +the @t{CURRENT} special parameter are modified to refer only to the +normal arguments when the @var{action} is executed or evaluated. With +three colons before the @var{message} they are modified to refer only to +the normal arguments covered by this description. + +@item @var{optspec} +@itemx @var{optspec}@t{:}@var{...} +This describes an option. The colon indicates handling for one or more +arguments to the option; if it is not present, the option is assumed to +take no arguments. + +@noindent +The following forms are available for the initial @var{optspec}, whether +or not the option has arguments. + +@noindent +@table @asis +@item @t{*}@var{optspec} +Here @var{optspec} is one of the remaining forms below. This indicates +the following @var{optspec} may be repeated. Otherwise if the +corresponding option is already present on the command line to the left +of the cursor it will not be offered again. + +@item @t{-}@var{optname} +@itemx @t{+}@var{optname} +In the simplest form the @var{optspec} is just the option name beginning +with a minus or a plus sign, such as `@t{-foo}'. The first argument for +the option (if any) must follow as a @emph{separate} word directly after the +option. + +@noindent +Either of `@t{-+}@var{optname}' and `@t{+-}@var{optname}' can be used to +specify that @t{-}@var{optname} and @t{+}@var{optname} are both valid. + +@noindent +In all the remaining forms, the leading `@t{-}' may be replaced by or +paired with `@t{+}' in this way. + +@item @t{-}@var{optname}@t{-} +The first argument of the option must come directly after the option name +@emph{in the same word}. For example, `@t{-foo-:}@var{...}' specifies that +the completed option and argument will look like `@t{-foo}@var{arg}'. + +@item @t{-}@var{optname}@t{+} +The first argument may appear immediately after @var{optname} in the same +word, or may appear as a separate word after the option. For example, +`@t{-foo+:}@var{...}' specifies that the completed option and argument +will look like either `@t{-foo}@var{arg}' or `@t{-foo} @var{arg}'. + +@item @t{-}@var{optname}@t{=} +The argument may appear as the next word, or in same word as the option +name provided that it is separated from it by an equals sign, for +example `@t{-foo=}@var{arg}' or `@t{-foo} @var{arg}'. + +@item @t{-}@var{optname}@t{=-} +The argument to the option must appear after an equals sign in the same +word, and may not be given in the next argument. + +@item @var{optspec}@t{[}@var{explanation}@t{]} +An explanation string may be appended to any of the preceding forms of +@var{optspec} by enclosing it in brackets, as in `@t{-q[query operation]}'. + +@noindent +The @t{verbose} style is used to decide whether the explanation strings +are displayed with the option in a completion listing. + +@noindent +If no bracketed explanation string is given but the @t{auto-description} +style is set and only one argument is described for this @var{optspec}, the +value of the style is displayed, with any appearance of the sequence +`@t{%d}' in it replaced by the @var{message} of the first @var{optarg} +that follows the @var{optspec}; see below. + +@end table + +@noindent +It is possible for options with a literal `@t{+}' or `@t{=}' to +appear, but that character must be quoted, for example `@t{-\+}'. + +@noindent +Each @var{optarg} following an @var{optspec} must take one of the +following forms: + +@noindent +@table @asis +@item @t{:}@var{message}@t{:}@var{action} +@itemx @t{::}@var{message}@t{:}@var{action} +An argument to the option; @var{message} and @var{action} are treated as +for ordinary arguments. In the first form, the argument is mandatory, +and in the second form it is optional. + +@noindent +This group may be repeated for options which take multiple arguments. +In other words, +@t{:}@var{message1}@t{:}@var{action1}@t{:}@var{message2}@t{:}@var{action2} +specifies that the option takes two arguments. + +@item @t{:*}@var{pattern}@t{:}@var{message}@t{:}@var{action} +@itemx @t{:*}@var{pattern}@t{::}@var{message}@t{:}@var{action} +@itemx @t{:*}@var{pattern}@t{:::}@var{message}@t{:}@var{action} +This describes multiple arguments. Only the last @var{optarg} for +an option taking multiple arguments may be +given in this form. If the @var{pattern} is empty (i.e. @t{:*:}), all +the remaining words on the line are to be completed as described by the +@var{action}; otherwise, all the words up to and including a word matching +the @var{pattern} are to be completed using the @var{action}. + +@noindent +Multiple colons are treated as for the `@t{*:}@var{...}' forms for +ordinary arguments: when the @var{message} is preceded by two colons, +the @t{words} special array and the @t{CURRENT} special parameter are +modified during the execution or evaluation of the @var{action} to refer +only to the words after the option. When preceded by three colons, they +are modified to refer only to the words covered by this description. + +@end table + +@end table + +@noindent +Any literal colon in an @var{optname}, @var{message}, or @var{action} +must be preceded by a backslash, `@t{\:}'. + +@noindent +Each of the forms above may be preceded by a list in parentheses +of option names and argument numbers. If the given option is on +the command line, the options and arguments indicated in parentheses +will not be offered. For example, +`@t{(-two -three 1)-one:}@var{...}' completes the option `@t{-one}'; if this +appears on the command line, the options @t{-two} and @t{-three} and the +first ordinary argument will not be completed after it. +`@t{(-foo):}@var{...}' specifies an ordinary argument completion; +@t{-foo} will not be completed if that argument is already present. + +@noindent +Other items may appear in the list of excluded options to indicate +various other items that should not be applied when the current +specification is matched: a single star (@t{*}) for the rest arguments +(i.e. a specification of the form `@t{*:}@var{...}'); a colon (@t{:}) +for all normal (non-option-) arguments; and a hyphen (@t{-}) for all +options. For example, if `@t{(*)}' appears before an option and the +option appears on the command line, the list of remaining arguments +(those shown in the above table beginning with `@t{*:}') will not be +completed. + +@noindent +To aid in reuse of specifications, it is possible to precede any of the +forms above with `@t{!}'; then the form will no longer be completed, +although if the option or argument appears on the command line they will +be skipped as normal. The main use for this is when the arguments are +given by an array, and @t{_arguments} is called repeatedly for more +specific contexts: on the first call `@t{_arguments $global_options}' is +used, and on subsequent calls `@t{_arguments !$^global_options}'. + +@noindent +@emph{@var{spec}s: actions} + + +@noindent +In each of the forms above the @var{action} determines how +completions should be generated. Except for the `@t{->}@var{string}' +form below, the @var{action} will be executed by calling the +@t{_all_labels} function to process all tag labels. No special handling +of tags is needed unless a function call introduces a new one. + +@noindent +The functions called to execute @var{action}s will be called with the +elements of the array named by the `@t{-O} @var{name}' option as arguments. +This can be used, for example, to pass the same set of options for the +@t{compadd} builtin to all @var{action}s. + +@noindent +The forms for @var{action} are as follows. + +@noindent +@table @asis +@item @t{@ }(single unquoted space) +This is useful where an argument is required but it is not possible or +desirable to generate matches for it. The +@var{message} will be displayed but no completions listed. Note +that even in this case the colon at the end of the @var{message} is +needed; it may only be omitted when neither a @var{message} +nor an @var{action} is given. + +@item @t{(}@var{item1} @var{item2} @var{...}@t{)} +One of a list of possible matches, for example: + +@noindent +@example +@t{:foo:(foo bar baz}@t{)} +@end example + +@item @t{((@var{item1}\:@var{desc1} @var{...}))} +Similar to the above, but with descriptions for each possible match. +Note the backslash before the colon. For example, + +@noindent +@example +@t{:foo:((a\:bar b\:baz}@t{))} +@end example + +@noindent +The matches will be listed together with their descriptions if the +@t{description} style is set with the @t{values} tag in the context. + +@item @t{->}@var{string} +@vindex context, use of +@vindex line, use of +@vindex opt_args, use of +In this form, @t{_arguments} processes the arguments and options and then +returns control to the calling function with parameters set to indicate the +state of processing; the calling function then makes its own arrangements +for generating completions. For example, functions that implement a state +machine can use this type of action. + +@noindent +Where @t{_arguments} encounters @var{action} in the `@t{->}@var{string}' +format, it will strip all leading and trailing whitespace from @var{string} +and set the array @t{state} to the set of all @var{string}s for which an +action is to be performed. The elements of the array @t{state_descr} are +assigned the corresponding @var{message} field from each @var{optarg} +containing such an @var{action}. + +@noindent +By default and in common with all other well behaved completion +functions, _arguments returns status zero if it was able to add matches and +non-zero otherwise. However, if the @t{-R} option is given, +@t{_arguments} will instead return a status of 300 to indicate that +@t{$state} is to be handled. + +@noindent +In addition to @t{$state} and @t{$state_descr}, @t{_arguments} also +sets the global +parameters `@t{context}', `@t{line}' and `@t{opt_args}' as described +below, and does not reset any changes made to the special parameters +such as @t{PREFIX} and @t{words}. This gives the calling function the +choice of resetting these parameters or propagating changes in them. + +@noindent +A function calling @t{_arguments} with at least +one action containing a `@t{->}@var{string}' must therefore declare +appropriate local parameters: + +@noindent +@example +local context state state_descr line +typeset -A opt_args +@end example + +@noindent +to prevent @t{_arguments} from altering the global environment. + +@item @t{@{}@var{eval-string}@t{@}} +@vindex expl, use of +A string in braces is evaluated as shell code to generate matches. If the +@var{eval-string} itself does not begin with an opening parenthesis or +brace it is split into separate words before execution. + +@item @t{= }@var{action} +If the @var{action} starts with `@t{= }' (an equals sign followed by a +space), @t{_arguments} will insert the contents of the @var{argument} +field of the current context as the new first element in the @t{words} +special array and increment the value of the @t{CURRENT} special +parameter. This has the effect of inserting a dummy word onto the +completion command line while not changing the point at which completion is +taking place. + +@noindent +This is most useful with one of the specifiers that restrict the words on +the command line on which the @var{action} is to operate (the two- and +three-colon forms above). One particular use is when an @var{action} itself +causes @t{_arguments} on a restricted range; it is necessary to use this +trick to insert an appropriate command name into the range for the second +call to @t{_arguments} to be able to parse the line. + +@item @var{@t{@ }word...} +@itemx @var{word...} +This covers all forms other than those above. If the @var{action} +starts with a space, the remaining list of words will be invoked unchanged. + +@noindent +Otherwise it will be invoked with some extra strings placed after the +first word; these are to be passed down as options to the @t{compadd} +builtin. They ensure that the state specified by @t{_arguments}, in +particular the descriptions of options and arguments, is correctly passed +to the completion command. These additional arguments +are taken from the array parameter `@t{expl}'; this will be set up +before executing the @var{action} and hence may be referred to inside it, +typically in an expansion of the form `@t{$expl[@@]}' which preserves empty +elements of the array. + +@end table + +@noindent +During the performance of the action the array `@t{line}' will be set to +the normal arguments from the command line, i.e. the words from the +command line after the command name excluding all options and their +arguments. Options are stored in the associative array +`@t{opt_args}' with option names as keys and their arguments as +the values. By default, all colons and backslashes in the value are escaped +with backslashes, and if an option has multiple arguments (for example, when +using an @var{optspec} of the form `@t{*}@var{optspec}'), they are joined with +(unescaped) colons. However, if the @t{-0} option was passed, no backslash +escaping is performed, and multiple values are joined with NUL bytes. For +example, after `@t{zsh -o foo:foo -o bar:bar -o <TAB>}', the contents of +`@t{opt_args}' would be + +@noindent +@example +typeset -A opt_args=( [-o]='foo\:foo:bar\:bar:' ) +@end example + +@noindent +by default, and + +@noindent +@example +typeset -A opt_args=( [-o]=$'foo:foo\x00bar:bar\x00' ) +@end example + +@noindent +if @t{_arguments} had been called with the @t{-0} option. + +@noindent +The parameter `@t{context}' is set when returning to the calling function +to perform an action of the form `@t{->}@var{string}'. It is set to an +array of elements corresponding to the elements of @t{$state}. Each +element is a suitable name for the argument field of the context: either a +string of the form `@t{option}@var{-opt}@t{-}@var{n}' for the @var{n}'th +argument of the option @var{-opt}, or a string of the form +`@t{argument-}@var{n}' for the @var{n}'th argument. For `rest' arguments, +that is those in the list at the end not handled by position, @var{n} is the +string `@t{rest}'. For example, when completing the argument of the @t{-o} +option, the name is `@t{option-o-1}', while for the second normal +(non-option-) argument it is `@t{argument-2}'. + +@noindent +Furthermore, during the evaluation of the @var{action} the context name in +the @t{curcontext} parameter is altered to append the same string that is +stored in the @t{context} parameter. + +@noindent +The option @t{-C} tells @t{_arguments} to modify the @t{curcontext} +parameter for an action of the form `@t{->}@var{state}'. This is the +standard parameter used to keep track of the current context. Here it +(and not the @t{context} array) should be made local to the calling +function to avoid passing back the modified value and should be +initialised to the current value at the start of the function: + +@noindent +@example +local curcontext="$curcontext" +@end example + +@noindent +This is useful where it is not possible for multiple states to be valid +together. + +@noindent +@emph{Grouping Options} + +@noindent +Options can be grouped to simplify exclusion lists. A group is +introduced with `@t{+}' followed by a name for the group in the +subsequent word. Whole groups can then be referenced in an exclusion +list or a group name can be used to disambiguate between two forms of +the same option. For example: + +@noindent +@example +_arguments \ + '(group2--x)-a' \ + + group1 \ + -m \ + '(group2)-n' \ + + group2 \ + -x -y +@end example + +@noindent +If the name of a group is specified in the form +`@t{(}@var{name}@t{)}' then only one value from that group +will ever be completed; more formally, all specifications are mutually +exclusive to all other specifications in that group. This is useful for +defining options that are aliases for each other. For example: + +@noindent +@example +_arguments \ + -a -b \ + + '(operation)' \ + @{-c,--compress@}'[compress]' \ + @{-d,--decompress@}'[decompress]' \ + @{-l,--list@}'[list]' +@end example + +@noindent +If an option in a group appears on the command line, it is stored in the +associative array `@t{opt_args}' with '@var{group}@t{-}@var{option}' +as a key. In the example above, a key `@t{operation--c}' is used if the option +`@t{-c}' is present on the command line. + +@noindent +@emph{Specifying Multiple Sets of Arguments} + +@noindent +It is possible to specify multiple sets of options and arguments with +the sets separated by single hyphens. This differs from groups in that +sets are considered to be mutually exclusive of each other. + +@noindent +Specifications before the first set and from any group are common to +all sets. For example: + +@noindent +@example +_arguments \ + -a \ + - set1 \ + -c \ + - set2 \ + -d \ + ':arg:(x2 y2)' +@end example + +@noindent +This defines two sets. When the command line contains the option +`@t{-c}', the `@t{-d}' option and the argument will not be considered +possible completions. When it contains `@t{-d}' or an argument, the +option `@t{-c}' will not be considered. However, after `@t{-a}' +both sets will still be considered valid. + +@noindent +As for groups, the name of a set may appear in exclusion lists, either +alone or preceding a normal option or argument specification. + +@noindent +The completion code has to parse the command line separately for each +set. This can be slow so sets should only be used when necessary. +A useful alternative is often an option specification with rest-arguments +(as in `@t{-foo:*:...}'); here the option @t{-foo} swallows up all +remaining arguments as described by the @var{optarg} definitions. + +@noindent +@emph{Deriving @var{spec} forms from the help output} + +@noindent +The option `@t{-}@t{-}' allows @t{_arguments} to work out the names of long +options that support the `@t{-}@t{-help}' option which is standard in many +GNU commands. The command word is called with the argument +`@t{-}@t{-help}' and the output examined for option names. Clearly, it can +be dangerous to pass this to commands which may not support this option as +the behaviour of the command is unspecified. + +@noindent +In addition to options, `@t{_arguments -}@t{-}' will try to deduce the +types of arguments available for options when the form +`@t{-}@t{-}@var{opt}@t{=}@var{val}' is valid. It is also possible to provide +hints by examining the help text of the command and adding @var{helpspec} of +the form `@var{pattern}@t{:}@var{message}@t{:}@var{action}'; note that other +@t{_arguments} @var{spec} forms are not used. The @var{pattern} is matched +against the help text for an option, and if it matches the @var{message} and +@var{action} are used as for other argument specifiers. The special case +of `@t{*:}' means both @var{message} and @var{action} are empty, which has +the effect of causing options having no description in the help output to +be ordered in listings ahead of options that have a description. + +@noindent +For example: + +@noindent +@example +_arguments -- '*\*:toggle:(yes no)' \ + '*=FILE*:file:_files' \ + '*=DIR*:directory:_files -/' \ + '*=PATH*:directory:_files -/' +@end example + +@noindent +Here, `@t{yes}' and `@t{no}' will be completed as the argument of +options whose description ends in a star; file names will be completed for +options that contain the substring `@t{=FILE}' in the description; and +directories will be completed for options whose description contains +`@t{=DIR}' or `@t{=PATH}'. The last three are in fact the default and so +need not be given explicitly, although it is possible to override the use +of these patterns. A typical help text which uses this feature is: + +@noindent +@example + -C, --directory=DIR change to directory DIR +@end example + +@noindent +so that the above specifications will cause directories to be completed +after `@t{-}@t{-directory}', though not after `@t{-C}'. + +@noindent +Note also that @t{_arguments} tries to find out automatically if the +argument for an option is optional. This can be specified explicitly by +doubling the colon before the @var{message}. + +@noindent +If the @var{pattern} ends in `@t{(-)}', this will be removed from the +pattern and the @var{action} will be used only directly after the +`@t{=}', not in the next word. This is the behaviour of a normal +specification defined with the form `@t{=-}'. + +@noindent +By default, the command (with the option `@t{--help}') is run after +resetting all the locale categories (except for @t{LC_CTYPE}) to `@t{C}'. +If the localized help output is known to work, the option `@t{-l}' can +be specified after the `@t{_arguments -}@t{-}' so that the command is +run in the current locale. + +@noindent +The `@t{_arguments -}@t{-}' can be followed by the option `@t{-i} +@var{patterns}' to give patterns for options which are not to be +completed. The patterns can be given as the name of an array parameter +or as a literal list in parentheses. For example, + +@noindent +@example +_arguments -- -i \ + "(--(en|dis)able-FEATURE*)" +@end example + +@noindent +will cause completion to ignore the options +`@t{-}@t{-enable-FEATURE}' and `@t{-}@t{-disable-FEATURE}' (this example is +useful with GNU @t{configure}). + +@noindent +The `@t{_arguments -}@t{-}' form can also be followed by the option `@t{-s} +@var{pair}' to describe option aliases. The @var{pair} consists of a list +of alternating patterns and corresponding replacements, enclosed in parens +and quoted so that it forms a single argument word in the @t{_arguments} +call. + +@noindent +For example, some @t{configure}-script help output describes options only +as `@t{-}@t{-enable-foo}', but the script also accepts the negated form +`@t{-}@t{-disable-foo}'. To allow completion of the second form: + +@noindent +@example +_arguments -- -s "((#s)--enable- --disable-)" +@end example + +@noindent +@emph{Miscellaneous notes} + +@noindent +Finally, note that @t{_arguments} generally expects to be the primary +function handling any completion for which it is used. It may have side +effects which change the treatment of any matches added by other functions +called after it. To combine @t{_arguments} with other functions, those +functions should be called either before @t{_arguments}, as an @var{action} +within a @var{spec}, or in handlers for `@t{->}@var{state}' actions. + +@noindent +Here is a more general example of the use of @t{_arguments}: + +@noindent +@example +_arguments '-l+:left border:' \ + '-format:paper size:(letter A4)' \ + '*-copy:output file:_files::resolution:(300 600)' \ + ':postscript file:_files -g \*.\(ps\|eps\)' \ + '*:page number:' +@end example + +@noindent +This describes three options: `@t{-l}', `@t{-format}', and +`@t{-copy}'. The first takes one argument described as `@var{left +border}' for which no completion will be offered because of the empty +action. Its argument may come directly after the `@t{-l}' or it may be +given as the next word on the line. + +@noindent +The `@t{-format}' option takes one +argument in the next word, described as `@var{paper size}' for which +only the strings `@t{letter}' and `@t{A4}' will be completed. + +@noindent +The `@t{-copy}' option may appear more than once on the command line and +takes two arguments. The first is mandatory and will be completed as a +filename. The second is optional (because of the second colon before +the description `@var{resolution}') and will be completed from the strings +`@t{300}' and `@t{600}'. + +@noindent +The last two descriptions say what should be completed as +arguments. The first describes the first argument as a +`@var{postscript file}' and makes files ending in `@t{ps}' or `@t{eps}' +be completed. The last description gives all other arguments the +description `@var{page number}' but does not offer completions. + +@findex _cache_invalid +@item @t{_cache_invalid} @var{cache_identifier} +This function returns status zero if the completions cache corresponding to +the given cache identifier needs rebuilding. It determines this by +looking up the @t{cache-policy} style for the current context. +This should provide a function name which is run with the full path to the +relevant cache file as the only argument. + +@noindent +Example: + +@noindent +@example +_example_caching_policy () @{ + # rebuild if cache is more than a week old + local -a oldp + oldp=( "$1"(Nm+7) ) + (( $#oldp )) +@} +@end example + +@findex _call_function +@item @t{_call_function} @var{return} @var{name} [ @var{arg} ... ] +If a function @var{name} exists, it is called with the arguments +@var{arg}s. The @var{return} argument gives the name of a parameter in which +the return status from the function @var{name} should be stored; if @var{return} +is empty or a single hyphen it is ignored. + +@noindent +The return status of @t{_call_function} itself is zero if the function +@var{name} exists and was called and non-zero otherwise. + +@findex _call_program +@item @t{_call_program} [ @t{-l} ] [ @t{-p} ] @var{tag} @var{string} ... +This function provides a mechanism for the user to override the use of an +external command. It looks up the @t{command} style with the supplied +@var{tag}. If the style is set, its value is used as the command to +execute. The @var{string}s from the call to @t{_call_program}, or from the +style if set, are concatenated with spaces between them and the resulting +string is evaluated. The return status is the return status of the command +called. + +@noindent +By default, the command is run in an environment where all the locale +categories (except for @t{LC_CTYPE}) are reset to `@t{C}' by calling the +utility function @t{_comp_locale} (see below). If the option `@t{-l}' is +given, the command is run with the current locale. + +@noindent +If the option `@t{-p}' is supplied it indicates that the command +output is influenced by the permissions it is run with. If the +@t{gain-privileges} style is set to true, @t{_call_program} will make +use of commands such as @t{sudo}, if present on the command-line, to +match the permissions to whatever the final command is likely to run +under. When looking up the @t{gain-privileges} and @t{command} styles, +the command component of the zstyle context will end with a slash +(`@t{/}') followed by the command that would be used to gain privileges. + +@findex _combination +@item @t{_combination} [ @t{-s} @var{pattern} ] @var{tag} @var{style} @var{spec} ... @var{field} @var{opts} ... +This function is used to complete combinations of values, for example +pairs of hostnames and usernames. The @var{style} argument gives the style +which defines the pairs; it is looked up in a context with the @var{tag} +specified. + +@noindent +The style name consists of field names separated by hyphens, for example +`@t{users-hosts-ports}'. For each field for a value is already known, a +@var{spec} of the form `@var{field}@t{=}@var{pattern}' is given. For example, +if the command line so far specifies a user `@t{pws}', the argument +`@t{users=pws}' should appear. + +@noindent +The next argument with no equals sign is taken as the name of the field +for which completions should be generated (presumably not one of the +@var{field}s for which the value is known). + +@noindent +The matches generated will be taken from the value of the style. These +should contain the possible values for the combinations in the appropriate +order (users, hosts, ports in the example above). +The values for the different fields are separated by colons. This +can be altered with the option @t{-s} to @t{_combination} which specifies a +pattern. Typically this is a character class, as for example +`@t{-s "[:@@]"}' in the case of the @t{users-hosts} style. Each +`@var{field}@t{=}@var{pattern}' specification restricts the +completions which apply to elements of the style with appropriately +matching fields. + +@noindent +If no style with the given name is defined for the given tag, +or if none of the strings in style's value match, but a +function name of the required field preceded by an +underscore is defined, that function will be called to generate the +matches. For example, if there is no `@t{users-hosts-ports}' or no +matching hostname when a host is required, the function `@t{_hosts}' will +automatically be called. + +@noindent +If the same name is used for more than one field, in both the +`@var{field}@t{=}@var{pattern}' and the argument that gives the name of the +field to be completed, the number of the field (starting with one) may +be given after the fieldname, separated from it by a colon. + +@noindent +All arguments after the required field name are passed to +@t{compadd} when generating matches from the style value, or to +the functions for the fields if they are called. + +@findex _command_names +@item @t{_command_names} [ @t{-e} | @t{-} ] +This function completes words that are valid at command position: names of +aliases, builtins, hashed commands, functions, and so on. With the @t{-e} +flag, only hashed commands are completed. The @t{-} flag is ignored. + +@findex _comp_locale +@item @t{_comp_locale} +This function resets all the locale categories other than @t{LC_CTYPE} to +`@t{C}' so that the output from external commands can be easily analyzed by +the completion system. @t{LC_CTYPE} retains the current value (taking +@t{LC_ALL} and @t{LANG} into account), ensuring that non-ASCII characters +in file names are still handled properly. + +@noindent +This function should normally be run only in a subshell, because the new +locale is exported to the environment. Typical usage would be +`@t{$(_comp_locale; }@var{command} ...@t{)}'. + +@findex _completers +@item @t{_completers} [ @t{-p} ] +This function completes names of completers. + +@noindent +@table @asis +@item @t{-p} +Include the leading underscore (`@t{_}') in the matches. + +@end table + +@findex _default +@item @t{_default} +This function corresponds to the @t{-default-} special context which is +applied where no completion is defined. It is useful to call it under +certain error conditions such as completion after an unrecognised +subcommand. This applies the concept of graceful degradation to the +completion system, allowing it to fallback on basic completion of +commonly useful things like filenames. + +@findex _describe + +@item @t{_describe }[@t{-12JVx}] [ @t{-oO} | @t{-t} @var{tag} ] @var{descr} @var{name1} [ @var{name2} ] [ @var{opt} ... ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ }[ @t{-}@t{-} @var{name1} [ @var{name2} ] [ @var{opt} ... ] ... ] +This function associates completions with descriptions. +Multiple groups separated by @t{-}@t{-} can be supplied, potentially with +different completion options @var{opt}s. + +@noindent +The @var{descr} is taken as a string to display above the matches if the +@t{format} style for the @t{descriptions} tag is set. This is followed by +one or two names of arrays followed by options to pass to @t{compadd}. The +array @var{name1} contains the possible completions with their descriptions in +the form `@var{completion}@t{:}@var{description}'. Any literal colons in +@var{completion} must be quoted with a backslash. If a @var{name2} is +given, it should have the same number of elements as @var{name1}; in this +case the corresponding elements are added as possible completions instead +of the @var{completion} strings from @var{name1}. The completion list +will retain the descriptions from @var{name1}. Finally, a set of +completion options can appear. + +@noindent +If the option `@t{-o}' appears before the first argument, the matches added +will be treated as names of command options (N.B. not shell options), +typically following a `@t{-}', `@t{-}@t{-}' or `@t{+}' on the command +line. In this case @t{_describe} uses the @t{prefix-hidden}, +@t{prefix-needed} and @t{verbose} styles to find out if the strings should +be added as completions and if the descriptions should be shown. Without +the `@t{-o}' option, only the @t{verbose} style is used to decide how +descriptions are shown. If `@t{-O}' is used instead of `@t{-o}', command +options are completed as above but @t{_describe} will not handle the +@t{prefix-needed} style. + +@noindent +With the @t{-t} option a @var{tag} can be specified. The default is +`@t{values}' or, if the @t{-o} option is given, `@t{options}'. + +@noindent +The options @t{-1}, @t{-2}, @t{-J}, @t{-V}, @t{-x} are passed to +@t{_next_label}. + +@noindent +If selected by the @t{list-grouped} style, strings with the same +description will appear together in the list. + +@noindent +@t{_describe} uses the @t{_all_labels} function to generate the matches, so +it does not need to appear inside a loop over tag labels. + +@findex _description +@item @t{_description} [ @t{-x} ] [ @t{-12VJ} ] @var{tag} @var{name} @var{descr} [ @var{spec} ... ] +This function is not to be confused with the previous one; it is used as +a helper function for creating options to @t{compadd}. It is buried +inside many of the higher level completion functions and so often does +not need to be called directly. + +@noindent +The styles listed below are tested in the current context using the +given @var{tag}. The resulting options for @t{compadd} are put into the +array named @var{name} (this is traditionally `@t{expl}', but this +convention is not enforced). The description for the corresponding set +of matches is passed to the function in @var{descr}. + +@noindent +The styles tested are: @t{format}, @t{hidden}, @t{matcher}, +@t{ignore-line}, @t{ignored-patterns}, @t{group-name} and @t{sort}. +The @t{format} style is first tested for the given @var{tag} and then for +the @t{descriptions} tag if no value was found, while the remainder are +only tested for the tag given as the first argument. The function also +calls @t{_setup} which tests some more styles. + +@noindent +The string returned by the @t{format} style (if any) will be modified so +that the sequence `@t{%d}' is replaced by the @var{descr} given as the third +argument without any leading or trailing white space. If, after +removing the white space, the @var{descr} is the empty string, the format +style will not be used and the options put into the @var{name} array will +not contain an explanation string to be displayed above the matches. + +@noindent +If @t{_description} is called with more than three arguments, +the additional @var{spec}s should be of the form `@var{char}@t{:}@var{str}'. +These supply escape sequence replacements for the @t{format} style: +every appearance of `@t{%}@var{char}' will be replaced by @var{string}. +If no additional @var{spec}s are given but the description in @var{descr} +conforms to a common form then further escape sequences are set for +elements of that description. These elements correspond to a default +value (`@t{%o}'), the units (`@t{%m}') range of acceptable values +(`@t{%r}') and the remaining initial part of the description (`@t{%h}'). +The form the description takes consists of specifying the units and +range in parentheses and the default value in square brackets, for +example: + +@noindent +@example +_description times expl 'timeout (seconds) (0-60) [20]' +@end example + +@noindent +It is possible to use @t{zformat} conditional expressions when styling +these elements. So, for example, to add `@t{default:}' as a tag but only +when there is a default value to show, the @t{format} style might +include `@t{%(o.default: %o.)}'. + +@noindent +If the @t{-x} option is given, the description will be passed to +@t{compadd} using the @t{-x} option instead of the default @t{-X}. This +means that the description will be displayed even if there are no +corresponding matches. + +@noindent +The options placed in the array @var{name} take account of the +@t{group-name} style, so matches are placed in a separate group where +necessary. The group normally has its elements sorted (by passing the +option @t{-J} to @t{compadd}), but if an option starting with `@t{-V}', +`@t{-J}', `@t{-1}', or `@t{-2}' is passed to @t{_description}, that +option will be included in the array. Hence it is possible for the +completion group to be unsorted by giving the option `@t{-V}', +`@t{-1V}', or `@t{-2V}'. + +@noindent +In most cases, the function will be used like this: + +@noindent +@example +local expl +_description files expl file +compadd "$expl[@@]" - "$files[@@]" +@end example + +@noindent +Note the use of the parameter @t{expl}, the hyphen, and the list of +matches. Almost all calls to @t{compadd} within the completion system use +a similar format; this ensures that user-specified styles are correctly +passed down to the builtins which implement the internals of completion. + +@findex _dir_list +@item @t{_dir_list} [ @t{-s} @var{sep} ] [ @t{-S} ] +Complete a list of directory names separated by colons +(the same format as @t{$PATH}). + +@noindent +@table @asis +@item @t{-s} @var{sep} +Use @var{sep} as separator between items. +@var{sep} defaults to a colon (`@t{:}'). + +@item @t{-S} +Add @var{sep} instead of slash (`@t{/}') as an autoremoveable suffix. + +@end table + +@findex _dispatch +@item @t{_dispatch} @var{context string} ... +This sets the current context to @var{context} and looks for completion +functions to handle this context by hunting through the list of command +names or special contexts (as described above for @t{compdef}) +given as @var{string}s. The first completion function to be defined +for one of the contexts in the list is used to generate matches. +Typically, the last @var{string} is @t{-default-} to cause the function +for default completion to be used as a fallback. + +@noindent +The function sets the parameter +@t{$service} to the @var{string} being tried, and sets +the @var{context/command} field (the fourth) of the @t{$curcontext} +parameter to the @var{context} given as the first argument. + +@findex _email_addresses +@item @t{_email_addresses} [ @t{-c} ] [ @t{-n} @var{plugin} ] +Complete email addresses. Addresses are provided by plugins. + +@noindent +@table @asis +@item @t{-c} +Complete bare @t{localhost@@domain.tld} addresses, without a name part or +a comment. +Without this option, RFC822 `@var{Firstname Lastname} @t{<}@var{address}@t{>}' +strings are completed. + +@item @t{-n} @var{plugin} +Complete aliases from @var{plugin}. + +@end table + +@noindent +The following plugins are available by default: +@t{_email-ldap} (see the @t{filter} style), +@t{_email-local} (completes @var{user}@t{@@}@var{hostname} Unix addresses), +@t{_email-mail} (completes aliases from @t{~/.mailrc}), +@t{_email-mush}, +@t{_email-mutt}, +and +@t{_email-pine}. + +@noindent +Addresses from the @t{_email-}@var{foo} plugin are added under the +tag `@t{email-}@var{foo}'. + +@noindent +@emph{Writing plugins} + +@noindent +Plugins are written as separate functions with names starting with `@t{_email-}'. +They are invoked with the @t{-c} option and @t{compadd} options. +They should either do their own completion or +set the @t{$reply} array to a list of `@var{alias}@t{:}@var{address}' elements and return @t{300}. +New plugins will be picked up and run automatically. + +@findex _files +@item @t{_files} +The function @t{_files} is a wrapper around @t{_path_files}. It supports +all of the same functionality, with some enhancements --- notably, it +respects the @t{list-dirs-first} style, and it allows users to override +the behaviour of the @t{-g} and @t{-/} options with the @t{file-patterns} +style. @t{_files} should therefore be preferred over @t{_path_files} in +most cases. + +@noindent +This function accepts the full set of options allowed by +@t{_path_files}, described below. + +@findex _gnu_generic +@item @t{_gnu_generic} +This function is a simple wrapper around the @t{_arguments} function +described above. It can be used to determine automatically the long +options understood by commands that produce a list when passed the +option `@t{-}@t{-help}'. It is intended to be used as a top-level +completion function in its own right. For example, to enable option +completion for the commands @t{foo} and @t{bar}, use + +@noindent +@example +compdef _gnu_generic foo bar +@end example + +@noindent +after the call to @t{compinit}. + +@noindent +The completion system as supplied is conservative in its use of this +function, since it is important to be sure the command understands the +option `@t{-}@t{-help}'. + +@findex _guard +@item @t{_guard} [ @var{options} ] @var{pattern descr} +This function displays @var{descr} if @var{pattern} matches the string to +be completed. It is intended to be used in the @var{action} for the +specifications passed to @t{_arguments} and similar functions. + +@noindent +The return status is zero if the message was displayed and the word to +complete is not empty, and non-zero otherwise. + +@noindent +The @var{pattern} may be preceded by any of the options understood by +@t{compadd} that are passed down from @t{_description}, namely @t{-M}, +@t{-J}, @t{-V}, @t{-1}, @t{-2}, @t{-n}, @t{-F} and @t{-X}. All of these +options will be ignored. This fits in conveniently with the +argument-passing conventions of actions for @t{_arguments}. + +@noindent +As an example, consider a command taking the options @t{-n} and +@t{-none}, where @t{-n} must be followed by a numeric value in the +same word. By using: + +@noindent +@example +_arguments '-n-: :_guard "[0-9]#" "numeric value"' '-none' +@end example + +@noindent +@t{_arguments} can be made to both display the message `@t{numeric +value}' and complete options after `@t{-n<TAB>}'. If the `@t{-n}' is +already followed by one or more digits (the pattern passed to +@t{_guard}) only the message will be displayed; if the `@t{-n}' is +followed by another character, only options are completed. + +@findex _message +@item @t{_message} [ @t{-r12} ] [ @t{-VJ} @var{group} ] @var{descr} +@itemx @t{_message -e} [ @var{tag} ] @var{descr} +The @var{descr} is used in the same way as the third +argument to the @t{_description} function, except that the resulting +string will always be shown whether or not matches were +generated. This is useful for displaying a help message in places where +no completions can be generated. + +@noindent +The @t{format} style is examined with the @t{messages} tag to find a +message; the usual tag, @t{descriptions}, is used only if the style is +not set with the former. + +@noindent +If the @t{-r} option is given, no style is used; the @var{descr} is +taken literally as the string to display. This is most useful +when the @var{descr} comes from a pre-processed argument list +which already contains an expanded description. Note that this +option does not disable the `@t{%}'-sequence parsing done by +@t{compadd}. + +@noindent +The @t{-12VJ} options and the @var{group} are passed to @t{compadd} and +hence determine the group the message string is added to. + +@noindent +The second @t{-e} form gives a description for completions with the tag +@var{tag} to be shown even if there are no matches for that tag. This form +is called by @t{_arguments} in the event that there is no action for an +option specification. The tag can be omitted and if so the tag is taken +from the parameter @t{$curtag}; this is maintained by the completion +system and so is usually correct. Note that if there are no matches at +the time this function is called, @t{compstate[insert]} is cleared, so +additional matches generated later are not inserted on the command line. + +@findex _multi_parts +@item @t{_multi_parts} [ @t{-i} ] @var{sep} @var{array} +The argument @var{sep} is a separator character. +The @var{array} may be either the +name of an array parameter or a literal array in the form +`@t{(foo bar}@t{)}', a parenthesised list of words separated +by whitespace. The possible completions are the +strings from the array. However, each chunk delimited by @var{sep} will be +completed separately. For example, the @t{_tar} function uses +`@t{_multi_parts} @t{/} @var{patharray}' to complete partial file paths +from the given array of complete file paths. + +@noindent +The @t{-i} option causes @t{_multi_parts} to insert a unique match even +if that requires multiple separators to be inserted. This is not usually +the expected behaviour with filenames, but certain other types of +completion, for example those with a fixed set of possibilities, may be +more suited to this form. + +@noindent +Like other utility functions, this function accepts the `@t{-V}', +`@t{-J}', `@t{-1}', `@t{-2}', `@t{-n}', `@t{-f}', `@t{-X}', `@t{-M}', +`@t{-P}', `@t{-S}', `@t{-r}', `@t{-R}', and `@t{-q}' options and passes +them to the @t{compadd} builtin. + +@findex _next_label +@item @t{_next_label} [ @t{-x} ] [ @t{-12VJ} ] @var{tag} @var{name} @var{descr} [ @var{option} ... ] +This function is used to implement the loop over different tag +labels for a particular tag as described above for the @t{tag-order} +style. On each call it checks to see if there are any more tag labels; if +there is it returns status zero, otherwise non-zero. +As this function requires a current tag to be set, it must always follow +a call to @t{_tags} or @t{_requested}. + +@noindent +The @t{-x12VJ} options and the first three arguments are passed to the +@t{_description} function. Where appropriate the @var{tag} will be +replaced by a tag label in this call. Any description given in +the @t{tag-order} style is preferred to the @var{descr} passed to +@t{_next_label}. + +@noindent +The @var{option}s given after the @var{descr} +are set in the parameter given by @var{name}, and hence are to be passed +to @t{compadd} or whatever function is called to add the matches. + +@noindent +Here is a typical use of this function for the tag @t{foo}. The call to +@t{_requested} determines if tag @t{foo} is required at all; the loop +over @t{_next_label} handles any labels defined for the tag in the +@t{tag-order} style. + +@noindent +@example +local expl ret=1 +... +if _requested foo; then + ... + while _next_label foo expl '...'; do + compadd "$expl[@@]" ... && ret=0 + done + ... +fi +return ret +@end example + +@findex _normal +@item @t{_normal} [ @t{-P} | @t{-p} @var{precommand} ] +This is the standard function called to handle completion outside +any special @t{-}@var{context}@t{-}. It is called both to complete the command +word and also the arguments for a command. In the second case, +@t{_normal} looks for a special completion for that command, and if +there is none it uses the completion for the @t{-default-} context. + +@noindent +A second use is to reexamine the command line specified by the @t{$words} +array and the @t{$CURRENT} parameter after those have been modified. +For example, the function @t{_precommand}, which +completes after precommand specifiers such as @t{nohup}, removes the +first word from the @t{words} array, decrements the @t{CURRENT} parameter, +then calls `@t{_normal -p $service}'. The effect is that +`@t{nohup} @var{cmd ...}' is treated in the same way as `@var{cmd ...}'. + +@noindent +@table @asis +@item @t{-P} +Reset the list of precommands. This option should be used if completing +a command line which allows internal commands (e.g. builtins and +functions) regardless of prior precommands (e.g. `@t{zsh -c}'). + +@item @t{-p} @var{precommand} +Append @var{precommand} to the list of precommands. This option should be +used in nearly all cases in which @t{-P} is not applicable. + +@end table + +@noindent +If the command name matches one of the patterns given by one of the +options @t{-p} or @t{-P} to @t{compdef}, the corresponding completion +function is called and then the parameter @t{_compskip} is +checked. If it is set completion is terminated at that point even if +no matches have been found. This is the same effect as in the +@t{-first-} context. + +@findex _numbers +@item @t{_numbers} [ @var{option} ... ] [ @var{description} ] [ @var{suffix} ... ] +This can be used where a number is followed by a suffix to indicate the units. +The unit suffixes are completed and can also be included in the description +used when completion is invoked for the preceding number. + +@noindent +In addition to common @t{compadd} options, @t{_numbers} accepts the following +options: + +@noindent +@table @asis +@item @t{-t} @var{tag} +Specify a tag to use instead of the default of @t{numbers}. + +@item @t{-u} @var{units} +Indicate the default units for the number, e.g. @t{bytes}. + +@item @t{-l} @var{min} +Specify the lowest possible value for the number. + +@item @t{-m} @var{max} +Specify the highest possible value for the number. + +@item @t{-d} @var{default} +Specify the default value. + +@item @t{-N} +Allow negative numbers. This is implied if the range includes a negative. + +@item @t{-f} +Allow decimal numbers. + +@end table + +@noindent +Where a particular suffix represents the default units for a number, it +should be prefixed with a colon. Additionally, suffixes can be followed +by a colon and a description. So for example, the following allows the +age of something to be specified, either in seconds or with an optional +suffix with a longer unit of time: + +@noindent +@example +_numbers -u seconds age :s:seconds m:minutes h:hours d:days +@end example + +@noindent +It is typically helpful for units to be presented in order of magnitude +when completed. To facilitate this, the order in which they are given +is preserved. + +@noindent +When the @t{format} style is looked up with the @t{descriptions} tag or +the tag specified with @t{-t}, the list of suffixes is available as a +`@t{%x}' escape sequence. This is in addition to the usual sequences +documented under the @t{format} style. The form this list takes can also +be configured. To this end, the @t{format} style is first looked up with +the tag @t{unit-suffixes}. The retrieved format is applied to each +suffix in turn and the results are then concatenated to form the +completed list. For the @t{unit-suffixes} format, `@t{%x}' expands to +the individual suffix and `@t{%X}' to its description. @t{%d}' indicates +a default suffix and can be used in a condition. The index and reverse +index are set in `@t{%i}' and `@t{%r}' respectively and are useful for +text included only with the first and last suffixes in the list. So for +example, the following joins the suffixes together as a comma-separated +list: + +@noindent +@example +zstyle ':completion:*:unit-suffixes' format '%x%(r::,)' +@end example + + +@noindent +@findex _options +@item @t{_options} +This can be used to complete the names of shell options. It provides a +matcher specification that ignores a leading `@t{no}', ignores +underscores and allows upper-case letters to +match their lower-case counterparts (for example, `@t{glob}', +`@t{noglob}', `@t{NO_GLOB}' are all completed). Any arguments +are propagated to the @t{compadd} builtin. + +@findex _options_set +@findex _options_unset +@item @t{_options_set} and @t{_options_unset} +These functions complete only set or unset options, with the same +matching specification used in the @t{_options} function. + +@noindent +Note that you need to uncomment a few lines in the @t{_main_complete} +function for these functions to work properly. The lines in question +are used to store the option settings in effect before the completion +widget locally sets the options it needs. Hence these functions are not +generally used by the completion system. + +@findex _parameters +@item @t{_parameters} +This is used to complete the names of shell parameters. + +@noindent +The option `@t{-g} @var{pattern}' limits the completion to parameters +whose type matches the @var{pattern}. The type of a parameter is that +shown by `@t{print $@{(t)}@var{param}@t{@}}', hence judicious use of +`@t{*}' in @var{pattern} is probably necessary. + +@noindent +All other arguments are passed to the @t{compadd} builtin. + +@findex _path_files +@item @t{_path_files} +This function is used throughout the completion system +to complete filenames. It allows completion of partial paths. For +example, the string `@t{/u/i/s/sig}' may be completed to +`@t{/usr/include/sys/signal.h}'. + +@noindent +The options accepted by both @t{_path_files} and @t{_files} are: + +@noindent +@table @asis +@item @t{-f} +Complete all filenames. This is the default. + +@item @t{-/} +Specifies that only directories should be completed. + +@item @t{-g} @var{pattern} +Specifies that only files matching the @var{pattern} should be completed. + +@item @t{-W} @var{paths} +Specifies path prefixes that are to be prepended to the string from the +command line to generate the filenames but that should not be inserted +as completions nor shown in completion listings. Here, @var{paths} may be +the name of an array parameter, a literal list of paths enclosed in +parentheses or an absolute pathname. + +@item @t{-F} @var{ignored-files} +This behaves as for the corresponding option to the @t{compadd} builtin. +It gives direct control over which +filenames should be ignored. If the option is not present, the +@t{ignored-patterns} style is used. + +@end table + +@noindent +Both @t{_path_files} and @t{_files} also accept the following options +which are passed to @t{compadd}: `@t{-J}', `@t{-V}', +`@t{-1}', `@t{-2}', `@t{-n}', `@t{-X}', `@t{-M}', `@t{-P}', `@t{-S}', +`@t{-q}', `@t{-r}', and `@t{-R}'. + +@noindent +Finally, the @t{_path_files} function uses the styles @t{expand}, +@t{ambiguous}, @t{special-dirs}, @t{list-suffixes} and @t{file-sort} +described above. + +@findex _pick_variant + +@item @t{_pick_variant }[ @t{-b} @var{builtin-label} ] [ @t{-c} @var{command} ] [ @t{-r} @var{name} ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ @ @ @ @ }@var{label}@t{=}@var{pattern} ... @var{label} [ @var{arg} ... ] +This function is used to resolve situations where a single command name +requires more than one type of handling, either because it +has more than one variant or because there is a name clash between two +different commands. + +@noindent +The command to run is taken from the first element of the array +@t{words} unless this is overridden by the option @t{-c}. This command +is run and its output is compared with a series of patterns. Arguments +to be passed to the command can be specified at the end after all the +other arguments. The patterns to try in order are given by the arguments +@var{label}@t{=}@var{pattern}; if the output of `@var{command} @var{arg} +...' contains @var{pattern}, then @var{label} is selected as the label +for the command variant. If none of the patterns match, the final +command label is selected and status 1 is returned. + +@noindent +If the `@t{-b} @var{builtin-label}' is given, the command is tested to +see if it is provided as a shell builtin, possibly autoloaded; if so, +the label @var{builtin-label} is selected as the label for the variant. + +@noindent +If the `@t{-r} @var{name}' is given, the @var{label} picked is stored in +the parameter named @var{name}. + +@noindent +The results are also cached in the @t{_cmd_variant} associative array +indexed by the name of the command run. + +@findex _regex_arguments +@item @t{_regex_arguments} @var{name} @var{spec} ... +This function generates a completion function @var{name} which matches +the specifications @var{spec}s, a set of regular expressions as +described below. After running @t{_regex_arguments}, the function +@var{name} should be called as a normal completion function. +The pattern to be matched is given by the contents of +the @t{words} array up to the current cursor position joined together +with null characters; no quotation is applied. + +@noindent +The arguments are grouped as sets of alternatives separated by `@t{|}', +which are tried one after the other until one matches. Each alternative +consists of a one or more specifications which are tried left to right, +with each pattern matched being stripped in turn from the command line +being tested, until all of the group succeeds or until one fails; in the +latter case, the next alternative is tried. This structure can be +repeated to arbitrary depth by using parentheses; matching proceeds from +inside to outside. + +@noindent +A special procedure is applied if no test succeeds but the remaining +command line string contains no null character (implying the remaining +word is the one for which completions are to be generated). The +completion target is restricted to the remaining word and any +@var{action}s for the corresponding patterns are executed. In this case, +nothing is stripped from the command line string. The order of +evaluation of the @var{action}s can be determined by the @t{tag-order} +style; the various formats supported by @t{_alternative} can be used +in @var{action}. The @var{descr} is used for setting up the array +parameter @t{expl}. + +@noindent +Specification arguments take one of following forms, in which +metacharacters such as `@t{(}', `@t{)}', `@t{#}' and `@t{|}' +should be quoted. + +@noindent +@table @asis +@item @t{/}@var{pattern}@t{/} [@t{%}@var{lookahead}@t{%}] [@t{-}@var{guard}] [@t{:}@var{tag}@t{:}@var{descr}@t{:}@var{action}] +This is a single primitive component. +The function tests whether the combined pattern +`@t{(#b)((#B)}@var{pattern}@t{)}@var{lookahead}@t{*}' matches +the command line string. If so, `@var{guard}' is evaluated and +its return status is examined to determine if the test has succeeded. +The @var{pattern} string `@t{[]}' is guaranteed never to match. +The @var{lookahead} is not stripped from the command line before the next +pattern is examined. + +@noindent +The argument starting with @t{:} is used in the same manner as an argument to +@t{_alternative}. + +@noindent +A component is used as follows: @var{pattern} is tested to +see if the component already exists on the command line. If +it does, any following specifications are examined to find something to +complete. If a component is reached but no such pattern exists yet on the +command line, the string containing the @var{action} is used to generate +matches to insert at that point. + +@item @t{/}@var{pattern}@t{/+} [@t{%}@var{lookahead}@t{%}] [@t{-}@var{guard}] [@t{:}@var{tag}@t{:}@var{descr}@t{:}@var{action}] +This is similar to `@t{/}@var{pattern}@t{/} ...' but the left part of the +command line string (i.e. the part already matched by previous patterns) +is also considered part of the completion target. + +@item @t{/}@var{pattern}@t{/-} [@t{%}@var{lookahead}@t{%}] [@t{-}@var{guard}] [@t{:}@var{tag}@t{:}@var{descr}@t{:}@var{action}] +This is similar to `@t{/}@var{pattern}@t{/} ...' but the @var{action}s of the +current and previously matched patterns are ignored even if the +following `@var{pattern}' matches the empty string. + +@item @t{(} @var{spec} @t{)} +Parentheses may be used to groups @var{spec}s; note each parenthesis +is a single argument to @t{_regex_arguments}. + +@item @var{spec} @t{#} +This allows any number of repetitions of @var{spec}. + +@item @var{spec} @var{spec} +The two @var{spec}s are to be matched one after the other as described +above. + +@item @var{spec} @t{|} @var{spec} +Either of the two @var{spec}s can be matched. + +@end table + +@noindent +The function @t{_regex_words} can be used as a helper function to +generate matches for a set of alternative words possibly with +their own arguments as a command line argument. + +@noindent +Examples: + +@noindent +@example +_regex_arguments _tst /$'[^\0]#\0'/ \ + /$'[^\0]#\0'/ :'compadd aaa' +@end example + +@noindent +This generates a function @t{_tst} that completes @t{aaa} as its only +argument. The @var{tag} and @var{description} for the action have been +omitted for brevity (this works but is not recommended in normal use). +The first component matches the command word, which is arbitrary; the +second matches any argument. As the argument is also arbitrary, any +following component would not depend on @t{aaa} being present. + +@noindent +@example +_regex_arguments _tst /$'[^\0]#\0'/ \ + /$'aaa\0'/ :'compadd aaa' +@end example + +@noindent +This is a more typical use; it is similar, but any following patterns +would only match if @t{aaa} was present as the first argument. + +@noindent +@example +_regex_arguments _tst /$'[^\0]#\0'/ \( \ + /$'aaa\0'/ :'compadd aaa' \ + /$'bbb\0'/ :'compadd bbb' \) \# +@end example + +@noindent +In this example, an indefinite number of command arguments may be +completed. Odd arguments are completed as @t{aaa} and even arguments +as @t{bbb}. Completion fails unless the set of @t{aaa} and @t{bbb} +arguments before the current one is matched correctly. + +@noindent +@example +_regex_arguments _tst /$'[^\0]#\0'/ \ + \( /$'aaa\0'/ :'compadd aaa' \| \ + /$'bbb\0'/ :'compadd bbb' \) \# +@end example + +@noindent +This is similar, but either @t{aaa} or @t{bbb} may be completed for +any argument. In this case @t{_regex_words} could be used to generate +a suitable expression for the arguments. + +@noindent + +@findex _regex_words [ @t{-t} @var{term} ] +@item @t{_regex_words} @var{tag} @var{description} @var{spec} ... +This function can be used to generate arguments for the +@t{_regex_arguments} command which may be inserted at any point where +a set of rules is expected. The @var{tag} and @var{description} give a +standard tag and description pertaining to the current context. Each +@var{spec} contains two or three arguments separated by a colon: note +that there is no leading colon in this case. + +@noindent +Each @var{spec} gives one of a set of words that may be completed at +this point, together with arguments. It is thus roughly equivalent to +the @t{_arguments} function when used in normal (non-regex) completion. + +@noindent +The part of the @var{spec} before the first colon is the word to be +completed. This may contain a @t{*}; the entire word, before and after +the @t{*} is completed, but only the text before the @t{*} is required +for the context to be matched, so that further arguments may be +completed after the abbreviated form. + +@noindent +The second part of @var{spec} is a description for the word being +completed. + +@noindent +The optional third part of the @var{spec} describes how words following +the one being completed are themselves to be completed. It will be +evaluated in order to avoid problems with quoting. This means that +typically it contains a reference to an array containing previously +generated regex arguments. + +@noindent +The option @t{-t} @var{term} specifies a terminator for the word +instead of the usual space. This is handled as an auto-removable suffix +in the manner of the option @t{-s} @var{sep} to @t{_values}. + +@noindent +The result of the processing by @t{_regex_words} is placed in the array +@t{reply}, which should be made local to the calling function. +If the set of words and arguments may be matched repeatedly, a @t{#} +should be appended to the generated array at that point. + +@noindent +For example: + +@noindent +@example +local -a reply +_regex_words mydb-commands 'mydb commands' \ + 'add:add an entry to mydb:$mydb_add_cmds' \ + 'show:show entries in mydb' +_regex_arguments _mydb "$reply[@@]" +_mydb "$@@" +@end example + +@noindent +This shows a completion function for a command @t{mydb} which takes +two command arguments, @t{add} and @t{show}. @t{show} takes no arguments, +while the arguments for @t{add} have already been prepared in an +array @t{mydb_add_cmds}, quite possibly by a previous call to +@t{_regex_words}. + +@findex _requested +@item @t{_requested} [ @t{-x} ] [ @t{-12VJ} ] @var{tag} [ @var{name} @var{descr} [ @var{command} [ @var{arg} ... ] ] +This function is called to decide whether a tag already registered by a +call to @t{_tags} (see below) has been requested by the user and hence +completion should be performed for it. It returns status zero if the +tag is requested and non-zero otherwise. The function is typically used +as part of a loop over different tags as follows: + +@noindent +@example +_tags foo bar baz +while _tags; do + if _requested foo; then + ... # perform completion for foo + fi + ... # test the tags bar and baz in the same way + ... # exit loop if matches were generated +done +@end example + +@noindent +Note that the test for whether matches were generated is not performed +until the end of the @t{_tags} loop. This is so that the user can set +the @t{tag-order} style to specify a set of tags to be completed at the +same time. + +@noindent +If @var{name} and @var{descr} are given, @t{_requested} calls the +@t{_description} function with these arguments together with the options +passed to @t{_requested}. + +@noindent +If @var{command} is given, the @t{_all_labels} function will be called +immediately with the same arguments. In simple cases this makes it +possible to perform the test for the tag and the matching in one go. +For example: + +@noindent +@example +local expl ret=1 +_tags foo bar baz +while _tags; do + _requested foo expl 'description' \ + compadd foobar foobaz && ret=0 + ... + (( ret )) || break +done +@end example + +@noindent +If the @var{command} is not @t{compadd}, it must nevertheless be prepared +to handle the same options. + +@findex _retrieve_cache +@item @t{_retrieve_cache} @var{cache_identifier} +This function retrieves completion information from the file given by +@var{cache_identifier}, stored in a directory specified by the +@t{cache-path} style which defaults to @t{~/.zcompcache}. The return status +is zero if retrieval was successful. It will only attempt retrieval +if the @t{use-cache} style is set, so you can call this function +without worrying about whether the user wanted to use the caching +layer. + +@noindent +See @t{_store_cache} below for more details. + +@findex _sep_parts +@item @t{_sep_parts} +This function is passed alternating arrays and separators as arguments. +The arrays specify completions for parts of strings to be separated by the +separators. The arrays may be the names of array parameters or +a quoted list of words in parentheses. For example, with the array +`@t{hosts=(ftp news)}' the call `@t{_sep_parts '(foo bar)' @@ hosts}' will +complete the string `@t{f}' to `@t{foo}' and the string `@t{b@@n}' to +`@t{bar@@news}'. + +@noindent +This function accepts the @t{compadd} options `@t{-V}', `@t{-J}', +`@t{-1}', `@t{-2}', `@t{-n}', `@t{-X}', `@t{-M}', `@t{-P}', `@t{-S}', +`@t{-r}', `@t{-R}', and `@t{-q}' and passes them on to the @t{compadd} +builtin used to add the matches. + +@findex _sequence +@item @t{_sequence} [ @t{-s} @var{sep} ] [ @t{-n} @var{max} ] [ @t{-d} ] @var{function} [ @t{-} ] ... +This function is a wrapper to other functions for completing items in a +separated list. The same function is used to complete each item in the +list. The separator is specified with the @t{-s} option. If @t{-s} is +omitted it will use `@t{,}'. Duplicate values are not matched unless +@t{-d} is specified. If there is a fixed or maximum number of items in +the list, this can be specified with the @t{-n} option. + +@noindent +Common @t{compadd} options are passed on to the function. It is possible +to use @t{compadd} directly with @t{_sequence}, though @t{_values} may +be more appropriate in this situation. + +@findex _setup +@item @t{_setup} @var{tag} [ @var{group} ] +This function sets up the special +parameters used by the completion system appropriately for the @var{tag} +given as the first argument. It uses the styles @t{list-colors}, +@t{list-packed}, @t{list-rows-first}, @t{last-prompt}, @t{accept-exact}, +@t{menu} and @t{force-list}. + +@noindent +The optional @var{group} supplies the name of the group in which the +matches will be placed. If it is not given, the @var{tag} is used as +the group name. + +@noindent +This function is called automatically from @t{_description} +and hence is not normally called explicitly. + +@findex _store_cache +@item @t{_store_cache} @var{cache_identifier} @var{param} ... +This function, together with @t{_retrieve_cache} and +@t{_cache_invalid}, implements a caching layer which can be used +in any completion function. Data obtained by +costly operations are stored in parameters; +this function then dumps the values of those parameters to a file. The +data can then be retrieved quickly from that file via @t{_retrieve_cache}, +even in different instances of the shell. + +@noindent +The @var{cache_identifier} specifies the file which the data should be +dumped to. The file is stored in a directory specified by the +@t{cache-path} style which defaults to @t{~/.zcompcache}. The remaining +@var{param}s arguments are the parameters to dump to the file. + +@noindent +The return status is zero if storage was successful. The function will +only attempt storage if the @t{use-cache} style is set, so you can +call this function without worrying about whether the user wanted to +use the caching layer. + +@noindent +The completion function may avoid calling @t{_retrieve_cache} when it +already has the completion data available as parameters. +However, in that case it should +call @t{_cache_invalid} to check whether the data in the parameters and +in the cache are still valid. + +@noindent +See the _perl_modules completion function for a simple example of +the usage of the caching layer. + +@findex _tags +@item @t{_tags} [ [ @t{-C} @var{name} ] @var{tag} ... ] +If called with arguments, these are taken to be the names of tags +valid for completions in the current context. These tags are stored +internally and sorted by using the @t{tag-order} style. + +@noindent +Next, @t{_tags} is called repeatedly without arguments from the same +completion function. This successively selects the first, second, +etc. set of tags requested by the user. The return status is zero if at +least one of the tags is requested and non-zero otherwise. To test if a +particular tag is to be tried, the @t{_requested} function should be +called (see above). + +@noindent +If `@t{-C} @var{name}' is given, @var{name} is temporarily stored in the +@var{argument} field (the fifth) of the context in the @t{curcontext} parameter +during the call to @t{_tags}; the field is restored on exit. This +allows @t{_tags} to use a more +specific context without having to change and reset the +@t{curcontext} parameter (which has the same effect). + +@findex _tilde_files +@item @t{_tilde_files} +Like @t{_files}, but resolve leading tildes according to the rules of +filename expansion, so the suggested completions don't start with +a `@t{~}' even if the filename on the command-line does. + +@findex _values +@item @t{_values} [ @t{-O} @var{name} ] [ @t{-s} @var{sep} ] [ @t{-S} @var{sep} ] [ @t{-wC} ] @var{desc} @var{spec} ... +This is used to complete arbitrary keywords (values) and their arguments, +or lists of such combinations. + +@noindent +If the first argument is the option `@t{-O} @var{name}', it will be used +in the same way as by the @t{_arguments} function. In other words, the +elements of the @var{name} array will be passed to @t{compadd} +when executing an action. + +@noindent +If the first argument (or the first argument after `@t{-O} @var{name}') +is `@t{-s}', the next argument is used as the character that separates +multiple values. This character is automatically added after each value +in an auto-removable fashion (see below); all values completed by +`@t{_values -s}' appear in the same word on the command line, unlike +completion using @t{_arguments}. If this option is not present, only a +single value will be completed per word. + +@noindent +Normally, @t{_values} will only use the current word to determine +which values are already present on the command line and hence are not +to be completed again. If the @t{-w} option is given, other arguments +are examined as well. + +@noindent +The first non-option argument, @var{desc}, is used as a string to print as a +description before listing the values. + +@noindent +All other arguments describe the possible values and their +arguments in the same format used for the description of options by +the @t{_arguments} function (see above). The only differences are that +no minus or plus sign is required at the beginning, +values can have only one argument, and the forms of action +beginning with an equal sign are not supported. + +@noindent +The character separating a value from its argument can be set using the +option @t{-S} (like @t{-s}, followed by the character to use as the +separator in the next argument). By default the equals +sign will be used as the separator between values and arguments. + +@noindent +Example: + +@noindent +@example +_values -s , 'description' \ + '*foo[bar]' \ + '(two)*one[number]:first count:' \ + 'two[another number]::second count:(1 2 3)' +@end example + +@noindent +This describes three possible values: `@t{foo}', `@t{one}', and +`@t{two}'. The first is described as `@t{bar}', takes no argument +and may appear more than once. The second is described as +`@t{number}', may appear more than once, and takes one mandatory +argument described as `@t{first count}'; no action is +specified, so it will not be completed. The +`@t{(two)}' at the beginning says that if the value `@t{one}' is on +the line, the value `@t{two}' will no longer be considered a possible +completion. Finally, the last value (`@t{two}') is described +as `@t{another number}' and takes an optional argument described as +`@t{second count}' for which the completions (to appear after an +`@t{=}') are `@t{1}', `@t{2}', and `@t{3}'. The @t{_values} function +will complete lists of these values separated by commas. + +@noindent +Like @t{_arguments}, this function temporarily adds another context name +component to the arguments element (the fifth) of the current context +while executing the @var{action}. Here this name is just the name of the +value for which the argument is completed. + +@noindent +The style @t{verbose} is used to decide if the descriptions for the +values (but not those for the arguments) should be printed. + +@noindent +The associative array @t{val_args} is used to report values and their +arguments; this works similarly to the @t{opt_args} associative array +used by @t{_arguments}. Hence the function calling @t{_values} should +declare the local parameters @t{state}, @t{state_descr}, @t{line}, +@t{context} and @t{val_args}: + +@noindent +@example +local context state state_descr line +typeset -A val_args +@end example + +@noindent +when using an action of the form `@t{->}@var{string}'. With this +function the @t{context} parameter will be set to the name of the +value whose argument is to be completed. Note that for @t{_values}, +the @t{state} and @t{state_descr} are scalars rather than arrays. +Only a single matching state is returned. + +@noindent +Note also that @t{_values} normally adds the character used as the +separator between values as an auto-removable suffix (similar to a +`@t{/}' after a directory). However, this is not possible for a +`@t{->}@var{string}' action as the matches for the argument are +generated by the calling function. To get the usual behaviour, +the calling function can add the separator @var{x} as a suffix by +passing the options `@t{-qS} @var{x}' either directly or indirectly to +@t{compadd}. + +@noindent +The option @t{-C} is treated in the same way as it is by @t{_arguments}. +In that case the parameter @t{curcontext} should be made local instead +of @t{context} (as described above). + +@findex _wanted +@item @t{_wanted} [ @t{-x} ] [ @t{-C} @var{name} ] [ @t{-12VJ} ] @var{tag} @var{name} @var{descr} @var{command} [ @var{arg} ...] +In many contexts, completion can only generate one particular set of +matches, usually corresponding to a single tag. However, it is +still necessary to decide whether the user requires matches of this type. +This function is useful in such a case. + +@noindent +The arguments to @t{_wanted} are the same as those to @t{_requested}, +i.e. arguments to be passed to @t{_description}. However, in this case +the @var{command} is not optional; all the processing of tags, including +the loop over both tags and tag labels and the generation of matches, +is carried out automatically by @t{_wanted}. + +@noindent +Hence to offer only one tag and immediately add the corresponding +matches with the given description: + +@noindent +@example +local expl +_wanted tag expl 'description' \ + compadd -- @var{match1} @var{match2}... +@end example + +@noindent +See also the use of @t{_wanted} in the example function in +@ref{Dynamic named directories}. + +@noindent +Note that, as for @t{_requested}, the @var{command} must be able to +accept options to be passed down to @t{compadd}. + +@noindent +Like @t{_tags} this function supports the @t{-C} option to give a +different name for the argument context field. The @t{-x} option has +the same meaning as for @t{_description}. + +@findex _widgets +@item @t{_widgets} [ @t{-g} @var{pattern} ] +This function completes names of zle widgets (see +@ref{Zle Widgets}). The @var{pattern}, if present, is matched against values of the @t{$widgets} +special parameter, documented in +@ref{The zsh/zleparameter Module}. + +@end table + +@noindent +@node Completion System Variables, Completion Directories, Completion Functions, Completion System + +@section Completion System Variables +@noindent +@cindex completion system, variables + +@noindent +There are some standard variables, initialised by the @t{_main_complete} +function and then used from other functions. + +@noindent +The standard variables are: + +@noindent +@table @asis +@item @t{_comp_caller_options} +The completion system uses @t{setopt} to set a number of options. This +allows functions to be written without concern for compatibility with +every possible combination of user options. However, sometimes completion +needs to know what the user's option preferences are. These are saved +in the @t{_comp_caller_options} associative array. Option names, spelled +in lowercase without underscores, are mapped to one or other of the +strings `@t{on}' and `@t{off}'. + +@item @t{_comp_priv_prefix} +Completion functions such as @t{_sudo} can set the @t{_comp_priv_prefix} +array to a command prefix that may then be used by @t{_call_program} to +match the privileges when calling programs to generate matches. + +@end table + +@noindent +@vindex compprefuncs, use of +@vindex comppostfuncs, use of +Two more features are offered by the @t{_main_complete} function. The +arrays @t{compprefuncs} and @t{comppostfuncs} may contain +names of functions that are to be called immediately before or after +completion has been tried. A function will only be called once unless +it explicitly reinserts itself into the array. + +@noindent +@node Completion Directories, , Completion System Variables, Completion System + +@section Completion Directories +@noindent +@cindex completion system, directory structure + +@noindent +In the source distribution, the files are contained in various +subdirectories of the @t{Completion} directory. They may have been +installed in the same structure, or into one single function directory. +The following is a description of the files found in the original directory +structure. If you wish to alter an installed file, you will need to copy +it to some directory which appears earlier in your @t{fpath} than the +standard directory where it appears. + +@noindent +@table @asis +@item @t{Base} +The core functions and special completion widgets automatically bound +to keys. You will certainly need most of these, though will +probably not need to alter them. Many of these are documented above. + +@item @t{Zsh} +Functions for completing arguments of shell builtin commands and +utility functions for this. Some of these are also used by functions from +the @t{Unix} directory. + +@item @t{Unix} +Functions for completing arguments of external commands and suites of +commands. They may need modifying for your system, although in many cases +some attempt is made to decide which version of a command is present. For +example, completion for the @t{mount} command tries to determine the system +it is running on, while completion for many other utilities try to decide +whether the GNU version of the command is in use, and hence whether the +@t{-}@t{-help} option is supported. + +@item @t{X}, @t{AIX}, @t{BSD}, ... +Completion and utility function for commands available only on some systems. +These are not arranged hierarchically, so, for example, both the +@t{Linux} and @t{Debian} directories, as well as the @t{X} directory, +may be useful on your system. + +@end table +@c (avoiding a yodl bug) +@c Yodl file: Zsh/compctl.yo +@node Completion Using compctl, Zsh Modules, Completion System, Top + +@chapter Completion Using compctl +@noindent +@cindex completion, programmable +@cindex completion, controlling + +@section Types of completion +@noindent +This version of zsh has two ways of performing completion of words on the +command line. New users of the shell may prefer to use the newer +and more powerful system based on shell functions; this is described +in @ref{Completion System}, and the basic shell mechanisms which support +it are described in @ref{Completion Widgets}. This chapter describes +the older @t{compctl} command. + +@section Description +@noindent +@findex compctl + +@table @asis +@item @t{compctl} [ @t{-CDT} ] @var{options} [ @var{command} ... ] +@item @t{compctl }[ @t{-CDT} ] @var{options} [ @t{-x} @var{pattern} @var{options} @t{-} ... @t{-}@t{-} ] +@item @t{@ @ @ @ @ @ @ @ }[ @t{+} @var{options} [ @t{-x} ... @t{-}@t{-} ] ... [@t{+}] ] [ @var{command} ... ] +@item @t{compctl} @t{-M} @var{match-specs} ... +@item @t{compctl} @t{-L} [ @t{-CDTM} ] [ @var{command} ... ] +@item @t{compctl} @t{+} @var{command} ... +@end table +@sp 1 + +@noindent +Control the editor's completion behavior according to the supplied set +of @var{options}. Various editing commands, notably +@t{expand-or-complete-word}, usually bound to tab, will +attempt to complete a word typed by the user, while others, notably +@t{delete-char-or-list}, usually bound to ^D in EMACS editing +mode, list the possibilities; @t{compctl} controls what those +possibilities are. They may for example be filenames (the most common +case, and hence the default), shell variables, or words from a +user-specified list. +@menu +* Command Flags:: +* Option Flags:: +* Alternative Completion:: +* Extended Completion:: +* Example:: +@end menu + +@noindent +@node Command Flags, Option Flags, , Completion Using compctl + +@section Command Flags +@noindent +Completion of the arguments of a command may be different for each +command or may use the default. The behavior when completing the +command word itself may also be separately specified. These +correspond to the following flags and arguments, all of which (except +for @t{-L}) may be combined with any combination of the +@var{options} described subsequently in @ref{Option Flags}: + +@noindent +@table @asis +@item @var{command} ... +controls completion for the named commands, which must be listed last +on the command line. If completion is attempted for a command with a +pathname containing slashes and no completion definition is found, the +search is retried with the last pathname component. If the command starts +with a @t{=}, completion is tried with the pathname of the command. + +@noindent +Any of the @var{command} strings may be patterns of the form normally +used for filename generation. These should be quoted to protect them +from immediate expansion; for example the command string @t{'foo*'} +arranges for completion of the words of any command beginning with +@t{foo}. When completion is attempted, all pattern completions are +tried in the reverse order of their definition until one matches. By +default, completion then proceeds as normal, i.e. the shell will try to +generate more matches for the specific command on the command line; this +can be overridden by including @t{-tn} in the flags for the pattern +completion. + +@noindent +Note that aliases +are expanded before the command name is determined unless the +@t{COMPLETE_ALIASES} option is set. Commands may not be combined +with the @t{-C}, @t{-D} or @t{-T} flags. + +@item @t{-C} +controls completion when the command word itself is being completed. +If no @t{compctl -C} command has been issued, the names of any +executable command (whether in the path or specific to the shell, such +as aliases or functions) are completed. + +@item @t{-D} +controls default completion behavior for the arguments of commands not +assigned any special behavior. If no @t{compctl -D} command has +been issued, filenames are completed. + +@item @t{-T} +supplies completion flags to be used before any other processing is +done, even before processing for @t{compctl}s defined for specific +commands. This is especially useful when combined with extended +completion (the @t{-x} flag, see @ref{Extended Completion} below). +Using this flag you can define default behavior +which will apply to all commands without exception, or you can alter +the standard behavior for all commands. For example, if your access +to the user database is too slow and/or it contains too many users (so +that completion after `@t{~}' is too slow to be usable), you can use + +@noindent +@example +compctl -T -x 's[~] C[0,[^/]#]' -k friends -S/ -tn +@end example + +@noindent +to complete the strings in the array @t{friends} after a `@t{~}'. +The @t{C[}@var{...}@t{]} argument is necessary so that this form of +@t{~}-completion is +not tried after the directory name is finished. + +@item @t{-L} +lists the existing completion behavior in a manner suitable for +putting into a start-up script; the existing behavior is not changed. +Any combination of the above forms, or the @t{-M} flag (which must +follow the @t{-L} flag), may be specified, otherwise all defined +completions are listed. Any other flags supplied are ignored. + +@item @emph{no argument} +If no argument is given, @t{compctl} lists all defined completions +in an abbreviated form; with a list of @var{options}, all completions +with those flags set (not counting extended completion) are listed. + +@end table + +@noindent +If the @t{+} flag is alone and followed immediately by the @var{command} +list, the completion behavior for all the commands in the list is reset to +the default. In other words, completion will subsequently use the +options specified by the @t{-D} flag. + +@noindent +The form with @t{-M} as the first and only option defines global +matching specifications (see +@ref{Completion Matching Control}). The match specifications given will be used for every completion +attempt (only when using @t{compctl}, not with the new completion +system) and are tried in the order in which they are defined until one +generates at least one match. E.g.: + +@noindent +@example +compctl -M @value{dsq} 'm:@{a-zA-Z@}=@{A-Za-z@}' +@end example + +@noindent +This will first try completion without any global match specifications +(the empty string) and, if that generates no matches, will try case +insensitive completion. + +@noindent +@node Option Flags, Alternative Completion, Command Flags, Completion Using compctl + +@section Option Flags +@noindent +@table @asis +@item [ @t{-fcFBdeaRGovNAIOPZEnbjrzu/12} ] +@item [ @t{-k} @var{array} ] [ @t{-g} @var{globstring} ] [ @t{-s} @var{subststring} ] +@item [ @t{-K} @var{function} ] +@item [ @t{-Q} ] [ @t{-P} @var{prefix} ] [ @t{-S} @var{suffix} ] +@item [ @t{-W} @var{file-prefix} ] [ @t{-H} @var{num pattern} ] +@item [ @t{-q} ] [ @t{-X} @var{explanation} ] [ @t{-Y} @var{explanation} ] +@item [ @t{-y} @var{func-or-var} ] [ @t{-l} @var{cmd} ] [ @t{-h} @var{cmd} ] [ @t{-U} ] +@item [ @t{-t} @var{continue} ] [ @t{-J} @var{name} ] [ @t{-V} @var{name} ] +@item [ @t{-M} @var{match-spec} ] +@end table +@sp 1 + +@noindent +The remaining @var{options} specify the type of command arguments +to look for during completion. Any combination of these flags may be +specified; the result is a sorted list of all the possibilities. The +options are as follows. +@menu +* Simple Flags:: +* Flags with Arguments:: +* Control Flags:: +@end menu + +@noindent +@node Simple Flags, Flags with Arguments, , Option Flags + +@subsection Simple Flags +@noindent +These produce completion lists made up by the shell itself: + +@noindent +@table @asis +@item @t{-f} +Filenames and file system paths. + +@item @t{-/} +Just file system paths. + +@item @t{-c} +Command names, including aliases, shell functions, builtins +and reserved words. + +@item @t{-F} +Function names. + +@item @t{-B} +Names of builtin commands. + +@item @t{-m} +Names of external commands. + +@item @t{-w} +Reserved words. + +@item @t{-a} +Alias names. + +@item @t{-R} +Names of regular (non-global) aliases. + +@item @t{-G} +Names of global aliases. + +@item @t{-d} +This can be combined with @t{-F}, @t{-B}, @t{-w}, +@t{-a}, @t{-R} and @t{-G} to get names of disabled +functions, builtins, reserved words or aliases. + +@item @t{-e} +This option (to show enabled commands) is in effect by default, but +may be combined with @t{-d}; @t{-de} in combination with +@t{-F}, @t{-B}, @t{-w}, @t{-a}, @t{-R} and @t{-G} +will complete names of functions, builtins, reserved words or aliases +whether or not they are disabled. + +@item @t{-o} +Names of shell options (see +@ref{Options}). + +@item @t{-v} +Names of any variable defined in the shell. + +@item @t{-N} +Names of scalar (non-array) parameters. + +@item @t{-A} +Array names. + +@item @t{-I} +Names of integer variables. + +@item @t{-O} +Names of read-only variables. + +@item @t{-p} +Names of parameters used by the shell (including special parameters). + +@item @t{-Z} +Names of shell special parameters. + +@item @t{-E} +Names of environment variables. + +@item @t{-n} +Named directories. + +@item @t{-b} +Key binding names. + +@item @t{-j} +Job names: the first word of the job leader's command line. This is useful +with the @t{kill} builtin. + +@item @t{-r} +Names of running jobs. + +@item @t{-z} +Names of suspended jobs. + +@item @t{-u} +User names. + +@end table + +@noindent +@node Flags with Arguments, Control Flags, Simple Flags, Option Flags + +@subsection Flags with Arguments +@noindent +These have user supplied arguments to determine how the list of +completions is to be made up: + +@noindent +@table @asis +@item @t{-k} @var{array} +Names taken from the elements of @t{$}@var{array} (note that the `@t{$}' +does not appear on the command line). +Alternatively, the argument @var{array} itself may be a set +of space- or comma-separated values in parentheses, in which any +delimiter may be escaped with a backslash; in this case the argument +should be quoted. For example, + +@noindent +@example +compctl -k "(cputime filesize datasize stacksize + coredumpsize resident descriptors)" limit +@end example + +@item @t{-g} @var{globstring} +The @var{globstring} is expanded using filename globbing; it should be +quoted to protect it from immediate expansion. The resulting +filenames are taken as the possible completions. Use `@t{*(/)}' instead of +`@t{*/}' for directories. The @t{fignore} special parameter is not +applied to the resulting files. More than one pattern may be given +separated by blanks. (Note that brace expansion is @emph{not} part of +globbing. Use the syntax `@t{(either|or)}' to match alternatives.) + +@item @t{-s} @var{subststring} +The @var{subststring} is split into words and these words are than +expanded using all shell expansion mechanisms (see +@ref{Expansion}). The resulting words are taken as possible +completions. The @t{fignore} special parameter is not applied to the +resulting files. Note that @t{-g} is faster for filenames. + +@item @t{-K} @var{function} +@vindex reply, use of +Call the given function to get the completions. Unless the name +starts with an underscore, the function is +passed two arguments: the prefix and the suffix of the word on which +completion is to be attempted, in other words those characters before +the cursor position, and those from the cursor position onwards. The +whole command line can be accessed with the @t{-c} and @t{-l} flags +of the @t{read} builtin. The +function should set the variable @t{reply} to an array containing +the completions (one completion per element); note that @t{reply} +should not be made local to the function. From such a function the +command line can be accessed with the @t{-c} and @t{-l} flags to +the @t{read} builtin. For example, + +@noindent +@example +function whoson @{ reply=(`users`); @} +compctl -K whoson talk +@end example + +@noindent +completes only logged-on users after `@t{talk}'. Note that `@t{whoson}' must +return an array, so `@t{reply=`users`}' would be incorrect. + +@item @t{-H} @var{num pattern} +The possible completions are taken from the last @var{num} history +lines. Only words matching @var{pattern} are taken. If @var{num} is +zero or negative the whole history is searched and if @var{pattern} is +the empty string all words are taken (as with `@t{*}'). A typical +use is + +@noindent +@example +compctl -D -f + -H 0 @value{dsq} +@end example + +@noindent +which forces completion to look back in the history list for a word if +no filename matches. + +@end table + +@noindent +@node Control Flags, , Flags with Arguments, Option Flags + +@subsection Control Flags +@noindent +These do not directly specify types of name to be completed, but +manipulate the options that do: + +@noindent +@table @asis +@item @t{-Q} +This instructs the shell not to quote any metacharacters in the possible +completions. Normally the results of a completion are inserted into +the command line with any metacharacters quoted so that they are +interpreted as normal characters. This is appropriate for filenames +and ordinary strings. However, for special effects, such as inserting +a backquoted expression from a completion array (@t{-k}) so that +the expression will not be evaluated until the complete line is +executed, this option must be used. + +@item @t{-P} @var{prefix} +The @var{prefix} is inserted just before the completed string; any +initial part already typed will be completed and the whole @var{prefix} +ignored for completion purposes. For example, + +@noindent +@example +compctl -j -P "%" kill +@end example + +@noindent +inserts a `%' after the kill command and then completes job names. + +@item @t{-S} @var{suffix} +When a completion is found the @var{suffix} is inserted after +the completed string. In the case of menu completion the suffix is +inserted immediately, but it is still possible to cycle through the +list of completions by repeatedly hitting the same key. + +@item @t{-W} @var{file-prefix} +With directory @var{file-prefix}: for command, file, directory and +globbing completion (options @t{-c}, @t{-f}, @t{-/}, @t{-g}), the file +prefix is implicitly added in front of the completion. For example, + +@noindent +@example +compctl -/ -W ~/Mail maildirs +@end example + +@noindent +completes any subdirectories to any depth beneath the directory +@t{~/Mail}, although that prefix does not appear on the command line. +The @var{file-prefix} may also be of the form accepted by the @t{-k} +flag, i.e. the name of an array or a literal list in parenthesis. In +this case all the directories in the list will be searched for +possible completions. + +@item @t{-q} +If used with a suffix as specified by the @t{-S} option, this +causes the suffix to be removed if the next character typed is a blank +or does not insert anything or if the suffix consists of only one character +and the next character typed is the same character; this the same rule used +for the @t{AUTO_REMOVE_SLASH} option. The option is most useful for list +separators (comma, colon, etc.). + +@item @t{-l} @var{cmd} +This option restricts the range +of command line words that are considered to be arguments. If +combined with one of the extended completion patterns `@t{p[}...@t{]}', +`@t{r[}...@t{]}', or `@t{R[}...@t{]}' (see @ref{Extended Completion} +below) the range is restricted to the range of arguments +specified in the brackets. Completion is then performed as if these +had been given as arguments to the @var{cmd} supplied with the +option. If the @var{cmd} string is empty the first word in the range +is instead taken as the command name, and command name completion +performed on the first word in the range. For example, + +@noindent +@example +compctl -x 'r[-exec,;]' -l @value{dsq} -- find +@end example + +@noindent +completes arguments between `@t{-exec}' and the following `@t{;}' (or the end +of the command line if there is no such string) as if they were +a separate command line. + +@item @t{-h} @var{cmd} +Normally zsh completes quoted strings as a whole. With this option, +completion can be done separately on different parts of such +strings. It works like the @t{-l} option but makes the completion code +work on the parts of the current word that are separated by +spaces. These parts are completed as if they were arguments to the +given @var{cmd}. If @var{cmd} is the empty string, the first part is +completed as a command name, as with @t{-l}. + +@item @t{-U} +Use the whole list of possible completions, whether or not they +actually match the word on the command line. The word typed so far +will be deleted. This is most useful with a function (given by the +@t{-K} option) which can examine the word components passed to it +(or via the @t{read} builtin's @t{-c} and @t{-l} flags) and +use its own criteria to decide what matches. If there is no +completion, the original word is retained. Since the produced +possible completions seldom have interesting common prefixes +and suffixes, menu completion is started immediately if @t{AUTO_MENU} is +set and this flag is used. + +@item @t{-y} @var{func-or-var} +@vindex reply, use of +The list provided by @var{func-or-var} is displayed instead of the list +of completions whenever a listing is required; the actual completions +to be inserted are not affected. It can be provided in two +ways. Firstly, if @var{func-or-var} begins with a @t{$} it defines a +variable, or if it begins with a left parenthesis a literal +array, which contains the list. A variable may have been set by a +call to a function using the @t{-K} option. Otherwise it contains the +name of a function which will be executed to create the list. The +function will be passed as an argument list all matching completions, +including prefixes and suffixes expanded in full, and should set the +array @t{reply} to the result. In both cases, the display list will +only be retrieved after a complete list of matches has been created. + +@noindent +Note that the returned list does not have to correspond, even in +length, to the original set of matches, and may be passed as a scalar +instead of an array. No special formatting of characters is +performed on the output in this case; in particular, newlines are +printed literally and if they appear output in columns is suppressed. + +@item @t{-X} @var{explanation} +Print @var{explanation} when trying completion on the current set of +options. A `@t{%n}' in this string is replaced by the number of +matches that were added for this explanation string. +The explanation only appears if completion was tried and there was +no unique match, or when listing completions. Explanation strings +will be listed together with the matches of the group specified +together with the @t{-X} option (using the @t{-J} or @t{-V} +option). If the same explanation string is given to multiple @t{-X} +options, the string appears only once (for each group) and the number +of matches shown for the `@t{%n}' is the total number of all matches +for each of these uses. In any case, the explanation string will only +be shown if there was at least one match added for the explanation +string. + +@noindent +The sequences @t{%B}, @t{%b}, @t{%S}, @t{%s}, @t{%U}, and @t{%u} specify +output attributes (bold, standout, and underline), @t{%F}, @t{%f}, @t{%K}, +@t{%k} specify foreground and background colours, and @t{%@{}@var{...}@t{%@}} can +be used to include literal escape sequences as in prompts. + +@item @t{-Y} @var{explanation} +Identical to @t{-X}, except that the @var{explanation} first undergoes +expansion following the usual rules for strings in double quotes. +The expansion will be carried out after any functions are called for +the @t{-K} or @t{-y} options, allowing them to set variables. + +@item @t{-t} @var{continue} +The @var{continue}-string contains a character that specifies which set +of completion flags should be used next. It is useful: + +@noindent +(i) With @t{-T}, or when trying a list of pattern completions, when +@t{compctl} would usually continue with ordinary processing after +finding matches; this can be suppressed with `@t{-tn}'. + +@noindent +(ii) With a list of alternatives separated by @t{+}, when @t{compctl} +would normally stop when one of the alternatives generates matches. It +can be forced to consider the next set of completions by adding `@t{-t+}' +to the flags of the alternative before the `@t{+}'. + +@noindent +(iii) In an extended completion list (see below), when @t{compctl} would +normally continue until a set of conditions succeeded, then use only +the immediately following flags. With `@t{-t-}', @t{compctl} will +continue trying extended completions after the next `@t{-}'; with +`@t{-tx}' it will attempt completion with the default flags, in other +words those before the `@t{-x}'. + +@item @t{-J} @var{name} +This gives the name of the group the matches should be placed in. Groups +are listed and sorted separately; likewise, menu completion will offer +the matches in the groups in the order in which the groups were +defined. If no group name is explicitly given, the matches are stored in +a group named @t{default}. The first time a group name is encountered, +a group with that name is created. After that all matches with the same +group name are stored in that group. + +@noindent +This can be useful with non-exclusive alternative completions. For +example, in + +@noindent +@example +compctl -f -J files -t+ + -v -J variables foo +@end example + +@noindent +both files and variables are possible completions, as the @t{-t+} forces +both sets of alternatives before and after the @t{+} to be considered at +once. Because of the @t{-J} options, however, all files are listed +before all variables. + +@item @t{-V} @var{name} +Like @t{-J}, but matches within the group will not be sorted in listings +nor in menu completion. These unsorted groups are in a different name +space from the sorted ones, so groups defined as @t{-J files} and @t{-V +files} are distinct. + +@item @t{-1} +If given together with the @t{-V} option, makes +only consecutive duplicates in the group be removed. Note that groups +with and without this flag are in different name spaces. + +@item @t{-2} +If given together with the @t{-J} or @t{-V} option, makes all +duplicates be kept. Again, groups with and without this flag are in +different name spaces. + +@item @t{-M} @var{match-spec} +This defines additional matching control specifications that should be used +only when testing words for the list of flags this flag appears in. The format +of the @var{match-spec} string is described in +@ref{Completion Matching Control}. + +@end table + +@noindent +@node Alternative Completion, Extended Completion, Option Flags, Completion Using compctl + +@section Alternative Completion +@noindent +@table @asis +@item @t{compctl} [ @t{-CDT} ] @var{options} @t{+} @var{options} [ @t{+} ... ] [ @t{+} ] @var{command} ... +@end table +@sp 1 + +@noindent +The form with `@t{+}' specifies alternative options. Completion is +tried with the options before the first `@t{+}'. If this produces no +matches completion is tried with the flags after the `@t{+}' and so on. If +there are no flags after the last `@t{+}' and a match has not been found +up to that point, default completion is tried. +If the list of flags contains a @t{-t} with a @t{+} character, the next +list of flags is used even if the current list produced matches. + +@noindent +@node Extended Completion, Example, Alternative Completion, Completion Using compctl + +@noindent +Additional options are available that restrict completion to some part +of the command line; this is referred to as `extended completion'. + +@noindent + +@section Extended Completion +@noindent + +@table @asis +@item @t{compctl }[ @t{-CDT} ] @var{options} @t{-x} @var{pattern} @var{options} @t{-} ... @t{-}@t{-} +@item @t{@ @ @ @ @ @ @ @ }[ @var{command} ... ] +@item @t{compctl }[ @t{-CDT} ] @var{options} [ @t{-x} @var{pattern} @var{options} @t{-} ... @t{-}@t{-} ] +@item @t{@ @ @ @ @ @ @ @ }[ @t{+} @var{options} [ @t{-x} ... @t{-}@t{-} ] ... [@t{+}] ] [ @var{command} ... ] +@end table +@sp 1 + +@noindent +The form with `@t{-x}' specifies extended completion for the +commands given; as shown, it may be combined with alternative +completion using `@t{+}'. Each @var{pattern} is examined in turn; when a +match is found, the corresponding @var{options}, as described in +@ref{Option Flags} above, are used to generate possible +completions. If no @var{pattern} matches, the @var{options} given +before the @t{-x} are used. + +@noindent +Note that each pattern should be supplied as a single argument and +should be quoted to prevent expansion of metacharacters by the +shell. + +@noindent +A @var{pattern} is built of sub-patterns separated by commas; it +matches if at least one of these sub-patterns matches (they are +`or'ed). These sub-patterns are in turn composed of other +sub-patterns separated by white spaces which match if all of the +sub-patterns match (they are `and'ed). An element of the +sub-patterns is of the form `@var{c}@t{[}...@t{][}...@t{]}', where the pairs of +brackets may be repeated as often as necessary, and matches if any of +the sets of brackets match (an `or'). The example below makes this +clearer. + +@noindent +The elements may be any of the following: + +@noindent +@table @asis +@item @t{s[}@var{string}@t{]}... +Matches if the current word on the command line starts with +one of the strings given in brackets. The @var{string} is not removed +and is not part of the completion. + +@item @t{S[}@var{string}@t{]}... +Like @t{s[}@var{string}@t{]} except that the @var{string} is part of the +completion. + +@item @t{p[}@var{from}@t{,}@var{to}@t{]}... +Matches if the number of the current word is between one of +the @var{from} and @var{to} pairs inclusive. The comma and @var{to} +are optional; @var{to} defaults to the same value as @var{from}. The +numbers may be negative: @t{-}@var{n} refers to the @var{n}'th last word +on the line. + +@item @t{c[}@var{offset}@t{,}@var{string}@t{]}... +Matches if the @var{string} matches the word offset by +@var{offset} from the current word position. Usually @var{offset} +will be negative. + +@item @t{C[}@var{offset}@t{,}@var{pattern}@t{]}... +Like @t{c} but using pattern matching instead. + +@item @t{w[}@var{index}@t{,}@var{string}@t{]}... +Matches if the word in position @var{index} is equal +to the corresponding @var{string}. Note that the word count is made +after any alias expansion. + +@item @t{W[}@var{index}@t{,}@var{pattern}@t{]}... +Like @t{w} but using pattern matching instead. + +@item @t{n[}@var{index}@t{,}@var{string}@t{]}... +Matches if the current word contains @var{string}. Anything up to and +including the @var{index}th occurrence of this string will not be +considered part of the completion, but the rest will. @var{index} may +be negative to count from the end: in most cases, @var{index} will be +1 or -1. For example, + +@noindent +@example +compctl -s '`users`' -x 'n[1,@@]' -k hosts -- talk +@end example + +@noindent +will usually complete usernames, but if you insert an @t{@@} after the +name, names from the array @var{hosts} (assumed to contain hostnames, +though you must make the array yourself) will be completed. Other +commands such as @t{rcp} can be handled similarly. + +@item @t{N[}@var{index}@t{,}@var{string}@t{]}... +Like @t{n} except that the string will be +taken as a character class. Anything up to and including the +@var{index}th occurrence of any of the characters in @var{string} +will not be considered part of the completion. + +@item @t{m[}@var{min}@t{,}@var{max}@t{]}... +Matches if the total number of words lies between @var{min} and +@var{max} inclusive. + +@item @t{r[}@var{str1}@t{,}@var{str2}@t{]}... +Matches if the cursor is after a word with prefix @var{str1}. If there +is also a word with prefix @var{str2} on the command line after the one +matched by @var{str1} it matches +only if the cursor is before this word. If the comma and @var{str2} are +omitted, it matches if the cursor is after a word with prefix @var{str1}. + +@item @t{R[}@var{str1}@t{,}@var{str2}@t{]}... +Like @t{r} but using pattern matching instead. + +@item @t{q[}@var{str}@t{]}... +Matches the word currently being completed is in single quotes and the +@var{str} begins with the letter `s', or if completion is done in +double quotes and @var{str} starts with the letter `d', or if +completion is done in backticks and @var{str} starts with a `b'. + +@end table + +@noindent +@node Example, , Extended Completion, Completion Using compctl + +@section Example +@noindent + +@noindent +@example +compctl -u -x 's[+] c[-1,-f],s[-f+]' \ + -g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail +@end example + +@noindent +This is to be interpreted as follows: + +@noindent +If the current command is @t{mail}, then + +@noindent +@quotation + +if ((the current word begins with @t{+} and the previous word is @t{-f}) +or (the current word begins with @t{-f+})), then complete the +non-directory part (the `@t{:t}' glob modifier) of files in the directory +@t{~/Mail}; else + +@noindent +if the current word begins with @t{-f} or the previous word was @t{-f}, then +complete any file; else + +@noindent +complete user names. + +@end quotation +@c (avoiding a yodl bug) +@c Yodl file: Zsh/modules.yo +@node Zsh Modules, Calendar Function System, Completion Using compctl, Top + +@chapter Zsh Modules +@noindent +@cindex modules + +@section Description +@noindent +Some optional parts of zsh are in modules, separate from the core +of the shell. Each of these modules may be linked in to the +shell at build time, +or can be dynamically linked while the shell is running +if the installation supports this feature. +Modules are linked at runtime with the @t{zmodload} command, +see @ref{Shell Builtin Commands}. + +@noindent +The modules that are bundled with the zsh distribution are: + +@noindent +@c Yodl file: Zsh/modlist.yo +@table @asis +@item @t{zsh/attr} +Builtins for manipulating extended attributes (xattr). + +@item @t{zsh/cap} +Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege) sets. + +@item @t{zsh/clone} +A builtin that can clone a running shell onto another terminal. + +@item @t{zsh/compctl} +The @t{compctl} builtin for controlling completion. + +@item @t{zsh/complete} +The basic completion code. + +@item @t{zsh/complist} +Completion listing extensions. + +@item @t{zsh/computil} +A module with utility builtins needed for the shell function based +completion system. + +@item @t{zsh/curses} +curses windowing commands + +@item @t{zsh/datetime} +Some date/time commands and parameters. + +@item @t{zsh/db/gdbm} +Builtins for managing associative array parameters tied to GDBM databases. + +@item @t{zsh/deltochar} +A ZLE function duplicating EMACS' @t{zap-to-char}. + +@item @t{zsh/example} +An example of how to write a module. + +@item @t{zsh/files} +Some basic file manipulation commands as builtins. + +@item @t{zsh/langinfo} +Interface to locale information. + +@item @t{zsh/mapfile} +Access to external files via a special associative array. + +@item @t{zsh/mathfunc} +Standard scientific functions for use in mathematical evaluations. + +@item @t{zsh/nearcolor} +Map colours to the nearest colour in the available palette. + +@item @t{zsh/newuser} +Arrange for files for new users to be installed. + +@item @t{zsh/parameter} +Access to internal hash tables via special associative arrays. + +@item @t{zsh/pcre} +Interface to the PCRE library. + +@item @t{zsh/param/private} +Builtins for managing private-scoped parameters in function context. + +@item @t{zsh/regex} +Interface to the POSIX regex library. + +@item @t{zsh/sched} +A builtin that provides a timed execution facility within the shell. + +@item @t{zsh/net/socket} +Manipulation of Unix domain sockets + +@item @t{zsh/stat} +A builtin command interface to the @t{stat} system call. + +@item @t{zsh/system} +A builtin interface to various low-level system features. + +@item @t{zsh/net/tcp} +Manipulation of TCP sockets + +@item @t{zsh/termcap} +Interface to the termcap database. + +@item @t{zsh/terminfo} +Interface to the terminfo database. + +@item @t{zsh/watch} +Reporting of login and logout events. + +@item @t{zsh/zftp} +A builtin FTP client. + +@item @t{zsh/zle} +The Zsh Line Editor, including the @t{bindkey} and @t{vared} builtins. + +@item @t{zsh/zleparameter} +Access to internals of the Zsh Line Editor via parameters. + +@item @t{zsh/zprof} +A module allowing profiling for shell functions. + +@item @t{zsh/zpty} +A builtin for starting a command in a pseudo-terminal. + +@item @t{zsh/zselect} +Block and return when file descriptors are ready. + +@item @t{zsh/zutil} +Some utility builtins, e.g. the one for supporting configuration via +styles. + +@end table +@c Yodl file: Zsh/modmenu.yo +@menu +* 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/watch 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:: +@end menu +@c (avoiding a yodl bug) +@node The zsh/attr Module, The zsh/cap Module, , Zsh Modules + +@section The zsh/attr Module +@noindent +@c Yodl file: Zsh/mod_attr.yo + +The @t{zsh/attr} module is used for manipulating extended attributes. +The @t{-h} option causes all commands to operate on symbolic links instead +of their targets. +The builtins in this module are: + +@noindent +@table @asis +@findex zgetattr +@cindex extended attributes, xattr, getting from files +@item @t{zgetattr} [ @t{-h} ] @var{filename} @var{attribute} [ @var{parameter} ] +Get the extended attribute @var{attribute} from the specified +@var{filename}. If the optional argument @var{parameter} is given, the +attribute is set on that parameter instead of being printed to stdout. + +@findex zsetattr +@cindex extended attributes, xattr, setting on files +@item @t{zsetattr} [ @t{-h} ] @var{filename} @var{attribute} @var{value} +Set the extended attribute @var{attribute} on the specified +@var{filename} to @var{value}. + +@findex zdelattr +@cindex extended attributes, xattr, removing, deleting +@item @t{zdelattr} [ @t{-h} ] @var{filename} @var{attribute} +Remove the extended attribute @var{attribute} from the specified +@var{filename}. + +@findex zlistattr +@cindex extended attributes, xattr, listing +@item @t{zlistattr} [ @t{-h} ] @var{filename} [ @var{parameter} ] +List the extended attributes currently set on the specified +@var{filename}. If the optional argument @var{parameter} is given, the +list of attributes is set on that parameter instead of being printed to stdout. + +@end table + +@noindent +@t{zgetattr} and @t{zlistattr} allocate memory dynamically. If the +attribute or list of attributes grows between the allocation and the call +to get them, they return 2. On all other errors, 1 is returned. This +allows the calling function to check for this case and retry. +@c (avoiding a yodl bug) +@node The zsh/cap Module, The zsh/clone Module, The zsh/attr Module, Zsh Modules + +@section The zsh/cap Module +@noindent +@c Yodl file: Zsh/mod_cap.yo + +The @t{zsh/cap} module is used for manipulating POSIX.1e (POSIX.6) capability +sets. If the operating system does not support this interface, the +builtins defined by this module will do nothing. +The builtins in this module are: + +@noindent +@table @asis +@findex cap +@cindex capabilities, setting +@item @t{cap} [ @var{capabilities} ] +Change the shell's process capability sets to the specified @var{capabilities}, +otherwise display the shell's current capabilities. + +@findex getcap +@cindex capabilities, getting from files +@item @t{getcap} @var{filename} ... +This is a built-in implementation of the POSIX standard utility. It displays +the capability sets on each specified @var{filename}. + +@findex setcap +@cindex capabilities, setting on files +@item @t{setcap} @var{capabilities} @var{filename} ... +This is a built-in implementation of the POSIX standard utility. It sets +the capability sets on each specified @var{filename} to the specified +@var{capabilities}. + +@end table +@c (avoiding a yodl bug) +@node The zsh/clone Module, The zsh/compctl Module, The zsh/cap Module, Zsh Modules + +@section The zsh/clone Module +@noindent +@c Yodl file: Zsh/mod_clone.yo + +The @t{zsh/clone} module makes available one builtin command: + +@noindent +@table @asis +@findex clone +@cindex shell, cloning +@cindex cloning the shell +@cindex terminal +@item @t{clone} @var{tty} +Creates a forked instance of the current shell, attached to the specified +@var{tty}. In the new shell, the @t{PID}, @t{PPID} and @t{TTY} special +parameters are changed appropriately. @t{$!} is set to zero in the new +shell, and to the new shell's PID in the original shell. + +@noindent +The return status of the builtin is zero in both shells if successful, +and non-zero on error. + +@noindent +The target of @t{clone} should be an unused terminal, such as an unused virtual +console or a virtual terminal created by + +@noindent +@example +xterm -e sh -c 'trap : INT QUIT TSTP; tty; + while :; do sleep 100000000; done' +@end example + +@noindent +Some words of explanation are warranted about this long xterm command +line: when doing clone on a pseudo-terminal, some other session +("session" meant as a unix session group, or SID) is already owning +the terminal. Hence the cloned zsh cannot acquire the pseudo-terminal +as a controlling tty. That means two things: + +@noindent +@itemize @bullet + +@item +the job control signals will go to the sh-started-by-xterm process +group (that's why we disable INT QUIT and TSTP with trap; otherwise +the while loop could get suspended or killed) +@item +the cloned shell will have job control disabled, and the job +control keys (control-C, control-\ and control-Z) will not work. +@end itemize + +@noindent +This does not apply when cloning to an @emph{unused} vc. + +@noindent +Cloning to a used (and unprepared) terminal will result in two +processes reading simultaneously from the same terminal, with +input bytes going randomly to either process. + +@noindent +@t{clone} is mostly useful as a shell built-in replacement for +openvt. + +@end table +@c (avoiding a yodl bug) +@node The zsh/compctl Module, The zsh/complete Module, The zsh/clone Module, Zsh Modules + +@section The zsh/compctl Module +@noindent +@c Yodl file: Zsh/mod_compctl.yo + +The @t{zsh/compctl} module makes available two builtin commands. @t{compctl}, +is the old, deprecated way to control completions for ZLE. See +@ref{Completion Using compctl}. +The other builtin command, @t{compcall} can be used in user-defined +completion widgets, see +@ref{Completion Widgets}. +@c (avoiding a yodl bug) +@node The zsh/complete Module, The zsh/complist Module, The zsh/compctl Module, Zsh Modules + +@section The zsh/complete Module +@noindent +@c Yodl file: Zsh/mod_complete.yo + +The @t{zsh/complete} module makes available several builtin commands which +can be used in user-defined completion widgets, see +@ref{Completion Widgets}. +@c (avoiding a yodl bug) +@node The zsh/complist Module, The zsh/computil Module, The zsh/complete Module, Zsh Modules + +@section The zsh/complist Module +@noindent +@c Yodl file: Zsh/mod_complist.yo + +@cindex completion, listing +@cindex completion, coloured listings +@cindex completion, scroll listings +The @t{zsh/complist} module offers three extensions to completion listings: +the ability to highlight matches in such a list, the ability to +scroll through long lists and a different style of menu completion. + +@noindent + +@subsection Colored completion listings +@noindent +Whenever one of the parameters @t{ZLS_COLORS} or @t{ZLS_COLOURS} is set +and the @t{zsh/complist} module is loaded or linked into the shell, +completion lists will be colored. Note, however, that @t{complist} will +not automatically be loaded if it is not linked in: on systems with +dynamic loading, `@t{zmodload zsh/complist}' is required. + +@noindent +@vindex ZLS_COLORS +@vindex ZLS_COLOURS +The parameters @t{ZLS_COLORS} and @t{ZLS_COLOURS} describe how matches +are highlighted. To turn on highlighting an empty value suffices, in +which case all the default values given below will be used. The format of +the value of these parameters is the same as used by the GNU version of the +@t{ls} command: a colon-separated list of specifications of the form +`@var{name}@t{=}@var{value}'. The @var{name} may be one of the following strings, +most of which specify file types for which the @var{value} will be used. +The strings and their default values are: + +@noindent +@table @asis +@item @t{no 0} +for normal text (i.e. when displaying something other than a matched file) + +@item @t{fi 0} +for regular files + +@item @t{di 32} +for directories + +@item @t{ln 36} +for symbolic links. If this has the special value @t{target}, +symbolic links are dereferenced and the target file used to +determine the display format. + +@item @t{pi 31} +for named pipes (FIFOs) + +@item @t{so 33} +for sockets + +@item @t{bd 44;37} +for block devices + +@item @t{cd 44;37} +for character devices + +@item @t{or} @var{none} +for a symlink to nonexistent file (default is the value defined for @t{ln}) + +@item @t{mi} @var{none} +for a non-existent file (default is the value defined for @t{fi}); this code +is currently not used + +@item @t{su 37;41} +for files with setuid bit set + +@item @t{sg 30;43} +for files with setgid bit set + +@item @t{tw 30;42} +for world writable directories with sticky bit set + +@item @t{ow 34;43} +for world writable directories without sticky bit set + +@item @t{sa} @var{none} +for files with an associated suffix alias; this is only tested +after specific suffixes, as described below + +@item @t{st 37;44} +for directories with sticky bit set but not world writable + +@item @t{ex 35} +for executable files + +@item @t{lc \e[} +for the left code (see below) + +@item @t{rc m} +for the right code + +@item @t{tc 0} +for the character indicating the file type printed after filenames if +the @t{LIST_TYPES} option is set + +@item @t{sp 0} +for the spaces printed after matches to align the next column + +@item @t{ec} @var{none} +for the end code + +@end table + +@noindent +Apart from these strings, the @var{name} may also be an asterisk +(`@t{*}') followed by any string. The @var{value} given for such a +string will be used for all files whose name ends with the string. +The @var{name} may also be an equals sign (`@t{=}') followed by a +pattern; the @t{EXTENDED_GLOB} option will be turned on for evaluation +of the pattern. The @var{value} given for this pattern will be used for all +matches (not just filenames) whose display string are matched by +the pattern. Definitions for the form with the leading equal sign take +precedence over the values defined for file types, which in turn take +precedence over the form with the leading asterisk (file extensions). + +@noindent +The leading-equals form also allows different parts of the displayed +strings to be colored differently. For this, the pattern has to use the +`@t{(#b)}' globbing flag and pairs of parentheses surrounding the +parts of the strings that are to be colored differently. In this case +the @var{value} may consist of more than one color code separated by +equal signs. The first code will be used for all parts for which no +explicit code is specified and the following codes will be used for +the parts matched by the sub-patterns in parentheses. For example, +the specification `@t{=(#b)(?)*(?)=0=3=7}' will be used for all +matches which are at least two characters long and will use +the code `@t{3}' for the first character, `@t{7}' for the last +character and `@t{0}' for the rest. + +@noindent +All three forms of @var{name} may be preceded by a pattern in +parentheses. If this is given, the @var{value} will be used +only for matches in groups whose names are matched by the pattern +given in the parentheses. For example, `@t{(g*)m*=43}' highlights all +matches beginning with `@t{m}' in groups whose names begin with +`@t{g}' using the color code `@t{43}'. In case of the `@t{lc}', +`@t{rc}', and `@t{ec}' codes, the group pattern is ignored. + +@noindent +Note also that all patterns are tried in the order in which they +appear in the parameter value until the first one matches which is +then used. Patterns may be matched against completions, descriptions +(possibly with spaces appended for padding), or lines consisting of a +completion followed by a description. For consistent coloring it may be +necessary to use more than one pattern or a pattern with backreferences. + +@noindent +When printing a match, the code prints the value of @t{lc}, the value +for the file-type or the last matching specification with a `@t{*}', +the value of @t{rc}, the string to display for the match itself, and +then the value of @t{ec} if that is defined or the values of @t{lc}, +@t{no}, and @t{rc} if @t{ec} is not defined. + +@noindent +The default values are ISO 6429 (ANSI) compliant and can be used on +vt100 compatible terminals such as @t{xterm}s. On monochrome terminals +the default values will have no visible effect. The @t{colors} +function from the contribution can be used to get associative arrays +containing the codes for ANSI terminals (see +@ref{Other Functions}). For example, after loading @t{colors}, one could use +`@t{$color[red]}' to get the code for foreground color red and +`@t{$color[bg-green]}' for the code for background color green. + +@noindent +If the completion system invoked by compinit is used, these +parameters should not be set directly because the system controls them +itself. Instead, the @t{list-colors} style should be used (see +@ref{Completion System Configuration}). + +@noindent + +@subsection Scrolling in completion listings +@noindent +To enable scrolling through a completion list, the @t{LISTPROMPT} +parameter must be set. Its value will be used as the prompt; if it +is the empty string, a default prompt will be used. The value may +contain escapes of the form `@t{%x}'. It supports the escapes +`@t{%B}', `@t{%b}', `@t{%S}', `@t{%s}', `@t{%U}', `@t{%u}', `@t{%F}', +`@t{%f}', `@t{%K}', `@t{%k}' and +`@t{%@{}@var{...}@t{%@}}' used also in shell prompts as well as three pairs of +additional sequences: a `@t{%l}' or `@t{%L}' is replaced by the number +of the last line shown and the total number of lines in the form +`@var{number}@t{/}@var{total}'; a `@t{%m}' or `@t{%M}' is replaced with +the number of the last match shown and the total number of matches; and +`@t{%p}' or `@t{%P}' is replaced with `@t{Top}', `@t{Bottom}' or the +position of the first line shown in percent of the total number of +lines, respectively. In each of these cases the form with the uppercase +letter will be replaced with a string of fixed width, padded to the +right with spaces, while the lowercase form will not be padded. + +@noindent +If the parameter @t{LISTPROMPT} is set, the completion code will not ask if +the list should be shown. Instead it immediately starts displaying the +list, stopping after the first screenful, showing the prompt at the bottom, +waiting for a keypress after temporarily switching to the @t{listscroll} +keymap. Some of the zle functions have a special meaning while scrolling +lists: + +@noindent +@table @asis +@item @t{send-break} +stops listing discarding the key pressed + +@item @t{accept-line}, @t{down-history}, @t{down-line-or-history} +@itemx @t{down-line-or-search}, @t{vi-down-line-or-history} +scrolls forward one line + +@item @t{complete-word}, @t{menu-complete}, @t{expand-or-complete} +@itemx @t{expand-or-complete-prefix}, @t{menu-complete-or-expand} +scrolls forward one screenful + +@item @t{accept-search} +stop listing but take no other action + +@end table + +@noindent +Every other character stops listing and immediately processes the key +as usual. Any key that is not bound in the @t{listscroll} keymap or +that is bound to @t{undefined-key} is looked up in the keymap +currently selected. + +@noindent +As for the @t{ZLS_COLORS} and @t{ZLS_COLOURS} parameters, +@t{LISTPROMPT} should not be set directly when using the shell +function based completion system. Instead, the @t{list-prompt} style +should be used. + +@noindent + +@subsection Menu selection +@noindent +@cindex completion, selecting by cursor +@vindex MENUSELECT +@tindex menu-select +The @t{zsh/complist} module also offers an alternative style of selecting +matches from a list, called menu selection, which can be used if the +shell is set up to return to the last prompt after showing a +completion list (see the @t{ALWAYS_LAST_PROMPT} option in +@ref{Options}). + +@noindent +Menu selection can be invoked directly by +the widget @t{menu-select} defined by this module. This is a standard +ZLE widget that can be bound to a key in the usual way as described +in @ref{Zsh Line Editor}. + +@noindent +Alternatively, +the parameter @t{MENUSELECT} can be set to an integer, which gives the +minimum number of matches that must be present before menu selection is +automatically turned on. This second method requires that menu completion +be started, either directly from a widget such as @t{menu-complete}, or due +to one of the options @t{MENU_COMPLETE} or @t{AUTO_MENU} being set. If +@t{MENUSELECT} is set, but is 0, 1 or empty, menu selection will always be +started during an ambiguous menu completion. + +@noindent +When using the completion system based on shell functions, the +@t{MENUSELECT} parameter should not be used (like the @t{ZLS_COLORS} +and @t{ZLS_COLOURS} parameters described above). Instead, the @t{menu} +style should be used with the @t{select=}@var{...} keyword. + +@noindent +After menu selection is started, the matches will be listed. If there +are more matches than fit on the screen, only the first screenful is +shown. The +matches to insert into the command line can be selected from this +list. In the list one match is highlighted using the value for @t{ma} +from the @t{ZLS_COLORS} or @t{ZLS_COLOURS} parameter. The default +value for this is `@t{7}' which forces the selected match to be +highlighted using standout mode on a vt100-compatible terminal. If +neither @t{ZLS_COLORS} nor @t{ZLS_COLOURS} is set, the same terminal +control sequence as for the `@t{%S}' escape in prompts is used. + +@noindent +If there are more matches than fit on the screen and the parameter +@t{MENUPROMPT} is set, its value will be shown below the matches. It +supports the same escape sequences as @t{LISTPROMPT}, but the number +of the match or line shown will be that of the one where the mark is +placed. If its value is the empty string, a default prompt will be +used. + +@noindent +The @t{MENUSCROLL} parameter can be used to specify how the list is +scrolled. If the parameter is unset, this is done line by line, if it +is set to `@t{0}' (zero), the list will scroll half the number of +lines of the screen. If the value is positive, it gives the number of +lines to scroll and if it is negative, the list will be scrolled +the number of lines of the screen minus the (absolute) value. + +@noindent +As for the @t{ZLS_COLORS}, @t{ZLS_COLOURS} and @t{LISTPROMPT} +parameters, neither @t{MENUPROMPT} nor @t{MENUSCROLL} should be +set directly when using the shell function based completion +system. Instead, the @t{select-prompt} and @t{select-scroll} styles +should be used. + +@noindent +The completion code sometimes decides not to show all of the matches +in the list. These hidden matches are either matches for which the +completion function which added them explicitly requested that they +not appear in the list (using the @t{-n} option of the @t{compadd} +builtin command) or they are matches which duplicate a string already +in the list (because they differ only in things like prefixes or +suffixes that are not displayed). In the list used for menu selection, +however, even these matches are shown so that it is possible to select +them. To highlight such matches the @t{hi} and @t{du} capabilities in +the @t{ZLS_COLORS} and @t{ZLS_COLOURS} parameters are supported for +hidden matches of the first and second kind, respectively. + +@noindent +Selecting matches is done by moving the mark around using the zle movement +functions. When not all matches can be shown on the screen at the same +time, the list will scroll up and down when crossing the top or +bottom line. The following zle functions have special meaning during +menu selection. Note that the following always +perform the same task within the menu selection map and cannot be +replaced by user defined widgets, nor can the set of functions +be extended: + +@noindent +@table @asis +@item @t{accept-line}, @t{accept-search} +accept the current match and leave menu selection (but do +not cause the command line to be accepted) + +@item @t{send-break} +leaves menu selection and restores the previous contents of the +command line + +@item @t{redisplay}, @t{clear-screen} +execute their normal function without leaving menu selection + +@item @t{accept-and-hold}, @t{accept-and-menu-complete} +accept the currently inserted match and continue selection allowing to +select the next match to insert into the line + +@item @t{accept-and-infer-next-history} +accepts the current match and then tries completion with +menu selection again; in the case of files this allows one to select +a directory and immediately attempt to complete files in it; if there +are no matches, a message is shown and one can use @t{undo} to go back +to completion on the previous level, every other key leaves menu +selection (including the other zle functions which are otherwise +special during menu selection) + +@item @t{undo} +removes matches inserted during the menu selection by one of the three +functions before + +@item @t{down-history}, @t{down-line-or-history} +@itemx @t{vi-down-line-or-history}, @t{down-line-or-search} +moves the mark one line down + +@item @t{up-history}, @t{up-line-or-history} +@itemx @t{vi-up-line-or-history}, @t{up-line-or-search} +moves the mark one line up + +@item @t{forward-char}, @t{vi-forward-char} +moves the mark one column right + +@item @t{backward-char}, @t{vi-backward-char} +moves the mark one column left + +@item @t{forward-word}, @t{vi-forward-word} +@itemx @t{vi-forward-word-end}, @t{emacs-forward-word} +moves the mark one screenful down + +@item @t{backward-word}, @t{vi-backward-word}, @t{emacs-backward-word} +moves the mark one screenful up + +@item @t{vi-forward-blank-word}, @t{vi-forward-blank-word-end} +moves the mark to the first line of the next group of matches + +@item @t{vi-backward-blank-word} +moves the mark to the last line of the previous group of matches + +@item @t{beginning-of-history} +moves the mark to the first line + +@item @t{end-of-history} +moves the mark to the last line + +@item @t{beginning-of-buffer-or-history}, @t{beginning-of-line} +@itemx @t{beginning-of-line-hist}, @t{vi-beginning-of-line} +moves the mark to the leftmost column + +@item @t{end-of-buffer-or-history}, @t{end-of-line} +@itemx @t{end-of-line-hist}, @t{vi-end-of-line} +moves the mark to the rightmost column + +@item @t{complete-word}, @t{menu-complete}, @t{expand-or-complete} +@itemx @t{expand-or-complete-prefix}, @t{menu-expand-or-complete} +moves the mark to the next match + +@item @t{reverse-menu-complete} +moves the mark to the previous match + +@item @t{vi-insert} +this toggles between normal and interactive mode; in interactive mode +the keys bound to @t{self-insert} and @t{self-insert-unmeta} insert +into the command line as in normal editing mode but without leaving +menu selection; after each character completion is tried again and the +list changes to contain only the new matches; the completion widgets +make the longest unambiguous string be inserted in the command line +and @t{undo} and @t{backward-delete-char} go back to the previous set +of matches + +@item @t{history-incremental-search-forward} +@itemx @t{history-incremental-search-backward} +this starts incremental searches in the list of completions displayed; +in this mode, @t{accept-line} only leaves incremental search, going +back to the normal menu selection mode + +@end table + +@noindent +All movement functions wrap around at the edges; any other zle function not +listed leaves menu selection and executes that function. It is possible to +make widgets in the above list do the same by using the form of the widget +with a `@t{.}' in front. For example, the widget `@t{.accept-line}' has +the effect of leaving menu selection and accepting the entire command line. + +@noindent +During this selection the widget uses the keymap @t{menuselect}. Any +key that is not defined in this keymap or that is bound to +@t{undefined-key} is looked up in the keymap currently selected. This +is used to ensure that the most important keys used during selection +(namely the cursor keys, return, and TAB) have sensible defaults. However, +keys in the @t{menuselect} keymap can be modified directly using the +@t{bindkey} builtin command (see +@ref{The zsh/zle Module}). For example, to make the return key leave menu selection without +accepting the match currently selected one could call + +@noindent +@example +bindkey -M menuselect '^M' send-break +@end example + +@noindent +after loading the @t{zsh/complist} module. +@c (avoiding a yodl bug) +@node The zsh/computil Module, The zsh/curses Module, The zsh/complist Module, Zsh Modules + +@section The zsh/computil Module +@noindent +@c Yodl file: Zsh/mod_computil.yo + +@cindex completion, utility +The @t{zsh/computil} module adds several builtin commands that are used by +some of the completion functions in the completion system based on shell +functions (see +@ref{Completion System} +). Except for @t{compquote} these builtin commands are very +specialised and thus not very interesting when writing your own +completion functions. In summary, these builtin commands are: + +@noindent +@table @asis +@findex comparguments +@item @t{comparguments} +This is used by the @t{_arguments} function to do the argument and +command line parsing. Like @t{compdescribe} it has an option @t{-i} to +do the parsing and initialize some internal state and various options +to access the state information to decide what should be completed. + +@findex compdescribe +@item @t{compdescribe} +This is used by the @t{_describe} function to build the displays for +the matches and to get the strings to add as matches with their +options. On the first call one of the options @t{-i} or @t{-I} should be +supplied as the first argument. In the first case, display strings without +the descriptions will be generated, in the second case, the string used to +separate the matches from their descriptions must be given as the +second argument and the descriptions (if any) will be shown. All other +arguments are like the definition arguments to @t{_describe} itself. + +@noindent +Once @t{compdescribe} has been called with either the @t{-i} or the +@t{-I} option, it can be repeatedly called with the @t{-g} option and +the names of four parameters as its arguments. This will step through +the different sets of matches and store the value of @t{compstate[list]} +in the first scalar, the options for @t{compadd} in the second array, +the matches in the third array, and the strings to be displayed in the +completion listing in the fourth array. The arrays may then be directly +given to @t{compadd} to register the matches with the completion code. + +@findex compfiles +@item @t{compfiles} +Used by the @t{_path_files} function to optimize complex recursive +filename generation (globbing). It does three things. With the +@t{-p} and @t{-P} options it builds the glob patterns to use, +including the paths already handled and trying to optimize the +patterns with respect to the prefix and suffix from the line and the +match specification currently used. The @t{-i} option does the +directory tests for the @t{ignore-parents} style and the @t{-r} option +tests if a component for some of the matches are equal to the string +on the line and removes all other matches if that is true. + +@findex compgroups +@item @t{compgroups} +Used by the @t{_tags} function to implement the internals of the +@t{group-order} style. This only takes its arguments as names of +completion groups and creates the groups for it (all six types: sorted +and unsorted, both without removing duplicates, with removing all +duplicates and with removing consecutive duplicates). + +@findex compquote +@item @t{compquote} [ @t{-p} ] @var{names} ... +There may be reasons to write completion functions that have to add +the matches using the @t{-Q} option to @t{compadd} and perform quoting +themselves. Instead of interpreting the first character of the +@t{all_quotes} key of the @t{compstate} special association and using +the @t{q} flag for parameter expansions, one can use this builtin +command. The arguments are the names of scalar or array parameters +and the values of these parameters are quoted as needed for the +innermost quoting level. If the @t{-p} option is given, quoting is +done as if there is some prefix before the values of the parameters, +so that a leading equal sign will not be quoted. + +@noindent +The return status is non-zero in case of an error and zero otherwise. + +@findex comptags +@findex comptry +@item @t{comptags} +@itemx @t{comptry} +These implement the internals of the tags mechanism. + +@findex compvalues +@item @t{compvalues} +Like @t{comparguments}, but for the @t{_values} function. + +@end table +@c (avoiding a yodl bug) +@node The zsh/curses Module, The zsh/datetime Module, The zsh/computil Module, Zsh Modules + +@section The zsh/curses Module +@noindent +@c Yodl file: Zsh/mod_curses.yo + +The @t{zsh/curses} module makes available one builtin command and +various parameters. + +@noindent + +@subsection Builtin +@noindent + +@noindent +@table @asis +@findex zcurses +@cindex windows, curses +@item @t{zcurses} @t{init} +@itemx @t{zcurses} @t{end} +@itemx @t{zcurses} @t{addwin} @var{targetwin} @var{nlines} @var{ncols} @var{begin_y} @var{begin_x} [ @var{parentwin} ] +@itemx @t{zcurses} @t{delwin} @var{targetwin} +@itemx @t{zcurses} @t{refresh} [ @var{targetwin} ... ] +@itemx @t{zcurses} @t{touch} @var{targetwin} ... +@itemx @t{zcurses} @t{move} @var{targetwin} @var{new_y} @var{new_x} +@itemx @t{zcurses} @t{clear} @var{targetwin} [ @t{redraw} | @t{eol} | @t{bot} ] +@itemx @t{zcurses} @t{position} @var{targetwin} @var{array} +@itemx @t{zcurses} @t{char} @var{targetwin} @var{character} +@itemx @t{zcurses} @t{string} @var{targetwin} @var{string} +@itemx @t{zcurses} @t{border} @var{targetwin} @var{border} +@itemx @t{zcurses} @t{attr} @var{targetwin} [ [@t{+}|@t{-}]@var{attribute} | @var{fg_col}@t{/}@var{bg_col} ] [...] +@itemx @t{zcurses} @t{bg} @var{targetwin} [ [@t{+}|@t{-}]@var{attribute} | @var{fg_col}@t{/}@var{bg_col} | @t{@@}@var{char} ] [...] +@itemx @t{zcurses} @t{scroll} @var{targetwin} [ @t{on} | @t{off} | [@t{+}|@t{-}]@var{lines} ] +@itemx @t{zcurses} @t{input} @var{targetwin} [ @var{param} [ @var{kparam} [ @var{mparam} ] ] ] +@itemx @t{zcurses} @t{mouse} [ @t{delay} @var{num} | [@t{+}|@t{-}]@t{motion} ] +@itemx @t{zcurses} @t{timeout} @var{targetwin} @var{intval} +@itemx @t{zcurses} @t{querychar} @var{targetwin} [ @var{param} ] +@itemx @t{zcurses} @t{resize} @var{height} @var{width} [ @t{endwin} | @t{nosave} | @t{endwin_nosave} ] +Manipulate curses windows. All uses of this command should be +bracketed by `@t{zcurses init}' to initialise use of curses, and +`@t{zcurses end}' to end it; omitting `@t{zcurses end}' can cause +the terminal to be in an unwanted state. + +@noindent +The subcommand @t{addwin} creates a window with @var{nlines} lines and +@var{ncols} columns. Its upper left corner will be placed at row +@var{begin_y} and column +@var{begin_x} of the screen. @var{targetwin} is a string and refers +to the name of a window that is not currently assigned. Note +in particular the curses convention that vertical values appear +before horizontal values. + +@noindent +If @t{addwin} is given an existing window as the final argument, the new +window is created as a subwindow of @var{parentwin}. This differs from an +ordinary new window in that the memory of the window contents is shared +with the parent's memory. Subwindows must be deleted before their parent. +Note that the coordinates of subwindows are relative to the screen, not +the parent, as with other windows. + +@noindent +Use the subcommand @t{delwin} to delete a window created with +@t{addwin}. Note that @t{end} does @emph{not} implicitly delete windows, +and that @t{delwin} does not erase the screen image of the window. + +@noindent +The window corresponding to the full visible screen is called +@t{stdscr}; it always exists after `@t{zcurses init}' and cannot +be delete with @t{delwin}. + +@noindent +The subcommand @t{refresh} will refresh window @var{targetwin}; this is +necessary to make any pending changes (such as characters you have +prepared for output with @t{char}) visible on the screen. @t{refresh} +without an argument causes the screen to be cleared and redrawn. +If multiple windows are given, the screen is updated once at the end. + +@noindent +The subcommand @t{touch} marks the @var{targetwin}s listed as changed. +This is necessary before @t{refresh}ing windows if a window that +was in front of another window (which may be @t{stdscr}) is deleted. + +@noindent +The subcommand @t{move} moves the cursor position in @var{targetwin} to +new coordinates @var{new_y} and @var{new_x}. Note that the +subcommand @t{string} (but not the subcommand @t{char}) advances the +cursor position over the characters added. + +@noindent +The subcommand @t{clear} erases the contents of @var{targetwin}. One +(and no more than one) of three options may be specified. With the +option @t{redraw}, in addition the next @t{refresh} of @var{targetwin} +will cause the screen to be cleared and repainted. With the option +@t{eol}, @var{targetwin} is only cleared to the end of the current cursor +line. With the option +@t{bot}, @var{targetwin} is cleared to the end of the window, i.e +everything to the right and below the cursor is cleared. + +@noindent +The subcommand @t{position} writes various positions associated with +@var{targetwin} into the array named @var{array}. +These are, in order: +@table @asis +@item - +The y and x coordinates of the cursor relative to the top left +of @var{targetwin} +@item - +The y and x coordinates of the top left of @var{targetwin} on the +screen +@item - +The size of @var{targetwin} in y and x dimensions. +@end table + +@noindent +Outputting characters and strings are achieved by @t{char} and @t{string} +respectively. + +@noindent +To draw a border around window @var{targetwin}, use @t{border}. Note +that the border is not subsequently handled specially: in other words, +the border is simply a set of characters output at the edge of the +window. Hence it can be overwritten, can scroll off the window, etc. + +@noindent +The subcommand @t{attr} will set @var{targetwin}'s attributes or +foreground/background color pair for any successive character output. +Each @var{attribute} given on the line may be prepended by a @t{+} to set +or a @t{-} to unset that attribute; @t{+} is assumed if absent. The +attributes supported are @t{blink}, @t{bold}, @t{dim}, @t{reverse}, +@t{standout}, and @t{underline}. + +@noindent +Each @var{fg_col}@t{/}@var{bg_col} attribute (to be read as +`@var{fg_col} on @var{bg_col}') sets the foreground and background color +for character output. The color @t{default} is sometimes available +(in particular if the library is ncurses), specifying the foreground +or background color with which the terminal started. The color pair +@t{default/default} is always available. To use more than the 8 named +colors (red, green, etc.) construct the @var{fg_col}@t{/}@var{bg_col} +pairs where @var{fg_col} and @var{bg_col} are decimal integers, e.g +@t{128/200}. The maximum color value is 254 if the terminal supports +256 colors. + +@noindent +@t{bg} overrides the color and other attributes of all characters in the +window. Its usual use is to set the background initially, but it will +overwrite the attributes of any characters at the time when it is called. +In addition to the arguments allowed with @t{attr}, an argument @t{@@}@var{char} +specifies a character to be shown in otherwise blank areas of the window. +Owing to limitations of curses this cannot be a multibyte character +(use of ASCII characters only is recommended). As the specified set +of attributes override the existing background, turning attributes +off in the arguments is not useful, though this does not cause an error. + +@noindent +The subcommand @t{scroll} can be used with @t{on} or @t{off} to enabled +or disable scrolling of a window when the cursor would otherwise move +below the window due to typing or output. It can also be used with a +positive or negative integer to scroll the window up or down the given +number of lines without changing the current cursor position (which +therefore appears to move in the opposite direction relative to the +window). In the second case, if scrolling is @t{off} it is temporarily +turned @t{on} to allow the window to be scrolled. + +@noindent +The subcommand @t{input} reads a single character from the window +without echoing it back. If @var{param} is supplied the character is +assigned to the parameter @var{param}, else it is assigned to the +parameter @t{REPLY}. + +@noindent +If both @var{param} and @var{kparam} are supplied, the key is read in +`keypad' mode. In this mode special keys such as function keys and +arrow keys return the name of the key in the parameter @var{kparam}. The +key names are the macros defined in the @t{curses.h} or @t{ncurses.h} +with the prefix `@t{KEY_}' removed; see also the description of the +parameter @t{zcurses_keycodes} below. Other keys cause a value to be +set in @var{param} as before. On a successful return only one of +@var{param} or @var{kparam} contains a non-empty string; the other is set +to an empty string. + +@noindent +If @var{mparam} is also supplied, @t{input} attempts to handle mouse +input. This is only available with the ncurses library; mouse handling +can be detected by checking for the exit status of `@t{zcurses mouse}' with +no arguments. If a mouse +button is clicked (or double- or triple-clicked, or pressed or released with +a configurable delay from being clicked) then @var{kparam} is set to the string +@t{MOUSE}, and @var{mparam} is set to an array consisting of the +following elements: +@table @asis +@item - +An identifier to discriminate different input devices; this +is only rarely useful. +@item - +The x, y and z coordinates of the mouse click relative to +the full screen, as three elements in that order (i.e. the y coordinate +is, unusually, after the x coordinate). The z coordinate is only +available for a few unusual input devices and is otherwise set to zero. +@item - +Any events that occurred as separate items; usually +there will be just one. An event consists of @t{PRESSED}, @t{RELEASED}, +@t{CLICKED}, @t{DOUBLE_CLICKED} or @t{TRIPLE_CLICKED} followed +immediately (in the same element) by the number of the button. +@item - +If the shift key was pressed, the string @t{SHIFT}. +@item - +If the control key was pressed, the string @t{CTRL}. +@item - +If the alt key was pressed, the string @t{ALT}. +@end table + +@noindent +Not all mouse events may be passed through to the terminal window; +most terminal emulators handle some mouse events themselves. Note +that the ncurses manual implies that using input both with and +without mouse handling may cause the mouse cursor to appear and +disappear. + +@noindent +The subcommand @t{mouse} can be used to configure the use of the mouse. +There is no window argument; mouse options are global. +`@t{zcurses mouse}' with no arguments returns status 0 if mouse handling +is possible, else status 1. Otherwise, the possible arguments (which +may be combined on the same command line) are as follows. +@t{delay} @var{num} sets the maximum delay in milliseconds between press and +release events to be considered as a click; the value 0 disables click +resolution, and the default is one sixth of a second. @t{motion} proceeded +by an optional `@t{+}' (the default) or @t{-} turns on or off +reporting of mouse motion in addition to clicks, presses and releases, +which are always reported. However, it appears reports for mouse +motion are not currently implemented. + +@noindent +The subcommand @t{timeout} specifies a timeout value for input from +@var{targetwin}. If @var{intval} is negative, `@t{zcurses input}' waits +indefinitely for a character to be typed; this is the default. If +@var{intval} is zero, `@t{zcurses input}' returns immediately; if there +is typeahead it is returned, else no input is done and status 1 is +returned. If @var{intval} is positive, `@t{zcurses input}' waits +@var{intval} milliseconds for input and if there is none at the end of +that period returns status 1. + +@noindent +The subcommand @t{querychar} queries the character at the current cursor +position. The return values are stored in the array named @var{param} if +supplied, else in the array @t{reply}. The first value is the character +(which may be a multibyte character if the system supports them); the +second is the color pair in the usual @var{fg_col}@t{/}@var{bg_col} +notation, or @t{0} if color is not supported. Any attributes other than +color that apply to the character, as set with the subcommand @t{attr}, +appear as additional elements. + +@noindent +The subcommand @t{resize} resizes @t{stdscr} and all windows to given +dimensions (windows that stick out from the new dimensions are resized +down). The underlying curses extension (@t{resize_term call}) can be +unavailable. To verify, zeroes can be used for @var{height} and +@var{width}. If the result of the subcommand is @t{0}, resize_term is +available (@t{2} otherwise). Tests show that resizing can be normally +accomplished by calling @t{zcurses end} and @t{zcurses refresh}. The +@t{resize} subcommand is provided for versatility. Multiple system +configurations have been checked and @t{zcurses end} and @t{zcurses +refresh} are still needed for correct terminal state after resize. To +invoke them with @t{resize}, use @var{endwin} argument. Using +@var{nosave} argument will cause new terminal state to not be saved +internally by @t{zcurses}. This is also provided for versatility and +should normally be not needed. + +@end table + +@noindent + +@subsection Parameters +@noindent + +@noindent +@table @asis +@vindex ZCURSES_COLORS +@item @t{ZCURSES_COLORS} +Readonly integer. The maximum number of colors the terminal +supports. This value is initialised by the curses library and is not +available until the first time @t{zcurses init} is run. + +@vindex ZCURSES_COLOR_PAIRS +@item @t{ZCURSES_COLOR_PAIRS} +Readonly integer. The maximum number of color pairs +@var{fg_col}@t{/}@var{bg_col} that may be defined in `@t{zcurses attr}' +commands; note this limit applies to all color pairs that have been +used whether or not they are currently active. This value is initialised +by the curses library and is not available until the first time @t{zcurses +init} is run. + +@vindex zcurses_attrs +@item @t{zcurses_attrs} +Readonly array. The attributes supported by @t{zsh/curses}; available +as soon as the module is loaded. + +@vindex zcurses_colors +@item @t{zcurses_colors} +Readonly array. The colors supported by @t{zsh/curses}; available +as soon as the module is loaded. + +@vindex zcurses_keycodes +@item @t{zcurses_keycodes} +Readonly array. The values that may be returned in the second +parameter supplied to `@t{zcurses input}' in the order in which they +are defined internally by curses. Not all function keys +are listed, only @t{F0}; curses reserves space for @t{F0} up to @t{F63}. + +@vindex zcurses_windows +@item @t{zcurses_windows} +Readonly array. The current list of windows, i.e. all windows that +have been created with `@t{zcurses addwin}' and not removed with +`@t{zcurses delwin}'. + +@end table +@c (avoiding a yodl bug) +@node The zsh/datetime Module, The zsh/db/gdbm Module, The zsh/curses Module, Zsh Modules + +@section The zsh/datetime Module +@noindent +@c Yodl file: Zsh/mod_datetime.yo + +The @t{zsh/datetime} module makes available one builtin command: + +@noindent +@table @asis +@findex strftime +@cindex date string, printing +@item @t{strftime} [ @t{-s} @var{scalar} | @t{-n} ] @var{format} [ @var{epochtime} [ @var{nanoseconds} ] ] +@itemx @t{strftime} @t{-r} [ @t{-q} ] [ @t{-s} @var{scalar} | @t{-n} ] @var{format} @var{timestring} +Output the date in the @var{format} specified. With no @var{epochtime}, the +current system date/time is used; optionally, @var{epochtime} may be used to +specify the number of seconds since the epoch, and @var{nanoseconds} may +additionally be used to specify the number of nanoseconds past the second +(otherwise that number is assumed to be 0). +See strftime(3) for details. The zsh extensions described in +@ref{Prompt Expansion} are also available. + +@noindent +@table @asis +@item @t{-n} +Suppress printing a newline after the formatted string. + +@item @t{-q} +Run quietly; suppress printing of all error messages described below. +Errors for invalid @var{epochtime} values are always printed. + +@item @t{-r} +With the option @t{-r} (reverse), use @var{format} to parse the input +string @var{timestring} and output the number of seconds since the epoch at +which the time occurred. The parsing is implemented by the system +function @t{strptime}; see strptime(3). This means that zsh +format extensions are not available, but for reverse lookup they are not +required. + +@noindent +In most implementations of @t{strftime} any timezone in the +@var{timestring} is ignored and the local timezone declared by the @t{TZ} +environment variable is used; other parameters are set to zero if not +present. + +@noindent +If @var{timestring} does not match @var{format} the command returns status 1 +and prints an error message. If @var{timestring} matches @var{format} but +not all characters in @var{timestring} were used, the conversion succeeds +but also prints an error message. + +@noindent +If either of the system functions @t{strptime} or @t{mktime} is not +available, status 2 is returned and an error message is printed. + +@item @t{-s} @var{scalar} +Assign the date string (or epoch time in seconds if @t{-r} is given) to +@var{scalar} instead of printing it. + +@end table + +@noindent +Note that depending on the system's declared integral time type, +@t{strftime} may produce incorrect results for epoch times greater than +2147483647 which corresponds to 2038-01-19 03:14:07 +0000. + +@end table + +@noindent +The @t{zsh/datetime} module makes available several parameters; +all are readonly: + +@noindent +@table @asis +@vindex EPOCHREALTIME +@item @t{EPOCHREALTIME} +A floating point value representing the number of seconds since +the epoch. The notional accuracy is to nanoseconds if the +@t{clock_gettime} call is available and to microseconds otherwise, +but in practice the range of double precision floating point and +shell scheduling latencies may be significant effects. + +@vindex EPOCHSECONDS +@item @t{EPOCHSECONDS} +An integer value representing the number of seconds since the +epoch. + +@vindex epochtime +@item @t{epochtime} +An array value containing the number of seconds since the epoch +in the first element and the remainder of the time since the epoch +in nanoseconds in the second element. To ensure the two elements +are consistent the array should be copied or otherwise referenced +as a single substitution before the values are used. The following +idiom may be used: + +@noindent +@example +for secs nsecs in $epochtime; do + ... +done +@end example + +@noindent + +@end table +@c (avoiding a yodl bug) +@node The zsh/db/gdbm Module, The zsh/deltochar Module, The zsh/datetime Module, Zsh Modules + +@section The zsh/db/gdbm Module +@noindent +@c Yodl file: Zsh/mod_db_gdbm.yo + +The @t{zsh/db/gdbm} module is used to create "tied" associative arrays +that interface to database files. If the GDBM interface is not available, +the builtins defined by this module will report an error. This module is +also intended as a prototype for creating additional database interfaces, +so the @t{ztie} builtin may move to a more generic module in the future. + +@noindent +The builtins in this module are: + +@noindent +@table @asis +@findex ztie +@cindex database tied array, creating +@item @t{ztie -d db/gdbm -f} @var{filename} [ @t{-r} ] @var{arrayname} +Open the GDBM database identified by @var{filename} and, if successful, +create the associative array @var{arrayname} linked to the file. To create +a local tied array, the parameter must first be declared, so commands +similar to the following would be executed inside a function scope: + +@noindent +@example +local -A sampledb +ztie -d db/gdbm -f sample.gdbm sampledb +@end example + +@noindent +The @t{-r} option opens the database file for reading only, creating a +parameter with the readonly attribute. Without this option, using +`@t{ztie}' on a file for which the user does not have write permission is +an error. If writable, the database is opened synchronously so fields +changed in @var{arrayname} are immediately written to @var{filename}. + +@noindent +Changes to the file modes @var{filename} after it has been opened do not +alter the state of @var{arrayname}, but `@t{typeset -r} @var{arrayname}' +works as expected. + +@findex zuntie +@cindex database tied array, destroying +@item @t{zuntie} [ @t{-u} ] @var{arrayname} ... +Close the GDBM database associated with each @var{arrayname} and then +unset the parameter. The @t{-u} option forces an unset of parameters +made readonly with `@t{ztie -r}'. + +@noindent +This happens automatically if the parameter is explicitly unset or its +local scope (function) ends. Note that a readonly parameter may not be +explicitly unset, so the only way to unset a global parameter created with +`@t{ztie -r}' is to use `@t{zuntie -u}'. + +@findex zgdbmpath +@cindex database file path, reading +@item @t{zgdbmpath} @var{parametername} +Put path to database file assigned to @var{parametername} into @t{REPLY} +scalar. + +@findex zgdbm_tied +@cindex database tied arrays, enumerating +@item @t{zgdbm_tied} +Array holding names of all tied parameters. + +@end table + +@noindent +The fields of an associative array tied to GDBM are neither cached nor +otherwise stored in memory, they are read from or written to the database +on each reference. Thus, for example, the values in a readonly array may +be changed by a second writer of the same database file. +@c (avoiding a yodl bug) +@node The zsh/deltochar Module, The zsh/example Module, The zsh/db/gdbm Module, Zsh Modules + +@section The zsh/deltochar Module +@noindent +@c Yodl file: Zsh/mod_deltochar.yo + +The @t{zsh/deltochar} module makes available two ZLE functions: + +@noindent +@table @asis +@tindex delete-to-char +@item @t{delete-to-char} +Read a character from the keyboard, and +delete from the cursor position up to and including the next +(or, with repeat count @var{n}, the @var{n}th) instance of that character. +Negative repeat counts mean delete backwards. + +@tindex zap-to-char +@item @t{zap-to-char} +This behaves like @t{delete-to-char}, except that the final occurrence of +the character itself is not deleted. + +@end table +@c (avoiding a yodl bug) +@node The zsh/example Module, The zsh/files Module, The zsh/deltochar Module, Zsh Modules + +@section The zsh/example Module +@noindent +@c Yodl file: Zsh/mod_example.yo + +The @t{zsh/example} module makes available one builtin command: + +@noindent +@table @asis +@findex example +@cindex modules, example +@cindex modules, writing +@cindex writing modules +@item @t{example} [ @t{-flags} ] [ @var{args} ... ] +Displays the flags and arguments it is invoked with. + +@end table + +@noindent +The purpose of the module is to serve as an example of how to write a +module. +@c (avoiding a yodl bug) +@node The zsh/files Module, The zsh/langinfo Module, The zsh/example Module, Zsh Modules + +@section The zsh/files Module +@noindent +@c Yodl file: Zsh/mod_files.yo + +@cindex files, manipulating +The @t{zsh/files} module makes available some common commands for file +manipulation as builtins; these commands are probably not needed for +many normal situations but can be useful in emergency recovery +situations with constrained resources. The commands do not implement +all features now required by relevant standards committees. + +@noindent +For all commands, a variant beginning @t{zf_} is also available and loaded +automatically. Using the features capability of zmodload will let you load +only those names you want. Note that it's possible to load only the +builtins with zsh-specific names using the following command: + +@noindent +@example +zmodload -m -F zsh/files b:zf_\* +@end example + +@noindent +The commands loaded by default are: + +@noindent +@table @asis +@findex chgrp +@item @t{chgrp} [ @t{-hRs} ] @var{group} @var{filename} ... +Changes group of files specified. This is equivalent to @t{chown} with +a @var{user-spec} argument of `@t{:}@var{group}'. + +@findex chmod +@item @t{chmod} [ @t{-Rs} ] @var{mode} @var{filename} ... +Changes mode of files specified. + +@noindent +The specified @var{mode} must be in octal. + +@noindent +The @t{-R} option causes @t{chmod} to recursively descend into directories, +changing the mode of all files in the directory after +changing the mode of the directory itself. + +@noindent +The @t{-s} option is a zsh extension to @t{chmod} functionality. It enables +paranoid behaviour, intended to avoid security problems involving +a @t{chmod} being tricked into affecting files other than the ones +intended. It will refuse to follow symbolic links, so that (for example) +@value{dsbq}@t{chmod 600 /tmp/foo/passwd}@value{dsq} can't accidentally chmod @t{/etc/passwd} +if @t{/tmp/foo} happens to be a link to @t{/etc}. It will also check +where it is after leaving directories, so that a recursive chmod of +a deep directory tree can't end up recursively chmoding @t{/usr} as +a result of directories being moved up the tree. + +@findex chown +@item @t{chown} [ @t{-hRs} ] @var{user-spec} @var{filename} ... +Changes ownership and group of files specified. + +@noindent +The @var{user-spec} can be in four forms: + +@noindent +@table @asis +@item @var{user} +change owner to @var{user}; do not change group +@item @var{user}@t{::} +change owner to @var{user}; do not change group +@item @var{user}@t{:} +change owner to @var{user}; change group to @var{user}'s primary group +@item @var{user}@t{:}@var{group} +change owner to @var{user}; change group to @var{group} +@item @t{:}@var{group} +do not change owner; change group to @var{group} +@end table + +@noindent +In each case, the `@t{:}' may instead be a `@t{.}'. The rule is that +if there is a `@t{:}' then the separator is `@t{:}', otherwise +if there is a `@t{.}' then the separator is `@t{.}', otherwise +there is no separator. + +@noindent +Each of @var{user} and @var{group} may be either a username (or group name, as +appropriate) or a decimal user ID (group ID). Interpretation as a name +takes precedence, if there is an all-numeric username (or group name). + +@noindent +If the target is a symbolic link, the @t{-h} option causes @t{chown} to set +the ownership of the link instead of its target. + +@noindent +The @t{-R} option causes @t{chown} to recursively descend into directories, +changing the ownership of all files in the directory after +changing the ownership of the directory itself. + +@noindent +The @t{-s} option is a zsh extension to @t{chown} functionality. It enables +paranoid behaviour, intended to avoid security problems involving +a @t{chown} being tricked into affecting files other than the ones +intended. It will refuse to follow symbolic links, so that (for example) +@value{dsbq}@t{chown luser /tmp/foo/passwd}@value{dsq} can't accidentally chown @t{/etc/passwd} +if @t{/tmp/foo} happens to be a link to @t{/etc}. It will also check +where it is after leaving directories, so that a recursive chown of +a deep directory tree can't end up recursively chowning @t{/usr} as +a result of directories being moved up the tree. + +@findex ln +@item @t{ln} [ @t{-dfhins} ] @var{filename} @var{dest} +@itemx @t{ln} [ @t{-dfhins} ] @var{filename} ... @var{dir} +Creates hard (or, with @t{-s}, symbolic) links. In the first form, the +specified @var{dest}ination is created, as a link to the specified +@var{filename}. In the second form, each of the @var{filename}s is +taken in turn, and linked to a pathname in the specified @var{dir}ectory +that has the same last pathname component. + +@noindent +Normally, @t{ln} will not attempt to create hard links to +directories. This check can be overridden using the @t{-d} option. +Typically only the super-user can actually succeed in creating +hard links to directories. +This does not apply to symbolic links in any case. + +@noindent +By default, existing files cannot be replaced by links. +The @t{-i} option causes the user to be queried about replacing +existing files. The @t{-f} option causes existing files to be +silently deleted, without querying. @t{-f} takes precedence. + +@noindent +The @t{-h} and @t{-n} options are identical and both exist for +compatibility; either one indicates that if the target is a symlink +then it should not be dereferenced. +Typically this is used in combination with @t{-sf} so that if an +existing link points to a directory then it will be removed, +instead of followed. +If this option is used with multiple filenames and the target +is a symbolic link pointing to a directory then the result is +an error. + +@findex mkdir +@item @t{mkdir} [ @t{-p} ] [ @t{-m} @var{mode} ] @var{dir} ... +Creates directories. With the @t{-p} option, non-existing parent +directories are first created if necessary, and there will be +no complaint if the directory already exists. +The @t{-m} option can be used to specify (in octal) a set of file permissions +for the created directories, otherwise mode 777 modified by the current +@t{umask} (see umask(2)) is used. + +@findex mv +@item @t{mv} [ @t{-fi} ] @var{filename} @var{dest} +@itemx @t{mv} [ @t{-fi} ] @var{filename} ... @var{dir} +Moves files. In the first form, the specified @var{filename} is moved +to the specified @var{dest}ination. In the second form, each of the +@var{filename}s is +taken in turn, and moved to a pathname in the specified @var{dir}ectory +that has the same last pathname component. + +@noindent +By default, the user will be queried before replacing any file +that the user cannot write to, but writable files will be silently +removed. +The @t{-i} option causes the user to be queried about replacing +any existing files. The @t{-f} option causes any existing files to be +silently deleted, without querying. @t{-f} takes precedence. + +@noindent +Note that this @t{mv} will not move files across devices. +Historical versions of @t{mv}, when actual renaming is impossible, +fall back on copying and removing files; if this behaviour is desired, +use @t{cp} and @t{rm} manually. This may change in a future version. + +@findex rm +@item @t{rm} [ @t{-dfiRrs} ] @var{filename} ... +Removes files and directories specified. + +@noindent +Normally, @t{rm} will not remove directories (except with the @t{-R} or @t{-r} +options). The @t{-d} option causes @t{rm} to try removing directories +with @t{unlink} (see unlink(2)), the same method used for files. +Typically only the super-user can actually succeed in unlinking +directories in this way. +@t{-d} takes precedence over @t{-R} and @t{-r}. + +@noindent +By default, the user will be queried before removing any file +that the user cannot write to, but writable files will be silently +removed. +The @t{-i} option causes the user to be queried about removing +any files. The @t{-f} option causes files to be +silently deleted, without querying, and suppresses all error indications. +@t{-f} takes precedence. + +@noindent +The @t{-R} and @t{-r} options cause @t{rm} to recursively descend into +directories, deleting all files in the directory before removing the directory +with the @t{rmdir} system call (see rmdir(2)). + +@noindent +The @t{-s} option is a zsh extension to @t{rm} functionality. It enables +paranoid behaviour, intended to avoid common security problems involving +a root-run @t{rm} being tricked into removing files other than the ones +intended. It will refuse to follow symbolic links, so that (for example) +@value{dsbq}@t{rm /tmp/foo/passwd}@value{dsq} can't accidentally remove @t{/etc/passwd} +if @t{/tmp/foo} happens to be a link to @t{/etc}. It will also check +where it is after leaving directories, so that a recursive removal of +a deep directory tree can't end up recursively removing @t{/usr} as +a result of directories being moved up the tree. + +@findex rmdir +@item @t{rmdir} @var{dir} ... +Removes empty directories specified. + +@findex sync +@item @t{sync} +Calls the system call of the same name (see sync(2)), which +flushes dirty buffers to disk. It might return before the I/O has +actually been completed. + +@end table +@c (avoiding a yodl bug) +@node The zsh/langinfo Module, The zsh/mapfile Module, The zsh/files Module, Zsh Modules + +@section The zsh/langinfo Module +@noindent +@c Yodl file: Zsh/mod_langinfo.yo + +The @t{zsh/langinfo} module makes available one parameter: + +@noindent +@table @asis +@vindex langinfo +@item @t{langinfo} +An associative array that maps langinfo elements to +their values. + +@noindent +Your implementation may support a number of the following keys: + +@noindent +@t{CODESET}, +@t{D_T_FMT}, +@t{D_FMT}, +@t{T_FMT}, +@t{RADIXCHAR}, +@t{THOUSEP}, +@t{YESEXPR}, +@t{NOEXPR}, +@t{CRNCYSTR}, +@t{ABDAY_@{1..7@}}, +@t{DAY_@{1..7@}}, +@t{ABMON_@{1..12@}}, +@t{MON_@{1..12@}}, +@t{T_FMT_AMPM}, +@t{AM_STR}, +@t{PM_STR}, +@t{ERA}, +@t{ERA_D_FMT}, +@t{ERA_D_T_FMT}, +@t{ERA_T_FMT}, +@t{ALT_DIGITS} + +@noindent + +@end table +@c (avoiding a yodl bug) +@node The zsh/mapfile Module, The zsh/mathfunc Module, The zsh/langinfo Module, Zsh Modules + +@section The zsh/mapfile Module +@noindent +@c Yodl file: Zsh/mod_mapfile.yo + +@cindex parameter, file access via +The @t{zsh/mapfile} module provides one special associative array parameter of +the same name. + +@noindent +@table @asis +@vindex mapfile +@item @t{mapfile} +This associative array takes as keys the names of files; the resulting +value is the content of the file. The value is treated identically to any +other text coming from a parameter. The value may also be assigned to, in +which case the file in question is written (whether or not it originally +existed); or an element may be unset, which will delete the file in +question. For example, `@t{vared 'mapfile[myfile]'}' works as expected, +editing the file `@t{myfile}'. + +@noindent +When the array is accessed as a whole, the keys are the names of files in +the current directory, and the values are empty (to save a huge overhead in +memory). Thus @t{$@{(k)mapfile@}} has the same effect as the glob operator +@t{*(D)}, since files beginning with a dot are not special. Care must be +taken with expressions such as @t{rm $@{(k)mapfile@}}, which will delete +every file in the current directory without the usual `@t{rm *}' test. + +@noindent +The parameter @t{mapfile} may be made read-only; in that case, files +referenced may not be written or deleted. + +@noindent +A file may conveniently be read into an array as one line per element +with the form +`@var{array}@t{=("$@{(f@@)mapfile[}@var{filename}@t{]@}")}'. +The double quotes and the `@t{@@}' are necessary to prevent empty lines +from being removed. Note that if the file ends with a newline, +the shell will split on the final newline, generating an additional +empty field; this can be suppressed by using +`@var{array}@t{=("$@{(f@@)$@{mapfile[}@var{filename}@t{]%$'\n'@}@}")}'. + +@end table + +@noindent + +@subsection Limitations +@noindent + +@noindent +Although reading and writing of the file in question is efficiently +handled, zsh's internal memory management may be arbitrarily baroque; +however, @t{mapfile} is usually very much more efficient than +anything involving a loop. Note in particular that +the whole contents of the file will always reside physically in memory when +accessed (possibly multiple times, due to standard parameter substitution +operations). In particular, this means handling of sufficiently long files +(greater than the machine's swap space, or than the range of the pointer +type) will be incorrect. + +@noindent +No errors are printed or flagged for non-existent, unreadable, or +unwritable files, as the parameter mechanism is too low in the shell +execution hierarchy to make this convenient. + +@noindent +It is unfortunate that the mechanism for loading modules does not yet allow +the user to specify the name of the shell parameter to be given the special +behaviour. +@c (avoiding a yodl bug) +@node The zsh/mathfunc Module, The zsh/nearcolor Module, The zsh/mapfile Module, Zsh Modules + +@section The zsh/mathfunc Module +@noindent +@c Yodl file: Zsh/mod_mathfunc.yo + +@cindex functions, mathematical +@cindex mathematical functions +The @t{zsh/mathfunc} module provides standard +mathematical functions for use when +evaluating mathematical formulae. The syntax agrees with normal C and +FORTRAN conventions, for example, + +@noindent +@example +(( f = sin(0.3) )) +@end example + +@noindent +assigns the sine of 0.3 to the parameter f. + +@noindent +Most functions take floating point arguments and return a floating point +value. However, any necessary conversions from or to integer type will be +performed automatically by the shell. Apart from @t{atan} with a second +argument and the @t{abs}, @t{int} and @t{float} functions, all functions +behave as noted in the manual page for the corresponding C function, +except that any arguments out of range for the function in question will be +detected by the shell and an error reported. + +@noindent +The following functions take a single floating point argument: @t{acos}, +@t{acosh}, @t{asin}, @t{asinh}, @t{atan}, @t{atanh}, @t{cbrt}, @t{ceil}, +@t{cos}, @t{cosh}, @t{erf}, @t{erfc}, @t{exp}, @t{expm1}, @t{fabs}, +@t{floor}, @t{gamma}, @t{j0}, @t{j1}, @t{lgamma}, @t{log}, @t{log10}, +@t{log1p}, @t{log2}, @t{logb}, @t{sin}, @t{sinh}, @t{sqrt}, @t{tan}, +@t{tanh}, @t{y0}, @t{y1}. The @t{atan} function can optionally take a +second argument, in which case it behaves like the C function @t{atan2}. +The @t{ilogb} function takes a single floating point argument, but +returns an integer. + +@noindent +The function @t{signgam} takes no arguments, and returns an integer, which +is the C variable of the same name, as described in gamma(3). Note +that it is therefore only useful immediately after a call to @t{gamma} or +@t{lgamma}. Note also that `@t{signgam()}' and `@t{signgam}' are +distinct expressions. + +@noindent +The functions @t{min}, @t{max}, and @t{sum} are defined not in this module +but in the @t{zmathfunc} autoloadable function, described in +@ref{Mathematical Functions}. + +@noindent +The following functions take two floating point arguments: @t{copysign}, +@t{fmod}, @t{hypot}, @t{nextafter}. + +@noindent +The following take an integer first argument and a floating point second +argument: @t{jn}, @t{yn}. + +@noindent +The following take a floating point first argument and an integer second +argument: @t{ldexp}, @t{scalb}. + +@noindent +The function @t{abs} does not convert the type of its single argument; it +returns the absolute value of either a floating point number or an +integer. The functions @t{float} and @t{int} convert their arguments into +a floating point or integer value (by truncation) respectively. + +@noindent +Note that the C @t{pow} function is available in ordinary math evaluation +as the `@t{**}' operator and is not provided here. + +@noindent +The function @t{rand48} is available if your system's mathematical library +has the function @t{erand48(3)}. It returns a pseudo-random floating point +number between 0 and 1. It takes a single string optional argument. + +@noindent +If the argument is not present, the random number seed is initialised by +three calls to the @t{rand(3)} function --- this produces the +same random +numbers as the next three values of @t{$RANDOM}. + +@noindent +If the argument is present, it gives the name of a scalar parameter where +the current random number seed will be stored. On the first call, the +value must contain at least twelve hexadecimal digits (the remainder of the +string is ignored), or the seed will be initialised in the same manner as +for a call to @t{rand48} with no argument. Subsequent calls to +@t{rand48}(@var{param}) will then maintain the seed in the +parameter @var{param} as a string of twelve hexadecimal digits, with no base +signifier. The random number sequences for different parameters are +completely independent, and are also independent from that used by calls to +@t{rand48} with no argument. + +@noindent +For example, consider + +@noindent +@example +print $(( rand48(seed) )) +print $(( rand48() )) +print $(( rand48(seed) )) +@end example + +@noindent +Assuming @t{$seed} does not exist, it will be initialised by the first +call. In the second call, the default seed is initialised; note, however, +that because of the properties of @t{rand()} there is a +correlation between +the seeds used for the two initialisations, so for more secure uses, you +should generate your own 12-byte seed. The third call returns to the same +sequence of random numbers used in the first call, unaffected by the +intervening @t{rand48()}. +@c (avoiding a yodl bug) +@node The zsh/nearcolor Module, The zsh/newuser Module, The zsh/mathfunc Module, Zsh Modules + +@section The zsh/nearcolor Module +@noindent +@c Yodl file: Zsh/mod_nearcolor.yo + +The @t{zsh/nearcolor} module replaces colours specified as hex triplets +with the nearest colour in the 88 or 256 colour palettes that are widely +used by terminal emulators. By default, 24-bit true colour escape codes +are generated when colours are specified using hex triplets. These are +not supported by all terminals. The purpose of this module is to make +it easier to define colour preferences in a form that can work across a +range of terminal emulators. + +@noindent +Aside from the default colour, the ANSI standard for terminal escape +codes provides for eight colours. The bright attribute brings this to +sixteen. These basic colours are commonly used in terminal applications +due to being widely supported. Expanded 88 and 256 colour palettes are +also common and, while the first sixteen colours vary somewhat between +terminals and configurations, these add a generally consistent and +predictable set of colours. + +@noindent +In order to use the @t{zsh/nearcolor} module, it only needs to be +loaded. Thereafter, whenever a colour is specified using a hex triplet, +it will be compared against each of the available colours and the +closest will be selected. The first sixteen colours are never matched in +this process due to being unpredictable. + +@noindent +It isn't possible to reliably detect support for true colour in the +terminal emulator. It is therefore recommended to be selective in +loading the @t{zsh/nearcolor} module. For example, the following +checks the @t{COLORTERM} environment variable: + +@noindent +@example +[[ $COLORTERM = *(24bit|truecolor)* ]] || zmodload zsh/nearcolor +@end example + +@noindent +Note that some terminals accept the true color escape codes but map +them internally to a more limited palette in a similar manner to the +@t{zsh/nearcolor} module. +@c (avoiding a yodl bug) +@node The zsh/newuser Module, The zsh/parameter Module, The zsh/nearcolor Module, Zsh Modules + +@section The zsh/newuser Module +@noindent +@c Yodl file: Zsh/mod_newuser.yo + +The @t{zsh/newuser} module is loaded at boot if it is +available, the @t{RCS} option is set, and the @t{PRIVILEGED} option is not +set (all three are true by default). This takes +place immediately after commands in the global @t{zshenv} file (typically +@t{/etc/zshenv}), if any, have been executed. If the module is not +available it is silently ignored by the shell; the module may safely be +removed from @t{$MODULE_PATH} by the administrator if it is not required. + +@noindent +On loading, the module tests if any of the start-up files @t{.zshenv}, +@t{.zprofile}, @t{.zshrc} or @t{.zlogin} exist in the directory given by +the environment variable @t{ZDOTDIR}, or the user's home directory if that +is not set. The test is not performed and the module halts processing if +the shell was in an emulation mode (i.e. had been invoked as some other +shell than zsh). + +@noindent +If none of the start-up files were found, the module then looks for the +file @t{newuser} first in a sitewide directory, usually the parent +directory of the @t{site-functions} directory, and if that is not found the +module searches in a version-specific directory, usually the parent of the +@t{functions} directory containing version-specific functions. (These +directories can be configured when zsh is built using the +@t{--enable-site-scriptdir=}@var{dir} and @t{--enable-scriptdir=}@var{dir} +flags to @t{configure}, respectively; the defaults are +@var{prefix}@t{/share/zsh} and @var{prefix}@t{/share/zsh/$ZSH_VERSION} where +the default @var{prefix} is @t{/usr/local}.) + +@noindent +If the file @t{newuser} is found, it is then sourced in the same manner as +a start-up file. The file is expected to contain code to install start-up +files for the user, however any valid shell code will be executed. + +@noindent +The @t{zsh/newuser} module is then unconditionally unloaded. + +@noindent +Note that it is possible to achieve exactly the same effect as the +@t{zsh/newuser} module by adding code to @t{/etc/zshenv}. The module +exists simply to allow the shell to make arrangements for new users without +the need for intervention by package maintainers and system administrators. + +@noindent +The script supplied with the module invokes the shell function +@t{zsh-newuser-install}. This may be invoked directly by the user +even if the @t{zsh/newuser} module is disabled. Note, however, that +if the module is not installed the function will not be installed either. +The function is documented in +@ref{User Configuration Functions}. +@c (avoiding a yodl bug) +@node The zsh/parameter Module, The zsh/pcre Module, The zsh/newuser Module, Zsh Modules + +@section The zsh/parameter Module +@noindent +@c Yodl file: Zsh/mod_parameter.yo + +@cindex parameters, special +The @t{zsh/parameter} module gives access to some of the internal hash +tables used by the shell by defining some special parameters. + +@noindent +@table @asis +@vindex options +@item @t{options} +The keys for this associative array are the names of the options that +can be set and unset using the @t{setopt} and @t{unsetopt} +builtins. The value of each key is either the string @t{on} if the +option is currently set, or the string @t{off} if the option is unset. +Setting a key to one of these strings is like setting or unsetting +the option, respectively. Unsetting a key in this array is like +setting it to the value @t{off}. + +@vindex commands +@item @t{commands} +This array gives access to the command hash table. The keys are the +names of external commands, the values are the pathnames of the files +that would be executed when the command would be invoked. Setting a +key in this array defines a new entry in this table in the same way as +with the @t{hash} builtin. Unsetting a key as in `@t{unset +"commands[foo]"}' removes the entry for the given key from the command +hash table. + +@vindex functions +@item @t{functions} +This associative array maps names of enabled functions to their +definitions. Setting a key in it is like defining a function with the +name given by the key and the body given by the value. Unsetting a key +removes the definition for the function named by the key. + +@vindex dis_functions +@item @t{dis_functions} +Like @t{functions} but for disabled functions. + +@vindex functions_source +@item @t{functions_source} +This readonly associative array maps names of enabled functions to the +name of the file containing the source of the function. + +@noindent +For an autoloaded function that has already been loaded, or marked for +autoload with an absolute path, or that has had its path resolved with +`@t{functions -r}', this is the file found for autoloading, resolved +to an absolute path. + +@noindent +For a function defined within the body of a script or sourced file, +this is the name of that file. In this case, this is the exact path +originally used to that file, which may be a relative path. + +@noindent +For any other function, including any defined at an interactive prompt or +an autoload function whose path has not yet been resolved, this is +the empty string. However, the hash element is reported as defined +just so long as the function is present: the keys to this hash are +the same as those to @t{$functions}. + +@vindex dis_functions_source +@item @t{dis_functions_source} +Like @t{functions_source} but for disabled functions. + +@vindex builtins +@item @t{builtins} +This associative array gives information about the builtin commands +currently enabled. The keys are the names of the builtin commands and +the values are either `@t{undefined}' for builtin commands that will +automatically be loaded from a module if invoked or `@t{defined}' for +builtin commands that are already loaded. + +@vindex dis_builtins +@item @t{dis_builtins} +Like @t{builtins} but for disabled builtin commands. + +@vindex reswords +@item @t{reswords} +This array contains the enabled reserved words. + +@vindex dis_reswords +@item @t{dis_reswords} +Like @t{reswords} but for disabled reserved words. + +@vindex patchars +@item @t{patchars} +This array contains the enabled pattern characters. + +@vindex dis_patchars +@item @t{dis_patchars} +Like @t{patchars} but for disabled pattern characters. + +@vindex aliases +@item @t{aliases} +This maps the names of the regular aliases currently enabled to their +expansions. + +@vindex dis_aliases +@item @t{dis_aliases} +Like @t{aliases} but for disabled regular aliases. + +@vindex galiases +@item @t{galiases} +Like @t{aliases}, but for global aliases. + +@vindex dis_galiases +@item @t{dis_galiases} +Like @t{galiases} but for disabled global aliases. + +@vindex saliases +@item @t{saliases} +Like @t{raliases}, but for suffix aliases. + +@vindex dis_saliases +@item @t{dis_saliases} +Like @t{saliases} but for disabled suffix aliases. + +@vindex parameters +@item @t{parameters} +The keys in this associative array are the names of the parameters +currently defined. The values are strings describing the type of the +parameter, in the same format used by the @t{t} parameter flag, see +@ref{Parameter Expansion} +. +Setting or unsetting keys in this array is not possible. + +@vindex modules +@item @t{modules} +An associative array giving information about modules. The keys are the names +of the modules loaded, registered to be autoloaded, or aliased. The +value says which state the named module is in and is one of the +strings `@t{loaded}', `@t{autoloaded}', or `@t{alias:}@var{name}', +where @var{name} is the name the module is aliased to. + +@noindent +Setting or unsetting keys in this array is not possible. + +@vindex dirstack +@item @t{dirstack} +A normal array holding the elements of the directory stack. Note that +the output of the @t{dirs} builtin command includes one more +directory, the current working directory. + +@vindex history +@item @t{history} +This associative array maps history event numbers to the full history lines. +Although it is presented as an associative array, the array of all values +(@t{$@{history[@@]@}}) is guaranteed to be returned in order from most recent +to oldest history event, that is, by decreasing history event number. + +@vindex historywords +@item @t{historywords} +A special array containing the words stored in the history. These also +appear in most to least recent order. + +@vindex jobdirs +@item @t{jobdirs} +This associative array maps job numbers to the directories from which the +job was started (which may not be the current directory of the job). + +@noindent +The keys of the associative arrays are usually valid job numbers, +and these are the values output with, for example, @t{$@{(k)jobdirs@}}. +Non-numeric job references may be used when looking up a value; +for example, @t{$@{jobdirs[%+]@}} refers to the current job. + +@noindent +See the @t{jobs} builtin for how job information is provided in a subshell. + +@vindex jobtexts +@item @t{jobtexts} +This associative array maps job numbers to the texts of the command lines +that were used to start the jobs. + +@noindent +Handling of the keys of the associative array is as described for +@t{jobdirs} above. + +@noindent +See the @t{jobs} builtin for how job information is provided in a subshell. + +@vindex jobstates +@item @t{jobstates} +This associative array gives information about the states of the jobs +currently known. The keys are the job numbers and the values are +strings of the form +`@var{job-state}@t{:}@var{mark}@t{:}@var{pid}@t{=}@var{state}...'. The +@var{job-state} gives the state the whole job is currently in, one of +`@t{running}', `@t{suspended}', or `@t{done}'. The @var{mark} is +`@t{+}' for the current job, `@t{-}' for the previous job and empty +otherwise. This is followed by one `@t{:}@var{pid}@t{=}@var{state}' for every +process in the job. The @var{pid}s are, of course, the process IDs and +the @var{state} describes the state of that process. + +@noindent +Handling of the keys of the associative array is as described for +@t{jobdirs} above. + +@noindent +See the @t{jobs} builtin for how job information is provided in a subshell. + +@vindex nameddirs +@item @t{nameddirs} +This associative array maps the names of named directories to the pathnames +they stand for. + +@vindex userdirs +@item @t{userdirs} +This associative array maps user names to the pathnames of their home +directories. + +@vindex usergroups +@item @t{usergroups} +This associative array maps names of system groups of which the current +user is a member to the corresponding group identifiers. The contents +are the same as the groups output by the @t{id} command. + +@vindex funcfiletrace +@item @t{funcfiletrace} +This array contains the absolute line numbers and corresponding file +names for the point where the current function, sourced file, or (if +@t{EVAL_LINENO} is set) @t{eval} command was +called. The array is of the same length as @t{funcsourcetrace} and +@t{functrace}, but differs from @t{funcsourcetrace} in that the line and +file are the point of call, not the point of definition, and differs +from @t{functrace} in that all values are absolute line numbers in +files, rather than relative to the start of a function, if any. + +@vindex funcsourcetrace +@item @t{funcsourcetrace} +This array contains the file names and line numbers of the +points where the functions, sourced files, and (if @t{EVAL_LINENO} is set) +@t{eval} commands currently being executed were +defined. The line number is the line where the `@t{function} @var{name}' +or `@var{name} @t{()}' started. In the case of an autoloaded +function the line number is reported as zero. +The format of each element is @var{filename}@t{:}@var{lineno}. + +@noindent +For functions autoloaded from a file in native zsh format, where only the +body of the function occurs in the file, or for files that have been +executed by the @t{source} or `@t{.}' builtins, the trace information is +shown as @var{filename}@t{:}@var{0}, since the entire file is the +definition. The source file name is resolved to an absolute path when +the function is loaded or the path to it otherwise resolved. + +@noindent +Most users will be interested in the information in the +@t{funcfiletrace} array instead. + +@vindex funcstack +@item @t{funcstack} +This array contains the names of the functions, sourced files, +and (if @t{EVAL_LINENO} is set) @t{eval} commands. currently being +executed. The first element is the name of the function using the +parameter. + +@noindent +The standard shell array @t{zsh_eval_context} can be used to +determine the type of shell construct being executed at each depth: +note, however, that is in the opposite order, with the most recent +item last, and it is more detailed, for example including an +entry for @t{toplevel}, the main shell code being executed +either interactively or from a script, which is not present +in @t{$funcstack}. + +@vindex functrace +@item @t{functrace} +This array contains the names and line numbers of the callers +corresponding to the functions currently being executed. +The format of each element is @var{name}@t{:}@var{lineno}. +Callers are also shown for sourced files; the caller is the point +where the @t{source} or `@t{.}' command was executed. + +@end table +@c (avoiding a yodl bug) +@node The zsh/pcre Module, The zsh/param/private Module, The zsh/parameter Module, Zsh Modules + +@section The zsh/pcre Module +@noindent +@c Yodl file: Zsh/mod_pcre.yo + +@cindex regular expressions, perl-compatible +The @t{zsh/pcre} module makes some commands available as builtins: + +@noindent +@table @asis +@findex pcre_compile +@item @t{pcre_compile} [ @t{-aimxs} ] @var{PCRE} +Compiles a perl-compatible regular expression. + +@noindent +Option @t{-a} will force the pattern to be anchored. +Option @t{-i} will compile a case-insensitive pattern. +Option @t{-m} will compile a multi-line pattern; that is, +@t{^} and @t{$} will match newlines within the pattern. +Option @t{-x} will compile an extended pattern, wherein +whitespace and @t{#} comments are ignored. +Option @t{-s} makes the dot metacharacter match all characters, +including those that indicate newline. + +@findex pcre_study +@item @t{pcre_study} +Studies the previously-compiled PCRE which may result in faster +matching. + +@findex pcre_match +@item @t{pcre_match} [ @t{-v} @var{var} ] [ @t{-a} @var{arr} ] [ @t{-n} @var{offset} ] [ @t{-b} ] @var{string} +Returns successfully if @t{string} matches the previously-compiled +PCRE. + +@noindent +Upon successful match, +if the expression captures substrings within parentheses, +@t{pcre_match} will set the array @t{match} to those +substrings, unless the @t{-a} option is given, in which +case it will set the array @var{arr}. Similarly, the variable +@t{MATCH} will be set to the entire matched portion of the +string, unless the @t{-v} option is given, in which case the variable +@var{var} will be set. +No variables are altered if there is no successful match. +A @t{-n} option starts searching for a match from the +byte @var{offset} position in @var{string}. If the @t{-b} option is given, +the variable @t{ZPCRE_OP} will be set to an offset pair string, +representing the byte offset positions of the entire matched portion +within the @var{string}. For example, a @t{ZPCRE_OP} set to "32 45" indicates +that the matched portion began on byte offset 32 and ended on byte offset 44. +Here, byte offset position 45 is the position directly after the matched +portion. Keep in mind that the byte position isn't necessarily the same +as the character position when UTF-8 characters are involved. +Consequently, the byte offset positions are only to be relied on in the +context of using them for subsequent searches on @var{string}, using an offset +position as an argument to the @t{-n} option. This is mostly +used to implement the "find all non-overlapping matches" functionality. + +@noindent +A simple example of "find all non-overlapping matches": + +@noindent +@example +string="The following zip codes: 78884 90210 99513" +pcre_compile -m "\d@{5@}" +accum=() +pcre_match -b -- $string +while [[ $? -eq 0 ]] do + b=($=ZPCRE_OP) + accum+=$MATCH + pcre_match -b -n $b[2] -- $string +done +print -l $accum +@end example + +@end table + +@noindent +The @t{zsh/pcre} module makes available the following test condition: + +@noindent +@table @asis +@findex pcre-match +@item @var{expr} @t{-pcre-match} @var{pcre} +Matches a string against a perl-compatible regular expression. + +@noindent +For example, + +@noindent +@example +[[ "$text" -pcre-match ^d+$ ]] && +print text variable contains only "d's". +@end example + +@noindent +@pindex REMATCH_PCRE +@pindex NO_CASE_MATCH +If the @t{REMATCH_PCRE} option is set, the @t{=~} operator is equivalent to +@t{-pcre-match}, and the @t{NO_CASE_MATCH} option may be used. Note that +@t{NO_CASE_MATCH} never applies to the @t{pcre_match} builtin, instead use +the @t{-i} switch of @t{pcre_compile}. + +@end table +@c (avoiding a yodl bug) +@node The zsh/param/private Module, The zsh/regex Module, The zsh/pcre Module, Zsh Modules + +@section The zsh/param/private Module +@noindent +@c Yodl file: Zsh/mod_private.yo + +The @t{zsh/param/private} module is used to create parameters whose scope +is limited to the current function body, and @emph{not} to other functions +called by the current function. + +@noindent +This module provides a single autoloaded builtin: + +@table @asis +@findex private +@cindex private parameter, creating +@item @t{private} [ @{@t{+}|@t{-}@}@t{AHUahlmrtux} ] [ @{@t{+}|@t{-}@}@t{EFLRZi} [ @var{n} ] ] [ @var{name}[@t{=}@var{value}] ... ] +The @t{private} builtin accepts all the same options and arguments as @t{local} +(@ref{Shell Builtin Commands}) except +for the `@t{-}@t{T}' option. Tied parameters may not be made private. + +@noindent +The `@t{-}@t{p}' option is presently a no-op because the state of +private parameters cannot reliably be reloaded. This also applies +to printing private parameters with `@t{typeset -p}'. + +@noindent +If used at the top level (outside a function scope), @t{private} creates a +normal parameter in the same manner as @t{declare} or @t{typeset}. A +warning about this is printed if @t{WARN_CREATE_GLOBAL} is set +(@ref{Options}). Used inside a +function scope, @t{private} creates a local parameter similar to one +declared with @t{local}, except having special properties noted below. + +@noindent +Special parameters which expose or manipulate internal shell state, such +as @t{ARGC}, @t{argv}, @t{COLUMNS}, @t{LINES}, @t{UID}, @t{EUID}, @t{IFS}, +@t{PROMPT}, @t{RANDOM}, @t{SECONDS}, etc., cannot be made private unless +the `@t{-}@t{h}' option is used to hide the special meaning of the +parameter. This may change in the future. + +@end table + +@noindent +As with other @t{typeset} equivalents, @t{private} is both a builtin and a +reserved word, so arrays may be assigned with parenthesized word list +@var{name}@t{=(}@var{value}...@t{)} syntax. However, the reserved +word `@t{private}' is not available until @t{zsh/param/private} is loaded, +so care must be taken with order of execution and parsing for function +definitions which use @t{private}. To compensate for this, the module +also adds the option `@t{-P}' to the `@t{local}' builtin to declare private +parameters. + +@noindent +For example, this construction fails if @t{zsh/param/private} has not yet +been loaded when `@t{bad_declaration}' is defined: +@example +bad_declaration() @{ + zmodload zsh/param/private + private array=( one two three ) +@} +@end example + +@noindent +This construction works because @t{local} is already a keyword, and the +module is loaded before the statement is executed: +@example +good_declaration() @{ + zmodload zsh/param/private + local -P array=( one two three ) +@} +@end example + +@noindent +The following is usable in scripts but may have trouble with @t{autoload}: +@example +zmodload zsh/param/private +iffy_declaration() @{ + private array=( one two three ) +@} +@end example + +@noindent +The @t{private} builtin may always be used with scalar assignments and +for declarations without assignments. + +@noindent +Parameters declared with @t{private} have the following properties: + +@itemize @bullet + +@item +Within the function body where it is declared, the parameter +behaves as a local, except as noted above for tied or special parameters. +@item +The type of a parameter declared private cannot be changed in the +scope where it was declared, even if the parameter is unset. Thus an +array cannot be assigned to a private scalar, etc. +@item +Within any other function called by the declaring function, the +private parameter does @emph{NOT} hide other parameters of the same name, so +for example a global parameter of the same name is visible and may be +assigned or unset. This includes calls to anonymous functions, although +that may also change in the future. However, the private name may not be +created outside the local scope when it was not previously declared. +@item +An exported private remains in the environment of inner scopes but +appears unset for the current shell in those scopes. Generally, exporting +private parameters should be avoided. +@end itemize + +@noindent +Note that this differs from the static scope defined by compiled languages +derived from C, in that the a new call to the same function creates a new +scope, i.e., the parameter is still associated with the call stack rather +than with the function definition. It differs from ksh `@t{typeset -S}' +because the syntax used to define the function has no bearing on whether +the parameter scope is respected. +@c (avoiding a yodl bug) +@node The zsh/regex Module, The zsh/sched Module, The zsh/param/private Module, Zsh Modules + +@section The zsh/regex Module +@noindent +@c Yodl file: Zsh/mod_regex.yo + +@cindex regular expressions +@cindex regex +The @t{zsh/regex} module makes available the following test condition: + +@noindent +@table @asis +@findex regex-match +@item @var{expr} @t{-regex-match} @var{regex} +Matches a string against a POSIX extended regular expression. +On successful match, +matched portion of the string will normally be placed in the @t{MATCH} +variable. If there are any capturing parentheses within the regex, then +the @t{match} array variable will contain those. +If the match is not successful, then the variables will not be altered. + +@noindent +For example, + +@noindent +@example +[[ alphabetical -regex-match ^a([^a]+)a([^a]+)a ]] && +print -l $MATCH X $match +@end example + +@noindent +If the option @t{REMATCH_PCRE} is not set, then the @t{=~} operator will +automatically load this module as needed and will invoke the +@t{-regex-match} operator. + +@noindent +If @t{BASH_REMATCH} is set, then the array @t{BASH_REMATCH} will be set +instead of @t{MATCH} and @t{match}. + +@noindent +Note that the @t{zsh/regex} module logic relies on the host system. The +same @var{expr} and @var{regex} pair could produce different results on different +platforms if a @var{regex} with non-standard syntax is given. + +@noindent +For example, no syntax for matching a word boundary is defined in the POSIX +extended regular expression standard. GNU @t{libc} and BSD @t{libc} both provide +such syntaxes as extensions (@t{\b} and @t{[[:<:]]}/@t{[[:>:]]} respectively), +but neither of these syntaxes is supported by both of these implementations. + +@noindent +Refer to the regcomp(3) and re_format(7) manual pages on your +system for locally-supported syntax. + +@end table +@c (avoiding a yodl bug) +@node The zsh/sched Module, The zsh/net/socket Module, The zsh/regex Module, Zsh Modules + +@section The zsh/sched Module +@noindent +@c Yodl file: Zsh/mod_sched.yo + +The @t{zsh/sched} module makes available one builtin command and one +parameter. + +@noindent +@table @asis +@findex sched +@cindex timed execution +@cindex execution, timed +@item @t{sched} [@t{-o}] [@t{+}]@var{hh}@t{:}@var{mm}[@t{:}@var{ss}] @var{command} ... +@itemx @t{sched} [@t{-o}] [@t{+}]@var{seconds} @var{command} ... +@itemx @t{sched} [ @t{-}@var{item} ] +Make an entry in the scheduled list of commands to execute. +The time may be specified in either absolute or relative time, +and either as hours, minutes and (optionally) seconds separated by a +colon, or seconds alone. +An absolute number of seconds indicates the time since the epoch +(1970/01/01 00:00); this is useful in combination with the features in +the @t{zsh/datetime} module, see +@ref{The zsh/datetime Module}. + +@noindent +With no arguments, prints the list of scheduled commands. If the +scheduled command has the @t{-o} flag set, this is shown at the +start of the command. + +@noindent +With the argument `@t{-}@var{item}', removes the given item +from the list. The numbering of the list is continuous and entries are +in time order, so the numbering can change when entries are added or +deleted. + +@noindent +Commands are executed either immediately before a prompt, or while +the shell's line editor is waiting for input. In the latter case +it is useful to be able to produce output that does not interfere +with the line being edited. Providing the option @t{-o} causes +the shell to clear the command line before the event and redraw it +afterwards. This should be used with any scheduled event that produces +visible output to the terminal; it is not needed, for example, with +output that updates a terminal emulator's title bar. + +@noindent +To effect changes to the editor buffer when an event executes, use the +`@t{zle}' command with no arguments to test whether the editor is active, +and if it is, then use `@t{zle }@var{widget}' to access the editor via +the named @var{widget}. + +@noindent +The @t{sched} builtin is not made available by default when the shell +starts in a mode emulating another shell. It can be made available +with the command `@t{zmodload -F zsh/sched b:sched}'. + +@end table + +@noindent +@table @asis +@vindex zsh_scheduled_events +@item @t{zsh_scheduled_events} +A readonly array corresponding to the events scheduled by the +@t{sched} builtin. The indices of the array correspond to the numbers +shown when @t{sched} is run with no arguments (provided that the +@t{KSH_ARRAYS} option is not set). The value of the array +consists of the scheduled time in seconds since the epoch +(see @ref{The zsh/datetime Module} for facilities for +using this number), followed by a colon, followed by any options +(which may be empty but will be preceded by a `@t{-}' otherwise), +followed by a colon, followed by the command to be executed. + +@noindent +The @t{sched} builtin should be used for manipulating the events. Note +that this will have an immediate effect on the contents of the array, +so that indices may become invalid. + +@end table +@c (avoiding a yodl bug) +@node The zsh/net/socket Module, The zsh/stat Module, The zsh/sched Module, Zsh Modules + +@section The zsh/net/socket Module +@noindent +@c Yodl file: Zsh/mod_socket.yo + +The @t{zsh/net/socket} module makes available one builtin command: + +@noindent +@table @asis +@findex zsocket +@cindex sockets +@cindex sockets, Unix domain +@item @t{zsocket} [ @t{-altv} ] [ @t{-d} @var{fd} ] [ @var{args} ] +@t{zsocket} is implemented as a builtin to allow full use of shell +command line editing, file I/O, and job control mechanisms. + +@end table + +@noindent + +@subsection Outbound Connections +@noindent +@cindex sockets, outbound Unix domain + +@noindent +@table @asis +@item @t{zsocket} [ @t{-v} ] [ @t{-d} @var{fd} ] @var{filename} +Open a new Unix domain connection to @var{filename}. +The shell parameter @t{REPLY} will be set to the file descriptor +associated with that connection. Currently, only stream connections +are supported. + +@noindent +If @t{-d} is specified, its argument +will be taken as the target file descriptor for the +connection. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@noindent +File descriptors can be closed with normal shell syntax when no longer +needed, for example: + +@noindent +@example +exec @{REPLY@}>&- +@end example + +@end table + +@noindent + +@subsection Inbound Connections +@noindent +@cindex sockets, inbound Unix domain + +@noindent +@table @asis +@item @t{zsocket} @t{-l} [ @t{-v} ] [ @t{-d} @var{fd} ] @var{filename} +@t{zsocket -l} will open a socket listening on @var{filename}. +The shell parameter @t{REPLY} will be set to the file descriptor +associated with that listener. The file descriptor remains open in subshells +and forked external executables. + +@noindent +If @t{-d} is specified, its argument +will be taken as the target file descriptor for +the connection. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@item @t{zsocket} @t{-a} [ @t{-tv} ] [ @t{-d} @var{targetfd} ] @var{listenfd} +@t{zsocket -a} will accept an incoming connection +to the socket associated with @var{listenfd}. +The shell parameter @t{REPLY} will +be set to the file descriptor associated with +the inbound connection. The file descriptor remains open in subshells +and forked external executables. + +@noindent +If @t{-d} is specified, its argument +will be taken as the target file descriptor for the +connection. + +@noindent +If @t{-t} is specified, @t{zsocket} will return +if no incoming connection is pending. Otherwise +it will wait for one. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@end table +@c (avoiding a yodl bug) +@node The zsh/stat Module, The zsh/system Module, The zsh/net/socket Module, Zsh Modules + +@section The zsh/stat Module +@noindent +@c Yodl file: Zsh/mod_stat.yo + +The @t{zsh/stat} module makes available one builtin command under +two possible names: + +@noindent +@table @asis +@findex zstat +@findex stat +@cindex files, listing +@cindex files, examining + +@item @t{zstat }[ @t{-gnNolLtTrs} ] [ @t{-f} @var{fd} ] [ @t{-H} @var{hash} ] [ @t{-A} @var{array} ] [ @t{-F} @var{fmt} ] +@itemx @t{@ @ @ @ @ @ }[ @t{+}@var{element} ] [ @var{file} ... ] +@itemx @t{stat} @var{...} +The command acts as a front end to the @t{stat} system call (see +stat(2)). The same command is provided with two names; as +the name @t{stat} is often used by an external command it is recommended +that only the @t{zstat} form of the command is used. This can be +arranged by loading the module with the command `@t{zmodload -F zsh/stat +b:zstat}'. + +@noindent +If the @t{stat} call fails, the appropriate system error message +printed and status 1 is returned. +The fields of @t{struct stat} give information about +the files provided as arguments to the command. In addition to those +available from the @t{stat} call, an extra element `@t{link}' is provided. +These elements are: + +@noindent +@table @asis +@item @t{device} +The number of the device on which the file resides. + +@item @t{inode} +The unique number of the file on this device (`@emph{inode}' number). + +@item @t{mode} +The mode of the file; that is, the file's type and access permissions. +With the @t{-s} option, this will +be returned as a string corresponding to the first column in the +display of the @t{ls -l} command. + +@item @t{nlink} +The number of hard links to the file. + +@item @t{uid} +The user ID of the owner of the file. With the @t{-s} +option, this is displayed as a user name. + +@item @t{gid} +The group ID of the file. With the @t{-s} option, this +is displayed as a group name. + +@item @t{rdev} +The raw device number. This is only useful for special devices. + +@item @t{size} +The size of the file in bytes. + +@item @t{atime} +@itemx @t{mtime} +@itemx @t{ctime} +The last access, modification and inode change times +of the file, respectively, as the number of seconds since +midnight GMT on 1st January, 1970. With the @t{-s} option, +these are printed as strings for the local time zone; the format +can be altered with the @t{-F} option, and with the @t{-g} +option the times are in GMT. + +@item @t{blksize} +The number of bytes in one allocation block on the +device on which the file resides. + +@item @t{block} +The number of disk blocks used by the file. + +@item @t{link} +If the file is a link and the @t{-L} option is in +effect, this contains the name of the file linked to, otherwise +it is empty. Note that if this element is selected (@value{dsbq}@t{zstat +link}@value{dsq}) +then the @t{-L} option is automatically used. + +@end table + +@noindent +A particular element may be selected by including its name +preceded by a `@t{+}' in the option list; only one element is allowed. +The element may be shortened to any unique set of leading +characters. Otherwise, all elements will be shown for all files. + +@noindent +Options: + +@noindent +@table @asis +@item @t{-A} @var{array} +Instead of displaying the results on standard +output, assign them to an @var{array}, one @t{struct stat} element per array +element for each file in order. In this case neither the name +of the element nor the name of the files appears in @var{array} unless the +@t{-t} or @t{-n} options were given, respectively. If @t{-t} is given, +the element name appears as a prefix to the +appropriate array element; if @t{-n} is given, the file name +appears as a separate array element preceding all the others. +Other formatting options are respected. + +@item @t{-H} @var{hash} +Similar to @t{-A}, but instead assign the values to @var{hash}. The keys +are the elements listed above. If the @t{-n} option is provided then the +name of the file is included in the hash with key @t{name}. + +@item @t{-f} @var{fd} +Use the file on file descriptor @var{fd} instead of +named files; no list of file names is allowed in this case. + +@item @t{-F} @var{fmt} +Supplies a @t{strftime} (see strftime(3)) string for the +formatting of the time elements. The format string supports all of the +zsh extensions described in +@ref{Prompt Expansion}. +In particular, @t{-F %s.%N} can be used to show timestamps with nanosecond +precision if supported by the system. +The @t{-s} option is implied. + +@item @t{-g} +Show the time elements in the GMT time zone. The +@t{-s} option is implied. + +@item @t{-l} +List the names of the type elements (to standard +output or an array as appropriate) and return immediately; +arguments, and options other than @t{-A}, are ignored. + +@item @t{-L} +Perform an @t{lstat} (see lstat(2)) rather than a @t{stat} +system call. In this case, if the file is a link, information +about the link itself rather than the target file is returned. +This option is required to make the @t{link} element useful. +It's important to note that this is the exact opposite from ls(1), +etc. + +@item @t{-n} +Always show the names of files. Usually these are +only shown when output is to standard output and there is more +than one file in the list. + +@item @t{-N} +Never show the names of files. + +@item @t{-o} +If a raw file mode is printed, show it in octal, which is more useful for +human consumption than the default of decimal. A leading zero will be +printed in this case. Note that this does not affect whether a raw or +formatted file mode is shown, which is controlled by the @t{-r} and @t{-s} +options, nor whether a mode is shown at all. + +@item @t{-r} +Print raw data (the default format) alongside string +data (the @t{-s} format); the string data appears in parentheses +after the raw data. + +@item @t{-s} +Print @t{mode}, @t{uid}, @t{gid} and the three time +elements as strings instead of numbers. In each case the format +is like that of @t{ls -l}. + +@item @t{-t} +Always show the type names for the elements of +@t{struct stat}. Usually these are only shown when output is to +standard output and no individual element has been selected. + +@item @t{-T} +Never show the type names of the @t{struct stat} elements. + +@end table + +@end table +@c (avoiding a yodl bug) +@node The zsh/system Module, The zsh/net/tcp Module, The zsh/stat Module, Zsh Modules + +@section The zsh/system Module +@noindent +@c Yodl file: Zsh/mod_system.yo + +The @t{zsh/system} module makes available various builtin commands and +parameters. + +@noindent + +@subsection Builtins +@noindent + +@noindent +@table @asis +@findex syserror +@item @t{syserror} [ @t{-e} @var{errvar} ] [ @t{-p} @var{prefix} ] [ @var{errno} | @var{errname} ] +This command prints out the error message associated with @var{errno}, a +system error number, followed by a newline to standard error. + +@noindent +Instead of the error number, a name @var{errname}, for example +@t{ENOENT}, may be used. The set of names is the same as the contents +of the array @t{errnos}, see below. + +@noindent +If the string @var{prefix} is given, it is printed in front of the error +message, with no intervening space. + +@noindent +If @var{errvar} is supplied, the entire message, without a newline, is +assigned to the parameter names @var{errvar} and nothing is output. + +@noindent +A return status of 0 indicates the message was successfully printed +(although it may not be useful if the error number was out of the +system's range), a return status of 1 indicates an error in the +parameters, and a return status of 2 indicates the error name was +not recognised (no message is printed for this). + +@findex sysopen + +@item @t{sysopen} [ @t{-arw} ] [ @t{-m} @var{permissions} ] [ @t{-o} @var{options} ] +@itemx @t{@ @ @ @ @ @ @ @ }@t{-u} @var{fd} @var{file} +This command opens a file. The @t{-r}, @t{-w} and @t{-a} flags indicate +whether the file should be opened for reading, writing and appending, +respectively. The @t{-m} option allows the initial permissions to use when +creating a file to be specified in octal form. The file descriptor is +specified with @t{-u}. Either an explicit file descriptor in the range 0 to 9 can +be specified or a variable name can be given to which the file descriptor +number will be assigned. + +@noindent +The @t{-o} option allows various system specific options to be +specified as a comma-separated list. The following is a list of possible +options. Note that, depending on the system, some may not be available. +@table @asis +@item @t{cloexec} +mark file to be closed when other programs are executed (else +the file descriptor remains open in subshells and forked external +executables) + +@item @t{create} +@itemx @t{creat} +create file if it does not exist + +@item @t{excl} +create file, error if it already exists + +@item @t{noatime} +suppress updating of the file atime + +@item @t{nofollow} +fail if @var{file} is a symbolic link + +@item @t{nonblock} +the file is opened in nonblocking mode + +@item @t{sync} +request that writes wait until data has been physically written + +@item @t{truncate} +@itemx @t{trunc} +truncate file to size 0 + +@end table + +@noindent +To close the file, use one of the following: + +@noindent +@example +@t{exec @{}@var{fd}@t{@}<&-} +@t{exec @{}@var{fd}@t{@}>&-} +@end example + +@findex sysread + +@item @t{sysread }[ @t{-c} @var{countvar} ] [ @t{-i} @var{infd} ] [ @t{-o} @var{outfd} ] +@itemx @t{@ @ @ @ @ @ @ @ }[ @t{-s} @var{bufsize} ] [ @t{-t} @var{timeout} ] [ @var{param} ] +Perform a single system read from file descriptor @var{infd}, or zero if +that is not given. The result of the read is stored in @var{param} or +@t{REPLY} if that is not given. If @var{countvar} is given, the number +of bytes read is assigned to the parameter named by @var{countvar}. + +@noindent +The maximum number of bytes read is @var{bufsize} or 8192 if that is not +given, however the command returns as soon as any number of bytes was +successfully read. + +@noindent +If @var{timeout} is given, it specifies a timeout in seconds, which may +be zero to poll the file descriptor. This is handled by the @t{poll} +system call if available, otherwise the @t{select} system call if +available. + +@noindent +If @var{outfd} is given, an attempt is made to write all the bytes just +read to the file descriptor @var{outfd}. If this fails, because of a +system error other than @t{EINTR} or because of an internal zsh error +during an interrupt, the bytes read but not written are stored in the +parameter named by @var{param} if supplied (no default is used in this +case), and the number of bytes read but not written is stored in the +parameter named by @var{countvar} if that is supplied. If it was +successful, @var{countvar} contains the full number of bytes transferred, +as usual, and @var{param} is not set. + +@noindent +The error @t{EINTR} (interrupted system call) is handled internally so +that shell interrupts are transparent to the caller. Any other error +causes a return. + +@noindent +The possible return statuses are +@table @asis +@item 0 +At least one byte of data was successfully read and, if appropriate, +written. + +@item 1 +There was an error in the parameters to the command. This is the only +error for which a message is printed to standard error. + +@item 2 +There was an error on the read, or on polling the input file descriptor +for a timeout. The parameter @t{ERRNO} gives the error. + +@item 3 +Data were successfully read, but there was an error writing them +to @var{outfd}. The parameter @t{ERRNO} gives the error. + +@item 4 +The attempt to read timed out. Note this does not set @t{ERRNO} as this +is not a system error. + +@item 5 +No system error occurred, but zero bytes were read. This usually +indicates end of file. The parameters are set according to the +usual rules; no write to @var{outfd} is attempted. + +@end table + +@item @t{sysseek} [ @t{-u} @var{fd} ] [ @t{-w} @t{start}|@t{end}|@t{current} ] @var{offset} +The current file position at which future reads and writes will take place is +adjusted to the specified byte offset. The @var{offset} is evaluated as a math +expression. The @t{-u} option allows the file descriptor to be specified. By +default the offset is specified relative to the start or the file but, with the +@t{-w} option, it is possible to specify that the offset should be relative to +the current position or the end of the file. + +@item @t{syswrite} [ @t{-c} @var{countvar} ] [ @t{-o} @var{outfd} ] @var{data} +The data (a single string of bytes) are written to the file descriptor +@var{outfd}, or 1 if that is not given, using the @t{write} system call. +Multiple write operations may be used if the first does not write all +the data. + +@noindent +If @var{countvar} is given, the number of byte written is stored in the +parameter named by @var{countvar}; this may not be the full length of +@var{data} if an error occurred. + +@noindent +The error @t{EINTR} (interrupted system call) is handled internally by +retrying; otherwise an error causes the command to return. For example, +if the file descriptor is set to non-blocking output, an error +@t{EAGAIN} (on some systems, @t{EWOULDBLOCK}) may result in the command +returning early. + +@noindent +The return status may be 0 for success, 1 for an error in the parameters +to the command, or 2 for an error on the write; no error message is +printed in the last case, but the parameter @t{ERRNO} will reflect +the error that occurred. + +@item @t{zsystem flock} [ @t{-t} @var{timeout} ] [ @t{-i} @var{interval} ] [ @t{-f} @var{var} ] [@t{-er}] @var{file} +@itemx @t{zsystem flock -u} @var{fd_expr} +The builtin @t{zsystem}'s subcommand @t{flock} performs advisory file +locking (via the fcntl(2) system call) over the entire contents +of the given file. This form of locking requires the processes +accessing the file to cooperate; its most obvious use is between two +instances of the shell itself. + +@noindent +In the first form the named @var{file}, which must already exist, is +locked by opening a file descriptor to the file and applying a lock to +the file descriptor. The lock terminates when the shell process that +created the lock exits; it is therefore often convenient to create file +locks within subshells, since the lock is automatically released when +the subshell exits. Note that use of the @t{print} builtin with the +@t{-u} option will, as a side effect, release the lock, as will redirection +to the file in the shell holding the lock. To work around this use a +subshell, e.g. `@t{(print message) >> }@var{file}'. Status 0 is +returned if the lock succeeds, else status 1. + +@noindent +In the second form the file descriptor given by the arithmetic +expression @var{fd_expr} is closed, releasing a lock. The file descriptor +can be queried by using the `@t{-f} @var{var}' form during the lock; +on a successful lock, the shell variable @var{var} is set to the file +descriptor used for locking. The lock will be released if the +file descriptor is closed by any other means, for example using +`@t{exec @{}@var{var}@t{@}>&-}'; however, the form described here performs +a safety check that the file descriptor is in use for file locking. + +@noindent +By default the shell waits indefinitely for the lock to succeed. +The option @t{-t} @var{timeout} specifies a timeout for the lock in +seconds; fractional seconds are allowed. During this period, the +shell will attempt to lock the file every @var{interval} seconds +if the @t{-i} @var{interval} option is given, otherwise once a second. +(This @var{interval} is shortened before the last attempt if needed, +so that the shell waits only until the @var{timeout} and not longer.) +If the attempt times out, status 2 is returned. + +@noindent +(Note: @var{timeout} is limited to 2^30-1 seconds (about 34 years), and +@var{interval} to 0.999 * LONG_MAX microseconds (only about 35 minutes +on 32-bit systems).) + +@noindent +If the option @t{-e} is given, the file descriptor for the lock is +preserved when the shell uses @t{exec} to start a new process; +otherwise it is closed at that point and the lock released. + +@noindent +If the option @t{-r} is given, the lock is only for reading, otherwise +it is for reading and writing. The file descriptor is opened +accordingly. + +@item @t{zsystem supports} @var{subcommand} +The builtin @t{zsystem}'s subcommand @t{supports} tests whether a +given subcommand is supported. It returns status 0 if so, else +status 1. It operates silently unless there was a syntax error +(i.e. the wrong number of arguments), in which case status 255 +is returned. Status 1 can indicate one of two things: @var{subcommand} +is known but not supported by the current operating system, or +@var{subcommand} is not known (possibly because this is an older +version of the shell before it was implemented). + +@end table + +@noindent + +@subsection Math Functions +@noindent + +@noindent +@table @asis +@item @t{systell(@var{fd})} +The systell math function returns the current file position for the file +descriptor passed as an argument. + +@end table + +@noindent + +@subsection Parameters +@noindent + +@noindent +@table @asis +@vindex errnos +@item @t{errnos} +A readonly array of the names of errors defined on the system. These +are typically macros defined in C by including the system header file +@t{errno.h}. The index of each name (assuming the option @t{KSH_ARRAYS} +is unset) corresponds to the error number. Error numbers @var{num} +before the last known error which have no name are given the name +@t{E}@var{num} in the array. + +@noindent +Note that aliases for errors are not handled; only the canonical name is +used. + +@vindex sysparams +@item @t{sysparams} +A readonly associative array. The keys are: + +@noindent +@table @asis +@item @t{pid} +@vindex pid, sysparams +Returns the process ID of the current process, even in subshells. Compare +@t{$$}, which returns the process ID of the main shell process. + +@item @t{ppid} +@vindex ppid, sysparams +Returns the current process ID of the parent of the current process, even +in subshells. Compare @t{$PPID}, which returns the process ID of the +initial parent of the main shell process. + +@item @t{procsubstpid} +Returns the process ID of the last process started for process +substitution, i.e. the @t{<(}@var{...}@t{)} and +@t{>(}@var{...}@t{)} expansions. + +@end table + +@end table +@c (avoiding a yodl bug) +@node The zsh/net/tcp Module, The zsh/termcap Module, The zsh/system Module, Zsh Modules + +@section The zsh/net/tcp Module +@noindent +@c Yodl file: Zsh/mod_tcp.yo + +The @t{zsh/net/tcp} module makes available one builtin command: + +@noindent +@table @asis +@findex ztcp +@cindex TCP +@cindex sockets, TCP +@item @t{ztcp} [ @t{-acflLtv} ] [ @t{-d} @var{fd} ] [ @var{args} ] +@t{ztcp} is implemented as a builtin to allow full use of shell +command line editing, file I/O, and job control mechanisms. + +@noindent +If @t{ztcp} is run with no options, it will output +the contents of its session table. + +@noindent +If it is run with only the option @t{-L}, it will output the contents of +the session table in a format suitable for automatic parsing. The option +is ignored if given with a command to open or close a session. The output +consists of a set of lines, one per session, each containing the following +elements separated by spaces: + +@noindent +@table @asis +@item File descriptor +The file descriptor in use for the connection. For normal inbound (@t{I}) +and outbound (@t{O}) connections this may be read and written by the usual +shell mechanisms. However, it should only be close with `@t{ztcp -c}'. + +@item Connection type +A letter indicating how the session was created: + +@noindent +@table @asis +@item @t{Z} +A session created with the @t{zftp} command. + +@item @t{L} +A connection opened for listening with `@t{ztcp -l}'. + +@item @t{I} +An inbound connection accepted with `@t{ztcp -a}'. + +@item @t{O} +An outbound connection created with `@t{ztcp} @var{host} @var{...}'. + +@end table + +@noindent + +@item The local host +This is usually set to an all-zero IP address as the address of the +localhost is irrelevant. + +@item The local port +This is likely to be zero unless the connection is for listening. + +@item The remote host +This is the fully qualified domain name of the peer, if available, else an +IP address. It is an all-zero IP address for a session opened for +listening. + +@item The remote port +This is zero for a connection opened for listening. + +@end table + +@end table + +@noindent + +@subsection Outbound Connections +@noindent +@cindex sockets, outbound TCP + +@noindent +@table @asis +@item @t{ztcp} [ @t{-v} ] [ @t{-d} @var{fd} ] @var{host} [ @var{port} ] +Open a new TCP connection to @var{host}. If the @var{port} is +omitted, it will default to port 23. The connection will +be added to the session table and the shell parameter +@t{REPLY} will be set to the file descriptor associated +with that connection. + +@noindent +If @t{-d} is specified, its argument will be taken as the target file +descriptor for the connection. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@end table + +@noindent + +@subsection Inbound Connections +@noindent +@cindex sockets, inbound TCP + +@noindent +@table @asis +@item @t{ztcp} @t{-l} [ @t{-v} ] [ @t{-d} @var{fd} ] @var{port} +@t{ztcp -l} will open a socket listening on TCP +@var{port}. The socket will be added to the +session table and the shell parameter @t{REPLY} +will be set to the file descriptor associated +with that listener. + +@noindent +If @t{-d} is specified, its argument will be taken as the target file +descriptor for the connection. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@item @t{ztcp} @t{-a} [ @t{-tv} ] [ @t{-d} @var{targetfd} ] @var{listenfd} +@t{ztcp -a} will accept an incoming connection +to the port associated with @var{listenfd}. +The connection will be added to the session +table and the shell parameter @t{REPLY} will +be set to the file descriptor associated with +the inbound connection. + +@noindent +If @t{-d} is specified, its argument +will be taken as the target file descriptor for the +connection. + +@noindent +If @t{-t} is specified, @t{ztcp} will return +if no incoming connection is pending. Otherwise +it will wait for one. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@end table + +@noindent + +@subsection Closing Connections +@noindent +@cindex sockets, closing TCP + +@noindent +@table @asis +@item @t{ztcp} @t{-cf} [ @t{-v} ] [ @var{fd} ] +@itemx @t{ztcp} @t{-c} [ @t{-v} ] [ @var{fd} ] +@t{ztcp -c} will close the socket associated +with @var{fd}. The socket will be removed from the +session table. If @var{fd} is not specified, +@t{ztcp} will close everything in the session table. + +@noindent +Normally, sockets registered by zftp (see +@ref{The zsh/zftp Module} +) cannot be closed this way. In order +to force such a socket closed, use @t{-f}. + +@noindent +In order to elicit more verbose output, use @t{-v}. + +@end table + +@noindent + +@subsection Example +@noindent +@cindex TCP, example +Here is how to create a TCP connection between two instances of zsh. We +need to pick an unassigned port; here we use the randomly chosen 5123. + +@noindent +On @t{host1}, +@example +zmodload zsh/net/tcp +ztcp -l 5123 +listenfd=$REPLY +ztcp -a $listenfd +fd=$REPLY +@end example +The second from last command blocks until there is an incoming connection. + +@noindent +Now create a connection from @t{host2} (which may, of course, be the same +machine): +@example +zmodload zsh/net/tcp +ztcp host1 5123 +fd=$REPLY +@end example + +@noindent +Now on each host, @t{$fd} contains a file descriptor for talking to the +other. For example, on @t{host1}: +@example +print This is a message >&$fd +@end example +and on @t{host2}: +@example +read -r line <&$fd; print -r - $line +@end example +prints `@t{This is a message}'. + +@noindent +To tidy up, on @t{host1}: +@example +ztcp -c $listenfd +ztcp -c $fd +@end example +and on @t{host2} +@example +ztcp -c $fd +@end example +@c (avoiding a yodl bug) +@node The zsh/termcap Module, The zsh/terminfo Module, The zsh/net/tcp Module, Zsh Modules + +@section The zsh/termcap Module +@noindent +@c Yodl file: Zsh/mod_termcap.yo + +The @t{zsh/termcap} module makes available one builtin command: + +@noindent +@table @asis +@findex echotc +@cindex termcap value, printing +@item @t{echotc} @var{cap} [ @var{arg} ... ] +Output the termcap value corresponding to the capability +@var{cap}, with optional arguments. + +@end table + +@noindent +The @t{zsh/termcap} module makes available one parameter: + +@noindent +@table @asis +@vindex termcap +@item @t{termcap} +An associative array that maps termcap capability codes to +their values. + +@end table +@c (avoiding a yodl bug) +@node The zsh/terminfo Module, The zsh/watch Module, The zsh/termcap Module, Zsh Modules + +@section The zsh/terminfo Module +@noindent +@c Yodl file: Zsh/mod_terminfo.yo + +The @t{zsh/terminfo} module makes available one builtin command: + +@noindent +@table @asis +@findex echoti +@cindex terminfo value, printing +@item @t{echoti} @var{cap} [ @var{arg} ] +Output the terminfo value corresponding to the capability +@var{cap}, instantiated with @var{arg} if applicable. + +@end table + +@noindent +The @t{zsh/terminfo} module makes available one parameter: + +@noindent +@table @asis +@vindex terminfo +@item @t{terminfo} +An associative array that maps terminfo capability names to +their values. + +@end table +@c (avoiding a yodl bug) +@node The zsh/watch Module, The zsh/zftp Module, The zsh/terminfo Module, Zsh Modules + +@section The zsh/watch Module +@noindent +@c Yodl file: Zsh/mod_watch.yo + +The @t{zsh/watch} module can be used to report when specific users log in or +out. This is controlled via the following parameters. + +@noindent +@table @asis +@vindex LOGCHECK +@item @t{LOGCHECK} +The interval in seconds between checks for login/logout activity +using the @t{watch} parameter. + +@vindex watch +@vindex WATCH +@item @t{watch} <S> <Z> (@t{WATCH} <S>) +An array (colon-separated list) of login/logout events to report. + +@noindent +If it contains the single word `@t{all}', then all login/logout events +are reported. If it contains the single word `@t{notme}', then all +events are reported as with `@t{all}' except @t{$USERNAME}. + +@noindent +An entry in this list may consist of a username, +an `@t{@@}' followed by a remote hostname, +and a `@t{%}' followed by a line (tty). Any of these may +be a pattern (be sure to quote this during the assignment to +@t{watch} so that it does not immediately perform file generation); +the setting of the @t{EXTENDED_GLOB} option is respected. +Any or all of these components may be present in an entry; +if a login/logout event matches all of them, +it is reported. + +@noindent +For example, with the @t{EXTENDED_GLOB} option set, the following: + +@noindent +@example +watch=('^(pws|barts)') +@end example + +@noindent +causes reports for activity associated with any user other than @t{pws} +or @t{barts}. + +@vindex WATCHFMT +@item @t{WATCHFMT} +The format of login/logout reports if the @t{watch} parameter is set. +Default is `@t{%n has %a %l from %m}'. +Recognizes the following escape sequences: + +@noindent +@table @asis +@item @t{%n} +The name of the user that logged in/out. + +@item @t{%a} +The observed action, i.e. "logged on" or "logged off". + +@item @t{%l} +The line (tty) the user is logged in on. + +@item @t{%M} +The full hostname of the remote host. + +@item @t{%m} +The hostname up to the first `@t{.}'. If only the +IP address is available or the utmp field contains +the name of an X-windows display, the whole name is printed. + +@noindent +@emph{NOTE:} +The `@t{%m}' and `@t{%M}' escapes will work only if there is a host name +field in the utmp on your machine. Otherwise they are +treated as ordinary strings. + +@item @t{%F@{}@var{color}@t{@}} (@t{%f}) +Start (stop) using a different foreground color. + +@item @t{%K@{}@var{color}@t{@}} (@t{%k}) +Start (stop) using a different background color. + +@item @t{%S} (@t{%s}) +Start (stop) standout mode. + +@item @t{%U} (@t{%u}) +Start (stop) underline mode. + +@item @t{%B} (@t{%b}) +Start (stop) boldface mode. + +@item @t{%t} +@itemx @t{%@@} +The time, in 12-hour, am/pm format. + +@item @t{%T} +The time, in 24-hour format. + +@item @t{%w} +The date in `@var{day}@t{-}@var{dd}' format. + +@item @t{%W} +The date in `@var{mm}@t{/}@var{dd}@t{/}@var{yy}' format. + +@item @t{%D} +The date in `@var{yy}@t{-}@var{mm}@t{-}@var{dd}' format. + +@item @t{%D@{}@var{string}@t{@}} +The date formatted as @var{string} using the @t{strftime} function, with +zsh extensions as described by +@ref{Prompt Expansion}. + +@item @t{%(}@var{x}@t{:}@var{true-text}@t{:}@var{false-text}@t{)} +Specifies a ternary expression. +The character following the @var{x} is +arbitrary; the same character is used to separate the text +for the "true" result from that for the "false" result. +Both the separator and the right parenthesis may be escaped +with a backslash. +Ternary expressions may be nested. + +@noindent +The test character @var{x} may be any one of `@t{l}', `@t{n}', `@t{m}' +or `@t{M}', which indicate a `true' result if the corresponding +escape sequence would return a non-empty value; or it may be `@t{a}', +which indicates a `true' result if the watched user has logged in, +or `false' if he has logged out. +Other characters evaluate to neither true nor false; the entire +expression is omitted in this case. + +@noindent +If the result is `true', then the @var{true-text} +is formatted according to the rules above and printed, +and the @var{false-text} is skipped. +If `false', the @var{true-text} is skipped and the @var{false-text} +is formatted and printed. +Either or both of the branches may be empty, but +both separators must be present in any case. + +@end table + +@end table + +@noindent +Furthermore, the @t{zsh/watch} module makes available one builtin +command: + +@noindent +@table @asis +@findex log +@vindex watch, use of +@cindex watching users +@cindex users, watching +@item @t{log} +List all users currently logged in who are affected by +the current setting of the @t{watch} parameter. + +@end table +@c (avoiding a yodl bug) +@node The zsh/zftp Module, The zsh/zle Module, The zsh/watch Module, Zsh Modules + +@section The zsh/zftp Module +@noindent +@c Yodl file: Zsh/mod_zftp.yo + +The @t{zsh/zftp} module makes available one builtin command: + +@noindent +@table @asis +@findex zftp +@cindex FTP +@cindex files, transferring +@item @t{zftp} @var{subcommand} [ @var{args} ] +The @t{zsh/zftp} module is a client for FTP (file transfer protocol). It +is implemented as a builtin to allow full use of shell command line +editing, file I/O, and job control mechanisms. Often, users will +access it via shell functions providing a more powerful interface; a set is +provided with the @t{zsh} distribution and is described in +@ref{Zftp Function System}. However, the @t{zftp} command is entirely usable in its +own right. + +@noindent +All commands consist of the command name @t{zftp} followed by the name +of a subcommand. These are listed below. The return status of each +subcommand is supposed to reflect the success or failure of the remote +operation. See a description of the variable @t{ZFTP_VERBOSE} for +more information on how responses from the server may be printed. + +@end table + +@noindent + +@subsection Subcommands +@noindent +@cindex zftp, subcommands + +@noindent +@table @asis +@cindex FTP, starting a session +@item @t{open} @var{host}[@t{:}@var{port}] [ @var{user} [ @var{password} [ @var{account} ] ] ] +Open a new FTP session to @var{host}, which may be the name of a TCP/IP +connected host or an IP number in the standard dot notation. If the +argument is in the form @var{host}@t{:}@var{port}, open a connection to +TCP port @var{port} instead of the standard FTP port 21. This may be +the name of a TCP service or a number: see the description of +@t{ZFTP_PORT} below for more information. + +@noindent +If IPv6 addresses in colon format are used, the @var{host} should be +surrounded by quoted square brackets to distinguish it from the @var{port}, +for example @t{'[fe80::203:baff:fe02:8b56]'}. For consistency this is +allowed with all forms of @var{host}. + +@noindent +Remaining arguments are passed to the @t{login} subcommand. Note that +if no arguments beyond @var{host} are supplied, @t{open} will @emph{not} +automatically call @t{login}. If no arguments at all are supplied, +@t{open} will use the parameters set by the @t{params} subcommand. + +@noindent +After a successful open, the shell variables @t{ZFTP_HOST}, @t{ZFTP_PORT}, +@t{ZFTP_IP} and @t{ZFTP_SYSTEM} are available; see `Variables' +below. + +@item @t{login} [ @var{name} [ @var{password} [ @var{account} ] ] ] +@itemx @t{user} [ @var{name} [ @var{password} [ @var{account} ] ] ] +Login the user @var{name} with parameters @var{password} and @var{account}. +Any of the parameters can be omitted, and will be read from standard +input if needed (@var{name} is always needed). If +standard input is a terminal, a prompt for each one will be printed on +standard error and @var{password} will not be echoed. If any of the +parameters are not used, a warning message is printed. + +@noindent +After a successful login, the shell variables @t{ZFTP_USER}, +@t{ZFTP_ACCOUNT} and @t{ZFTP_PWD} are available; see `Variables' +below. + +@noindent +This command may be re-issued when a user is already logged in, and +the server will first be reinitialized for a new user. + +@item @t{params} [ @var{host} [ @var{user} [ @var{password} [ @var{account} ] ] ] ] +@itemx @t{params} @t{-} +Store the given parameters for a later @t{open} command with no +arguments. Only those given on the command line will be remembered. +If no arguments are given, the parameters currently set are printed, +although the password will appear as a line of stars; the return status is +one if no parameters were set, zero otherwise. + +@noindent +Any of the parameters may be specified as a `@t{?}', which +may need to be quoted to protect it from shell expansion. In this case, +the appropriate parameter will be read from stdin as with the +@t{login} subcommand, including special handling of @var{password}. If the +`@t{?}' is followed by a string, that is used as the prompt for reading the +parameter instead of the default message (any necessary punctuation and +whitespace should be included at the end of the prompt). The first letter +of the parameter (only) may be quoted with a `@t{\}'; hence an argument +@t{"\\$word"} guarantees that the string from the shell parameter @t{$word} +will be treated literally, whether or not it begins with a `@t{?}'. + +@noindent +If instead a single `@t{-}' is given, the existing parameters, if any, +are deleted. In that case, calling @t{open} with no arguments will +cause an error. + +@noindent +The list of parameters is not deleted after a @t{close}, however it +will be deleted if the @t{zsh/zftp} module is unloaded. + +@noindent +For example, + +@noindent +@example +zftp params ftp.elsewhere.xx juser '?Password for juser: ' +@end example + +@noindent +will store the host @t{ftp.elsewhere.xx} and the user @t{juser} and +then prompt the user for the corresponding password with the given prompt. + +@item @t{test} +Test the connection; if the server has reported +that it has closed the connection (maybe due to a timeout), return +status 2; if no connection was open anyway, return status 1; else +return status 0. The @t{test} subcommand is +silent, apart from messages printed by the @t{$ZFTP_VERBOSE} +mechanism, or error messages if the connection closes. There is no +network overhead for this test. + +@noindent +The test is only supported on systems with either the +@t{select(2)} or +@t{poll(2)} system calls; otherwise the message `@t{not +supported on this system}' is printed instead. + +@noindent +The @t{test} subcommand will automatically be called at the start of any +other subcommand for the current session when a connection is open. + +@item @t{cd} @var{directory} +Change the remote directory to @var{directory}. Also alters the shell +variable @t{ZFTP_PWD}. + +@item @t{cdup} +Change the remote directory to the one higher in the directory tree. +Note that @t{cd ..} will also work correctly on non-UNIX systems. + +@item @t{dir} [ @var{arg} ... ] +Give a (verbose) listing of the remote directory. The @var{arg}s are +passed directly to the server. The command's behaviour is implementation +dependent, but a UNIX server will typically interpret @var{arg}s as +arguments to the @t{ls} command and with no arguments return the +result of `@t{ls -l}'. The directory is listed to standard output. + +@item @t{ls} [ @var{arg} ... ] +Give a (short) listing of the remote directory. With no @var{arg}, +produces a raw list of the files in the directory, one per line. +Otherwise, up to vagaries of the server implementation, behaves +similar to @t{dir}. + +@item @t{type} [ @var{type} ] +Change the type for the transfer to @var{type}, or print the current type +if @var{type} is absent. The allowed values are `@t{A}' (ASCII), +`@t{I}' (Image, i.e. binary), or `@t{B}' (a synonym for `@t{I}'). + +@noindent +The FTP default for a transfer is ASCII. However, if @t{zftp} finds +that the remote host is a UNIX machine with 8-bit byes, it will +automatically switch to using binary for file transfers upon +@t{open}. This can subsequently be overridden. + +@noindent +The transfer type is only passed to the remote host when a data +connection is established; this command involves no network overhead. + +@item @t{ascii} +The same as @t{type A}. + +@item @t{binary} +The same as @t{type I}. + +@item @t{mode} [ @t{S} | @t{B} ] +Set the mode type to stream (@t{S}) or block (@t{B}). Stream mode is +the default; block mode is not widely supported. + +@item @t{remote} @var{file} ... +@itemx @t{local} [ @var{file} ... ] +Print the size and last modification time of the remote or local +files. If there is more than one item on the list, the name of the +file is printed first. The first number is the file size, the second +is the last modification time of the file in the format +@t{CCYYMMDDhhmmSS} consisting of year, month, date, hour, minutes and +seconds in GMT. Note that this format, including the length, is +guaranteed, so that time strings can be directly compared via the +@t{[[} builtin's @t{<} and @t{>} operators, even if they are too long +to be represented as integers. + +@noindent +Not all servers support the commands for retrieving this information. +In that case, the @t{remote} command will print nothing and return +status 2, compared with status 1 for a file not found. + +@noindent +The @t{local} command (but not @t{remote}) may be used with no +arguments, in which case the information comes from examining file +descriptor zero. This is the same file as seen by a @t{put} command +with no further redirection. + +@item @t{get} @var{file} ... +Retrieve all @var{file}s from the server, concatenating them +and sending them to standard output. + +@item @t{put} @var{file} ... +For each @var{file}, read a file from standard input and send that to +the remote host with the given name. + +@item @t{append} @var{file} ... +As @t{put}, but if the remote @var{file} already exists, data is +appended to it instead of overwriting it. + +@item @t{getat} @var{file} @var{point} +@itemx @t{putat} @var{file} @var{point} +@itemx @t{appendat} @var{file} @var{point} +Versions of @t{get}, @t{put} and @t{append} which will start the +transfer at the given @var{point} in the remote @var{file}. This is +useful for appending to an incomplete local file. However, note that +this ability is not universally supported by servers (and is not quite +the behaviour specified by the standard). + +@item @t{delete} @var{file} ... +Delete the list of files on the server. + +@item @t{mkdir} @var{directory} +Create a new directory @var{directory} on the server. + +@item @t{rmdir} @var{directory} +Delete the directory @var{directory} on the server. + +@item @t{rename} @var{old-name} @var{new-name} +Rename file @var{old-name} to @var{new-name} on the server. + +@item @t{site} @var{arg} ... +Send a host-specific command to the server. You will probably +only need this if instructed by the server to use it. + +@item @t{quote} @var{arg} ... +Send the raw FTP command sequence to the server. You should be +familiar with the FTP command set as defined in RFC959 before doing +this. Useful commands may include @t{STAT} and @t{HELP}. Note also +the mechanism for returning messages as described for the variable +@t{ZFTP_VERBOSE} below, in particular that all messages from the +control connection are sent to standard error. + +@item @t{close} +@itemx @t{quit} +Close the current data connection. This unsets the shell parameters +@t{ZFTP_HOST}, @t{ZFTP_PORT}, @t{ZFTP_IP}, @t{ZFTP_SYSTEM}, @t{ZFTP_USER}, +@t{ZFTP_ACCOUNT}, @t{ZFTP_PWD}, @t{ZFTP_TYPE} and @t{ZFTP_MODE}. + +@item @t{session} [ @var{sessname} ] +Allows multiple FTP sessions to be used at once. The name of the session +is an arbitrary string of characters; the default session is called +`@t{default}'. If this command is called without an argument, it will list +all the current sessions; with an argument, it will either switch to the +existing session called @var{sessname}, or create a new session of that name. + +@noindent +Each session remembers the status of the connection, the set of +connection-specific shell parameters (the same set as are unset when a +connection closes, as given in the description of @t{close}), and any user +parameters specified with the @t{params} subcommand. Changing to a +previous session restores those values; changing to a new session +initialises them in the same way as if @t{zftp} had just been loaded. The +name of the current session is given by the parameter @t{ZFTP_SESSION}. + +@item @t{rmsession} [ @var{sessname} ] +Delete a session; if a name is not given, the current session is deleted. +If the current session is deleted, the earliest existing session becomes +the new current session, otherwise the current session is not changed. +If the session being deleted is the only one, a new session called +`@t{default}' is created and becomes the current session; note that this is +a new session even if the session being deleted is also called +`@t{default}'. It is recommended that sessions not be deleted while +background commands which use @t{zftp} are still active. + +@end table + +@noindent + +@subsection Parameters +@noindent +@cindex zftp, parameters +The following shell parameters are used by @t{zftp}. Currently none +of them are special. + +@noindent +@table @asis +@vindex ZFTP_TMOUT +@item @t{ZFTP_TMOUT} +Integer. The time in seconds to wait for a network operation to +complete before returning an error. If this is not set when the +module is loaded, it will be given the default value 60. A value of +zero turns off timeouts. If a timeout occurs on the control +connection it will be closed. Use a larger value if this occurs too +frequently. + +@vindex ZFTP_IP +@item @t{ZFTP_IP} +Readonly. The IP address of the current connection in dot notation. + +@vindex ZFTP_HOST +@item @t{ZFTP_HOST} +Readonly. The hostname of the current remote server. If the host was +opened as an IP number, @t{ZFTP_HOST} contains that instead; this +saves the overhead for a name lookup, as IP numbers are most commonly +used when a nameserver is unavailable. + +@vindex ZFTP_PORT +@item @t{ZFTP_PORT} +Readonly. The number of the remote TCP port to which the connection is +open (even if the port was originally specified as a named service). +Usually this is the standard FTP port, 21. + +@noindent +In the unlikely event that your system does not have the appropriate +conversion functions, this appears in network byte order. If your +system is little-endian, the port then consists of two swapped bytes and the +standard port will be reported as 5376. In that case, numeric ports passed +to @t{zftp open} will also need to be in this format. + +@vindex ZFTP_SYSTEM +@item @t{ZFTP_SYSTEM} +Readonly. The system type string returned by the server in response +to an FTP @t{SYST} request. The most interesting case is a string +beginning @t{"UNIX Type: L8"}, which ensures maximum compatibility +with a local UNIX host. + +@vindex ZFTP_TYPE +@item @t{ZFTP_TYPE} +Readonly. The type to be used for data transfers , either `@t{A}' or +`@t{I}'. Use the @t{type} subcommand to change this. + +@vindex ZFTP_USER +@item @t{ZFTP_USER} +Readonly. The username currently logged in, if any. + +@vindex ZFTP_ACCOUNT +@item @t{ZFTP_ACCOUNT} +Readonly. The account name of the current user, if any. Most servers +do not require an account name. + +@vindex ZFTP_PWD +@item @t{ZFTP_PWD} +Readonly. The current directory on the server. + +@vindex ZFTP_CODE +@item @t{ZFTP_CODE} +Readonly. The three digit code of the last FTP reply from the server +as a string. This can still be read after the connection is closed, and +is not changed when the current session changes. + +@vindex ZFTP_REPLY +@item @t{ZFTP_REPLY} +Readonly. The last line of the last reply sent by the server. This +can still be read after the connection is closed, and is not changed when +the current session changes. + +@vindex ZFTP_SESSION +@item @t{ZFTP_SESSION} +Readonly. The name of the current FTP session; see the description of the +@t{session} subcommand. + +@vindex ZFTP_PREFS +@item @t{ZFTP_PREFS} +A string of preferences for altering aspects of @t{zftp}'s behaviour. +Each preference is a single character. The following are defined: + +@noindent +@table @asis +@item @t{P} +Passive: attempt to make the remote server initiate data transfers. +This is slightly more efficient than sendport mode. If the letter +@t{S} occurs later in the string, @t{zftp} will use sendport mode if +passive mode is not available. + +@item @t{S} +Sendport: initiate transfers by the FTP @t{PORT} command. If this +occurs before any @t{P} in the string, passive mode will never be +attempted. + +@item @t{D} +Dumb: use only the bare minimum of FTP commands. This prevents +the variables @t{ZFTP_SYSTEM} and @t{ZFTP_PWD} from being set, and +will mean all connections default to ASCII type. It may prevent +@t{ZFTP_SIZE} from being set during a transfer if the server +does not send it anyway (many servers do). + +@end table + +@noindent +If @t{ZFTP_PREFS} is not set when @t{zftp} is loaded, it will be set to a +default of `@t{PS}', i.e. use passive mode if available, otherwise +fall back to sendport mode. + +@vindex ZFTP_VERBOSE +@item @t{ZFTP_VERBOSE} +A string of digits between 0 and 5 inclusive, specifying which +responses from the server should be printed. All responses go to +standard error. If any of the numbers 1 to 5 appear in the string, +raw responses from the server with reply codes beginning with that +digit will be printed to standard error. The first digit of the three +digit reply code is defined by RFC959 to correspond to: + +@noindent +@table @asis +@item 1. +A positive preliminary reply. + +@item 2. +A positive completion reply. + +@item 3. +A positive intermediate reply. + +@item 4. +A transient negative completion reply. + +@item 5. +A permanent negative completion reply. + +@end table + +@noindent +It should be noted that, for unknown reasons, the reply `Service not +available', which forces termination of a connection, is classified as +421, i.e. `transient negative', an interesting interpretation of the word +`transient'. + +@noindent +The code 0 is special: it indicates that all but the last line of +multiline replies read from the server will be printed to standard +error in a processed format. By convention, servers use this +mechanism for sending information for the user to read. The +appropriate reply code, if it matches the same response, takes +priority. + +@noindent +If @t{ZFTP_VERBOSE} is not set when @t{zftp} is loaded, it will be +set to the default value @t{450}, i.e., messages destined for the user +and all errors will be printed. A null string is valid and +specifies that no messages should be printed. + +@end table + +@noindent + +@subsection Functions +@noindent +@cindex zftp, functions + +@noindent +@table @asis +@findex zftp_chpwd, specification +@item @t{zftp_chpwd} +If this function is set by the user, it is called every time the +directory changes on the server, including when a user is logged +in, or when a connection is closed. In the last case, @t{$ZFTP_PWD} +will be unset; otherwise it will reflect the new directory. + +@findex zftp_progress, specification +@item @t{zftp_progress} +If this function is set by the user, it will be called during +a @t{get}, @t{put} or @t{append} operation each time sufficient data +has been received from the host. During a @t{get}, the data is sent +to standard output, so it is vital that this function should write +to standard error or directly to the terminal, @emph{not} to standard +output. + +@noindent +When it is called with a transfer in progress, the following +additional shell parameters are set: + +@noindent +@table @asis +@vindex ZFTP_FILE +@item @t{ZFTP_FILE} +The name of the remote file being transferred from or to. + +@vindex ZFTP_TRANSFER +@item @t{ZFTP_TRANSFER} +A @t{G} for a @t{get} operation and a @t{P} for a @t{put} operation. + +@vindex ZFTP_SIZE +@item @t{ZFTP_SIZE} +The total size of the complete file being transferred: +the same as the first value provided by the +@t{remote} and @t{local} subcommands for a particular file. +If the server cannot supply this value for a remote file being +retrieved, it will not be set. If input is from a pipe the value may +be incorrect and correspond simply to a full pipe buffer. + +@vindex ZFTP_COUNT +@item @t{ZFTP_COUNT} +The amount of data so far transferred; a number between zero and +@t{$ZFTP_SIZE}, if that is set. This number is always available. + +@end table + +@noindent +The function is initially called with @t{ZFTP_TRANSFER} set +appropriately and @t{ZFTP_COUNT} set to zero. After the transfer is +finished, the function will be called one more time with +@t{ZFTP_TRANSFER} set to @t{GF} or @t{PF}, in case it wishes to tidy +up. It is otherwise never called twice with the same value of +@t{ZFTP_COUNT}. + +@noindent +Sometimes the progress meter may cause disruption. It is up to the +user to decide whether the function should be defined and to use +@t{unfunction} when necessary. + +@end table + +@noindent + +@subsection Problems +@noindent +@cindex zftp, problems + +@noindent +A connection may not be opened in the left hand side of a pipe as this +occurs in a subshell and the file information is not updated in the main +shell. In the case of type or mode changes or closing the connection in a +subshell, the information is returned but variables are not updated until +the next call to @t{zftp}. Other status changes in subshells will not be +reflected by changes to the variables (but should be otherwise harmless). + +@noindent +Deleting sessions while a @t{zftp} command is active in the background can +have unexpected effects, even if it does not use the session being deleted. +This is because all shell subprocesses share information on the state of +all connections, and deleting a session changes the ordering of that +information. + +@noindent +On some operating systems, the control connection is not valid after a +fork(), so that operations in subshells, on the left hand side +of a pipeline, or in the background are not possible, as they should be. +This is presumably a bug in the operating system. +@c (avoiding a yodl bug) +@node The zsh/zle Module, The zsh/zleparameter Module, The zsh/zftp Module, Zsh Modules + +@section The zsh/zle Module +@noindent +@c Yodl file: Zsh/mod_zle.yo + +The @t{zsh/zle} module contains the Zsh Line Editor. See +@ref{Zsh Line Editor}. +@c (avoiding a yodl bug) +@node The zsh/zleparameter Module, The zsh/zprof Module, The zsh/zle Module, Zsh Modules + +@section The zsh/zleparameter Module +@noindent +@c Yodl file: Zsh/mod_zleparameter.yo + +@cindex parameters, special +The @t{zsh/zleparameter} module defines two special parameters that can be +used to access internal information of the Zsh Line Editor (see +@ref{Zsh Line Editor}). + +@noindent +@table @asis +@vindex keymaps +@item @t{keymaps} +This array contains the names of the keymaps currently defined. + +@vindex widgets +@item @t{widgets} +This associative array contains one entry per widget. The name +of the widget is the key and the value gives information about the +widget. It is either + the string `@t{builtin}' for builtin widgets, + a string of the form `@t{user:}@var{name}' for user-defined widgets, + where @var{name} is the name of the shell function implementing the widget, + a string of the form `@t{completion:}@var{type}@t{:}@var{name}' + for completion widgets, + or a null value if the widget is not yet fully defined. +In the penultimate case, @var{type} is the name of the builtin widget the +completion widget imitates in its behavior and @var{name} is the name +of the shell function implementing the completion widget. + +@end table +@c (avoiding a yodl bug) +@node The zsh/zprof Module, The zsh/zpty Module, The zsh/zleparameter Module, Zsh Modules + +@section The zsh/zprof Module +@noindent +@c Yodl file: Zsh/mod_zprof.yo + +@cindex functions, profiling +When loaded, the @t{zsh/zprof} causes shell functions to be profiled. +The profiling results can be obtained with the @t{zprof} +builtin command made available by this module. There is no way to turn +profiling off other than unloading the module. + +@noindent +@table @asis +@findex zprof +@item @t{zprof} [ @t{-c} ] +Without the @t{-c} option, @t{zprof} lists profiling results to +standard output. The format is comparable to that of commands like +@t{gprof}. + +@noindent +At the top there is a summary listing all functions that were called +at least once. This summary is sorted in decreasing order of the +amount of time spent in each. The lines contain +the number of the function in order, which is used in +other parts of the list in suffixes of the form +`@t{[}@var{num}@t{]}', then the number of calls made to the function. +The next three columns list the time in +milliseconds spent in the function and its descendants, the average +time in milliseconds spent in the function and its descendants per +call and the percentage of time spent in all shell functions used in +this function and its descendants. The following three columns give +the same information, but counting only the time spent in the function +itself. The final column shows the name of the function. + +@noindent +After the summary, detailed information about every function that was +invoked is listed, sorted in decreasing order of the amount of time spent +in each function and its descendants. Each of these entries consists of +descriptions for the functions that called the function described, the +function itself, and the functions that were called from it. The +description for the function itself has the same format as in the summary +(and shows the same information). The other lines don't show the number of +the function at the beginning and have their function named indented to +make it easier to distinguish the line showing the function described in +the section from the surrounding lines. + +@noindent +The information shown in this case is almost the same as in the summary, +but only refers to the call hierarchy being displayed. For example, for a +calling function the column showing the total running time lists the time +spent in the described function and its descendants only for the times when +it was called from that particular calling function. Likewise, for a +called function, this columns lists the total time spent in the called +function and its descendants only for the times when it was called from the +function described. + +@noindent +Also in this case, the column showing the number of calls to a function +also shows a slash and then the total number of invocations made to the +called function. + +@noindent +As long as the @t{zsh/zprof} module is loaded, profiling will be done and +multiple invocations of the @t{zprof} builtin command will show the +times and numbers of calls since the module was loaded. With the +@t{-c} option, the @t{zprof} builtin command will reset its internal +counters and will not show the listing. + +@end table +@c (avoiding a yodl bug) +@node The zsh/zpty Module, The zsh/zselect Module, The zsh/zprof Module, Zsh Modules + +@section The zsh/zpty Module +@noindent +@c Yodl file: Zsh/mod_zpty.yo + +The @t{zsh/zpty} module offers one builtin: + +@noindent +@table @asis +@findex zpty +@item @t{zpty} [ @t{-e} ] [ @t{-b} ] @var{name} [ @var{arg} ... ] +The arguments following @var{name} are concatenated with spaces between, +then executed as a command, as if passed to the @t{eval} builtin. The +command runs under a newly assigned pseudo-terminal; this is useful for +running commands non-interactively which expect an interactive +environment. The @var{name} is not part of the command, but is used to +refer to this command in later calls to @t{zpty}. + +@noindent +With the @t{-e} option, the pseudo-terminal is set up so that input +characters are echoed. + +@noindent +With the @t{-b} option, input to and output from the pseudo-terminal are +made non-blocking. + +@noindent +The shell parameter @t{REPLY} is set to the file descriptor assigned to +the master side of the pseudo-terminal. This allows the terminal to be +monitored with ZLE descriptor handlers (see @ref{Zle Builtins}) or manipulated with @t{sysread} and +@t{syswrite} (see @ref{The zsh/system Module}). @emph{Warning}: Use of @t{sysread} +and @t{syswrite} is @emph{not} recommended; use @t{zpty -r} and @t{zpty -w} +unless you know exactly what you are doing. + +@item @t{zpty} @t{-d} [ @var{name} ... ] +The second form, with the @t{-d} option, is used to delete commands +previously started, by supplying a list of their @var{name}s. If no +@var{name} is given, all commands are deleted. Deleting a command causes +the HUP signal to be sent to the corresponding process. + +@item @t{zpty} @t{-w} [ @t{-n} ] @var{name} [ @var{string} ... ] +The @t{-w} option can be used to send the to command @var{name} the given +@var{string}s as input (separated by spaces). If the @t{-n} option is +@emph{not} given, a newline is added at the end. + +@noindent +If no @var{string} is provided, the standard input is copied to the +pseudo-terminal; this may stop before copying the full input if the +pseudo-terminal is non-blocking. The exact input is always copied: +the @t{-n} option is not applied. + +@noindent +Note that the command under the pseudo-terminal sees this input as if it +were typed, so beware when sending special tty driver characters such as +word-erase, line-kill, and end-of-file. + +@item @t{zpty} @t{-r} [ @t{-mt} ] @var{name} [ @var{param} [ @var{pattern} ] ] +The @t{-r} option can be used to read the output of the command @var{name}. +With only a @var{name} argument, the output read is copied to the standard +output. Unless the pseudo-terminal is non-blocking, copying continues +until the command under the pseudo-terminal exits; when non-blocking, only +as much output as is immediately available is copied. The return status is +zero if any output is copied. + +@noindent +When also given a @var{param} argument, at most one line is read and stored +in the parameter named @var{param}. Less than a full line may be read if +the pseudo-terminal is non-blocking. The return status is zero if at least +one character is stored in @var{param}. + +@noindent +If a @var{pattern} is given as well, output is read until the whole string +read matches the @var{pattern}, even in the non-blocking case. The return +status is zero if the string read matches the pattern, or if the command +has exited but at least one character could still be read. If the option +@t{-m} is present, the return status is zero only if the pattern matches. +As of this writing, a maximum of one megabyte of output can be consumed +this way; if a full megabyte is read without matching the pattern, the +return status is non-zero. + +@noindent +In all cases, the return status is non-zero if nothing could be read, and +is @t{2} if this is because the command has finished. + +@noindent +If the @t{-r} option is combined with the @t{-t} option, @t{zpty} tests +whether output is available before trying to read. If no output is +available, @t{zpty} immediately returns the status @t{1}. When used +with a @var{pattern}, the behaviour on a failed poll is similar to +when the command has exited: the return value is zero if at least +one character could still be read even if the pattern failed to match. + +@item @t{zpty} @t{-t} @var{name} +The @t{-t} option without the @t{-r} option can be used to test +whether the command @var{name} is still running. It returns a zero +status if the command is running and a non-zero value otherwise. + +@item @t{zpty} [ @t{-L} ] +The last form, without any arguments, is used to list the commands +currently defined. If the @t{-L} option is given, this is done in the +form of calls to the @t{zpty} builtin. + +@end table +@c (avoiding a yodl bug) +@node The zsh/zselect Module, The zsh/zutil Module, The zsh/zpty Module, Zsh Modules + +@section The zsh/zselect Module +@noindent +@c Yodl file: Zsh/mod_zselect.yo + +The @t{zsh/zselect} module makes available one builtin command: + +@noindent +@table @asis +@findex zselect +@cindex select, system call +@cindex file descriptors, waiting for +@item @t{zselect} [ @t{-rwe} ] [ @t{-t} @var{timeout} ] [ @t{-a} @var{array} ] [ @t{-A} @var{assoc} ] [ @var{fd} ... ] +The @t{zselect} builtin is a front-end to the `select' system call, which +blocks until a file descriptor is ready for reading or writing, or has an +error condition, with an optional timeout. If this is not available on +your system, the command prints an error message and returns status 2 +(normal errors return status 1). For more information, see your system's +documentation for select(3). Note there is no connection with the +shell builtin of the same name. + +@noindent +Arguments and options may be intermingled in any order. Non-option +arguments are file descriptors, which must be decimal integers. By +default, file descriptors are to be tested for reading, i.e. @t{zselect} +will return when data is available to be read from the file descriptor, or +more precisely, when a read operation from the file descriptor will not +block. After a @t{-r}, @t{-w} and @t{-e}, the given file descriptors are +to be tested for reading, writing, or error conditions. These options and +an arbitrary list of file descriptors may be given in any order. + +@noindent +(The presence of an `error condition' is not well defined in the +documentation for many implementations of the select system call. +According to recent versions of the POSIX specification, it is really an +@emph{exception} condition, of which the only standard example is out-of-band +data received on a socket. So zsh users are unlikely to find the @t{-e} +option useful.) + +@noindent +The option `@t{-t} @var{timeout}' specifies a timeout in hundredths of a +second. This may be zero, in which case the file descriptors will simply +be polled and @t{zselect} will return immediately. It is possible to call +zselect with no file descriptors and a non-zero timeout for use as a +finer-grained replacement for `sleep'; note, however, the return status is +always 1 for a timeout. + +@noindent +The option `@t{-a} @var{array}' indicates that @var{array} should be set to +indicate the file descriptor(s) which are ready. If the option +is not +given, the array @t{reply} will be used for this purpose. The array will +contain a string similar to the arguments for @t{zselect}. For example, + +@noindent +@example +zselect -t 0 -r 0 -w 1 +@end example + +@noindent +might return immediately with status 0 and @t{$reply} containing `@t{-r 0 -w +1}' to show that both file descriptors are ready for the requested +operations. + +@noindent +The option `@t{-A} @var{assoc}' indicates that the associative array +@var{assoc} should be set to indicate the file descriptor(s) +which are ready. This option overrides the option @t{-a}, nor will +@t{reply} be modified. The keys of @t{assoc} are the file descriptors, and +the corresponding values are any of the characters `@t{rwe}' to indicate +the condition. + +@noindent +The command returns status 0 if some file descriptors are ready for +reading. If the operation timed out, or a timeout of 0 was given and no +file descriptors were ready, or there was an error, it returns status 1 and +the array will not be set (nor modified in any way). If there was an error +in the select operation the appropriate error message is printed. + +@end table +@c (avoiding a yodl bug) +@node The zsh/zutil Module, , The zsh/zselect Module, Zsh Modules + +@section The zsh/zutil Module +@noindent +@c Yodl file: Zsh/mod_zutil.yo + +@cindex builtins, utility +The @t{zsh/zutil} module only adds some builtins: + +@noindent +@table @asis +@findex zstyle +@item @t{zstyle} [ @t{-L} [ @var{metapattern} [ @var{style} ] ] ] +@itemx @t{zstyle} [ @t{-e} | @t{-} | @t{-}@t{-} ] @var{pattern} @var{style} @var{string} ... +@itemx @t{zstyle -d} [ @var{pattern} [ @var{style} ... ] ] +@itemx @t{zstyle -g} @var{name} [ @var{pattern} [ @var{style} ] ] +@itemx @t{zstyle -}@{@t{a}|@t{b}|@t{s}@} @var{context} @var{style} @var{name} [ @var{sep} ] +@itemx @t{zstyle -}@{@t{T}|@t{t}@} @var{context} @var{style} [ @var{string} ... ] +@itemx @t{zstyle -m} @var{context} @var{style} @var{pattern} +This builtin command is used to define and lookup styles. Styles are +pairs of names and values, where the values consist of any number of +strings. They are stored together with patterns and lookup is done by +giving a string, called the `@emph{context}', which is matched against the +patterns. The definition stored for the most specific pattern that matches +will be returned. + +@noindent +A pattern is considered to be more specific +than another if it contains more components (substrings separated by +colons) or if the patterns for the components are more specific, where +simple strings are considered to be more specific than patterns and +complex patterns are considered to be more specific than the pattern +`@t{*}'. A `@t{*}' in the pattern will match zero or more characters +in the context; colons are not treated specially in this regard. +If two patterns are equally specific, the tie is broken in favour of +the pattern that was defined first. + +@noindent +@emph{Example} +@kindex preferred-precipitation, example style +@findex weather, example function + +@noindent +For example, a fictional `@t{weather}' plugin might state in its documentation +that it looks up the @t{preferred-precipitation} style under the +`@t{:weather:}@var{continent}@t{:}@var{day-of-the-week}@t{:}@var{phase-of-the-moon}' context. +According to this, you might set the following in your @t{zshrc}: + +@noindent +@example +zstyle ':weather:europe:*' preferred-precipitation rain +zstyle ':weather:*:Sunday:*' preferred-precipitation snow +@end example + +@noindent +Then the plugin would run under the hood a command such as + +@noindent +@example +zstyle -s ":weather:$@{continent@}:$@{day_of_week@}:$@{moon_phase@}" preferred-precipitation REPLY +@end example + +@noindent +in order to retrieve your preference into the scalar variable @t{$REPLY}. +On Sundays @t{$REPLY} would be set to `@t{snow}'; in Europe it would be set +to `@t{rain}'; and on Sundays in Europe it would be set to `@t{snow}' again, +because the patterns `@t{:weather:europe:*}' and `@t{:weather:*:Sunday:*}' both +match the @var{context} argument to @t{zstyle -s}, are equally specific, and the +latter is more specific (because it has more colon-separated components). + +@noindent +@emph{Usage} + +@noindent +The forms that operate on patterns are the following. + +@noindent +@table @asis +@item @t{zstyle} [ @t{-L} [ @var{metapattern} [ @var{style} ] ] ] +Without arguments, lists style definitions. Styles +are shown in alphabetic order and patterns are shown in the order +@t{zstyle} will test them. + +@noindent +If the @t{-L} option is given, listing is done in the form of calls to +@t{zstyle}. The optional first argument, @var{metapattern}, is a pattern which +will be matched against the string supplied as @var{pattern} when the style was +defined. Note: +this means, for example, `@t{zstyle -L ":completion:*"}' will +match any supplied pattern beginning `@t{:completion:}', not +just @t{":completion:*"}: use @t{':completion:\*'} to match that. +The optional second argument limits the output to a specific @var{style} (not a +pattern). @t{-L} is not compatible with any other options. + +@item @t{zstyle} [ @t{-} | @t{-}@t{-} | @t{-e} ] @var{pattern} @var{style} @var{string} ... +@vindex reply, use of +Defines the given @var{style} for the @var{pattern} with the @var{string}s as +the value. If the @t{-e} option is given, the @var{string}s will be +concatenated (separated by spaces) and the resulting string will be +evaluated (in the same way as it is done by the @t{eval} builtin +command) when the style is looked up. In this case the parameter +`@t{reply}' must be assigned to set the strings returned after the +evaluation. Before evaluating the value, @t{reply} is unset, and +if it is still unset after the evaluation, the style is treated as if +it were not set. + +@item @t{zstyle -d} [ @var{pattern} [ @var{style} ... ] ] +Delete style definitions. Without arguments all definitions are deleted, +with a @var{pattern} all definitions for that pattern are deleted and if +any @var{style}s are given, then only those styles are deleted for the +@var{pattern}. + +@item @t{zstyle -g} @var{name} [ @var{pattern} [ @var{style} ] ] +Retrieve a style definition. The @var{name} is +used as the name of an array in which the results are stored. Without +any further arguments, all patterns defined are returned. With a +@var{pattern} the styles defined for that pattern are returned and with +both a @var{pattern} and a @var{style}, the value strings of that +combination is returned. + +@end table + +@noindent +The other forms can be used to look up or test styles for a given context. + +@noindent +@table @asis +@item @t{zstyle -s} @var{context} @var{style} @var{name} [ @var{sep} ] +The parameter @var{name} is set to the value of the style interpreted as a +string. If the value contains several strings they are concatenated with +spaces (or with the @var{sep} string if that is given) between them. + +@noindent +Return @t{0} if the style is set, @t{1} otherwise. + +@item @t{zstyle -b} @var{context} @var{style} @var{name} +The value is stored in @var{name} as a boolean, i.e. as the string +`@t{yes}' if the value has only one string and that string is equal to one +of `@t{yes}', `@t{true}', `@t{on}', or `@t{1}'. If the value is any other +string or has more than one string, the parameter is set to `@t{no}'. + +@noindent +Return @t{0} if @var{name} is set to `@t{yes}', @t{1} otherwise. + +@item @t{zstyle -a} @var{context} @var{style} @var{name} +The value is stored in @var{name} as an array. If @var{name} is declared +as an associative array, the first, third, etc. strings are used as the +keys and the other strings are used as the values. + +@noindent +Return @t{0} if the style is set, @t{1} otherwise. + +@item @t{zstyle -t} @var{context} @var{style} [ @var{string} ... ] +@itemx @t{zstyle -T} @var{context} @var{style} [ @var{string} ... ] +Test the value of a style, i.e. the @t{-t} option only returns a status +(sets @t{$?}). Without any @var{string} the return status is zero if the +style is defined for at least one matching pattern, has only one string in +its value, and that is equal to one of `@t{true}', `@t{yes}', `@t{on}' or +`@t{1}'. If any @var{string}s are given the status is zero if and only if +at least one of the @var{string}s is equal to at least one of the strings +in the value. If the style is defined but doesn't match, the return status +is @t{1}. If the style is not defined, the status is @t{2}. + +@noindent +The @t{-T} option tests the values of the style like @t{-t}, but it +returns status zero (rather than @t{2}) if the style is not defined for any +matching pattern. + +@item @t{zstyle -m} @var{context} @var{style} @var{pattern} +Match a value. Returns status zero if the +@var{pattern} matches at least one of the strings in the value. + +@end table + +@findex zformat +@item @t{zformat -f} @var{param} @var{format} @var{spec} ... +@itemx @t{zformat -F} @var{param} @var{format} @var{spec} ... +@itemx @t{zformat -a} @var{array} @var{sep} @var{spec} ... +This builtin provides different forms of formatting. The first form +is selected with the @t{-f} option. In this case the @var{format} +string will be modified by replacing sequences starting with a percent +sign in it with strings from the @var{spec}s. Each @var{spec} should be +of the form `@var{char}@t{:}@var{string}' which will cause every +appearance of the sequence `@t{%}@var{char}' in @var{format} to be replaced +by the @var{string}. The `@t{%}' sequence may also contain optional +minimum and maximum field width specifications between the `@t{%}' and +the `@var{char}' in the form `@t{%}@var{min}@t{.}@var{max}@t{c}', +i.e. the minimum field width is given first and if the maximum field +width is used, it has to be preceded by a dot. Specifying a minimum field +width makes the result be padded with spaces to the right if the +@var{string} is shorter than the requested width. Padding to the left +can be achieved by giving a negative minimum field width. If a maximum +field width is specified, the @var{string} will be truncated after that +many characters. After all `@t{%}' sequences for the given @var{spec}s +have been processed, the resulting string is stored in the parameter +@var{param}. + +@noindent +The @t{%}-escapes also understand ternary expressions in the form used by +prompts. The @t{%} is followed by a `@t{(}' and then an ordinary +format specifier character as described above. There may be a set of +digits either before or after the `@t{(}'; these specify a test +number, which defaults to zero. Negative numbers are also allowed. An +arbitrary delimiter character follows the format specifier, which is +followed by a piece of `true' text, the delimiter character again, a piece +of `false' text, and a closing parenthesis. The complete expression +(without the digits) thus looks like +`@t{%(}@var{X}@t{.}@var{text1}@t{.}@var{text2}@t{)}', except that +the `@t{.}' character is arbitrary. The value given for the format +specifier in the @var{char}@t{:}@var{string} expressions is evaluated as a +mathematical expression, and compared with the test number. If they are +the same, @var{text1} is output, else @var{text2} is output. A parenthesis +may be escaped in @var{text2} as @t{%)}. Either of @var{text1} or +@var{text2} may contain nested @t{%}-escapes. + +@noindent +For example: + +@noindent +@example +zformat -f REPLY "The answer is '%3(c.yes.no)'." c:3 +@end example + +@noindent +outputs "The answer is 'yes'." to @t{REPLY} since the value for the format +specifier @t{c} is 3, agreeing with the digit argument to the ternary +expression. + +@noindent +With @t{-F} instead of @t{-f}, ternary expressions choose between the +`true' or `false' text on the basis of whether the format specifier is +present and non-empty. A test number indicates a minimum width for the +value given in the format specifier. Negative numbers reverse this, +so the test is for whether the value exceeds a maximum width. + +@noindent +The form, using the @t{-a} option, can be used for aligning +strings. Here, the @var{spec}s are of the form +`@var{left}@t{:}@var{right}' where `@var{left}' and `@var{right}' are +arbitrary strings. These strings are modified by replacing the colons +by the @var{sep} string and padding the @var{left} strings with spaces +to the right so that the @var{sep} strings in the result (and hence the +@var{right} strings after them) are all aligned if the strings are +printed below each other. All strings without a colon are left +unchanged and all strings with an empty @var{right} string have the +trailing colon removed. In both cases the lengths of the strings +are not used to determine how the other strings are to be aligned. +A colon in the @var{left} string can be escaped with a backslash. +The resulting strings are stored in the @var{array}. + +@findex zregexparse +@item @t{zregexparse} +This implements some internals of the @t{_regex_arguments} function. + +@findex zparseopts +@item @t{zparseopts} [ @t{-D} @t{-E} @t{-F} @t{-K} @t{-M} ] [ @t{-a} @var{array} ] [ @t{-A} @var{assoc} ] [ @t{-} ] @var{spec} ... +This builtin simplifies the parsing of options in positional parameters, +i.e. the set of arguments given by @t{$*}. Each @var{spec} describes one +option and must be of the form `@var{opt}[@t{=}@var{array}]'. If an option +described by @var{opt} is found in the positional parameters it is copied +into the @var{array} specified with the @t{-a} option; if the optional +`@t{=}@var{array}' is given, it is instead copied into that array, which +should be declared as a normal array and never as an associative array. + +@noindent +Note that it is an error to give any @var{spec} without an +`@t{=}@var{array}' unless one of the @t{-a} or @t{-A} options is used. + +@noindent +Unless the @t{-E} option is given, parsing stops at the first string +that isn't described by one of the @var{spec}s. Even with @t{-E}, +parsing always stops at a positional parameter equal to `@t{-}' or +`@t{-}@t{-}'. See also @t{-F}. + +@noindent +The @var{opt} description must be one of the following. Any of the special +characters can appear in the option name provided it is preceded by a +backslash. + +@noindent +@table @asis +@item @var{name} +@itemx @var{name}@t{+} +The @var{name} is the name of the option without the leading `@t{-}'. To +specify a GNU-style long option, one of the usual two leading `@t{-}' must +be included in @var{name}; for example, a `@t{-}@t{-file}' option is +represented by a @var{name} of `@t{-file}'. + +@noindent +If a `@t{+}' appears after @var{name}, the option is appended to @var{array} +each time it is found in the positional parameters; without the `@t{+}' +only the @emph{last} occurrence of the option is preserved. + +@noindent +If one of these forms is used, the option takes no argument, so parsing +stops if the next positional parameter does not also begin with `@t{-}' +(unless the @t{-E} option is used). + +@item @var{name}@t{:} +@itemx @var{name}@t{:-} +@itemx @var{name}@t{::} +If one or two colons are given, the option takes an argument; with one +colon, the argument is mandatory and with two colons it is optional. The +argument is appended to the @var{array} after the option itself. + +@noindent +An optional argument is put into the same array element as the option name +(note that this makes empty strings as arguments indistinguishable). A +mandatory argument is added as a separate element unless the `@t{:-}' form +is used, in which case the argument is put into the same element. + +@noindent +A `@t{+}' as described above may appear between the @var{name} and the +first colon. + +@end table + +@noindent +In all cases, option-arguments must appear either immediately following the +option in the same positional parameter or in the next one. Even an optional +argument may appear in the next parameter, unless it begins with a `@t{-}'. +There is no special handling of `@t{=}' as with GNU-style argument parsers; +given the @var{spec} `@t{-foo:}', the positional parameter `@t{-}@t{-foo=bar}' +is parsed as `@t{-}@t{-foo}' with an argument of `@t{=bar}'. + +@noindent +When the names of two options that take no arguments overlap, the longest one +wins, so that parsing for the @var{spec}s `@t{-foo -foobar}' (for example) is +unambiguous. However, due to the aforementioned handling of option-arguments, +ambiguities may arise when at least one overlapping @var{spec} takes an +argument, as in `@t{-foo: -foobar}'. In that case, the last matching +@var{spec} wins. + +@noindent +The options of @t{zparseopts} itself cannot be stacked because, for +example, the stack `@t{-DEK}' is indistinguishable from a @var{spec} for +the GNU-style long option `@t{-}@t{-DEK}'. The options of @t{zparseopts} +itself are: + +@noindent +@table @asis +@item @t{-a} @var{array} +As described above, this names the default array in which to store the +recognised options. + +@item @t{-A} @var{assoc} +If this is given, the options and their values are also put into an +associative array with the option names as keys and the arguments (if any) +as the values. + +@item @t{-D} +If this option is given, all options found are removed from the positional +parameters of the calling shell or shell function, up to but not including +any not described by the @var{spec}s. If the first such parameter is `@t{-}' +or `@t{-}@t{-}', it is removed as well. This is similar to using the +@t{shift} builtin. + +@item @t{-E} +This changes the parsing rules to @emph{not} stop at the first string +that isn't described by one of the @var{spec}s. It can be used to test +for or (if used together with @t{-D}) extract options and their +arguments, ignoring all other options and arguments that may be in the +positional parameters. As indicated above, parsing still stops at the +first `@t{-}' or `@t{-}@t{-}' not described by a @var{spec}, but it is not +removed when used with @t{-D}. + +@item @t{-F} +If this option is given, @t{zparseopts} immediately stops at the first +option-like parameter not described by one of the @var{spec}s, prints an +error message, and returns status 1. Removal (@t{-D}) and extraction +(@t{-E}) are not performed, and option arrays are not updated. This +provides basic validation for the given options. + +@noindent +Note that the appearance in the positional parameters of an option without +its required argument always aborts parsing and returns an error as described +above regardless of whether this option is used. + +@item @t{-K} +With this option, the arrays specified with the @t{-a} option and with the +`@t{=}@var{array}' forms are kept unchanged when none of the @var{spec}s for +them is used. Otherwise the entire array is replaced when any of the +@var{spec}s is used. Individual elements of associative arrays specified +with the @t{-A} option are preserved by @t{-K}. This allows assignment of +default values to arrays before calling @t{zparseopts}. + +@item @t{-M} +This changes the assignment rules to implement a map among equivalent +option names. If any @var{spec} uses the `@t{=}@var{array}' form, the +string @var{array} is interpreted as the name of another @var{spec}, +which is used to choose where to store the values. If no other @var{spec} +is found, the values are stored as usual. This changes only the way the +values are stored, not the way @t{$*} is parsed, so results may be +unpredictable if the `@var{name}@t{+}' specifier is used inconsistently. + +@end table + +@noindent +For example, + +@noindent +@example +set -- -a -bx -c y -cz baz -cend +zparseopts a=foo b:=bar c+:=bar +@end example + +@noindent +will have the effect of + +@noindent +@example +foo=(-a) +bar=(-b x -c y -c z) +@end example + +@noindent +The arguments from `@t{baz}' on will not be used. + +@noindent +As an example for the @t{-E} option, consider: + +@noindent +@example +set -- -a x -b y -c z arg1 arg2 +zparseopts -E -D b:=bar +@end example + +@noindent +will have the effect of + +@noindent +@example +bar=(-b y) +set -- -a x -c z arg1 arg2 +@end example + +@noindent +I.e., the option @t{-b} and its arguments are taken from the +positional parameters and put into the array @t{bar}. + +@noindent +The @t{-M} option can be used like this: + +@noindent +@example +set -- -a -bx -c y -cz baz -cend +zparseopts -A bar -M a=foo b+: c:=b +@end example + +@noindent +to have the effect of + +@noindent +@example +foo=(-a) +bar=(-a @value{dsq} -b xyz) +@end example + +@end table +@c (avoiding a yodl bug) +@c (avoiding a yodl bug) +@c (avoiding a yodl bug) +@c Yodl file: Zsh/calsys.yo +@node Calendar Function System, TCP Function System, Zsh Modules, Top + +@chapter Calendar Function System +@noindent +@cindex calendar function system +@cindex zsh/datetime, function system based on + +@section Description +@noindent + +@noindent +The shell is supplied with a series of functions to replace and enhance the +traditional Unix @t{calendar} programme, which warns the user of imminent +or future events, details of which are stored in a text file (typically +@t{calendar} in the user's home directory). The version provided here +includes a mechanism for alerting the user when an event is due. + +@noindent +In addition functions @t{age}, @t{before} and @t{after} are provided +that can be used in a glob qualifier; they allow files to be selected +based on their modification times. + +@noindent +The format of the @t{calendar} file and the dates used there in and in +the @t{age} function are described first, then the functions that can +be called to examine and modify the @t{calendar} file. + +@noindent +The functions here depend on the availability of the @t{zsh/datetime} +module which is usually installed with the shell. The library function +@t{strptime()} must be available; it is present on most recent +operating systems. + +@noindent +@menu +* Calendar File and Date Formats:: +* Calendar System User Functions:: +* Calendar Styles:: +* Calendar Utility Functions:: +* Calendar Bugs:: +@end menu + +@noindent +@node Calendar File and Date Formats, Calendar System User Functions, , Calendar Function System + +@section File and Date Formats +@noindent + +@noindent + +@subsection Calendar File Format +@noindent + +@noindent +The calendar file is by default @t{~/calendar}. This can be configured +by the @t{calendar-file} style, see +@ref{Calendar Styles}. The basic format consists +of a series of separate lines, with no indentation, each including +a date and time specification followed by a description of the event. + +@noindent +Various enhancements to this format are supported, based on the syntax +of Emacs calendar mode. An indented line indicates a continuation line +that continues the description of the event from the preceding line +(note the date may not be continued in this way). An initial ampersand +(@t{&}) is ignored for compatibility. + +@noindent +An indented line on which the first non-whitespace character is @t{#} +is not displayed with the calendar entry, but is still scanned for +information. This can be used to hide information useful to the +calendar system but not to the user, such as the unique identifier +used by @t{calendar_add}. + +@noindent +The Emacs extension that a date with no description may refer to a number +of succeeding events at different times is not supported. + +@noindent +Unless the @t{done-file} style has been altered, any events which +have been processed are appended to the file with the same name as the +calendar file with the suffix @t{.done}, hence @t{~/calendar.done} by +default. + +@noindent +An example is shown below. + +@noindent + +@subsection Date Format +@noindent + +@noindent +The format of the date and time is designed to allow flexibility without +admitting ambiguity. (The words `date' and `time' are both used in the +documentation below; except where specifically noted this implies a string +that may include both a date and a time specification.) Note that there is +no localization support; month and day names must be in English and +separator characters are fixed. Matching is case insensitive, and only the +first three letters of the names are significant, although as a special +case a form beginning "month" does not match "Monday". Furthermore, time +zones are not handled; all times are assumed to be local. + +@noindent +It is recommended that, rather than exploring the intricacies of the +system, users find a date format that is natural to them and stick to it. +This will avoid unexpected effects. Various key facts should be noted. + +@noindent +@itemize @bullet + +@item +In particular, note the confusion between +@var{month}@t{/}@var{day}@t{/}@var{year} and +@var{day}@t{/}@var{month}@t{/}@var{year} when the month is numeric; these +formats should be avoided if at all possible. Many alternatives are +available. +@item +The year must be given in full to avoid confusion, and only years +from 1900 to 2099 inclusive are matched. +@end itemize + +@noindent +The following give some obvious examples; users finding here +a format they like and not subject to vagaries of style may skip +the full description. As dates and times are matched separately +(even though the time may be embedded in the date), any date format +may be mixed with any format for the time of day provide the +separators are clear (whitespace, colons, commas). + +@noindent +@example +2007/04/03 13:13 +2007/04/03:13:13 +2007/04/03 1:13 pm +3rd April 2007, 13:13 +April 3rd 2007 1:13 p.m. +Apr 3, 2007 13:13 +Tue Apr 03 13:13:00 2007 +13:13 2007/apr/3 +@end example + +@noindent +More detailed rules follow. + +@noindent +Times are parsed and extracted before dates. They must use colons +to separate hours and minutes, though a dot is allowed before seconds +if they are present. This limits time formats to the following: + +@noindent +@itemize @bullet + +@item +@var{HH}@t{:}@var{MM}[@t{:}@var{SS}[@t{.}@var{FFFFF}]] [@t{am}|@t{pm}|@t{a.m.}|@t{p.m.}] +@item +@var{HH}@t{:}@var{MM}@t{.}@var{SS}[@t{.}@var{FFFFF}] [@t{am}|@t{pm}|@t{a.m.}|@t{p.m.}] +@end itemize + +@noindent +Here, square brackets indicate optional elements, possibly with +alternatives. Fractions of a second are recognised but ignored. For +absolute times (the normal format require by the @t{calendar} file and the +@t{age}, @t{before} and @t{after} functions) a date is mandatory but a +time of day is not; the time returned is at the start of the date. One +variation is allowed: if @t{a.m.} or @t{p.m.} or one of their variants +is present, an hour without a minute is allowed, e.g. @t{3 p.m.}. + +@noindent +Time zones are not handled, though if one is matched following a time +specification it will be removed to allow a surrounding date to be +parsed. This only happens if the format of the timezone is not too +unusual. The following are examples of forms that are understood: + +@noindent +@example ++0100 +GMT +GMT-7 +CET+1CDT +@end example + +@noindent +Any part of the timezone that is not numeric must have exactly three +capital letters in the name. + +@noindent +Dates suffer from the ambiguity between @var{DD}@t{/}@var{MM}@t{/}@var{YYYY} +and @var{MM}@t{/}@var{DD}@t{/}@var{YYYY}. It is recommended this form is +avoided with purely numeric dates, but use of ordinals, +eg. @t{3rd/04/2007}, will resolve the ambiguity as the ordinal is always +parsed as the day of the month. Years must be four digits (and the first +two must be @t{19} or @t{20}); @t{03/04/08} is not recognised. Other +numbers may have leading zeroes, but they are not required. The following +are handled: + +@noindent +@itemize @bullet + +@item +@var{YYYY}@t{/}@var{MM}@t{/}@var{DD} +@item +@var{YYYY}@t{-}@var{MM}@t{-}@var{DD} +@item +@var{YYYY}@t{/}@var{MNM}@t{/}@var{DD} +@item +@var{YYYY}@t{-}@var{MNM}@t{-}@var{DD} +@item +@var{DD}[@t{th}|@t{st}|@t{rd}] @var{MNM}[@t{,}] [ @var{YYYY} ] +@item +@var{MNM} @var{DD}[@t{th}|@t{st}|@t{rd}][@t{,}] [ @var{YYYY} ] +@item +@var{DD}[@t{th}|@t{st}|@t{rd}]@t{/}@var{MM}[@t{,}] @var{YYYY} +@item +@var{DD}[@t{th}|@t{st}|@t{rd}]@t{/}@var{MM}@t{/}@var{YYYY} +@item +@var{MM}@t{/}@var{DD}[@t{th}|@t{st}|@t{rd}][@t{,}] @var{YYYY} +@item +@var{MM}@t{/}@var{DD}[@t{th}|@t{st}|@t{rd}]@t{/}@var{YYYY} +@end itemize + +@noindent +Here, @var{MNM} is at least the first three letters of a month name, +matched case-insensitively. The remainder of the month name may appear but +its contents are irrelevant, so janissary, febrile, martial, apricot, +maybe, junta, etc. are happily handled. + +@noindent +Where the year is shown as optional, the current year is assumed. There +are only two such cases, the form @t{Jun 20} or @t{14 September} (the only +two commonly occurring forms, apart from a "the" in some forms of English, +which isn't currently supported). Such dates will of course become +ambiguous in the future, so should ideally be avoided. + +@noindent +Times may follow dates with a colon, e.g. @t{1965/07/12:09:45}; this is in +order to provide a format with no whitespace. A comma and whitespace are +allowed, e.g. @t{1965/07/12, 09:45}. Currently the order of these +separators is not checked, so illogical formats such as @t{1965/07/12, : +,09:45} will also be matched. For simplicity such variations are not shown +in the list above. Otherwise, a time is only recognised as being +associated with a date if there is only whitespace in between, or if the +time was embedded in the date. + +@noindent +Days of the week are not normally scanned, but will be ignored if they +occur at the start of the date pattern only. However, in contexts where it +is useful to specify dates relative to today, days of the week with no +other date specification may be given. The day is assumed to be either +today or within the past week. Likewise, the words @t{yesterday}, +@t{today} and @t{tomorrow} are handled. All matches are case-insensitive. +Hence if today is Monday, then @t{Sunday} is equivalent to @t{yesterday}, +@t{Monday} is equivalent to @t{today}, but @t{Tuesday} gives a date six +days ago. This is not generally useful within the calendar file. +Dates in this format may be combined with a time specification; for +example @t{Tomorrow, 8 p.m.}. + +@noindent +For example, the standard date format: + +@noindent +@example +Fri Aug 18 17:00:48 BST 2006 +@end example + +@noindent +is handled by matching @var{HH}@t{:}@var{MM}@t{:}@var{SS} and removing it +together with the matched (but unused) time zone. This leaves the following: + +@noindent +@example +Fri Aug 18 2006 +@end example + +@noindent +@t{Fri} is ignored and the rest is matched according to the standard rules. + +@noindent + +@subsection Relative Time Format +@noindent + +@noindent +In certain places relative times are handled. Here, a date is not allowed; +instead a combination of various supported periods are allowed, together +with an optional time. The periods must be in order from most to +least significant. + +@noindent +In some cases, a more accurate calculation is possible when there is an +anchor date: offsets of months or years pick the correct day, rather than +being rounded, and it is possible to pick a particular day in a month as +`(1st Friday)', etc., as described in more detail below. + +@noindent +Anchors are available in the following cases. If one or two times are +passed to the function @t{calendar}, the start time acts an anchor for the +end time when the end time is relative (even if the start time is +implicit). When examining calendar files, the scheduled event being +examined anchors the warning time when it is given explicitly by means of +the @t{WARN} keyword; likewise, the scheduled event anchors a repetition +period when given by the @t{RPT} keyword, so that specifications such as +@t{RPT 2 months, 3rd Thursday} are handled properly. Finally, the @t{-R} +argument to @t{calendar_scandate} directly provides an anchor for relative +calculations. + +@noindent +The periods handled, with possible abbreviations are: + +@noindent +@table @asis +@item Years +@t{years}, @t{yrs}, @t{ys}, @t{year}, @t{yr}, @t{y}, @t{yearly}. +A year is 365.25 days unless there is an anchor. + +@item Months +@t{months}, @t{mons}, @t{mnths}, @t{mths}, @t{month}, @t{mon}, +@t{mnth}, @t{mth}, @t{monthly}. Note that @t{m}, @t{ms}, @t{mn}, @t{mns} +are ambiguous and are @emph{not} handled. A month is a period +of 30 days rather than a calendar month unless there is an anchor. + +@item Weeks +@t{weeks}, @t{wks}, @t{ws}, @t{week}, @t{wk}, @t{w}, @t{weekly} + +@item Days +@t{days}, @t{dys}, @t{ds}, @t{day}, @t{dy}, @t{d}, @t{daily} + +@item Hours +@t{hours}, @t{hrs}, @t{hs}, @t{hour}, @t{hr}, @t{h}, @t{hourly} + +@item Minutes +@t{minutes}, @t{mins}, @t{minute}, @t{min}, but @emph{not} @t{m}, +@t{ms}, @t{mn} or @t{mns} + +@item Seconds +@t{seconds}, @t{secs}, @t{ss}, @t{second}, @t{sec}, @t{s} + +@end table + +@noindent +Spaces between the numbers are optional, but are required between items, +although a comma may be used (with or without spaces). + +@noindent +The forms @t{yearly} to @t{hourly} allow the number to be omitted; it is +assumed to be 1. For example, @t{1 d} and @t{daily} are equivalent. Note +that using those forms with plurals is confusing; @t{2 yearly} is the same +as @t{2 years}, @emph{not} twice yearly, so it is recommended they only +be used without numbers. + +@noindent +When an anchor time is present, there is an extension to handle regular +events in the form of the @var{n}th @var{some}day of the month. Such a +specification must occur immediately after any year and month +specification, but before any time of day, and must be in the form +@var{n}(@t{th}|@t{st}|@t{rd}) @var{day}, for example @t{1st Tuesday} or +@t{3rd Monday}. As in other places, days are matched case insensitively, +must be in English, and only the first three letters are significant except +that a form beginning `month' does not match `Monday'. No attempt is made +to sanitize the resulting date; attempts to squeeze too many occurrences +into a month will push the day into the next month (but in the obvious +fashion, retaining the correct day of the week). + +@noindent +Here are some examples: + +@noindent +@example +30 years 3 months 4 days 3:42:41 +14 days 5 hours +Monthly, 3rd Thursday +4d,10hr +@end example + +@noindent + +@subsection Example +@noindent + +@noindent +Here is an example calendar file. It uses a consistent date format, +as recommended above. + +@noindent +@example +Feb 1, 2006 14:30 Pointless bureaucratic meeting +Mar 27, 2006 11:00 Mutual recrimination and finger pointing + Bring water pistol and waterproofs +Mar 31, 2006 14:00 Very serious managerial pontification + # UID 12C7878A9A50 +Apr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins +May 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday +@end example + +@noindent +The second entry has a continuation line. The third entry has a +continuation line that will not be shown when the entry is displayed, but +the unique identifier will be used by the @t{calendar_add} function when +updating the event. The fourth entry will produce a warning 30 minutes +before the event (to allow you to equip yourself appropriately). The fifth +entry repeats after a month on the 3rd Thursday, i.e. June 15, 2006, at the +same time. + +@noindent +@node Calendar System User Functions, Calendar Styles, Calendar File and Date Formats, Calendar Function System + +@section User Functions +@noindent + +@noindent +This section describes functions that are designed to be called +directly by the user. The first part describes those functions +associated with the user's calendar; the second part describes +the use in glob qualifiers. + +@noindent + +@subsection Calendar system functions +@noindent + +@noindent +@table @asis +@findex calendar + +@item @t{calendar }[ @t{-abdDsv} ] [ @t{-C} @var{calfile} ] [ @t{-n} @var{num} ] [ @t{-S} @var{showprog} ] +@itemx @t{@ @ @ @ @ @ @ @ @ }[ [ @var{start} ] @var{end} ] +@itemx @t{calendar -r} [ @t{-abdDrsv} ] [ @t{-C} @var{calfile} ] [ @t{-n} @var{num} ] [ @t{-S} @var{showprog} ] +@itemx @t{@ @ @ @ @ @ @ @ @ }[ @var{start} ] +Show events in the calendar. + +@noindent +With no arguments, show events from the start of today until the end of +the next working day after today. In other words, if today is Friday, +Saturday, or Sunday, show up to the end of the following Monday, otherwise +show today and tomorrow. + +@noindent +If @var{end} is given, show events from the start of today up to the time +and date given, which is in the format described in the previous section. +Note that if this is a date the time is assumed to be midnight at the +start of the date, so that effectively this shows all events before +the given date. + +@noindent +@var{end} may start with a @t{+}, in which case the remainder of the +specification is a relative time format as described in the previous +section indicating the range of time from the start time that is to +be included. + +@noindent +If @var{start} is also given, show events starting from that time and date. +The word @t{now} can be used to indicate the current time. + +@noindent +To implement an alert when events are due, include @t{calendar -s} in your +@t{~/.zshrc} file. + +@noindent +Options: + +@noindent +@table @asis +@item @t{-a} +Show all items in the calendar, regardless of the @t{start} and +@t{end}. + +@item @t{-b} +Brief: don't display continuation lines (i.e. indented lines following +the line with the date/time), just the first line. + +@item @t{-B} @var{lines} +Brief: display at most the first @var{lines} lines of the calendar +entry. `@t{-B 1}' is equivalent to `@t{-b}'. + +@item @t{-C} @var{calfile} +Explicitly specify a calendar file instead of the value of +the @t{calendar-file} style or the default @t{~/calendar}. + +@item @t{-d} +Move any events that have passed from the calendar file to the +"done" file, as given by the @t{done-file} style or the default +which is the calendar file with @t{.done} appended. This option +is implied by the @t{-s} option. + +@item @t{-D} +Turns off the option @t{-d}, even if the @t{-s} option is also present. + +@item @t{-n} @var{num}, @t{-}@var{num} +Show at least @var{num} events, if present in the calendar file, regardless +of the @t{start} and @t{end}. + +@item @t{-r} +Show all the remaining options in the calendar, ignoring the given @var{end} +time. The @var{start} time is respected; any argument given is treated +as a @var{start} time. + +@item @t{-s} +Use the shell's @t{sched} command to schedule a timed event that +will warn the user when an event is due. Note that the @t{sched} command +only runs if the shell is at an interactive prompt; a foreground task +blocks the scheduled task from running until it is finished. + +@noindent +The timed event usually runs the programme @t{calendar_show} to show +the event, as described in +@ref{Calendar Utility Functions}. + +@noindent +By default, a warning of the event is shown five minutes before it is due. +The warning period can be configured by the style @t{warn-time} or +for a single calendar entry by including @t{WARN} @var{reltime} in the first +line of the entry, where @var{reltime} is one of the usual relative time +formats. + +@noindent +A repeated event may be indicated by including @t{RPT} @var{reldate} in the +first line of the entry. After the scheduled event has been displayed +it will be re-entered into the calendar file at a time @var{reldate} +after the existing event. Note that this is currently the only use +made of the repeat count, so that it is not possible to query the schedule +for a recurrence of an event in the calendar until the previous event +has passed. + +@noindent +If @t{RPT} is used, it is also possible to specify that certain +recurrences of an event are rescheduled or cancelled. This is +done with the @t{OCCURRENCE} keyword, followed by whitespace and the +date and time of the occurrence in the regular sequence, followed by +whitespace and either the date and time of the rescheduled event or +the exact string @t{CANCELLED}. In this case the date and time must +be in exactly the "date with local time" format used by the +@t{text/calendar} MIME type (RFC 2445), +@var{<YYYY><MM><DD>}@t{T}@var{<hh><mm><ss>} (note the presence of the literal +character @t{T}). The first word (the regular recurrence) may be +something other than a proper date/time to indicate that the event +is additional to the normal sequence; a convention that retains +the formatting appearance is @t{XXXXXXXXTXXXXXX}. + +@noindent +Furthermore, it is useful to record the next regular recurrence +(as then the displayed date may be for a rescheduled event so cannot +be used for calculating the regular sequence). This is specified by +@t{RECURRENCE} and a time or date in the same format. @t{calendar_add} +adds such an indication when it encounters a recurring event that does not +include one, based on the headline date/time. + +@noindent +If @t{calendar_add} is used to update occurrences the @t{UID} keyword +described there should be present in both the existing entry and the added +occurrence in order to identify recurring event sequences. + +@noindent +For example, + +@noindent +@example +Thu May 6, 2010 11:00 Informal chat RPT 1 week + # RECURRENCE 20100506T110000 + # OCCURRENCE 20100513T110000 20100513T120000 + # OCCURRENCE 20100520T110000 CANCELLED +@end example + +@noindent +The event that occurs at 11:00 on 13th May 2010 is rescheduled an hour +later. The event that occurs a week later is cancelled. The occurrences +are given on a continuation line starting with a @t{#} character so will +not usually be displayed as part of the event. As elsewhere, no account of +time zones is taken with the times. After the next event occurs the headline +date/time will be `@t{Thu May 13, 2010 12:00}' while the @t{RECURRENCE} +date/time will be `@t{20100513T110000}' (note that cancelled and +moved events are not taken account of in the @t{RECURRENCE}, which +records what the next regular recurrence is, but they are accounted for in +the headline date/time). + +@noindent +It is safe to run @t{calendar -s} to reschedule an existing event +(if the calendar file has changed, for example), and also to have it +running in multiples instances of the shell since the calendar file +is locked when in use. + +@noindent +By default, expired events are moved to the "done" file; see the @t{-d} +option. Use @t{-D} to prevent this. + +@item @t{-S} @var{showprog} +Explicitly specify a programme to be used for showing events instead +of the value of the @t{show-prog} style or the default @t{calendar_show}. + +@item @t{-v} +Verbose: show more information about stages of processing. This +is useful for confirming that the function has successfully parsed +the dates in the calendar file. + +@end table + +@findex calendar_add +@item @t{calendar_add} [ @t{-BL} ] @var{event} ... +Adds a single event to the calendar in the appropriate location. +The event can contain multiple lines, as described in +@ref{Calendar File and Date Formats}. +Using this function ensures that the calendar file is sorted in date +and time order. It also makes special arrangements for locking +the file while it is altered. The old calendar is left in a file +with the suffix @t{.old}. + +@noindent +The option @t{-B} indicates that backing up the calendar file will be +handled by the caller and should not be performed by @t{calendar_add}. The +option @t{-L} indicates that @t{calendar_add} does not need to lock the +calendar file as it is already locked. These options will not usually be +needed by users. + +@noindent +If the style @t{reformat-date} is true, the date and time of the +new entry will be rewritten into the standard date format: see +the descriptions of this style and the style @t{date-format}. + +@noindent +The function can use a unique identifier stored with each event to ensure +that updates to existing events are treated correctly. The entry +should contain the word @t{UID}, followed by whitespace, followed by +a word consisting entirely of hexadecimal digits of arbitrary length +(all digits are significant, including leading zeroes). As the UID +is not directly useful to the user, it is convenient to hide it on +an indented continuation line starting with a @t{#}, for example: + +@noindent +@example +Aug 31, 2007 09:30 Celebrate the end of the holidays + # UID 045B78A0 +@end example + +@noindent +The second line will not be shown by the @t{calendar} function. + +@noindent +It is possible to specify the @t{RPT} keyword followed by @t{CANCELLED} +instead of a relative time. This causes any matched event or series +of events to be cancelled (the original event does not have to be marked +as recurring in order to be cancelled by this method). A @t{UID} is +required in order to match an existing event in the calendar. + +@noindent +@t{calendar_add} will attempt to manage recurrences and occurrences of +repeating events as described for event scheduling by @t{calendar -s} +above. To reschedule or cancel a single event @t{calendar_add} should be +called with an entry that includes the correct @t{UID} but does @emph{not} +include the @t{RPT} keyword as this is taken to mean the entry applies to a +series of repeating events and hence replaces all existing information. +Each rescheduled or cancelled occurrence must have an @t{OCCURRENCE} +keyword in the entry passed to @t{calendar_add} which will be merged into +the calendar file. Any existing reference to the occurrence is replaced. +An occurrence that does not refer to a valid existing event is added as a +one-off occurrence to the same calendar entry. + +@findex calendar_edit +@item @t{calendar_edit} +This calls the user's editor to edit the calendar file. If +there are arguments, they are taken as the editor to use (the file name +is appended to the commands); otherwise, the editor is given by the +variable @t{VISUAL}, if set, else the variable @t{EDITOR}. + +@noindent +If the calendar scheduler was running, then after editing the file +@t{calendar -s} is called to update it. + +@noindent +This function locks out the calendar system during the edit. +Hence it should be used to edit the calendar file if there is any +possibility of a calendar event occurring meanwhile. Note this +can lead to another shell with calendar functions enabled hanging waiting +for a lock, so it is necessary to quit the editor as soon as possible. + +@findex calendar_parse +@item @t{calendar_parse} @var{calendar-entry} +This is the internal function that analyses the parts of a calendar +entry, which is passed as the only argument. The function returns +status 1 if the argument could not be parsed as a calendar entry +and status 2 if the wrong number of arguments were passed; it also sets the +parameter @t{reply} to an empty associative array. Otherwise, +it returns status 0 and sets elements of the associative +array @t{reply} as follows: + +@noindent +@table @asis +@item @t{time} +The time as a string of digits in the same units as +@t{$EPOCHSECONDS} +@item @t{schedtime} +The regularly scheduled time. This may differ from +the actual event time @t{time} if this is a recurring event and the next +occurrence has been rescheduled. Then @t{time} gives the actual time +and @t{schedtime} the time of the regular recurrence before modification. +@item @t{text1} +The text from the line not including the date and time of the +event, but including any @t{WARN} or @t{RPT} keywords and values. +@item @t{warntime} +Any warning time given by the @t{WARN} keyword as a string +of digits containing the time at which to warn in the same units as +@t{$EPOCHSECONDS}. (Note this is an absolute time, not the relative time +passed down.) Not set no @t{WARN} keyword and value were +matched. +@item @t{warnstr} +The raw string matched after the @t{WARN} keyword, else unset. +@item @t{rpttime} +Any recurrence time given by the @t{RPT} keyword as a string +of digits containing the time of the recurrence in the same units +as @t{$EPOCHSECONDS}. (Note this is an absolute time.) Not set if +no @t{RPT} keyword and value were matched. +@item @t{schedrpttime} +The next regularly scheduled occurrence of a recurring +event before modification. This may differ from @t{rpttime}, which is the +actual time of the event that may have been rescheduled from the regular +time. +@item @t{rptstr} +The raw string matched after the @t{RPT} keyword, else unset. +@item @t{text2} +The text from the line after removal of the date and any +keywords and values. + +@end table + +@noindent +@findex calendar_showdate +@item @t{calendar_showdate} [ @t{-r} ] [ @t{-f} @var{fmt} ] @var{date-spec} ... +The given @var{date-spec} is interpreted and the corresponding date and +time printed. If the initial @var{date-spec} begins with a @t{+} or +@t{-} it is treated as relative to the current time; @var{date-spec}s after +the first are treated as relative to the date calculated so far and +a leading @t{+} is optional in that case. This allows one to +use the system as a date calculator. For example, @t{calendar_showdate '+1 +month, 1st Friday'} shows the date of the first Friday of next month. + +@noindent +With the option @t{-r} nothing is printed but the value of the date and +time in seconds since the epoch is stored in the parameter @t{REPLY}. + +@noindent +With the option @t{-f} @var{fmt} the given date/time conversion format +is passed to @t{strftime}; see notes on the @t{date-format} style below. + +@noindent +In order to avoid ambiguity with negative relative date specifications, +options must occur in separate words; in other words, @t{-r} and @t{-f} +should not be combined in the same word. + +@findex calendar_sort +@item @t{calendar_sort} +Sorts the calendar file into date and time order. The old calendar is +left in a file with the suffix @t{.old}. + +@end table + +@noindent + +@subsection Glob qualifiers +@noindent + +@noindent +@table @asis +@item @t{age} +@findex age +The function @t{age} can be autoloaded and use separately from +the calendar system, although it uses the function @t{calendar_scandate} +for date formatting. It requires the @t{zsh/stat} builtin, but uses +only the builtin @t{zstat}. + +@noindent +@t{age} selects files having a given modification time for use +as a glob qualifier. The format of the date is the same as that +understood by the calendar system, described in +@ref{Calendar File and Date Formats}. + +@noindent +The function can take one or two arguments, which can be supplied either +directly as command or arguments, or separately as shell parameters. + +@noindent +@example +print *(e:age 2006/10/04 2006/10/09:) +@end example + +@noindent +The example above matches all files modified between the start of those +dates. The second argument may alternatively be a relative time +introduced by a @t{+}: + +@noindent +@example +print *(e:age 2006/10/04 +5d:) +@end example + +@noindent +The example above is equivalent to the previous example. + +@noindent +In addition to the special use of days of the week, @t{today} and +@t{yesterday}, times with no date may be specified; these apply to today. +Obviously such uses become problematic around midnight. + +@noindent +@example +print *(e-age 12:00 13:30-) +@end example + +@noindent +The example above shows files modified between 12:00 and 13:00 today. + +@noindent +@example +print *(e:age 2006/10/04:) +@end example + +@noindent +The example above matches all files modified on that date. If the second +argument is omitted it is taken to be exactly 24 hours after the first +argument (even if the first argument contains a time). + +@noindent +@example +print *(e-age 2006/10/04:10:15 2006/10/04:10:45-) +@end example + +@noindent +The example above supplies times. Note that whitespace within the time and +date specification must be quoted to ensure @t{age} receives the correct +arguments, hence the use of the additional colon to separate the date and +time. + +@noindent +@example +AGEREF=2006/10/04:10:15 +AGEREF2=2006/10/04:10:45 +print *(+age) +@end example + +@noindent +This shows the same example before using another form of argument +passing. The dates and times in the parameters @t{AGEREF} and @t{AGEREF2} +stay in effect until unset, but will be overridden if any argument is +passed as an explicit argument to age. Any explicit argument +causes both parameters to be ignored. + +@noindent +Instead of an explicit date and time, it's possible to use the +modification time of a file as the date and time for either argument +by introducing the file name with a colon: + +@noindent +@example +print *(e-age :file1-) +@end example + +@noindent +matches all files created on the same day (24 hours starting from +midnight) as @t{file1}. + +@noindent +@example +print *(e-age :file1 :file2-) +@end example + +@noindent +matches all files modified no earlier than @t{file1} and +no later than @t{file2}; precision here is to the nearest second. + +@item @t{after} +@itemx @t{before} +@findex after +@findex before +The functions @t{after} and @t{before} are simpler versions of @t{age} +that take just one argument. The argument is parsed similarly to an +argument of @t{age}; if it is not given the variable @t{AGEREF} is +consulted. As the names of the functions suggest, a file matches if its +modification time is after or before the time and date specified. If +a time only is given the date is today. + +@noindent +The two following examples are therefore equivalent: +@example +print *(e-after 12:00-) +print *(e-after today:12:00-) +@end example + +@end table + +@noindent +@node Calendar Styles, Calendar Utility Functions, Calendar System User Functions, Calendar Function System + +@section Styles +@noindent + +@noindent +The zsh style mechanism using the @t{zstyle} command is describe in +@ref{The zsh/zutil Module}. This is the same mechanism +used in the completion system. + +@noindent +The styles below are all examined in the context +@t{:datetime:}@var{function}@t{:}, for example @t{:datetime:calendar:}. + +@noindent +@table @asis +@kindex calendar-file +@item @t{calendar-file} +The location of the main calendar. The default is @t{~/calendar}. + +@kindex date-format +@item @t{date-format} +A @t{strftime} format string (see strftime(3)) with the zsh +extensions providing various numbers with no leading zero or space +if the number is a single digit as described for the +@t{%D@{}@var{string}@t{@}} prompt format in +@ref{Prompt Expansion}. + +@noindent +This is used for outputting dates in @t{calendar}, both to support +the @t{-v} option and when adding recurring events back to the calendar +file, and in @t{calendar_showdate} as the final output format. + +@noindent +If the style is not set, the default used is similar the standard system +format as output by the @t{date} command (also known as `ctime format'): +`@t{%a %b %d %H:%M:%S %Z %Y}'. + +@kindex done-file +@item @t{done-file} +The location of the file to which events which have passed are appended. +The default is the calendar file location with the suffix @t{.done}. +The style may be set to an empty string in which case a "done" file +will not be maintained. + +@kindex reformat-date +@item @t{reformat-date} +Boolean, used by @t{calendar_add}. If it is true, the date and time +of new entries added to the calendar will be reformatted to the format +given by the style @t{date-format} or its default. Only the date and +time of the event itself is reformatted; any subsidiary dates and times +such as those associated with repeat and warning times are left alone. + +@kindex show-prog +@item @t{show-prog} +The programme run by @t{calendar} for showing events. It will +be passed the start time and stop time of the events requested in seconds +since the epoch followed by the event text. Note that @t{calendar -s} uses +a start time and stop time equal to one another to indicate alerts +for specific events. + +@noindent +The default is the function @t{calendar_show}. + +@kindex warn-time +@item @t{warn-time} +The time before an event at which a warning will be displayed, if the +first line of the event does not include the text @t{EVENT} @var{reltime}. +The default is 5 minutes. + +@end table + +@noindent +@node Calendar Utility Functions, Calendar Bugs, Calendar Styles, Calendar Function System + +@section Utility functions +@noindent + +@noindent +@table @asis +@findex calendar_lockfiles +@item @t{calendar_lockfiles} +Attempt to lock the files given in the argument. To prevent +problems with network file locking this is done in an ad hoc fashion +by attempting to create a symbolic link to the file with the name +@var{file}@t{.lockfile}. No other system level functions are used +for locking, i.e. the file can be accessed and modified by any +utility that does not use this mechanism. In particular, the user is not +prevented from editing the calendar file at the same time unless +@t{calendar_edit} is used. + +@noindent +Three attempts are made to lock the file before giving up. If the module +@t{zsh/zselect} is available, the times of the attempts are jittered so that +multiple instances of the calling function are unlikely to retry at the +same time. + +@noindent +The files locked are appended to the array @t{lockfiles}, which should +be local to the caller. + +@noindent +If all files were successfully locked, status zero is returned, else status one. + +@noindent +This function may be used as a general file locking function, although +this will only work if only this mechanism is used to lock files. + +@findex calendar_read +@item @t{calendar_read} +This is a backend used by various other functions to parse the +calendar file, which is passed as the only argument. The array +@t{calendar_entries} is set to the list of events in the file; no +pruning is done except that ampersands are removed from the start of +the line. Each entry may contain multiple lines. + +@findex calendar_scandate +@item @t{calendar_scandate} +This is a generic function to parse dates and times that may be +used separately from the calendar system. The argument is a date +or time specification as described in +@ref{Calendar File and Date Formats}. The parameter @t{REPLY} +is set to the number of seconds since the epoch corresponding to that date +or time. By default, the date and time may occur anywhere within the given +argument. + +@noindent +Returns status zero if the date and time were successfully parsed, +else one. + +@noindent +Options: +@table @asis +@item @t{-a} +The date and time are anchored to the start of the argument; they +will not be matched if there is preceding text. + +@item @t{-A} +The date and time are anchored to both the start and end of the argument; +they will not be matched if the is any other text in the argument. + +@item @t{-d} +Enable additional debugging output. + +@item @t{-m} +Minus. When @t{-R} @var{anchor_time} is also given the relative time is +calculated backwards from @var{anchor_time}. + +@item @t{-r} +The argument passed is to be parsed as a relative time. + +@item @t{-R} @var{anchor_time} +The argument passed is to be parsed as a relative time. The time is +relative to @var{anchor_time}, a time in seconds since the epoch, +and the returned value is the absolute time corresponding to advancing +@var{anchor_time} by the relative time given. +This allows lengths of months to be correctly taken into account. If +the final day does not exist in the given month, the last day of the +final month is given. For example, if the anchor time is during 31st +January 2007 and the relative time is 1 month, the final time is the +same time of day during 28th February 2007. + +@item @t{-s} +In addition to setting @t{REPLY}, set @t{REPLY2} to the remainder of +the argument after the date and time have been stripped. This is +empty if the option @t{-A} was given. + +@item @t{-t} +Allow a time with no date specification. The date is assumed to be +today. The behaviour is unspecified if the iron tongue of midnight +is tolling twelve. + +@end table + +@findex calendar_show +@item @t{calendar_show} +The function used by default to display events. It accepts a start time +and end time for events, both in epoch seconds, and an event description. + +@noindent +The event is always printed to standard output. If the command line editor +is active (which will usually be the case) the command line will be +redisplayed after the output. + +@noindent +If the parameter @t{DISPLAY} is set and the start and end times are +the same (indicating a scheduled event), the function uses the +command @t{xmessage} to display a window with the event details. + +@end table + +@noindent +@node Calendar Bugs, , Calendar Utility Functions, Calendar Function System + +@section Bugs +@noindent + +@noindent +As the system is based entirely on shell functions (with a little support +from the @t{zsh/datetime} module) the mechanisms used are not as robust as +those provided by a dedicated calendar utility. Consequently the user +should not rely on the shell for vital alerts. + +@noindent +There is no @t{calendar_delete} function. + +@noindent +There is no localization support for dates and times, nor any support +for the use of time zones. + +@noindent +Relative periods of months and years do not take into account the variable +number of days. + +@noindent +The @t{calendar_show} function is currently hardwired to use @t{xmessage} +for displaying alerts on X Window System displays. This should be +configurable and ideally integrate better with the desktop. + +@noindent +@t{calendar_lockfiles} hangs the shell while waiting for a lock on a file. +If called from a scheduled task, it should instead reschedule the event +that caused it. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/tcpsys.yo +@node TCP Function System, Zftp Function System, Calendar Function System, Top + +@chapter TCP Function System +@noindent +@cindex TCP function system +@cindex ztcp, function system based on + +@section Description +@noindent + +@noindent +A module @t{zsh/net/tcp} is provided to provide network I/O over +TCP/IP from within the shell; see its description in +@ref{Zsh Modules}. This manual page describes a function suite based on the module. +If the module is installed, the functions are usually installed at the +same time, in which case they will be available for +autoloading in the default function search path. In addition to the +@t{zsh/net/tcp} module, the @t{zsh/zselect} module is used to implement +timeouts on read operations. For troubleshooting tips, consult the +corresponding advice for the @t{zftp} functions described in +@ref{Zftp Function System}. + +@noindent +There are functions corresponding to the basic I/O operations open, close, +read and send, named @t{tcp_open} etc., as well as a function +@t{tcp_expect} for pattern match analysis of data read as input. The +system makes it easy to receive data from and send data to multiple named +sessions at once. In addition, it can be linked with the shell's line +editor in such a way that input data is automatically shown at the +terminal. Other facilities available including logging, filtering and +configurable output prompts. + +@noindent +To use the system where it is available, it should be enough to +`@t{autoload -U tcp_open}' and run @t{tcp_open} as documented below to +start a session. The @t{tcp_open} function will autoload the remaining +functions. + +@noindent +@menu +* TCP Functions:: +* TCP Parameters:: +* TCP Examples:: +* TCP Bugs:: +@end menu + +@noindent +@node TCP Functions, TCP Parameters, , TCP Function System + +@section TCP User Functions +@noindent + +@noindent + +@subsection Basic I/O +@noindent + +@noindent +@table @asis +@findex tcp_open +@item @t{tcp_open} [ @t{-qz} ] @var{host port} [ @var{sess} ] +@itemx @t{tcp_open} [ @t{-qz} ] [ @t{-s} @var{sess} | @t{-l} @var{sess}[@t{,}...] ] ... +@itemx @t{tcp_open} [ @t{-qz} ] [ @t{-a} @var{fd} | @t{-f} @var{fd} ] [ @var{sess} ] +Open a new session. In the first and simplest form, open a TCP connection +to host @var{host} at port @var{port}; numeric and symbolic forms are +understood for both. + +@noindent +If @var{sess} is given, this becomes the name of the session which can be +used to refer to multiple different TCP connections. If @var{sess} is +not given, the function will invent a numeric name value (note this is +@emph{not} the same as the file descriptor to which the session is attached). +It is recommended that session names not include `funny' characters, where +funny characters are not well-defined but certainly do not include +alphanumerics or underscores, and certainly do include whitespace. + +@noindent +In the second case, one or more sessions to be opened are given by name. +A single session name is given after @t{-s} and a comma-separated list +after @t{-l}; both options may be repeated as many times as necessary. +A failure to open any session causes @t{tcp_open} to abort. +The host and port are read from the file @t{.ztcp_sessions} in the same +directory as the user's zsh initialisation files, i.e. usually the home +directory, but @t{$ZDOTDIR} if that is set. The file consists of lines +each giving a session name and the corresponding host and port, in that +order (note the session name comes first, not last), separated by +whitespace. + +@noindent +The third form allows passive and fake TCP connections. If the option +@t{-a} is used, its argument is a file descriptor open for listening for +connections. No function front-end is provided to open such a file +descriptor, but a call to `@t{ztcp -l} @var{port}' will create one with the +file descriptor stored in the parameter @t{$REPLY}. The listening port can +be closed with `@t{ztcp -c} @var{fd}'. A call to `@t{tcp_open -a} @var{fd}' +will block until a remote TCP connection is made to @var{port} on the local +machine. At this point, a session is created in the usual way and is +largely indistinguishable from an active connection created with one of the +first two forms. + +@noindent +If the option @t{-f} is used, its argument is a file descriptor which is +used directly as if it were a TCP session. How well the remainder of the +TCP function system copes with this depends on what actually underlies this +file descriptor. A regular file is likely to be unusable; a FIFO (pipe) of +some sort will work better, but note that it is not a good idea for two +different sessions to attempt to read from the same FIFO at once. + +@noindent +If the option @t{-q} is given with any of the three forms, @t{tcp_open} +will not print informational messages, although it will in any case exit +with an appropriate status. + +@noindent +If the line editor (zle) is in use, which is typically the case if the +shell is interactive, @t{tcp_open} installs a handler inside zle which +will check for new data at the same time as it checks for keyboard input. +This is convenient as the shell consumes no CPU time while waiting; the +test is performed by the operating system. Giving the option @t{-z} to +any of the forms of @t{tcp_open} prevents the handler from being +installed, so data must be read explicitly. Note, however, this is not +necessary for executing complete sets of send and read commands from a +function, as zle is not active at this point. Generally speaking, the +handler is only active when the shell is waiting for input at a command +prompt or in the @t{vared} builtin. The option has no effect if zle is not +active; `@t{[[ -o zle]]}' will test for this. + +@noindent +The first session to be opened becomes the current session and subsequent +calls to @t{tcp_open} do not change it. The current session is stored +in the parameter @t{$TCP_SESS}; see below for more detail about the +parameters used by the system. + +@noindent +The function @t{tcp_on_open}, if defined, is called when a session +is opened. See the description below. + +@findex tcp_close +@item @t{tcp_close} [ @t{-qn} ] [ @t{-a} | @t{-l} @var{sess}[@t{,}...] | @var{sess} ... ] +Close the named sessions, or the current session if none is given, +or all open sessions if @t{-a} is given. The options @t{-l} and @t{-s} are +both handled for consistency with @t{tcp_open}, although the latter is +redundant. + +@noindent +If the session being closed is the current one, @t{$TCP_SESS} is unset, +leaving no current session, even if there are other sessions still open. + +@noindent +If the session was opened with @t{tcp_open -f}, the file descriptor is +closed so long as it is in the range 0 to 9 accessible directly from the +command line. If the option @t{-n} is given, no attempt will be made to +close file descriptors in this case. The @t{-n} option is not used for +genuine @t{ztcp} session; the file descriptors are always closed with the +session. + +@noindent +If the option @t{-q} is given, no informational messages will be printed. + +@findex tcp_read + +@item @t{tcp_read }[ @t{-bdq} ] [ @t{-t} @var{TO} ] [ @t{-T} @var{TO} ] +@itemx @t{@ @ @ @ @ @ @ @ @ }[ @t{-a} | @t{-u} @var{fd}[@t{,}...] | @t{-l} @var{sess}[@t{,}...] | @t{-s} @var{sess} ... ] +Perform a read operation on the current session, or on a list of +sessions if any are given with @t{-u}, @t{-l} or @t{-s}, or all open +sessions if the option @t{-a} is given. Any of the @t{-u}, @t{-l} or +@t{-s} options may be repeated or mixed together. The @t{-u} option +specifies a file descriptor directly (only those managed by this system +are useful), the other two specify sessions as described for +@t{tcp_open} above. + +@noindent +The function checks for new data available on all the sessions listed. +Unless the @t{-b} option is given, it will not block waiting for new data. +Any one line of data from any of the available sessions will be read, +stored in the parameter @t{$TCP_LINE}, and displayed to standard output +unless @t{$TCP_SILENT} contains a non-empty string. When printed to +standard output the string @t{$TCP_PROMPT} will be shown at the start of +the line; the default form for this includes the name of the session being +read. See below for more information on these parameters. In this mode, +@t{tcp_read} can be called repeatedly until it returns status 2 which +indicates all pending input from all specified sessions has been handled. + +@noindent +With the option @t{-b}, equivalent to an infinite timeout, the function +will block until a line is available to read from one of the specified +sessions. However, only a single line is returned. + +@noindent +The option @t{-d} indicates that all pending input should be drained. In +this case @t{tcp_read} may process multiple lines in the manner given +above; only the last is stored in @t{$TCP_LINE}, but the complete set is +stored in the array @t{$tcp_lines}. This is cleared at the start of each +call to @t{tcp_read}. + +@noindent +The options @t{-t} and @t{-T} specify a timeout in seconds, which may be a +floating point number for increased accuracy. With @t{-t} the timeout is +applied before each line read. With @t{-T}, the timeout applies to the +overall operation, possibly including multiple read operations if the +option @t{-d} is present; without this option, there is no distinction +between @t{-t} and @t{-T}. + +@noindent +The function does not print informational messages, but if the option +@t{-q} is given, no error message is printed for a non-existent session. + +@noindent +A return status of 2 indicates a timeout or no data to read. Any other +non-zero return status indicates some error condition. + +@noindent +See @t{tcp_log} for how to control where data is sent by @t{tcp_read}. + +@findex tcp_send +@item @t{tcp_send} [ @t{-cnq} ] [ @t{-s} @var{sess} | @t{-l} @var{sess}[@t{,}...] ] @var{data} ... +@itemx @t{tcp_send} [ @t{-cnq} ] @t{-a} @var{data} ... +Send the supplied data strings to all the specified sessions in turn. The +underlying operation differs little from a `@t{print -r}' to the session's +file descriptor, although it attempts to prevent the shell from dying owing +to a @t{SIGPIPE} caused by an attempt to write to a defunct session. + +@noindent +The option @t{-c} causes @t{tcp_send} to behave like @t{cat}. It reads +lines from standard input until end of input and sends them in turn to the +specified session(s) exactly as if they were given as @var{data} +arguments to individual @t{tcp_send} commands. + +@noindent +The option @t{-n} prevents @t{tcp_send} from putting a newline at the end +of the data strings. + +@noindent +The remaining options all behave as for @t{tcp_read}. + +@noindent +The data arguments are not further processed once they have been passed to +@t{tcp_send}; they are simply passed down to @t{print -r}. + +@noindent +If the parameter @t{$TCP_OUTPUT} is a non-empty string and logging is +enabled then the data sent to each session will be echoed to the log +file(s) with @t{$TCP_OUTPUT} in front where appropriate, much +in the manner of @t{$TCP_PROMPT}. + +@end table + +@noindent + +@subsection Session Management +@noindent + +@noindent +@table @asis +@findex tcp_alias +@item @t{tcp_alias} [ @t{-q} ] @var{alias}@t{=}@var{sess} ... +@itemx @t{tcp_alias} [ @t{-q} ] [ @var{alias} ... ] +@itemx @t{tcp_alias} @t{-d} [ @t{-q} ] @var{alias} ... +This function is not particularly well tested. + +@noindent +The first form creates an alias for a session name; @var{alias} can then be +used to refer to the existing session @var{sess}. As many aliases may be +listed as required. + +@noindent +The second form lists any aliases specified, or all aliases if none. + +@noindent +The third form deletes all the aliases listed. The underlying sessions are +not affected. + +@noindent +The option @t{-q} suppresses an inconsistently chosen subset of error +messages. + +@findex tcp_log +@item @t{tcp_log} [ @t{-asc} ] [ @t{-n} | @t{-N} ] [ @var{logfile} ] +With an argument @var{logfile}, all future input from @t{tcp_read} will be +logged to the named file. Unless @t{-a} (append) is given, this file will +first be truncated or created empty. With no arguments, show the current +status of logging. + +@noindent +With the option @t{-s}, per-session logging is enabled. Input from +@t{tcp_read} is output to the file @var{logfile}@t{.}@var{sess}. As the +session is automatically discriminated by the filename, the contents are +raw (no @t{$TCP_PROMPT}). The option @t{-a} applies as above. +Per-session logging and logging of all data in one file are not mutually +exclusive. + +@noindent +The option @t{-c} closes all logging, both complete and per-session logs. + +@noindent +The options @t{-n} and @t{-N} respectively turn off or restore output of +data read by @t{tcp_read} to standard output; hence `@t{tcp_log -cn}' turns +off all output by @t{tcp_read}. + +@noindent +The function is purely a convenient front end to setting the parameters +@t{$TCP_LOG}, @t{$TCP_LOG_SESS}, @t{$TCP_SILENT}, which are described below. + +@findex tcp_rename +@item @t{tcp_rename} @var{old} @var{new} +Rename session @var{old} to session @var{new}. The old name becomes invalid. + +@findex tcp_sess +@item @t{tcp_sess} [ @var{sess} [ @var{command} [ @var{arg} ... ] ] ] +With no arguments, list all the open sessions and associated file +descriptors. The current session is marked with a star. For use in +functions, direct access to the parameters @t{$tcp_by_name}, @t{$tcp_by_fd} +and @t{$TCP_SESS} is probably more convenient; see below. + +@noindent +With a @var{sess} argument, set the current session to @var{sess}. +This is equivalent to changing @t{$TCP_SESS} directly. + +@noindent +With additional arguments, temporarily set the current session while +executing `@var{command} @var{arg} ...'. @var{command} is re-evaluated +so as to expand aliases etc., but the remaining @var{arg}s are passed +through as that appear to @t{tcp_sess}. The original session is restored +when @t{tcp_sess} exits. + +@end table + +@noindent + +@subsection Advanced I/O +@noindent + +@noindent +@table @asis +@findex tcp_command +@item @t{tcp_command} @var{send-option} ... @var{send-argument} ... +This is a convenient front-end to @t{tcp_send}. All arguments are passed +to @t{tcp_send}, then the function pauses waiting for data. While data is +arriving at least every @t{$TCP_TIMEOUT} (default 0.3) seconds, data is +handled and printed out according to the current settings. Status 0 is +always returned. + +@noindent +This is generally only useful for interactive use, to prevent the display +becoming fragmented by output returned from the connection. Within a +programme or function it is generally better to handle reading data by a +more explicit method. + +@findex tcp_expect + +@item @t{tcp_expect }[ @t{-q} ] [ @t{-p} @var{var} | @t{-P} @var{var} ] [ @t{-t} @var{TO} | @t{-T} @var{TO} ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ @ }[ @t{-a} | @t{-s} @var{sess} | @t{-l} @var{sess}[@t{,}...] ] @var{pattern} ... +Wait for input matching any of the given @var{pattern}s from any of the +specified sessions. Input is ignored until an input line matches one of +the given patterns; at this point status zero is returned, the matching +line is stored in @t{$TCP_LINE}, and the full set of lines read during the +call to @t{tcp_expect} is stored in the array @t{$tcp_expect_lines}. + +@noindent +Sessions are specified in the same way as @t{tcp_read}: the default is to +use the current session, otherwise the sessions specified by @t{-a}, +@t{-s}, or @t{-l} are used. + +@noindent +Each @var{pattern} is a standard zsh extended-globbing pattern; note that it +needs to be quoted to avoid it being expanded immediately by filename +generation. It must match the full line, so to match a substring there +must be a `@t{*}' at the start and end. The line matched against includes +the @t{$TCP_PROMPT} added by @t{tcp_read}. It is possible to include the +globbing flags `@t{#b}' or `@t{#m}' in the patterns to make backreferences +available in the parameters @t{$MATCH}, @t{$match}, etc., as described in +the base zsh documentation on pattern matching. + +@noindent +Unlike @t{tcp_read}, the default behaviour of @t{tcp_expect} is to block +indefinitely until the required input is found. This can be modified by +specifying a timeout with @t{-t} or @t{-T}; these function as in +@t{tcp_read}, specifying a per-read or overall timeout, respectively, in +seconds, as an integer or floating-point number. As @t{tcp_read}, the +function returns status 2 if a timeout occurs. + +@noindent +The function returns as soon as any one of the patterns given match. If +the caller needs to know which of the patterns matched, the option @t{-p} +@var{var} can be used; on return, @t{$var} is set to the number of the +pattern using ordinary zsh indexing, i.e. the first is 1, and so on. Note +the absence of a `@t{$}' in front of @var{var}. To avoid clashes, the +parameter cannot begin with `@t{_expect}'. The index -1 is used if +there is a timeout and 0 if there is no match. + +@noindent +The option @t{-P} @var{var} works similarly to @t{-p}, but instead of +numerical indexes the regular arguments must begin with a prefix +followed by a colon: that prefix is then used as a tag to which @var{var} +is set when the argument matches. The tag @t{timeout} is used if there +is a timeout and the empty string if there is no match. Note it is +acceptable for different arguments to start with the same prefix if the +matches do not need to be distinguished. + +@noindent +The option @t{-q} is passed directly down to @t{tcp_read}. + +@noindent +As all input is done via @t{tcp_read}, all the usual rules about output of +lines read apply. One exception is that the parameter @t{$tcp_lines} will +only reflect the line actually matched by @t{tcp_expect}; use +@t{$tcp_expect_lines} for the full set of lines read during the function +call. + +@findex tcp_proxy +@item @t{tcp_proxy} +This is a simple-minded function to accept a TCP connection and execute a +command with I/O redirected to the connection. Extreme caution should be +taken as there is no security whatsoever and this can leave your computer +open to the world. Ideally, it should only be used behind a firewall. + +@noindent +The first argument is a TCP port on which the function will listen. + +@noindent +The remaining arguments give a command and its arguments to execute with +standard input, standard output and standard error redirected to the +file descriptor on which the TCP session has been accepted. +If no command is given, a new zsh is started. This gives everyone on +your network direct access to your account, which in many cases will be a +bad thing. + +@noindent +The command is run in the background, so @t{tcp_proxy} can then accept new +connections. It continues to accept new connections until interrupted. + +@findex tcp_spam +@item @t{tcp_spam} [ @t{-ertv} ] [ @t{-a} | @t{-s} @var{sess} | @t{-l} @var{sess}[@t{,}...] ] @var{cmd} [ @var{arg} ... ] +Execute `@var{cmd} [ @var{arg} ... ]' for each session in turn. Note this executes +the command and arguments; it does not send the command line as data +unless the @t{-t} (transmit) option is given. + +@noindent +The sessions may be selected explicitly with the standard @t{-a}, @t{-s} or +@t{-l} options, or may be chosen implicitly. If none of the three options +is given the rules are: first, if the array @t{$tcp_spam_list} is set, this +is taken as the list of sessions, otherwise all sessions are taken. +Second, any sessions given in the array @t{$tcp_no_spam_list} are removed +from the list of sessions. + +@noindent +Normally, any sessions added by the `@t{-a}' flag or when all sessions are +chosen implicitly are spammed in alphabetic order; sessions given by the +@t{$tcp_spam_list} array or on the command line are spammed in the order +given. The @t{-r} flag reverses the order however it was arrived it. + +@noindent +The @t{-v} flag specifies that a @t{$TCP_PROMPT} will be output before each +session. This is output after any modification to @t{TCP_SESS} by the +user-defined @t{tcp_on_spam} function described below. (Obviously that +function is able to generate its own output.) + +@noindent +If the option @t{-e} is present, the line given as `@var{cmd} [ @var{arg} ... ]' is executed +using @t{eval}, otherwise it is executed without any further processing. + +@findex tcp_talk +@item @t{tcp_talk} +This is a fairly simple-minded attempt to force input to the line editor to +go straight to the default @t{TCP_SESS}. + +@noindent +An escape string, @t{$TCP_TALK_ESCAPE}, default `@t{:}', is used to allow +access to normal shell operation. If it is on its own at the start of the +line, or followed only by whitespace, the line editor returns to normal +operation. Otherwise, the string and any following whitespace are skipped +and the remainder of the line executed as shell input without any change of +the line editor's operating mode. + +@noindent +The current implementation is somewhat deficient in terms of use of the +command history. For this reason, many users will prefer to use some form +of alternative approach for sending data easily to the current session. +One simple approach is to alias some special character (such as `@t{%}') to +`@t{tcp_command -}@t{-}'. + +@findex tcp_wait +@item @t{tcp_wait} +The sole argument is an integer or floating point number which gives the +seconds to delay. The shell will do nothing for that period except wait +for input on all TCP sessions by calling @t{tcp_read -a}. This is similar +to the interactive behaviour at the command prompt when zle handlers are +installed. + +@end table + +@noindent + +@subsection `One-shot' file transfer +@noindent +@table @asis +@item @t{tcp_point} @var{port} +@itemx @t{tcp_shoot} @var{host} @var{port} +This pair of functions provide a simple way to transfer a file between +two hosts within the shell. Note, however, that bulk data transfer is +currently done using @t{cat}. @t{tcp_point} reads any data arriving at +@var{port} and sends it to standard output; @t{tcp_shoot} connects to +@var{port} on @var{host} and sends its standard input. Any unused @var{port} +may be used; the standard mechanism for picking a port is to think of a +random four-digit number above 1024 until one works. + +@noindent +To transfer a file from host @t{woodcock} to host @t{springes}, on +@t{springes}: + +@noindent +@example +tcp_point 8091 >output_file +@end example + +@noindent +and on @t{woodcock}: + +@noindent +@example +tcp_shoot springes 8091 <input_file +@end example + +@noindent +As these two functions do not require @t{tcp_open} to set up a TCP +connection first, they may need to be autoloaded separately. + +@end table + +@noindent + +@section TCP User-defined Functions +@noindent + +@noindent +Certain functions, if defined by the user, will be called by the function +system in certain contexts. This facility depends on the module +@t{zsh/parameter}, which is usually available in interactive shells as the +completion system depends on it. None of the functions need be defined; +they simply provide convenient hooks when necessary. + +@noindent +Typically, these are called after the requested action has been taken, so +that the various parameters will reflect the new state. + +@noindent +@table @asis +@findex tcp_on_alias +@item @t{tcp_on_alias} @var{alias} @var{fd} +When an alias is defined, this function will be called with two arguments: +the name of the alias, and the file descriptor of the corresponding session. + +@findex tcp_on_awol +@item @t{tcp_on_awol} @var{sess} @var{fd} +If the function @t{tcp_fd_handler} is handling input from the line +editor and detects that the file descriptor is no longer reusable, +by default it removes it from the list of file descriptors handled +by this method and prints a message. If the function @t{tcp_on_awol} +is defined it is called immediately before this point. It may +return status 100, which indicates that the normal handling should +still be performed; any other return status indicates that no further +action should be taken and the @t{tcp_fd_handler} should return +immediately with the given status. Typically the action of @t{tcp_on_awol} +will be to close the session. + +@noindent +The variable @t{TCP_INVALIDATE_ZLE} will be a non-empty string if it is +necessary to invalidate the line editor display using `@t{zle -I}' before +printing output from the function. + +@noindent +(`AWOL' is military jargon for `absent without leave' or some +variation. It has no pre-existing technical meaning known to the author.) + +@findex tcp_on_close +@item @t{tcp_on_close} @var{sess} @var{fd} +This is called with the name of a session being closed and the file +descriptor which corresponded to that session. Both will be invalid by +the time the function is called. + +@findex tcp_on_open +@item @t{tcp_on_open} @var{sess} @var{fd} +This is called after a new session has been defined with the session name +and file descriptor as arguments. If it returns a non-zero status, +opening the session is assumed to fail and the session is closed +again; however, @t{tcp_open} will continue to attempt to open any +remaining sessions given on the command line. + +@findex tcp_on_rename +@item @t{tcp_on_rename} @var{oldsess} @var{fd} @var{newsess} +This is called after a session has been renamed with the three arguments +old session name, file descriptor, new session name. + +@findex tcp_on_spam +@item @t{tcp_on_spam} @var{sess} @var{command ...} +This is called once for each session spammed, just @emph{before} a command is +executed for a session by @t{tcp_spam}. The arguments are the session name +followed by the command list to be executed. If @t{tcp_spam} was called +with the option @t{-t}, the first command will be @t{tcp_send}. + +@noindent +This function is called after @t{$TCP_SESS} is set to reflect the session +to be spammed, but before any use of it is made. Hence it is possible to +alter the value of @t{$TCP_SESS} within this function. For example, the +session arguments to @t{tcp_spam} could include extra information to be +stripped off and processed in @t{tcp_on_spam}. + +@noindent +If the function sets the parameter @t{$REPLY} to `@t{done}', the command +line is not executed; in addition, no prompt is printed for the @t{-v} +option to @t{tcp_spam}. + +@findex tcp_on_unalias +@item @t{tcp_on_unalias} @var{alias} @var{fd} +This is called with the name of an alias and the corresponding session's +file descriptor after an alias has been deleted. + +@end table + +@noindent + +@section TCP Utility Functions +@noindent + +@noindent +The following functions are used by the TCP function system but will rarely +if ever need to be called directly. + +@noindent +@table @asis +@findex tcp_fd_handler +@item @t{tcp_fd_handler} +This is the function installed by @t{tcp_open} for handling input from +within the line editor, if that is required. It is in the format +documented for the builtin `@t{zle -F}' in +@ref{Zle Builtins} +. + +@noindent +While active, the function sets the parameter @t{TCP_HANDLER_ACTIVE} to 1. +This allows shell code called internally (for example, by setting +@t{tcp_on_read}) to tell if is being called when the shell is otherwise +idle at the editor prompt. + +@findex tcp_output +@item @t{tcp_output} [ @t{-q} ] @t{-P} @var{prompt} @t{-F} @var{fd} @t{-S} @var{sess} +This function is used for both logging and handling output to standard +output, from within @t{tcp_read} and (if @t{$TCP_OUTPUT} is set) +@t{tcp_send}. + +@noindent +The @var{prompt} to use is specified by @t{-P}; the default is the empty +string. It can contain: +@table @asis +@item @t{%c} +Expands to 1 if the session is the current session, otherwise 0. Used +with ternary expressions such as `@t{%(c.-.+)}' to +output `@t{+}' for the current session and `@t{-}' otherwise. + +@item @t{%f} +Replaced by the session's file descriptor. + +@item @t{%s} +Replaced by the session name. + +@item @t{%%} +Replaced by a single `@t{%}'. + +@end table + +@noindent +The option @t{-q} suppresses output to standard output, but not to any log +files which are configured. + +@noindent +The @t{-S} and @t{-F} options are used to pass in the session name and file +descriptor for possible replacement in the prompt. + +@end table + +@noindent +@node TCP Parameters, TCP Examples, TCP Functions, TCP Function System + +@section TCP User Parameters +@noindent + +@noindent +Parameters follow the usual convention that uppercase is used for scalars +and integers, while lowercase is used for normal and associative array. +It is always safe for user code to read these parameters. Some parameters +may also be set; these are noted explicitly. Others are included in this +group as they are set by the function system for the user's benefit, +i.e. setting them is typically not useful but is benign. + +@noindent +It is often also useful to make settable parameters local to a function. +For example, `@t{local TCP_SILENT=1}' specifies that data read during the +function call will not be printed to standard output, regardless of the +setting outside the function. Likewise, `@t{local TCP_SESS=}@var{sess}' +sets a session for the duration of a function, and `@t{local +TCP_PROMPT=}' specifies that no prompt is used for input during the +function. + +@noindent +@table @asis +@vindex tcp_expect_lines +@item @t{tcp_expect_lines} +Array. The set of lines read during the last call to @t{tcp_expect}, +including the last (@t{$TCP_LINE}). + +@vindex tcp_filter +@item @t{tcp_filter} +Array. May be set directly. A set of extended globbing patterns which, +if matched in @t{tcp_output}, will cause the line not to be printed to +standard output. The patterns should be defined as described for the +arguments to @t{tcp_expect}. Output of line to log files is not affected. + +@vindex TCP_HANDLER_ACTIVE +@item @t{TCP_HANDLER_ACTIVE} +Scalar. Set to 1 within @t{tcp_fd_handler} to indicate to functions +called recursively that they have been called during an editor session. +Otherwise unset. + +@vindex TCP_LINE +@item @t{TCP_LINE} +The last line read by @t{tcp_read}, and hence also @t{tcp_expect}. + +@vindex TCP_LINE_FD +@item @t{TCP_LINE_FD} +The file descriptor from which @t{$TCP_LINE} was read. +@t{$@{tcp_by_fd[$TCP_LINE_FD]@}} will give the corresponding session name. + +@vindex tcp_lines +@item @t{tcp_lines} +Array. The set of lines read during the last call to @t{tcp_read}, +including the last (@t{$TCP_LINE}). + +@vindex TCP_LOG +@item @t{TCP_LOG} +May be set directly, although it is also controlled by @t{tcp_log}. +The name of a file to which output from all sessions will be sent. +The output is proceeded by the usual @t{$TCP_PROMPT}. If it is not an +absolute path name, it will follow the user's current directory. + +@findex TCP_LOG_SESS +@item @t{TCP_LOG_SESS} +May be set directly, although it is also controlled by @t{tcp_log}. +The prefix for a set of files to which output from each session separately +will be sent; the full filename is @t{$@{TCP_LOG_SESS@}.}@var{sess}. +Output to each file is raw; no prompt is added. If it is not an absolute +path name, it will follow the user's current directory. + +@vindex tcp_no_spam_list +@item @t{tcp_no_spam_list} +Array. May be set directly. See @t{tcp_spam} for how this is used. + +@vindex TCP_OUTPUT +@item @t{TCP_OUTPUT} +May be set directly. If a non-empty string, any data sent to a session by +@t{tcp_send} will be logged. This parameter gives the prompt to be used +in a file specified by @t{$TCP_LOG} but not in a file generated from +@t{$TCP_LOG_SESS}. The prompt string has the same format as +@t{TCP_PROMPT} and the same rules for its use apply. + +@vindex TCP_PROMPT +@item @t{TCP_PROMPT} +May be set directly. Used as the prefix for data read by @t{tcp_read} +which is printed to standard output or to the log file given by +@t{$TCP_LOG}, if any. Any `@t{%s}', `@t{%f}' or `@t{%%}' occurring in the +string will be replaced by the name of the session, the session's +underlying file descriptor, or a single `@t{%}', respectively. The +expression `@t{%c}' expands to 1 if the session being read is the current +session, else 0; this is most useful in ternary expressions such as +`@t{%(c.-.+)}' which outputs `@t{+}' if the session is +the current one, else `@t{-}'. + +@noindent +If the prompt starts with @t{%P}, this is stripped and the complete +result of the previous stage is passed through standard prompt @t{%}-style +formatting before being output. + +@vindex TCP_READ_DEBUG +@item @t{TCP_READ_DEBUG} +May be set directly. If this has non-zero length, @t{tcp_read} will give +some limited diagnostics about data being read. + +@vindex TCP_SECONDS_START +@item @t{TCP_SECONDS_START} +This value is created and initialised to zero by tcp_open. + +@noindent +The functions @t{tcp_read} and @t{tcp_expect} use the shell's +@t{SECONDS} parameter for their own timing purposes. If that parameter +is not of floating point type on entry to one of the functions, it will +create a local parameter @t{SECONDS} which is floating point and set the +parameter @t{TCP_SECONDS_START} to the previous value of @t{$SECONDS}. +If the parameter is already floating point, it is used without a local +copy being created and @t{TCP_SECONDS_START} is not set. As the global +value is zero, the shell elapsed time is guaranteed to be the sum of +@t{$SECONDS} and @t{$TCP_SECONDS_START}. + +@noindent +This can be avoided by setting @t{SECONDS} globally to a floating point +value using `@t{typeset -F SECONDS}'; then the TCP functions will never +make a local copy and never set @t{TCP_SECONDS_START} to a non-zero value. + +@vindex TCP_SESS +@item @t{TCP_SESS} +May be set directly. The current session; must refer to one of the +sessions established by @t{tcp_open}. + +@vindex TCP_SILENT +@item @t{TCP_SILENT} +May be set directly, although it is also controlled by @t{tcp_log}. +If of non-zero length, data read by @t{tcp_read} will not be written to +standard output, though may still be written to a log file. + +@vindex tcp_spam_list +@item @t{tcp_spam_list} +Array. May be set directly. See the description of the function +@t{tcp_spam} for how this is used. + +@vindex TCP_TALK_ESCAPE +@item @t{TCP_TALK_ESCAPE} +May be set directly. See the description of the function @t{tcp_talk} for +how this is used. + +@vindex TCP_TIMEOUT +@item @t{TCP_TIMEOUT} +May be set directly. Currently this is only used by the function +@t{tcp_command}, see above. + +@end table + +@noindent + +@section TCP User-defined Parameters +@noindent + +@noindent +The following parameters are not set by the function system, but have +a special effect if set by the user. + +@noindent +@table @asis +@vindex tcp_on_read +@item @t{tcp_on_read} +This should be an associative array; if it is not, the behaviour is +undefined. Each key is the name of a shell function or other command, +and the corresponding value is a shell pattern (using @t{EXTENDED_GLOB}). +Every line read from a TCP session directly or indirectly using +@t{tcp_read} (which includes lines read by @t{tcp_expect}) is compared +against the pattern. If the line matches, the command given in the key is +called with two arguments: the name of the session from which the line was +read, and the line itself. + +@noindent +If any function called to handle a line returns a non-zero status, the +line is not output. Thus a @t{tcp_on_read} handler containing only +the instruction `@t{return 1}' can be used to suppress output of +particular lines (see, however, @t{tcp_filter} above). However, the line +is still stored in @t{TCP_LINE} and @t{tcp_lines}; this occurs after all +@t{tcp_on_read} processing. + +@end table + +@noindent + +@section TCP Utility Parameters +@noindent + +@noindent +These parameters are controlled by the function system; they may be read +directly, but should not usually be set by user code. + +@noindent +@table @asis +@findex tcp_aliases +@item @t{tcp_aliases} +Associative array. The keys are the names of sessions established with +@t{tcp_open}; each value is a space-separated list of aliases which refer +to that session. + +@findex tcp_by_fd +@item @t{tcp_by_fd} +Associative array. The keys are session file descriptors; each +value is the name of that session. + +@findex tcp_by_name +@item @t{tcp_by_name} +Associative array. The keys are the names of sessions; each value is the +file descriptor associated with that session. + +@end table + +@noindent +@node TCP Examples, TCP Bugs, TCP Parameters, TCP Function System + +@section TCP Examples +@noindent + +@noindent +Here is a trivial example using a remote calculator. + +@noindent +To create a calculator server on port 7337 (see the @t{dc} manual page for +quite how infuriating the underlying command is): + +@noindent +@example +tcp_proxy 7337 dc +@end example + +@noindent +To connect to this from the same host with a session also named `@t{dc}': + +@noindent +@example +tcp_open localhost 7337 dc +@end example + +@noindent +To send a command to the remote session and wait a short while for output +(assuming @t{dc} is the current session): + +@noindent +@example +tcp_command 2 4 + p +@end example + +@noindent +To close the session: + +@noindent +@example +tcp_close +@end example + +@noindent +The @t{tcp_proxy} needs to be killed to be stopped. Note this will not +usually kill any connections which have already been accepted, and also +that the port is not immediately available for reuse. + +@noindent +The following chunk of code puts a list of sessions into an xterm header, +with the current session followed by a star. + +@noindent +@example +print -n "\033]2;TCP:" $@{(k)tcp_by_name:/$TCP_SESS/$TCP_SESS\*@} "\a" +@end example + +@noindent +@node TCP Bugs, , TCP Examples, TCP Function System + +@section TCP Bugs +@noindent + +@noindent +The function @t{tcp_read} uses the shell's normal @t{read} builtin. As +this reads a complete line at once, data arriving without a terminating +newline can cause the function to block indefinitely. + +@noindent +Though the function suite works well for interactive use and for data +arriving in small amounts, the performance when large amounts of data are +being exchanged is likely to be extremely poor. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/zftpsys.yo +@node Zftp Function System, User Contributions, TCP Function System, Top + +@chapter Zftp Function System +@noindent +@cindex zftp function system +@cindex FTP, functions for using shell as client + +@section Description +@noindent + +@noindent +This describes the set of shell functions supplied with the source +distribution as an interface to the @t{zftp} builtin command, allowing you +to perform FTP operations from the shell command line or within functions +or scripts. The interface is similar to a traditional FTP client (e.g. the +@t{ftp} command itself, see ftp(1)), but as it is entirely done +within the shell all the familiar completion, editing and globbing features, +and so on, are present, and macros are particularly simple to write as they +are just ordinary shell functions. + +@noindent +The prerequisite is that the @t{zftp} command, as described in +@ref{The zsh/zftp Module} +, must be available in the +version of @t{zsh} installed at your site. If the shell is configured to +load new commands at run time, it probably is: typing `@t{zmodload zsh/zftp}' +will make sure (if that runs silently, it has worked). If this is not the +case, it is possible @t{zftp} was linked into the shell anyway: to test +this, type `@t{which zftp}' and if @t{zftp} is available you will get the +message `@t{zftp: shell built-in command}'. + +@noindent +Commands given directly with @t{zftp} builtin may be interspersed between +the functions in this suite; in a few cases, using @t{zftp} directly may +cause some of the status information stored in shell parameters to become +invalid. Note in particular the description of the variables +@t{$ZFTP_TMOUT}, @t{$ZFTP_PREFS} and @t{$ZFTP_VERBOSE} for @t{zftp}. + +@noindent +@menu +* Installation:: +* Zftp Functions:: +* Miscellaneous Features:: +@end menu + +@noindent +@node Installation, Zftp Functions, , Zftp Function System + +@section Installation +@noindent + +@noindent +You should make sure all the functions from the @t{Functions/Zftp} +directory of the source distribution are available; they all begin with the +two letters `@t{zf}'. They may already have been installed on your system; +otherwise, you will need to find them and copy them. The directory should +appear as one of the elements of the @t{$fpath} array (this should already +be the case if they were installed), and at least the function @t{zfinit} +should be autoloaded; it will autoload the rest. Finally, to initialize +the use of the system you need to call the @t{zfinit} function. The +following code in your @t{.zshrc} will arrange for this; assume the +functions are stored in the directory @t{~/myfns}: + +@noindent +@example +fpath=(~/myfns $fpath) +autoload -U zfinit +zfinit +@end example + +@noindent +Note that @t{zfinit} assumes you are using the @t{zmodload} method to +load the @t{zftp} command. If it is already built into the shell, change +@t{zfinit} to @t{zfinit -n}. It is helpful (though not essential) if the +call to @t{zfinit} appears after any code to initialize the new completion +system, else unnecessary @t{compctl} commands will be given. + +@noindent +@node Zftp Functions, Miscellaneous Features, Installation, Zftp Function System + +@section Functions +@noindent + +@noindent +The sequence of operations in performing a file transfer is essentially the +same as that in a standard FTP client. Note that, due to a quirk of the +shell's @t{getopts} builtin, for those functions that handle options you +must use `@t{-}@t{-}' rather than `@t{-}' to ensure the remaining arguments +are treated literally (a single `@t{-}' is treated as an argument). + +@noindent + +@subsection Opening a connection +@noindent +@table @asis +@findex zfparams +@item @t{zfparams} [ @var{host} [ @var{user} [ @var{password} ... ] ] ] +Set or show the parameters for a future @t{zfopen} with no arguments. If +no arguments are given, the current parameters are displayed (the password +will be shown as a line of asterisks). If a @var{host} is given, and either the +@var{user} or @var{password} is not, they will be prompted for; also, any +parameter given as `@t{?}' will be prompted for, and if the `@t{?}' is +followed by a string, that will be used as the prompt. As @t{zfopen} calls +@t{zfparams} to store the parameters, this usually need not be called +directly. + +@noindent +A single argument `@t{-}' will delete the stored parameters. This will +also cause the memory of the last directory (and so on) on the other host +to be deleted. + +@findex zfopen +@item @t{zfopen} [ @t{-1} ] [ @var{host} [ @var{user} [ @var{password} [ @var{account} ] ] ] ] +If @var{host} is present, open a connection to that host under username +@var{user} with password @var{password} (and, on the rare occasions when it +is necessary, account @var{account}). If a necessary parameter is missing or +given as `@t{?}' it will be prompted for. If @var{host} is not present, use +a previously stored set of parameters. + +@noindent +If the command was successful, and the terminal is compatible with +@t{xterm} or is @t{sun-cmd}, a summary will appear in the title bar, +giving the local @t{host:directory} and the remote @t{host:directory}; +this is handled by the function @t{zftp_chpwd}, described below. + +@noindent +Normally, the @var{host}, @var{user} and @var{password} are internally +recorded for later re-opening, either by a @t{zfopen} with no arguments, or +automatically (see below). With the option `@t{-1}', no information is +stored. Also, if an open command with arguments failed, the parameters +will not be retained (and any previous parameters will also be deleted). +A @t{zfopen} on its own, or a @t{zfopen -1}, never alters the stored +parameters. + +@noindent +Both @t{zfopen} and @t{zfanon} (but not @t{zfparams}) understand URLs of +the form @t{ftp://}@var{host}/@var{path...} as meaning to connect to the +@var{host}, then change directory to @var{path} (which must be a directory, +not a file). The `@t{ftp://}' can be omitted; the trailing `@t{/}' is enough +to trigger recognition of the @var{path}. Note prefixes other than +`@t{ftp:}' are not recognized, and that all characters after the first +slash beyond @var{host} are significant in @var{path}. + +@findex zfanon +@item @t{zfanon} [ @t{-1} ] @var{host} +Open a connection @var{host} for anonymous FTP. The username used is +`@t{anonymous}'. The password (which will be reported the first time) is +generated as @var{user}@t{@@}@var{host}; this is then stored in the shell +parameter @t{$EMAIL_ADDR} which can alternatively be set manually to a +suitable string. + +@end table + +@noindent + +@subsection Directory management +@noindent +@table @asis +@findex zfcd +@item @t{zfcd} [ @var{dir} ] +@itemx @t{zfcd -} +@itemx @t{zfcd} @var{old} @var{new} +Change the current directory on the remote server: this is implemented to +have many of the features of the shell builtin @t{cd}. + +@noindent +In the first form with @var{dir} present, change to the directory @var{dir}. +The command `@t{zfcd ..}' is treated specially, so is guaranteed to work on +non-UNIX servers (note this is handled internally by @t{zftp}). If @var{dir} +is omitted, has the effect of `@t{zfcd ~}'. + +@noindent +The second form changes to the directory previously current. + +@noindent +The third form attempts to change the current directory by replacing the +first occurrence of the string @var{old} with the string @var{new} in the +current directory. + +@noindent +Note that in this command, and indeed anywhere a remote filename is +expected, the string which on the local host corresponds to `@t{~}' is +converted back to a `@t{~}' before being passed to the remote machine. +This is convenient because of the way expansion is performed on the command +line before @t{zfcd} receives a string. For example, suppose the command +is `@t{zfcd ~/foo}'. The shell will expand this to a full path such as +`@t{zfcd /home/user2/pws/foo}'. At this stage, @t{zfcd} recognises the +initial path as corresponding to `@t{~}' and will send the directory to +the remote host as @t{~/foo}, so that the `@t{~}' will be expanded by the +server to the correct remote host directory. Other named directories of +the form `@t{~name}' are not treated in this fashion. + +@findex zfhere +@item @t{zfhere} +Change directory on the remote server to the one corresponding to the +current local directory, with special handling of `@t{~}' as in @t{zfcd}. +For example, if the current local directory is @t{~/foo/bar}, then +@t{zfhere} performs the effect of `@t{zfcd ~/foo/bar}'. + +@findex zfdir +@item @t{zfdir} [ @t{-rfd} ] [ @t{-} ] [ @var{dir-options} ] [ @var{dir} ] +Produce a long directory listing. The arguments @var{dir-options} and +@var{dir} are passed directly to the server and their effect is +implementation dependent, but specifying a particular remote directory +@var{dir} is usually possible. The output is passed through a pager +given by the environment variable @t{$PAGER}, or `@t{more}' if that is not +set. + +@noindent +The directory is usually cached for re-use. In fact, two caches are +maintained. One is for use when there is no @var{dir-options} or @var{dir}, +i.e. a full listing of the current remote directory; it is flushed +when the current remote directory changes. The other is +kept for repeated use of @t{zfdir} with the same arguments; for example, +repeated use of `@t{zfdir /pub/gnu}' will only require the directory to be +retrieved on the first call. Alternatively, this cache can be re-viewed with +the @t{-r} option. As relative directories will confuse +@t{zfdir}, the @t{-f} option can be used to force the cache to be flushed +before the directory is listed. The option @t{-d} will delete both +caches without showing a directory listing; it will also delete the cache +of file names in the current remote directory, if any. + +@findex zfls +@item @t{zfls} [ @var{ls-options} ] [ @var{dir} ] +List files on the remote server. With no arguments, this will produce a +simple list of file names for the current remote directory. Any arguments +are passed directly to the server. No pager and no caching is used. + +@end table + +@noindent + +@subsection Status commands +@noindent +@table @asis +@findex zftype +@item @t{zftype} [ @var{type} ] +With no arguments, show the type of data to be transferred, usually ASCII +or binary. With an argument, change the type: the types `@t{A}' or +`@t{ASCII}' for ASCII data and `@t{B}' or `@t{BINARY}', `@t{I}' or +`@t{IMAGE}' for binary data are understood case-insensitively. + +@findex zfstat +@item @t{zfstat} [ @t{-v} ] +Show the status of the current or last connection, as well as the status of +some of @t{zftp}'s status variables. With the @t{-v} option, a more +verbose listing is produced by querying the server for its version of +events, too. + +@end table + +@noindent + +@subsection Retrieving files +@noindent +The commands for retrieving files all take at least two options. @t{-G} +suppresses remote filename expansion which would otherwise be performed +(see below for a more detailed description of that). @t{-t} attempts +to set the modification time of the local file to that of the remote file: +see the description of the function @t{zfrtime} below for more information. + +@noindent +@table @asis +@findex zfget +@item @t{zfget} [ @t{-Gtc} ] @var{file1} ... +Retrieve all the listed files @var{file1} ... one at a time from the remote +server. If a file contains a `@t{/}', the full name is passed to the +remote server, but the file is stored locally under the name given by the +part after the final `@t{/}'. The option @t{-c} (cat) forces all files to +be sent as a single stream to standard output; in this case the @t{-t} +option has no effect. + +@findex zfuget +@item @t{zfuget} [ @t{-Gvst} ] @var{file1} ... +As @t{zfget}, but only retrieve files where the version on the remote +server is newer (has a later modification time), or where the local file +does not exist. If the remote file is older but the files have different +sizes, or if the sizes are the same but the remote file is newer, the user +will usually be queried. With the option @t{-s}, the command runs silently +and will always retrieve the file in either of those two cases. With the +option @t{-v}, the command prints more information about the files while it +is working out whether or not to transfer them. + +@findex zfcget +@item @t{zfcget} [ @t{-Gt} ] @var{file1} ... +As @t{zfget}, but if any of the local files exists, and is shorter than +the corresponding remote file, the command assumes that it is the result of +a partially completed transfer and attempts to transfer the rest of the +file. This is useful on a poor connection which keeps failing. + +@noindent +Note that this requires a commonly implemented, but non-standard, version +of the FTP protocol, so is not guaranteed to work on all servers. + +@findex zfgcp +@item @t{zfgcp} [ @t{-Gt} ] @var{remote-file} @var{local-file} +@itemx @t{zfgcp} [ @t{-Gt} ] @var{rfile1} ... @var{ldir} +This retrieves files from the remote server with arguments behaving +similarly to the @t{cp} command. + +@noindent +In the first form, copy @var{remote-file} from the server to the local file +@var{local-file}. + +@noindent +In the second form, copy all the remote files @var{rfile1} ... into the +local directory @var{ldir} retaining the same basenames. This assumes UNIX +directory semantics. + +@end table + +@noindent + +@subsection Sending files +@noindent +@table @asis +@findex zfput +@item @t{zfput} [ @t{-r} ] @var{file1} ... +Send all the @var{file1} ... given separately to the remote server. If a +filename contains a `@t{/}', the full filename is used locally to find the +file, but only the basename is used for the remote file name. + +@noindent +With the option @t{-r}, if any of the @var{files} are directories they are +sent recursively with all their subdirectories, including files beginning +with `@t{.}'. This requires that the remote machine understand UNIX file +semantics, since `@t{/}' is used as a directory separator. + +@findex zfuput +@item @t{zfuput} [ @t{-vs} ] @var{file1} ... +As @t{zfput}, but only send files which are newer than their remote +equivalents, or if the remote file does not exist. The logic is the same +as for @t{zfuget}, but reversed between local and remote files. + +@findex zfcput +@item @t{zfcput} @var{file1} ... +As @t{zfput}, but if any remote file already exists and is shorter than the +local equivalent, assume it is the result of an incomplete transfer and +send the rest of the file to append to the existing part. As the FTP +append command is part of the standard set, this is in principle more +likely to work than @t{zfcget}. + +@findex zfpcp +@item @t{zfpcp} @var{local-file} @var{remote-file} +@itemx @t{zfpcp} @var{lfile1} ... @var{rdir} +This sends files to the remote server with arguments behaving similarly to +the @t{cp} command. + +@noindent +With two arguments, copy @var{local-file} to the server as +@var{remote-file}. + +@noindent +With more than two arguments, copy all the local files @var{lfile1} ... into +the existing remote directory @var{rdir} retaining the same basenames. This +assumes UNIX directory semantics. + +@noindent +A problem arises if you attempt to use @t{zfpcp} @var{lfile1} @var{rdir}, +i.e. the second form of copying but with two arguments, as the command has +no simple way of knowing if @var{rdir} corresponds to a directory or a +filename. It attempts to resolve this in various ways. First, if the +@var{rdir} argument is `@t{.}' or `@t{..}' or ends in a slash, it is assumed +to be a directory. Secondly, if the operation of copying to a remote file +in the first form failed, and the remote server sends back the expected +failure code 553 and a reply including the string `@t{Is a directory}', +then @t{zfpcp} will retry using the second form. + +@end table + +@noindent + +@subsection Closing the connection +@noindent +@table @asis +@findex zfclose +@item @t{zfclose} +Close the connection. + +@end table + +@noindent + +@subsection Session management +@noindent +@table @asis +@findex zfsession +@item @t{zfsession} [ @t{-lvod} ] [ @var{sessname} ] +Allows you to manage multiple FTP sessions at once. By default, +connections take place in a session called `@t{default}'; by giving the +command `@t{zfsession} @var{sessname}' you can change to a new or existing +session with a name of your choice. The new session remembers its own +connection, as well as associated shell parameters, and also the host/user +parameters set by @t{zfparams}. Hence you can have different sessions set +up to connect to different hosts, each remembering the appropriate host, +user and password. + +@noindent +With no arguments, @t{zfsession} prints the name of the current session; +with the option @t{-l} it lists all sessions which currently exist, and +with the option @t{-v} it gives a verbose list showing the host and +directory for each session, where the current session is marked with an +asterisk. With @t{-o}, it will switch to the most recent previous session. + +@noindent +With @t{-d}, the given session (or else the current one) is removed; +everything to do with it is completely forgotten. If it was the only +session, a new session called `@t{default}' is created and made current. +It is safest not to delete sessions while background commands using +@t{zftp} are active. + +@findex zftransfer +@item @t{zftransfer} @var{sess1}@t{:}@var{file1} @var{sess2}@t{:}@var{file2} +Transfer files between two sessions; no local copy is made. The file +is read from the session @var{sess1} as @var{file1} and written to session +@var{sess2} as file @var{file2}; @var{file1} and @var{file2} may be relative to +the current directories of the session. Either @var{sess1} or @var{sess2} +may be omitted (though the colon should be retained if there is a +possibility of a colon appearing in the file name) and defaults to the +current session; @var{file2} may be omitted or may end with a slash, in +which case the basename of @var{file1} will be added. The sessions +@var{sess1} and @var{sess2} must be distinct. + +@noindent +The operation is performed using pipes, so it is required that the +connections still be valid in a subshell, which is not the case under +versions of some operating systems, presumably due to a system bug. + +@end table + +@noindent + +@subsection Bookmarks +@noindent +The two functions @t{zfmark} and @t{zfgoto} allow you to `bookmark' the +present location (host, user and directory) of the current FTP connection +for later use. The file to be used for storing and retrieving bookmarks is +given by the parameter @t{$ZFTP_BMFILE}; if not set when one of the two +functions is called, it will be set to the file @t{.zfbkmarks} in the +directory where your zsh startup files live (usually @t{~}). + +@noindent +@table @asis +@findex zfmark +@item @t{zfmark} [ @var{bookmark} ] +If given an argument, mark the current host, user and directory under the +name @var{bookmark} for later use by @t{zfgoto}. If there is no connection +open, use the values for the last connection immediately before it was +closed; it is an error if there was none. Any existing bookmark +under the same name will be silently replaced. + +@noindent +If not given an argument, list the existing bookmarks and the points to +which they refer in the form @var{user}@t{@@}@var{host}@t{:}@var{directory}; +this is the format in which they are stored, and the file may be edited +directly. + +@findex zfgoto +@item @t{zfgoto} [ @t{-n} ] @var{bookmark} +Return to the location given by @var{bookmark}, as previously set by +@t{zfmark}. If the location has user `@t{ftp}' or `@t{anonymous}', open +the connection with @t{zfanon}, so that no password is required. If the +user and host parameters match those stored for the current session, if +any, those will be used, and again no password is required. Otherwise a +password will be prompted for. + +@noindent +With the option @t{-n}, the bookmark is taken to be a nickname stored by +the @t{ncftp} program in its bookmark file, which is assumed to be +@t{~/.ncftp/bookmarks}. The function works identically in other ways. +Note that there is no mechanism for adding or modifying @t{ncftp} bookmarks +from the zftp functions. + +@end table + +@noindent + +@subsection Other functions +@noindent +Mostly, these functions will not be called directly (apart from +@t{zfinit}), but are described here for completeness. You may wish to +alter @t{zftp_chpwd} and @t{zftp_progress}, in particular. + +@noindent +@table @asis +@findex zfinit +@item @t{zfinit} [ @t{-n} ] +As described above, this is used to initialize the zftp function system. +The @t{-n} option should be used if the zftp command is already built into +the shell. + +@findex zfautocheck +@item @t{zfautocheck} [ @t{-dn} ] +This function is called to implement automatic reopening behaviour, as +described in more detail below. The options must appear in the first +argument; @t{-n} prevents the command from changing to the old directory, +while @t{-d} prevents it from setting the variable @t{do_close}, which it +otherwise does as a flag for automatically closing the connection after a +transfer. The host and directory for the last session are stored in the +variable @t{$zflastsession}, but the internal host/user/password parameters +must also be correctly set. + +@findex zfcd_match +@item @t{zfcd_match @var{prefix} @var{suffix}} +This performs matching for completion of remote directory names. If the +remote server is UNIX, it will attempt to persuade the server to list the +remote directory with subdirectories marked, which usually works but is not +guaranteed. On other hosts it simply calls @t{zfget_match} and hence +completes all files, not just directories. On some systems, directories +may not even look like filenames. + +@findex zfget_match +@item @t{zfget_match @var{prefix} @var{suffix}} +This performs matching for completion of remote filenames. It caches files +for the current directory (only) in the shell parameter @t{$zftp_fcache}. +It is in the form to be called by the @t{-K} option of @t{compctl}, but +also works when called from a widget-style completion function with +@var{prefix} and @var{suffix} set appropriately. + +@findex zfrglob +@item @t{zfrglob @var{varname}} +Perform remote globbing, as describes in more detail below. @var{varname} +is the name of a variable containing the pattern to be expanded; if there +were any matches, the same variable will be set to the expanded set of +filenames on return. + +@findex zfrtime +@item @t{zfrtime} @var{lfile} @var{rfile} [ @var{time} ] +Set the local file @var{lfile} to have the same modification time as the +remote file @var{rfile}, or the explicit time @var{time} in FTP format +@t{CCYYMMDDhhmmSS} for the GMT timezone. This uses the shell's +@t{zsh/datetime} module to perform the conversion from +GMT to local time. + +@findex zftp_chpwd, supplied version +@item @t{zftp_chpwd} +This function is called every time a connection is opened, or closed, or +the remote directory changes. This version alters the title bar of an +@t{xterm}-compatible or @t{sun-cmd} terminal emulator to reflect the +local and remote hostnames and current directories. It works best when +combined with the function @t{chpwd}. In particular, a function of +the form + +@noindent +@example +chpwd() @{ + if [[ -n $ZFTP_USER ]]; then + zftp_chpwd + else + # usual chpwd e.g put host:directory in title bar + fi +@} +@end example + +@noindent +fits in well. + +@findex zftp_progress, supplied version +@item @t{zftp_progress} +This function shows the status of the transfer. It will not write anything +unless the output is going to a terminal; however, if you transfer files in +the background, you should turn off progress reports by hand using +`@t{zstyle ':zftp:*' progress none}'. Note also that if you alter it, any +output @emph{must} be to standard error, as standard output may be a file +being received. The form of the progress meter, or whether it is used at +all, can be configured without altering the function, as described in the +next section. + +@findex zffcache +@item @t{zffcache} +This is used to implement caching of files in the current directory for +each session separately. It is used by @t{zfget_match} and @t{zfrglob}. + +@end table + +@noindent +@node Miscellaneous Features, , Zftp Functions, Zftp Function System + +@section Miscellaneous Features +@noindent + +@noindent + +@subsection Configuration +@noindent +@cindex zftp function system, configuration +@cindex zftp function system, styles +@cindex styles in zftp functions + +@noindent +Various styles are available using the standard shell style mechanism, +described in +@ref{The zsh/zutil Module}. Briefly, the +command `@t{zstyle ':zftp:*'} @var{style} @var{value} ...'. +defines the @var{style} to have value @var{value}; more than one value may be +given, although that is not useful in the cases described here. These +values will then be used throughout the zftp function system. For more +precise control, the first argument, which gives a pattern that matches @emph{contexts} in which the +style applies, can be modified to include a particular function, as for +example `@t{:zftp:zfget}': the style will then have the given value only +in the @t{zfget} function, and will override styles set under `@t{:zftp:*}'. +Note that only the top level function name, as called by +the user, is used; calling of lower level functions is transparent to the +user. Hence modifications to the title bar in @t{zftp_chpwd} use the +contexts @t{:zftp:zfopen}, @t{:zftp:zfcd}, etc., depending where it was +called from. The following styles are understood: + +@noindent +@table @asis +@kindex progress, zftp style +@item @t{progress} +Controls the way that @t{zftp_progress} reports on the progress of a +transfer. If empty, unset, or `@t{none}', no progress report is made; if +`@t{bar}' a growing bar of inverse video is shown; if `@t{percent}' (or any +other string, though this may change in future), the percentage of the file +transferred is shown. The bar meter requires that the width of the +terminal be available via the @t{$COLUMNS} parameter (normally this is set +automatically). If the size of the file being transferred is not +available, @t{bar} and @t{percent} meters will simply show the number of +bytes transferred so far. + +@noindent +When @t{zfinit} is run, if this style is not defined for the context +@t{:zftp:*}, it will be set to `bar'. + +@kindex update, zftp style +@item @t{update} +Specifies the minimum time interval between updates of the progress meter +in seconds. No update is made unless new data has been received, so the +actual time interval is limited only by @t{$ZFTP_TIMEOUT}. + +@noindent +As described for @t{progress}, @t{zfinit} will force this to default to 1. + +@kindex remote-glob, zftp style +@item @t{remote-glob} +If set to `@t{1}', `@t{yes}' or `@t{true}', filename generation (globbing) is +performed on the remote machine instead of by zsh itself; see below. + +@kindex titlebar, zftp style +@item @t{titlebar} +If set to `@t{1}', `@t{yes}' or `@t{true}', @t{zftp_chpwd} will put the remote host and +remote directory into the titlebar of terminal emulators such as xterm or +sun-cmd that allow this. + +@noindent +As described for @t{progress}, @t{zfinit} will force this to default to 1. + +@kindex chpwd, zftp style +@item @t{chpwd} +If set to `@t{1}' `@t{yes}' or `@t{true}', @t{zftp_chpwd} will call the function +@t{chpwd} when a connection is closed. This is useful if the remote host +details were put into the terminal title bar by @t{zftp_chpwd} and your +usual @t{chpwd} also modifies the title bar. + +@noindent +When @t{zfinit} is run, it will determine whether @t{chpwd} exists and if +so it will set the default value for the style to 1 if none exists +already. + +@end table + +@noindent +Note that there is also an associative array @t{zfconfig} which contains +values used by the function system. This should not be modified or +overwritten. + +@noindent + +@subsection Remote globbing +@noindent +@cindex zftp function system, remote globbing + +@noindent +The commands for retrieving files usually perform filename generation +(globbing) on their arguments; this can be turned off by passing the option +@t{-G} to each of the commands. Normally this operates by retrieving a +complete list of files for the directory in question, then matching these +locally against the pattern supplied. This has the advantage that the full +range of zsh patterns (respecting the setting of the option +@t{EXTENDED_GLOB}) can be used. However, it means that the directory part +of a filename will not be expanded and must be given exactly. If the +remote server does not support the UNIX directory semantics, directory +handling is problematic and it is recommended that globbing only be used +within the current directory. The list of files in the current directory, +if retrieved, will be cached, so that subsequent globs in the same +directory without an intervening @t{zfcd} are much faster. + +@noindent +If the @t{remote-glob} style (see above) is set, globbing is instead +performed on the remote host: the server is asked for a list of matching +files. This is highly dependent on how the server is implemented, though +typically UNIX servers will provide support for basic glob patterns. This +may in some cases be faster, as it avoids retrieving the entire list of +directory contents. + +@noindent + +@subsection Automatic and temporary reopening +@noindent +@cindex zftp function system, automatic reopening + +@noindent +As described for the @t{zfopen} command, a subsequent @t{zfopen} with no +parameters will reopen the connection to the last host (this includes +connections made with the @t{zfanon} command). Opened in this fashion, the +connection starts in the default remote directory and will remain open +until explicitly closed. + +@noindent +Automatic re-opening is also available. If a connection is not currently +open and a command requiring a connection is given, the last connection is +implicitly reopened. In this case the directory which was current when the +connection was closed again becomes the current directory (unless, of +course, the command given changes it). Automatic reopening will also take +place if the connection was close by the remote server for whatever reason +(e.g. a timeout). It is not available if the @t{-1} option to @t{zfopen} +or @t{zfanon} was used. + +@noindent +Furthermore, if the command issued is a file transfer, the connection will +be closed after the transfer is finished, hence providing a one-shot mode +for transfers. This does not apply to directory changing or listing +commands; for example a @t{zfdir} may reopen a connection but will leave it +open. Also, automatic closure will only ever happen in the same command as +automatic opening, i.e a @t{zfdir} directly followed by a @t{zfget} will +never close the connection automatically. + +@noindent +Information about the previous connection is given by the @t{zfstat} +function. So, for example, if that reports: + +@noindent +@example +Session: default +Not connected. +Last session: ftp.bar.com:/pub/textfiles +@end example + +@noindent +then the command @t{zfget file.txt} will attempt to reopen a connection to +@t{ftp.bar.com}, retrieve the file @t{/pub/textfiles/file.txt}, and +immediately close the connection again. On the other hand, @t{zfcd ..} +will open the connection in the directory @t{/pub} and leave it open. + +@noindent +Note that all the above is local to each session; if you return to a +previous session, the connection for that session is the one which will be +reopened. + +@noindent + +@subsection Completion +@noindent + +@noindent +Completion of local and remote files, directories, sessions and bookmarks +is supported. The older, @t{compctl}-style completion is defined when +@t{zfinit} is called; support for the new widget-based completion system is +provided in the function @t{Completion/Zsh/Command/_zftp}, which should be +installed with the other functions of the completion system and hence +should automatically be available. +@c (avoiding a yodl bug) +@c Yodl file: Zsh/contrib.yo +@node User Contributions, , Zftp Function System, Top + +@chapter User Contributions +@noindent +@cindex user contributions + +@section Description +@noindent + +@noindent +The Zsh source distribution includes a number of items contributed by the +user community. These are not inherently a part of the shell, and some +may not be available in every zsh installation. The most significant of +these are documented here. For documentation on other contributed items +such as shell functions, look for comments in the function source files. + +@noindent +@menu +* Utilities:: +* Recent Directories:: +* Other Directory Functions:: +* Version Control Information:: +* Prompt Themes:: +* ZLE Functions:: +* Exception Handling:: +* MIME Functions:: +* Mathematical Functions:: +* User Configuration Functions:: +* Other Functions:: +@end menu + +@noindent +@node Utilities, Recent Directories, , User Contributions + +@section Utilities +@noindent + +@noindent + +@subsection Accessing On-Line Help +@noindent +@cindex helpfiles utility + +@noindent +The key sequence @t{ESC h} is normally bound by ZLE to execute the +@t{run-help} widget (see +@ref{Zsh Line Editor}). This invokes the @t{run-help} command with the command word from the +current input line as its argument. By default, @t{run-help} is an alias +for the @t{man} command, so this often fails when the command word is a +shell builtin or a user-defined function. By redefining the @t{run-help} +alias, one can improve the on-line help provided by the shell. + +@noindent +The @t{helpfiles} utility, found in the @t{Util} directory of the +distribution, is a Perl program that can be used to process the zsh manual +to produce a separate help file for each shell builtin and for many other +shell features as well. The autoloadable @t{run-help} function, found in +@t{Functions/Misc}, searches for these helpfiles and performs several +other tests to produce the most complete help possible for the command. + +@noindent +Help files are installed by default to a subdirectory of @t{/usr/share/zsh} +or @t{/usr/local/share/zsh}. + +@noindent +To create your own help files with @t{helpfiles}, choose or create a +directory where the individual command help files will reside. For +example, you might choose @t{~/zsh_help}. If you unpacked the zsh +distribution in your home directory, you would use the commands: + +@noindent +@example +mkdir ~/zsh_help +perl ~/zsh-5.8.1.3-test/Util/helpfiles ~/zsh_help +@end example + +@noindent +@vindex HELPDIR +The @t{HELPDIR} parameter tells @t{run-help} where to look for the help +files. When unset, it uses the default installation path. +To use your own set of help files, set this to the appropriate path +in one of your startup files: + +@noindent +@example +HELPDIR=~/zsh_help +@end example + +@noindent +@findex run-help, use of +To use the @t{run-help} function, you need to add lines something +like the following to your @t{.zshrc} or equivalent startup file: + +@noindent +@example +unalias run-help +autoload run-help +@end example + +@noindent +Note that in order for `@t{autoload run-help}' to work, the @t{run-help} +file must be in one of the directories named in your @t{fpath} array (see +@ref{Parameters Used By The Shell}). This should already be the case if you have a standard zsh +installation; if it is not, copy @t{Functions/Misc/run-help} to an +appropriate directory. + +@noindent + +@subsection Recompiling Functions +@noindent +@cindex functions, recompiling +@cindex zrecompile utility + +@noindent +If you frequently edit your zsh functions, or periodically update your zsh +installation to track the latest developments, you may find that function +digests compiled with the @t{zcompile} builtin are frequently out of date +with respect to the function source files. This is not usually a problem, +because zsh always looks for the newest file when loading a function, but +it may cause slower shell startup and function loading. Also, if a digest +file is explicitly used as an element of @t{fpath}, zsh won't check whether +any of its source files has changed. + +@noindent +The @t{zrecompile} autoloadable function, found in @t{Functions/Misc}, can +be used to keep function digests up to date. + +@noindent +@table @asis +@findex zrecompile +@item @t{zrecompile} [ @t{-qt} ] [ @var{name} ... ] +@itemx @t{zrecompile} [ @t{-qt} ] @t{-p} @var{arg} ... [ @t{-}@t{-} @var{arg} ... ] +This tries to find @t{*.zwc} files and automatically re-compile them if at +least one of the original files is newer than the compiled file. This +works only if the names stored in the compiled files are full paths or are +relative to the directory that contains the @t{.zwc} file. + +@noindent +In the first form, each @var{name} is the name of a compiled file or a +directory containing @t{*.zwc} files that should be checked. If no +arguments are given, the directories and @t{*.zwc} files in @t{fpath} are +used. + +@noindent +When @t{-t} is given, no compilation is performed, but a return status of +zero (true) is set if there are files that need to be re-compiled and +non-zero (false) otherwise. The @t{-q} option quiets the chatty output +that describes what @t{zrecompile} is doing. + +@noindent +Without the @t{-t} option, the return status is zero if all files that +needed re-compilation could be compiled and non-zero if compilation for at +least one of the files failed. + +@noindent +If the @t{-p} option is given, the @var{arg}s are interpreted as one +or more sets of arguments for @t{zcompile}, separated by `@t{-}@t{-}'. +For example: + +@noindent +@example +zrecompile -p \ + -R ~/.zshrc -- \ + -M ~/.zcompdump -- \ + ~/zsh/comp.zwc ~/zsh/Completion/*/_* +@end example + +@noindent +This compiles @t{~/.zshrc} into @t{~/.zshrc.zwc} if that doesn't exist or +if it is older than @t{~/.zshrc}. The compiled file will be marked for +reading instead of mapping. The same is done for @t{~/.zcompdump} and +@t{~/.zcompdump.zwc}, but this compiled file is marked for mapping. The +last line re-creates the file @t{~/zsh/comp.zwc} if any of the files +matching the given pattern is newer than it. + +@noindent +Without the @t{-p} option, @t{zrecompile} does not create function digests +that do not already exist, nor does it add new functions to the digest. + +@end table + +@noindent +The following shell loop is an example of a method for creating function +digests for all functions in your @t{fpath}, assuming that you have write +permission to the directories: + +@noindent +@example +for ((i=1; i <= $#fpath; ++i)); do + dir=$fpath[i] + zwc=$@{dir:t@}.zwc + if [[ $dir == (.|..) || $dir == (.|..)/* ]]; then + continue + fi + files=($dir/*(N-.)) + if [[ -w $dir:h && -n $files ]]; then + files=($@{$@{(M)files%/*/*@}#/@}) + if ( cd $dir:h && + zrecompile -p -U -z $zwc $files ); then + fpath[i]=$fpath[i].zwc + fi + fi +done +@end example + +@noindent +The @t{-U} and @t{-z} options are appropriate for functions in the default +zsh installation @t{fpath}; you may need to use different options for your +personal function directories. + +@noindent +Once the digests have been created and your @t{fpath} modified to refer to +them, you can keep them up to date by running @t{zrecompile} with no +arguments. + +@noindent + +@subsection Keyboard Definition +@noindent +@cindex keyboard definition + +@noindent +@findex zkbd +The large number of possible combinations of keyboards, workstations, +terminals, emulators, and window systems makes it impossible for zsh to +have built-in key bindings for every situation. The @t{zkbd} utility, +found in @t{Functions/Misc}, can help you quickly create key bindings for your +configuration. + +@noindent +Run @t{zkbd} either as an autoloaded function, or as a shell script: + +@noindent +@example +zsh -f ~/zsh-5.8.1.3-test/Functions/Misc/zkbd +@end example + +@noindent +When you run @t{zkbd}, it first asks you to enter your terminal type; if +the default it offers is correct, just press return. It then asks you to +press a number of different keys to determine characteristics of your +keyboard and terminal; @t{zkbd} warns you if it finds anything out of the +ordinary, such as a Delete key that sends neither @t{^H} nor @t{^?}. + +@noindent +The keystrokes read by @t{zkbd} are recorded as a definition for an +associative array named @t{key}, written to a file in the subdirectory +@t{.zkbd} within either your @t{HOME} or @t{ZDOTDIR} directory. The name +of the file is composed from the @t{TERM}, @t{VENDOR} and @t{OSTYPE} +parameters, joined by hyphens. + +@noindent +You may read this file into your @t{.zshrc} or another startup file with +the `@t{source}' or `@t{.}' commands, then reference the @t{key} parameter +in bindkey commands, like this: + +@noindent +@example +source $@{ZDOTDIR:-$HOME@}/.zkbd/$TERM-$VENDOR-$OSTYPE +[[ -n $@{key[Left]@} ]] && bindkey "$@{key[Left]@}" backward-char +[[ -n $@{key[Right]@} ]] && bindkey "$@{key[Right]@}" forward-char +# etc. +@end example + +@noindent +Note that in order for `@t{autoload zkbd}' to work, the @t{zkdb} file must +be in one of the directories named in your @t{fpath} array (see +@ref{Parameters Used By The Shell}). This should already be the case if you have a standard zsh +installation; if it is not, copy @t{Functions/Misc/zkbd} to an +appropriate directory. + +@noindent + +@subsection Dumping Shell State +@noindent +@cindex reporter utility + +@noindent +Occasionally you may encounter what appears to be a bug in the shell, +particularly if you are using a beta version of zsh or a development +release. Usually it is sufficient to send a description of the +problem to one of the zsh mailing lists (see +@ref{Mailing Lists}), but sometimes one of the zsh developers will need to recreate your +environment in order to track the problem down. + +@noindent +The script named @t{reporter}, found in the @t{Util} directory of the +distribution, is provided for this purpose. (It is also possible to +@t{autoload reporter}, but @t{reporter} is not installed in @t{fpath} +by default.) This script outputs a detailed dump of the shell state, +in the form of another script that can be read with `@t{zsh -f}' to +recreate that state. + +@noindent +To use @t{reporter}, read the script into your shell with the `@t{.}' +command and redirect the output into a file: + +@noindent +@example +. ~/zsh-5.8.1.3-test/Util/reporter > zsh.report +@end example + +@noindent +You should check the @t{zsh.report} file for any sensitive information +such as passwords and delete them by hand before sending the script to the +developers. Also, as the output can be voluminous, it's best to wait for +the developers to ask for this information before sending it. + +@noindent +You can also use @t{reporter} to dump only a subset of the shell state. +This is sometimes useful for creating startup files for the first time. +Most of the output from reporter is far more detailed than usually is +necessary for a startup file, but the @t{aliases}, @t{options}, and +@t{zstyles} states may be useful because they include only changes from +the defaults. The @t{bindings} state may be useful if you have created +any of your own keymaps, because @t{reporter} arranges to dump the keymap +creation commands as well as the bindings for every keymap. + +@noindent +As is usual with automated tools, if you create a startup file with +@t{reporter}, you should edit the results to remove unnecessary commands. +Note that if you're using the new completion system, you should @emph{not} +dump the @t{functions} state to your startup files with @t{reporter}; use +the @t{compdump} function instead (see +@ref{Completion System}). + +@noindent +@table @asis +@item @t{reporter} [ @var{state} ... ] +@findex reporter +Print to standard output the indicated subset of the current shell state. +The @var{state} arguments may be one or more of: + +@noindent +@table @asis +@item @t{all} +Output everything listed below. +@item @t{aliases} +Output alias definitions. +@item @t{bindings} +Output ZLE key maps and bindings. +@item @t{completion} +Output old-style @t{compctl} commands. +New completion is covered by @t{functions} and @t{zstyles}. +@item @t{functions} +Output autoloads and function definitions. +@item @t{limits} +Output @t{limit} commands. +@item @t{options} +Output @t{setopt} commands. +@item @t{styles} +Same as @t{zstyles}. +@item @t{variables} +Output shell parameter assignments, plus @t{export} +commands for any environment variables. +@item @t{zstyles} +Output @t{zstyle} commands. +@end table + +@noindent +If the @var{state} is omitted, @t{all} is assumed. + + +@noindent +With the exception of `@t{all}', every @var{state} can be abbreviated by +any prefix, even a single letter; thus @t{a} is the same as @t{aliases}, +@t{z} is the same as @t{zstyles}, etc. +@end table + +@noindent + +@subsection Manipulating Hook Functions +@noindent +@cindex hook function utility + +@noindent +@table @asis +@findex add-zsh-hook +@item @t{add-zsh-hook} [ @t{-L} | @t{-dD} ] [ @t{-Uzk} ] @var{hook} @var{function} +Several functions are special to the shell, as described in the section +Special Functions, @ref{Functions}, +in that they are automatically called at specific points during shell execution. +Each has an associated array consisting of names of functions to be +called at the same point; these are so-called `hook functions'. +The shell function @t{add-zsh-hook} provides a simple way of adding or +removing functions from the array. + +@noindent +@var{hook} is one of @t{chpwd}, @t{periodic}, @t{precmd}, @t{preexec}, +@t{zshaddhistory}, @t{zshexit}, or @t{zsh_directory_name}, +the special functions in question. Note that @t{zsh_directory_name} +is called in a different way from the other functions, but may +still be manipulated as a hook. + +@noindent +@var{function} is name of an ordinary shell function. If no options +are given this will be added to the array of functions to be executed +in the given context. +Functions are invoked in the order they were added. + +@noindent +If the option @t{-L} is given, the current values for the hook arrays +are listed with @t{typeset}. + +@noindent +If the option @t{-d} is given, the @var{function} is removed from +the array of functions to be executed. + +@noindent +If the option @t{-D} is given, the @var{function} is treated as a pattern +and any matching names of functions are removed from the array of +functions to be executed. + +@noindent +The options @t{-U}, @t{-z} and @t{-k} are passed as arguments to +@t{autoload} for @var{function}. For functions contributed with zsh, the +options @t{-Uz} are appropriate. + +@findex add-zle-hook-widget +@item @t{add-zle-hook-widget} [ @t{-L} | @t{-dD} ] [ @t{-Uzk} ] @var{hook} @var{widgetname} +Several widget names are special to the line editor, as described in the section +Special Widgets, @ref{Zle Widgets}, +in that they are automatically called at specific points during editing. +Unlike function hooks, these do not use a predefined array of other names +to call at the same point; the shell function @t{add-zle-hook-widget} +maintains a similar array and arranges for the special widget to invoke +those additional widgets. + +@noindent +@var{hook} is one of @t{isearch-exit}, @t{isearch-update}, +@t{line-pre-redraw}, @t{line-init}, @t{line-finish}, @t{history-line-set}, +or @t{keymap-select}, corresponding to each of the special widgets +@t{zle-isearch-exit}, etc. The special widget names are also accepted +as the @var{hook} argument. + +@noindent +@var{widgetname} is the name of a ZLE widget. If no options are given this +is added to the array of widgets to be invoked in the given hook context. +Widgets are invoked in the order they were added, with +@example +@t{zle }@var{widgetname}@t{ -Nw -f "nolast" -- "$@@"} +@end example + +@noindent +@vindex WIDGET, in hooks +Note that this means that the `@t{WIDGET}' special parameter tracks the +@var{widgetname} when the widget function is called, rather than tracking +the name of the corresponding special hook widget. + +@noindent +If the option @t{-d} is given, the @var{widgetname} is removed from +the array of widgets to be executed. + +@noindent +If the option @t{-D} is given, the @var{widgetname} is treated as a pattern +and any matching names of widgets are removed from the array. + +@noindent +If @var{widgetname} does not name an existing widget when added to the +array, it is assumed that a shell function also named @var{widgetname} is +meant to provide the implementation of the widget. This name is therefore +marked for autoloading, and the options @t{-U}, @t{-z} and @t{-k} are +passed as arguments to @t{autoload} as with @t{add-zsh-hook}. The +widget is also created with `@t{zle -N }@var{widgetname}' to cause the +corresponding function to be loaded the first time the hook is called. + +@noindent +The arrays of @var{widgetname} are currently maintained in @t{zstyle} +contexts, one for each @var{hook} context, with a style of `@t{widgets}'. +If the @t{-L} option is given, this set of styles is listed with +`@t{zstyle -L}'. This implementation may change, and the special widgets +that refer to the styles are created only if @t{add-zle-hook-widget} is +called to add at least one widget, so if this function is used for any +hooks, then all hooks should be managed only via this function. + +@end table + +@noindent +@node Recent Directories, Other Directory Functions, Utilities, User Contributions +@cindex recent directories, maintaining list of +@cindex directories, maintaining list of recent +@findex cdr +@findex _cdr +@findex chpwd_recent_add +@findex chpwd_recent_dirs +@findex chpwd_recent_filehandler + +@section Remembering Recent Directories +@noindent + +@noindent +The function @t{cdr} allows you to change the working directory to a +previous working directory from a list maintained automatically. It is +similar in concept to the directory stack controlled by the @t{pushd}, +@t{popd} and @t{dirs} builtins, but is more configurable, and as it stores +all entries in files it is maintained across sessions and (by default) +between terminal emulators in the current session. Duplicates are +automatically removed, so that the list reflects the single most recent +use of each directory. + +@noindent +Note that the @t{pushd} directory stack is not actually modified or used +by @t{cdr} unless you configure it to do so as described in the +configuration section below. + +@noindent + +@subsection Installation +@noindent + +@noindent +The system works by means of a hook function that is called every time the +directory changes. To install the system, autoload the required functions +and use the @t{add-zsh-hook} function described above: + +@noindent +@example +autoload -Uz chpwd_recent_dirs cdr add-zsh-hook +add-zsh-hook chpwd chpwd_recent_dirs +@end example + +@noindent +Now every time you change directly interactively, no matter which +command you use, the directory to which you change will be remembered +in most-recent-first order. + +@noindent + +@subsection Use +@noindent + +@noindent +All direct user interaction is via the @t{cdr} function. + +@noindent +The argument to cdr is a number @var{N} corresponding to the @var{N}th most +recently changed-to directory. 1 is the immediately preceding directory; +the current directory is remembered but is not offered as a destination. +Note that if you have multiple windows open 1 may refer to a directory +changed to in another window; you can avoid this by having per-terminal +files for storing directory as described for the +@t{recent-dirs-file} style below. + +@noindent +If you set the @t{recent-dirs-default} style described below @t{cdr} +will behave the same as @t{cd} if given a non-numeric argument, or more +than one argument. The recent directory list is updated just the same +however you change directory. + +@noindent +If the argument is omitted, 1 is assumed. This is similar to @t{pushd}'s +behaviour of swapping the two most recent directories on the stack. + +@noindent +Completion for the argument to @t{cdr} is available if compinit has been +run; menu selection is recommended, using: + +@noindent +@example +zstyle ':completion:*:*:cdr:*:*' menu selection +@end example + +@noindent +to allow you to cycle through recent directories; the order is preserved, +so the first choice is the most recent directory before the current one. +The verbose style is also recommended to ensure the directory is shown; this +style is on by default so no action is required unless you have changed it. + +@noindent + +@subsection Options +@noindent + +@noindent +The behaviour of @t{cdr} may be modified by the following options. + +@noindent +@table @asis +@item @t{-l} +lists the numbers and the corresponding directories in +abbreviated form (i.e. with @t{~} substitution reapplied), one per line. +The directories here are not quoted (this would only be an issue if a +directory name contained a newline). This is used by the completion +system. + +@item @t{-r} +sets the variable @t{reply} to the current set of directories. Nothing +is printed and the directory is not changed. + +@item @t{-e} +allows you to edit the list of directories, one per line. The +list can be edited to any extent you like; no sanity checking is +performed. Completion is available. No quoting is necessary (except for +newlines, where I have in any case no sympathy); directories are in +unabbreviated form and contain an absolute path, i.e. they start with @t{/}. +Usually the first entry should be left as the current directory. + +@item @t{-p '}@var{pattern}@t{'} +Prunes any items in the directory list that match the given extended glob +pattern; the pattern needs to be quoted from immediate expansion on the +command line. The pattern is matched against each completely expanded +file name in the list; the full string must match, so wildcards at the +end (e.g. @t{'*removeme*'}) are needed to remove entries with a given +substring. + +@noindent +If output is to a terminal, then the function will print the new list +after pruning and prompt for confirmation by the user. This output and +confirmation step can be skipped by using @t{-P} instead of @t{-p}. + +@end table + +@noindent + +@subsection Configuration +@noindent + +@noindent +Configuration is by means of the styles mechanism that should be familiar +from completion; if not, see the description of the @t{zstyle} command in +@ref{The zsh/zutil Module}. The context for setting styles +should be @t{':chpwd:*'} in case the meaning of the context is extended in +future, for example: + +@noindent +@example +zstyle ':chpwd:*' recent-dirs-max 0 +@end example + +@noindent +sets the value of the @t{recent-dirs-max} style to 0. In practice the +style name is specific enough that a context of '*' should be fine. + +@noindent +An exception is @t{recent-dirs-insert}, which is used exclusively by the +completion system and so has the usual completion system context +(@t{':completion:*'} if nothing more specific is needed), though again +@t{'*'} should be fine in practice. + +@noindent +@table @asis +@item @t{recent-dirs-default} +If true, and the command is expecting a recent directory index, and +either there is more than one argument or the argument is not an +integer, then fall through to "cd". This allows the lazy to use only +one command for directory changing. Completion recognises this, too; +see recent-dirs-insert for how to control completion when this option +is in use. + +@item @t{recent-dirs-file} +The file where the list of directories is saved. The default +is @t{$@{ZDOTDIR:-$HOME@}/.chpwd-recent-dirs}, i.e. this is in your +home directory unless you have set the variable @t{ZDOTDIR} to point +somewhere else. Directory names are saved in @t{$'}@var{...}@t{'} quoted +form, so each line in the file can be supplied directly to the shell as an +argument. + +@noindent +The value of this style may be an array. In this case, the first +file in the list will always be used for saving directories while any +other files are left untouched. When reading the recent directory +list, if there are fewer than the maximum number of entries in the +first file, the contents of later files in the array will be appended +with duplicates removed from the list shown. The contents of the two +files are not sorted together, i.e. all the entries in the first file +are shown first. The special value @t{+} can appear in the list to +indicate the default file should be read at that point. This allows +effects like the following: + +@noindent +@example +zstyle ':chpwd:*' recent-dirs-file \ +~/.chpwd-recent-dirs-$@{TTY##*/@} + +@end example + +@noindent +Recent directories are read from a file numbered according to +the terminal. If there are insufficient entries the list +is supplemented from the default file. + +@noindent +It is possible to use @t{zstyle -e} to make the directory configurable +at run time: + +@noindent +@example +zstyle -e ':chpwd:*' recent-dirs-file pick-recent-dirs-file +pick-recent-dirs-file() @{ + if [[ $PWD = ~/text/writing(|/*) ]]; then + reply=(~/.chpwd-recent-dirs-writing) + else + reply=(+) + fi +@} +@end example + +@noindent +In this example, if the current directory is @t{~/text/writing} or a +directory under it, then use a special file for saving recent +directories, else use the default. + +@item @t{recent-dirs-insert} +Used by completion. If @t{recent-dirs-default} is true, then setting +this to @t{true} causes the actual directory, rather than its index, to +be inserted on the command line; this has the same effect as using +the corresponding index, but makes the history clearer and the line +easier to edit. With this setting, if part of an argument was +already typed, normal directory completion rather than recent +directory completion is done; this is because recent directory +completion is expected to be done by cycling through entries menu +fashion. + +@noindent +If the value of the style is @t{always}, then only recent directories will +be completed; in that case, use the @t{cd} command when you want to +complete other directories. + +@noindent +If the value is @t{fallback}, recent directories will be tried first, then +normal directory completion is performed if recent directory completion +failed to find a match. + +@noindent +Finally, if the value is @t{both} then both sets of completions are +presented; the usual tag mechanism can be used to distinguish results, with +recent directories tagged as @t{recent-dirs}. Note that the recent +directories inserted are abbreviated with directory names where appropriate. + +@item @t{recent-dirs-max} +The maximum number of directories to save to the file. If +this is zero or negative there is no maximum. The default is 20. +Note this includes the current directory, which isn't offered, +so the highest number of directories you will be offered +is one less than the maximum. + +@item @t{recent-dirs-prune} +This style is an array determining what directories should (or should +not) be added to the recent list. Elements of the array can include: + +@noindent +@table @asis +@item @t{parent} +Prune parents (more accurately, ancestors) from the recent list. +If present, changing directly down by any number of directories +causes the current directory to be overwritten. For example, +changing from ~pws to ~pws/some/other/dir causes ~pws not to be +left on the recent directory stack. This only applies to direct +changes to descendant directories; earlier directories on the +list are not pruned. For example, changing from ~pws/yet/another +to ~pws/some/other/dir does not cause ~pws to be pruned. + +@item @t{pattern:}@var{pattern} +Gives a zsh pattern for directories that should not be +added to the recent list (if not already there). This element +can be repeated to add different patterns. For example, +@t{'pattern:/tmp(|/*)'} stops @t{/tmp} or its descendants +from being added. The @t{EXTENDED_GLOB} option is always turned on +for these patterns. + +@end table + +@item @t{recent-dirs-pushd} +If set to true, @t{cdr} will use @t{pushd} instead of @t{cd} to change the +directory, so the directory is saved on the directory stack. As the +directory stack is completely separate from the list of files saved +by the mechanism used in this file there is no obvious reason to do +this. + +@end table + +@noindent + +@subsection Use with dynamic directory naming +@noindent + +@noindent +It is possible to refer to recent directories using the dynamic directory +name syntax by using the supplied function @t{zsh_directory_name_cdr} +a hook: + +@noindent +@example +autoload -Uz add-zsh-hook +add-zsh-hook -Uz zsh_directory_name zsh_directory_name_cdr +@end example + +@noindent +When this is done, @t{~[1]} will refer to the most recent +directory other than $PWD, and so on. Completion after @t{~[}@var{...} +also works. + +@noindent + +@subsection Details of directory handling +@noindent + +@noindent +This section is for the curious or confused; most users will not +need to know this information. + +@noindent +Recent directories are saved to a file immediately and hence are +preserved across sessions. Note currently no file locking is applied: +the list is updated immediately on interactive commands and nowhere else +(unlike history), and it is assumed you are only going to change +directory in one window at once. This is not safe on shared accounts, +but in any case the system has limited utility when someone else is +changing to a different set of directories behind your back. + +@noindent +To make this a little safer, only directory changes instituted from the +command line, either directly or indirectly through shell function calls +(but not through subshells, evals, traps, completion functions and the +like) are saved. Shell functions should use @t{cd -q} or @t{pushd -q} to +avoid side effects if the change to the directory is to be invisible at the +command line. See the contents of the function @t{chpwd_recent_dirs} for +more details. + +@noindent +@node Other Directory Functions, Version Control Information, Recent Directories, User Contributions +@cindex directories, named, dynamic, helper function +@cindex dynamic directory naming, helper function +@cindex named directories, dynamic, helper function +@findex zsh_directory_name_generic + +@section Abbreviated dynamic references to directories +@noindent + +@noindent +The dynamic directory naming system is described in the subsection +@emph{Dynamic named directories} of +@ref{Filename Expansion}. In this, a reference to +@t{~[}@var{...}@t{]} is expanded by a function found by the hooks +mechanism. + +@noindent +The contributed function @t{zsh_directory_name_generic} provides a +system allowing the user to refer to directories with only a limited +amount of new code. It supports all three of the standard interfaces +for directory naming: converting from a name to a directory, converting +in the reverse direction to find a short name, and completion of names. + +@noindent +The main feature of this function is a path-like syntax, +combining abbreviations at multiple levels separated by ":". +As an example, ~[g:p:s] might specify: +@table @asis +@item @t{g} +The top level directory for your git area. This first component +has to match, or the function will return indicating another +directory name hook function should be tried. + +@item @t{p} +The name of a project within your git area. + +@item @t{s} +The source area within that project. + +@end table +This allows you to collapse references to long hierarchies to a very +compact form, particularly if the hierarchies are similar across different +areas of the disk. + +@noindent +Name components may be completed: if a description is shown at the top +of the list of completions, it includes the path to which previous +components expand, while the description for an individual completion +shows the path segment it would add. No additional configuration is +needed for this as the completion system is aware of the dynamic +directory name mechanism. + +@noindent + +@subsection Usage +@noindent + +@noindent +To use the function, first define a wrapper function for your specific +case. We'll assume it's to be autoloaded. This can have any name but +we'll refer to it as zdn_mywrapper. This wrapper function will define +various variables and then call this function with the same arguments +that the wrapper function gets. This configuration is described below. + +@noindent +Then arrange for the wrapper to be run as a zsh_directory_name hook: + +@noindent +@example +autoload -Uz add-zsh-hook zsh_directory_name_generic zdn_mywrapper +add-zsh-hook -U zsh_directory_name zdn_mywrapper +@end example + +@noindent + +@subsection Configuration +@noindent + +@noindent +The wrapper function should define a local associative array zdn_top. +Alternatively, this can be set with a style called @t{mapping}. The +context for the style is @t{:zdn:}@var{wrapper-name} where +@var{wrapper-name} is the function calling zsh_directory_name_generic; +for example: + +@noindent +@example +zstyle :zdn:zdn_mywrapper: mapping zdn_mywrapper_top +@end example + +@noindent +The keys in this associative array correspond to the first component of +the name. The values are matching directories. They may have an +optional suffix with a slash followed by a colon and the name of a +variable in the same format to give the next component. (The slash +before the colon is to disambiguate the case where a colon is needed in +the path for a drive. There is otherwise no syntax for escaping this, +so path components whose names start with a colon are not supported.) A +special component @t{:default:} specifies a variable in the form +@t{/:}@var{var} (the path section is ignored and so is usually empty) +that will be used for the next component if no variable is given for the +path. Variables referred to within @t{zdn_top} have the same format as +@t{zdn_top} itself, but contain relative paths. + +@noindent +For example, + +@noindent +@example +local -A zdn_top=( + g ~/git + ga ~/alternate/git + gs /scratch/$USER/git/:second2 + :default: /:second1 +) +@end example + +@noindent +This specifies the behaviour of a directory referred to as @t{~[g:...]} +or @t{~[ga:...]} or @t{~[gs:...]}. Later path components are optional; +in that case @t{~[g]} expands to @t{~/git}, and so on. @t{gs} expands +to @t{/scratch/$USER/git} and uses the associative array @t{second2} to +match the second component; @t{g} and @t{ga} use the associative array +@t{second1} to match the second component. + +@noindent +When expanding a name to a directory, if the first component is not @t{g} or +@t{ga} or @t{gs}, it is not an error; the function simply returns 1 so that a +later hook function can be tried. However, matching the first component +commits the function, so if a later component does not match, an error +is printed (though this still does not stop later hooks from being +executed). + +@noindent +For components after the first, a relative path is expected, but note that +multiple levels may still appear. Here is an example of @t{second1}: + +@noindent +@example +local -A second1=( + p myproject + s somproject + os otherproject/subproject/:third +) +@end example + +@noindent +The path as found from @t{zdn_top} is extended with the matching +directory, so @t{~[g:p]} becomes @t{~/git/myproject}. The slash between +is added automatically (it's not possible to have a later component +modify the name of a directory already matched). Only @t{os} specifies +a variable for a third component, and there's no @t{:default:}, so it's +an error to use a name like @t{~[g:p:x]} or @t{~[ga:s:y]} because +there's nowhere to look up the @t{x} or @t{y}. + +@noindent +The associative arrays need to be visible within this function; the +generic function therefore uses internal variable names beginning +@t{_zdn_} in order to avoid clashes. Note that the variable @t{reply} +needs to be passed back to the shell, so should not be local in the +calling function. + +@noindent +The function does not test whether directories assembled by component +actually exist; this allows the system to work across automounted +file systems. The error from the command trying to use a non-existent +directory should be sufficient to indicate the problem. + +@noindent + +@subsection Complete example +@noindent + +@noindent +Here is a full fictitious but usable autoloadable definition of the +example function defined by the code above. So @t{~[gs:p:s]} expands +to @t{/scratch/$USER/git/myscratchproject/top/srcdir} (with @t{$USER} +also expanded). + +@noindent +@example +local -A zdn_top=( + g ~/git + ga ~/alternate/git + gs /scratch/$USER/git/:second2 + :default: /:second1 +) + +local -A second1=( + p myproject + s somproject + os otherproject/subproject/:third +) + +local -A second2=( + p myscratchproject + s somescratchproject +) + +local -A third=( + s top/srcdir + d top/documentation +) + +# autoload not needed if you did this at initialisation... +autoload -Uz zsh_directory_name_generic +zsh_directory_name_generic "$@@ +@end example + +@noindent +It is also possible to use global associative arrays, suitably named, +and set the style for the context of your wrapper function to +refer to this. Then your set up code would contain the following: + +@noindent +@example +typeset -A zdn_mywrapper_top=(...) +# ... and so on for other associative arrays ... +zstyle ':zdn:zdn_mywrapper:' mapping zdn_mywrapper_top +autoload -Uz add-zsh-hook zsh_directory_name_generic zdn_mywrapper +add-zsh-hook -U zsh_directory_name zdn_mywrapper +@end example + +@noindent +and the function @t{zdn_mywrapper} would contain only the following: + +@noindent +@example +zsh_directory_name_generic "$@@" +@end example + +@noindent +@node Version Control Information, Prompt Themes, Other Directory Functions, User Contributions + +@section Gathering information from version control systems +@noindent +@cindex version control utility + +@noindent +In a lot of cases, it is nice to automatically retrieve information from +version control systems (VCSs), such as subversion, CVS or git, to be able +to provide it to the user; possibly in the user's prompt. So that you can +instantly tell which branch you are currently on, for example. + +@noindent +In order to do that, you may use the @t{vcs_info} function. + +@noindent +The following VCSs are supported, showing the abbreviated name by which +they are referred to within the system: +@table @asis +@item Bazaar (@t{bzr}) +@t{@uref{https://bazaar.canonical.com/}} +@item Codeville (@t{cdv}) +@t{@uref{http://freecode.com/projects/codeville/}} +@item Concurrent Versioning System (@t{cvs}) +@t{@uref{https://www.nongnu.org/cvs/}} +@item Darcs (@t{darcs}) +@t{@uref{http://darcs.net/}} +@item Fossil (@t{fossil}) +@t{@uref{https://fossil-scm.org/}} +@item Git (@t{git}) +@t{@uref{https://git-scm.com/}} +@item GNU arch (@t{tla}) +@t{@uref{https://www.gnu.org/software/gnu-arch/}} +@item Mercurial (@t{hg}) +@t{@uref{https://www.mercurial-scm.org/}} +@item Monotone (@t{mtn}) +@t{@uref{https://monotone.ca/}} +@item Perforce (@t{p4}) +@t{@uref{https://www.perforce.com/}} +@item Subversion (@t{svn}) +@t{@uref{https://subversion.apache.org/}} +@item SVK (@t{svk}) +@t{@uref{https://svk.bestpractical.com/}} +@end table + +@noindent +There is also support for the patch management system @t{quilt} +(@t{@uref{https://savannah.nongnu.org/projects/quilt}}). See +@ref{vcs_info Quilt Support} +below for details. + +@noindent +To load @t{vcs_info}: + +@noindent +@example +autoload -Uz vcs_info +@end example + +@noindent +It can be used in any existing prompt, because it does not require any +specific @t{$psvar} entries to be available. + +@noindent +@menu +* vcs_info Quickstart:: +* vcs_info Configuration:: +* vcs_info Oddities:: +* vcs_info Quilt Support:: +* vcs_info API:: +* vcs_info Variables:: +* vcs_info Hooks:: +* vcs_info Examples:: +@end menu + +@noindent +@node vcs_info Quickstart, vcs_info Configuration, , Version Control Information + +@subsection Quickstart +@noindent + +@noindent +To get this feature working quickly (including colors), you can do the +following (assuming, you loaded @t{vcs_info} properly - see above): + +@noindent +@example +zstyle ':vcs_info:*' actionformats \ + '%F@{5@}(%f%s%F@{5@})%F@{3@}-%F@{5@}[%F@{2@}%b%F@{3@}|%F@{1@}%a%F@{5@}]%f ' +zstyle ':vcs_info:*' formats \ + '%F@{5@}(%f%s%F@{5@})%F@{3@}-%F@{5@}[%F@{2@}%b%F@{5@}]%f ' +zstyle ':vcs_info:(sv[nk]|bzr):*' branchformat '%b%F@{1@}:%F@{3@}%r' +precmd () @{ vcs_info @} +PS1='%F@{5@}[%F@{2@}%n%F@{5@}] %F@{3@}%3~ $@{vcs_info_msg_0_@}%f%# ' +@end example + +@noindent +Obviously, the last two lines are there for demonstration. You need to +call @t{vcs_info} from your @t{precmd} function. Once that is done you need +a @emph{single quoted} @t{'$@{vcs_info_msg_0_@}'} in your prompt. + +@noindent +To be able to use @t{'$@{vcs_info_msg_0_@}'} directly in your prompt like +this, you will need to have the @t{PROMPT_SUBST} option enabled. + +@noindent +Now call the @t{vcs_info_printsys} utility from the command line: + +@noindent +@example +% vcs_info_printsys +## list of supported version control backends: +## disabled systems are prefixed by a hash sign (#) +bzr +cdv +cvs +darcs +fossil +git +hg +mtn +p4 +svk +svn +tla +## flavours (cannot be used in the enable or disable styles; they +## are enabled and disabled with their master [git-svn -> git]) +## they *can* be used in contexts: ':vcs_info:git-svn:*'. +git-p4 +git-svn +hg-git +hg-hgsubversion +hg-hgsvn +@end example + +@noindent +You may not want all of these because there is no point in running the +code to detect systems you do not use. So there is a way to disable +some backends altogether: + +@noindent +@example +zstyle ':vcs_info:*' disable bzr cdv darcs mtn svk tla +@end example + +@noindent +You may also pick a few from that list and enable only those: + +@noindent +@example +zstyle ':vcs_info:*' enable git cvs svn +@end example + +@noindent +If you rerun @t{vcs_info_printsys} after one of these commands, you will +see the backends listed in the @t{disable} style (or backends not in the +@t{enable} style - if you used that) marked as disabled by a hash sign. +That means the detection of these systems is skipped @emph{completely}. No +wasted time there. + +@noindent +@node vcs_info Configuration, vcs_info Oddities, vcs_info Quickstart, Version Control Information + +@subsection Configuration +@noindent + +@noindent +The @t{vcs_info} feature can be configured via @t{zstyle}. + +@noindent +First, the context in which we are working: +@example +:vcs_info:@var{vcs-string}:@var{user-context}:@var{repo-root-name} +@end example + +@noindent +@table @asis +@item @var{vcs-string} +is one of: @t{git}, @t{git-svn}, @t{git-p4}, @t{hg}, @t{hg-git}, +@t{hg-hgsubversion}, @t{hg-hgsvn}, @t{darcs}, @t{bzr}, @t{cdv}, @t{mtn}, +@t{svn}, @t{cvs}, @t{svk}, @t{tla}, @t{p4} or @t{fossil}. +This is followed by `@t{.quilt-}@var{quilt-mode}' in Quilt mode +(see @ref{vcs_info Quilt Support} for details) +and by `@t{+}@var{hook-name}' while hooks are active +(see @ref{vcs_info Hooks} for details). + +@noindent + +Currently, hooks in quilt mode don't add the `@t{.quilt-}@var{quilt-mode}' information. +This may change in the future. + +@item @var{user-context} +is a freely configurable string, assignable by +the user as the first argument to @t{vcs_info} (see its description +below). + +@item @var{repo-root-name} +is the name of a repository in which you want a +style to match. So, if you want a setting specific to @t{/usr/src/zsh}, +with that being a CVS checkout, you can set @var{repo-root-name} to +@t{zsh} to make it so. + +@end table + +@noindent +There are three special values for @var{vcs-string}: The first is named +@t{-init-}, that is in effect as long as there was no decision what VCS +backend to use. The second is @t{-preinit-}; it is used @emph{before} +@t{vcs_info} is run, when initializing the data exporting variables. The +third special value is @t{formats} and is used by the @t{vcs_info_lastmsg} +for looking up its styles. + +@noindent +The initial value of @var{repo-root-name} is @t{-all-} and it is replaced +with the actual name, as soon as it is known. Only use this part of the +context for defining the @t{formats}, @t{actionformats} or +@t{branchformat} styles, as it is guaranteed that @var{repo-root-name} is +set up correctly for these only. For all other styles, just use @t{'*'} +instead. + +@noindent +There are two pre-defined values for @var{user-context}: +@table @asis +@item @t{default} +the one used if none is specified +@item @t{command} +used by vcs_info_lastmsg to lookup its styles +@end table + +@noindent +You can of course use @t{':vcs_info:*'} to match all VCSs in all +user-contexts at once. + +@noindent +This is a description of all styles that are looked up. + +@noindent +@table @asis +@kindex formats +@item @t{formats} +A list of formats, used when actionformats is not used +(which is most of the time). + +@kindex actionformats +@item @t{actionformats} +A list of formats, used if there is a special +action going on in your current repository; like an interactive rebase or +a merge conflict. + +@kindex branchformat +@item @t{branchformat} +Some backends replace @t{%b} in the formats and +actionformats styles above, not only by a branch name but also by a +revision number. This style lets you modify how that string should look. + +@kindex nvcsformats +@item @t{nvcsformats} +These "formats" are set when we didn't detect a version control system +for the current directory or @t{vcs_info} was disabled. This is useful if +you want @t{vcs_info} to completely take over the generation of your +prompt. You would do something like @t{PS1='$@{vcs_info_msg_0_@}'} to +accomplish that. + +@kindex hgrevformat +@item @t{hgrevformat} +@t{hg} uses both a hash and a revision number to reference a specific +changeset in a repository. With this style you can format the revision +string (see @t{branchformat}) to include either or both. It's only +useful when @t{get-revision} is true. Note, the full 40-character revision id +is not available (except when using the @t{use-simple} option) because +executing hg more than once per prompt is too slow; you may customize this +behavior using hooks. + +@kindex max-exports +@item @t{max-exports} +Defines the maximum number of +@t{vcs_info_msg_*_} variables @t{vcs_info} will set. + +@kindex enable +@item @t{enable} +A list of backends you want to use. Checked in the @t{-init-} context. If +this list contains an item called @t{NONE} no backend is used at all and +@t{vcs_info} will do nothing. If this list contains @t{ALL}, @t{vcs_info} +will use all known backends. Only with @t{ALL} in @t{enable} will the +@t{disable} style have any effect. @t{ALL} and @t{NONE} are case insensitive. + +@kindex disable +@item @t{disable} +A list of VCSs you don't want @t{vcs_info} to test for +repositories (checked in the @t{-init-} context, too). Only used if +@t{enable} contains @t{ALL}. + +@kindex disable-patterns +@item @t{disable-patterns} +A list of patterns that are checked against @t{$PWD}. If a pattern +matches, @t{vcs_info} will be disabled. This style is checked in the +@t{:vcs_info:-init-:*:-all-} context. + +@noindent +Say, @t{~/.zsh} is a directory under version control, in which you do +not want @t{vcs_info} to be active, do: +@example +zstyle ':vcs_info:*' disable-patterns "$@{(b)HOME@}/.zsh(|/*)" +@end example + +@kindex use-quilt +@item @t{use-quilt} +If enabled, the @t{quilt} support code is active in `addon' mode. +See @ref{vcs_info Quilt Support} for details. + +@kindex quilt-standalone +@item @t{quilt-standalone} +If enabled, `standalone' mode detection is attempted if no VCS is active +in a given directory. See @ref{vcs_info Quilt Support} for details. + +@kindex quilt-patch-dir +@item @t{quilt-patch-dir} +Overwrite the value of the @t{$QUILT_PATCHES} environment variable. See +@ref{vcs_info Quilt Support} for details. + +@kindex quiltcommand +@item @t{quiltcommand} +When @t{quilt} itself is called in quilt support, the value of this style +is used as the command name. + +@kindex check-for-changes +@item @t{check-for-changes} +If enabled, this style causes the @t{%c} and @t{%u} format escapes to show +when the working directory has uncommitted changes. The strings displayed by +these escapes can be controlled via the @t{stagedstr} and @t{unstagedstr} +styles. The only backends that currently support this option are @t{git}, +@t{hg}, and @t{bzr} (the latter two only support unstaged). + +@noindent +For this style to be evaluated with the @t{hg} backend, the @t{get-revision} +style needs to be set and the @t{use-simple} style needs to be unset. The +latter is the default; the former is not. + +@noindent +With the @t{bzr} backend, @emph{lightweight checkouts} only honor this style if +the @t{use-server} style is set. + +@noindent +Note, the actions taken if this style is enabled are potentially expensive +(read: they may be slow, depending on how big the current repository is). +Therefore, it is disabled by default. + +@kindex check-for-staged-changes +@item @t{check-for-staged-changes} +This style is like @t{check-for-changes}, but it never checks the worktree +files, only the metadata in the @t{.$@{vcs@}} dir. Therefore, +this style initializes only the @t{%c} escape (with @t{stagedstr}) but +not the @t{%u} escape. This style is faster than @t{check-for-changes}. + +@noindent +In the @t{git} backend, this style checks for changes in the index. +Other backends do not currently implement this style. + +@noindent +This style is disabled by default. + +@kindex stagedstr +@item @t{stagedstr} +This string will be used in the @t{%c} escape if there are staged changes in +the repository. + +@kindex unstagedstr +@item @t{unstagedstr} +This string will be used in the @t{%u} escape if there are unstaged changes +in the repository. + +@kindex command +@item @t{command} +This style causes @t{vcs_info} to use the supplied string as the command +to use as the VCS's binary. Note, that setting this in '@t{:vcs_info:*}' is +not a good idea. + +@noindent +If the value of this style is empty (which is the default), the used binary +name is the name of the backend in use (e.g. @t{svn} is used in an @t{svn} +repository). + +@noindent +The @t{repo-root-name} part in the context is always the default @t{-all-} +when this style is looked up. + +@noindent +For example, this style can be used to use binaries from non-default +installation directories. Assume, @t{git} is installed in /usr/bin but +your sysadmin installed a newer version in /usr/local/bin. Instead of +changing the order of your @t{$PATH} parameter, you can do this: +@example +zstyle ':vcs_info:git:*:-all-' command /usr/local/bin/git +@end example + +@kindex use-server +@item @t{use-server} +This is used by the Perforce backend (@t{p4}) to decide if it should +contact the Perforce server to find out if a directory is managed +by Perforce. This is the only reliable way of doing this, but runs +the risk of a delay if the server name cannot be found. If the +server (more specifically, the @var{host}@t{:}@var{port} pair describing the +server) cannot be contacted, its name is put into the associative array +@t{vcs_info_p4_dead_servers} and is not contacted again during the session +until it is removed by hand. If you do not set this style, the @t{p4} +backend is only usable if you have set the environment variable +@t{P4CONFIG} to a file name and have corresponding files in the root +directories of each Perforce client. See comments in the function +@t{VCS_INFO_detect_p4} for more detail. + +@noindent +The Bazaar backend (@t{bzr}) uses this to permit contacting the server +about lightweight checkouts, see the @t{check-for-changes} style. + +@kindex use-simple +@item @t{use-simple} +If there are two different ways of gathering +information, you can select the simpler one by setting this style to true; +the default is to use the not-that-simple code, which is potentially a lot +slower but might be more accurate in all possible cases. This style is +used by the @t{bzr}, @t{hg}, and @t{git} backends. In the case of @t{hg} it will invoke +the external hexdump program to parse the binary dirstate cache file; this +method will not return the local revision number. + +@kindex get-revision +@item @t{get-revision} +If set to true, vcs_info goes the extra mile to figure out the revision of +a repository's work tree (currently for the @t{git} and @t{hg} backends, +where this kind of information is not always vital). For @t{git}, the +hash value of the currently checked out commit is available via the @t{%i} +expansion. With @t{hg}, the local revision number and the corresponding +global hash are available via @t{%i}. + +@kindex get-mq +@item @t{get-mq} +If set to true, the @t{hg} backend will look for a Mercurial Queue (@t{mq}) +patch directory. Information will be available via the `@t{%m}' replacement. + +@kindex get-bookmarks +@item @t{get-bookmarks} +If set to true, the @t{hg} backend will try to get a list of current +bookmarks. They will be available via the `@t{%m}' replacement. + +@noindent +The default is to generate a comma-separated list of all bookmark names +that refer to the currently checked out revision. If a bookmark is active, +its name is suffixed an asterisk and placed first in the list. + +@kindex use-prompt-escapes +@item @t{use-prompt-escapes} +Determines if we assume that the assembled +string from @t{vcs_info} includes prompt escapes. (Used by +@t{vcs_info_lastmsg}.) + +@kindex debug +@item @t{debug} +Enable debugging output to track possible problems. Currently this style +is only used by @t{vcs_info}'s hooks system. + +@kindex hooks +@item @t{hooks} +A list style that defines hook-function names. See @ref{vcs_info Hooks} +below for details. + +@kindex patch-format +@kindex nopatch-format +@item @t{patch-format} +@itemx @t{nopatch-format} +This pair of styles format the patch information used by the @t{%m} expando in +formats and actionformats for the @t{git} and @t{hg} backends. The value is +subject to certain @t{%}-expansions described below. +The expanded value is made available in the global @t{backend_misc} array as +@t{$@{backend_misc[patches]@}} (also if a @t{set-patch-format} hook is used). + +@kindex get-unapplied +@item @t{get-unapplied} +This boolean style controls whether a backend should attempt to gather a list +of unapplied patches (for example with Mercurial Queue patches). + +@noindent +Used by the @t{quilt}, @t{hg}, and @t{git} backends. + +@end table + +@noindent +The default values for these styles in all contexts are: + +@noindent +@table @asis +@item @t{formats} +" (%s)-[%b]%u%c-" +@item @t{actionformats} +" (%s)-[%b|%a]%u%c-" +@item @t{branchformat} +"%b:%r" (for bzr, svn, svk and hg) +@item @t{nvcsformats} +"" +@item @t{hgrevformat} +"%r:%h" +@item @t{max-exports} +2 +@item @t{enable} +ALL +@item @t{disable} +(empty list) +@item @t{disable-patterns} +(empty list) +@item @t{check-for-changes} +false +@item @t{check-for-staged-changes} +false +@item @t{stagedstr} +(string: "S") +@item @t{unstagedstr} +(string: "U") +@item @t{command} +(empty string) +@item @t{use-server} +false +@item @t{use-simple} +false +@item @t{get-revision} +false +@item @t{get-mq} +true +@item @t{get-bookmarks} +false +@item @t{use-prompt-escapes} +true +@item @t{debug} +false +@item @t{hooks} +(empty list) +@item @t{use-quilt} +false +@item @t{quilt-standalone} +false +@item @t{quilt-patch-dir} +empty - use @t{$QUILT_PATCHES} +@item @t{quiltcommand} +quilt +@item @t{patch-format} +@var{backend dependent} +@item @t{nopatch-format} +@var{backend dependent} +@item @t{get-unapplied} +false +@end table + +@noindent +In normal @t{formats} and @t{actionformats} the following replacements are +done: + +@noindent +@table @asis +@item @t{%s} +The VCS in use (git, hg, svn, etc.). +@item @t{%b} +Information about the current branch. +@item @t{%a} +An identifier that describes the action. Only makes sense in +@t{actionformats}. +@item @t{%i} +The current revision number or identifier. For @t{hg} +the @t{hgrevformat} style may be used to customize the output. +@item @t{%c} +The string from the @t{stagedstr} style if there are staged +changes in the repository. +@item @t{%u} +The string from the @t{unstagedstr} style if there are +unstaged changes in the repository. +@item @t{%R} +The base directory of the repository. +@item @t{%r} +The repository name. If @t{%R} is @t{/foo/bar/repoXY}, @t{%r} +is @t{repoXY}. +@item @t{%S} +A subdirectory within a repository. If @t{$PWD} is +@t{/foo/bar/repoXY/beer/tasty}, @t{%S} is @t{beer/tasty}. +@end table +@table @asis +@item @t{%m} +A "misc" replacement. It is at the discretion of the backend to +decide what this replacement expands to. + +@noindent +The @t{hg} and @t{git} backends use this expando to display patch information. +@t{hg} sources patch information from the @t{mq} extensions; @t{git} from in-progress +@t{rebase} and @t{cherry-pick} operations and from the @t{stgit} extension. The @t{patch-format} +and @t{nopatch-format} styles control the generated string. The former is used +when at least one patch from the patch queue has been applied, and the latter +otherwise. + +@noindent +The @t{hg} backend displays bookmark information in this expando (in addition +to @t{mq} information). See the @t{get-mq} and @t{get-bookmarks} styles. Both +of these styles may be enabled at the same time. If both are enabled, both +resulting strings will be shown separated by a semicolon (that cannot currently +be customized). + +@noindent +The @t{quilt} `standalone' backend sets this expando to the same value as the +@t{%Q} expando. + +@item @t{%Q} +Quilt series information. +When quilt is used (either in `addon' mode or as a `standalone' backend), +this expando is set to the quilt series' @t{patch-format} string. +The @t{set-patch-format} hook and @t{nopatch-format} style are honoured. + +@noindent +See @ref{vcs_info Quilt Support} below for details. + +@end table + +@noindent +In @t{branchformat} these replacements are done: + +@noindent +@table @asis +@item @t{%b} +The branch name. For @t{hg}, the branch name can include a +topic name. +@item @t{%r} +The current revision number or the @t{hgrevformat} style for +@t{hg}. +@end table + +@noindent +In @t{hgrevformat} these replacements are done: + +@noindent +@table @asis +@item @t{%r} +The current local revision number. +@item @t{%h} +The current global revision identifier. +@end table + +@noindent +In @t{patch-format} and @t{nopatch-format} these replacements are done: + +@noindent +@table @asis +@item @t{%p} +The name of the top-most applied patch; may be overridden by the @t{applied-string} hook. +@item @t{%u} +The number of unapplied patches; may be overridden by the @t{unapplied-string} hook. +@item @t{%n} +The number of applied patches. +@item @t{%c} +The number of unapplied patches. +@item @t{%a} +The number of all patches (@t{%a = %n + %c}). +@item @t{%g} +The names of active @t{mq} guards (@t{hg} backend). +@item @t{%G} +The number of active @t{mq} guards (@t{hg} backend). +@end table + +@noindent +Not all VCS backends have to support all replacements. For @t{nvcsformats} +no replacements are performed at all, it is just a string. + +@noindent +@node vcs_info Oddities, vcs_info Quilt Support, vcs_info Configuration, Version Control Information + +@subsection Oddities +@noindent + +@noindent +If you want to use the @t{%b} (bold off) prompt expansion in @t{formats}, +which expands @t{%b} itself, use @t{%%b}. That will cause the @t{vcs_info} +expansion to replace @t{%%b} with @t{%b}, so that zsh's prompt expansion +mechanism can handle it. Similarly, to hand down @t{%b} from +@t{branchformat}, use @t{%%%%b}. Sorry for this inconvenience, but it +cannot be easily avoided. Luckily we do not clash with a lot of prompt +expansions and this only needs to be done for those. + +@noindent +When one of the @t{gen-applied-string}, @t{gen-unapplied-string}, and +@t{set-patch-format} hooks is defined, +applying @t{%}-escaping (`@t{foo=$@{foo//'%'/%%@}}') to the interpolated values +for use in the prompt is the responsibility of those hooks (jointly); +when neither of those hooks is defined, @t{vcs_info} handles escaping by itself. +We regret this coupling, but it was required for backwards compatibility. + +@noindent +@node vcs_info Quilt Support, vcs_info API, vcs_info Oddities, Version Control Information + +@subsection Quilt Support +@noindent + +@noindent +@cite{Quilt} is not a version control system, therefore this is not implemented +as a backend. It can help keeping track of a series of patches. People use it +to keep a set of changes they want to use on top of software packages (which +is tightly integrated into the package build process - the Debian project +does this for a large number of packages). Quilt can also help individual +developers keep track of their own patches on top of real version control +systems. + +@noindent +The @t{vcs_info} integration tries to support both ways of using quilt by +having two slightly different modes of operation: `addon' mode and +`standalone' mode). + +@noindent +Quilt integration is off by default; to enable it, set the @t{use-quilt} style, +and add @t{%Q} to your @t{formats} or @t{actionformats} style: +@example +zstyle ':vcs_info:*' use-quilt true +@end example + +@noindent +Styles looked up from the Quilt support code include `@t{.quilt-}@var{quilt-mode}' +in the @var{vcs-string} part of the context, where @var{quilt-mode} is either +@t{addon} or @t{standalone}. +Example: @t{:vcs_info:git.quilt-addon:default:}@var{repo-root-name}. + +@noindent +For `addon' mode to become active @t{vcs_info} must have already detected a +real version control system controlling the directory. If that is the case, +a directory that holds quilt's patches needs to be found. That directory is +configurable via the `@t{QUILT_PATCHES}' environment variable. If that +variable exists its value is used, otherwise the value `@t{patches}' is +assumed. The value from @t{$QUILT_PATCHES} can be overwritten using the +`@t{quilt-patch-dir}' style. (Note: you can use @t{vcs_info} to keep the value +of @t{$QUILT_PATCHES} correct all the time via the @t{post-quilt} hook). + +@noindent +When the directory in question is found, quilt is assumed to be active. To +gather more information, @t{vcs_info} looks for a directory called `.pc'; +Quilt uses that directory to track its current state. If this directory does +not exist we know that quilt has not done anything to the working directory +(read: no patches have been applied yet). + +@noindent +If patches are applied, @t{vcs_info} will try to find out which. If you want +to know which patches of a series are not yet applied, you need to activate +the @t{get-unapplied} style in the appropriate context. + +@noindent +@t{vcs_info} allows for very detailed control over how the gathered +information is presented (see +@ref{vcs_info Configuration} and @ref{vcs_info Hooks}), +all of which are documented below. Note there are a number of +other patch tracking systems that work on top of a certain version control +system (like @t{stgit} for @cite{git}, or @t{mq} for @cite{hg}); the configuration +for systems like that are generally configured the same way as the @cite{quilt} +support. + +@noindent +If the @cite{quilt} support is working in `addon' mode, the produced string is +available as a simple format replacement (@t{%Q} to be precise), which can +be used in @t{formats} and @t{actionformats}; see below for details). + +@noindent +If, on the other hand, the support code is working in `standalone' mode, +@t{vcs_info} will pretend as if @t{quilt} were an actual version control +system. That means that the version control system identifier (which +otherwise would be something like `svn' or `cvs') will be set to +`@t{-quilt-}'. This has implications on the used style context where this +identifier is the second element. @t{vcs_info} will have filled in a proper +value for the "repository's" root directory and the string containing the +information about quilt's state will be available as the `misc' replacement +(and @t{%Q} for compatibility with `addon' mode). + +@noindent +What is left to discuss is how `standalone' mode is detected. The detection +itself is a series of searches for directories. You can have this detection +enabled all the time in every directory that is not otherwise under version +control. If you know there is only a limited set of trees where you would +like @t{vcs_info} to try and look for Quilt in `standalone' mode to minimise +the amount of searching on every call to @t{vcs_info}, there are a number of +ways to do that: + +@noindent +Essentially, `standalone' mode detection is controlled by a style called +`@t{quilt-standalone}'. It is a string style and its value can have different +effects. The simplest values are: `@t{always}' to run detection every time +@t{vcs_info} is run, and `@t{never}' to turn the detection off entirely. + +@noindent +If the value of @t{quilt-standalone} is something else, it is interpreted +differently. If the value is the name of a scalar variable the value of that +variable is checked and that value is used in the same `always'/`never' way +as described above. + +@noindent +If the value of @t{quilt-standalone} is an array, the elements of that array +are used as directory names under which you want the detection to be active. + +@noindent +If @t{quilt-standalone} is an associative array, the keys are taken as +directory names under which you want the detection to be active, but only if +the corresponding value is the string `@t{true}'. + +@noindent +Last, but not least, if the value of @t{quilt-standalone} is the name of a +function, the function is called without arguments and the return value +decides whether detection should be active. A `0' return value is true; a +non-zero return value is interpreted as false. + +@noindent +Note, if there is both a function and a variable by the name of +@t{quilt-standalone}, the function will take precedence. + +@noindent +@node vcs_info API, vcs_info Variables, vcs_info Quilt Support, Version Control Information + +@subsection Function Descriptions (Public API) +@noindent + +@noindent +@table @asis +@findex vcs_info +@item @t{vcs_info} [@var{user-context}] +The main function, that runs all backends and assembles all data into +@t{$@{vcs_info_msg_*_@}}. This is the function you want to call from +@t{precmd} if you want to include up-to-date information in your prompt (see +@ref{vcs_info Variables} +below). If an argument is given, that string will be +used instead of @t{default} in the @var{user-context} field of the style +context. + +@findex vcs_info_hookadd +@item @t{vcs_info_hookadd} +Statically registers a number of functions to a given hook. The hook needs +to be given as the first argument; what follows is a list of hook-function +names to register to the hook. The `@t{+vi-}' prefix needs to be left out +here. See @ref{vcs_info Hooks} +below for details. + +@findex vcs_info_hookdel +@item @t{vcs_info_hookdel} +Remove hook-functions from a given hook. The hook needs to be given as the +first non-option argument; what follows is a list of hook-function +names to un-register from the hook. If `@t{-a}' is used as the first +argument, @t{all} occurrences of the functions are unregistered. Otherwise +only the last occurrence is removed (if a function was registered to a hook +more than once). The `@t{+vi-}' prefix needs to be left out here. +See @ref{vcs_info Hooks} +below for details. + +@findex vcs_info_lastmsg +@item @t{vcs_info_lastmsg} +Outputs the current values of @t{$@{vcs_info_msg_*_@}}. +Takes into account the value of the @t{use-prompt-escapes} style in +@t{':vcs_info:formats:command:-all-'}. It also only prints @t{max-exports} +values. + +@findex vcs_info_printsys +@item @t{vcs_info_printsys} [@var{user-context}] +Prints a list of all +supported version control systems. Useful to find out possible contexts +(and which of them are enabled) or values for the @t{disable} style. + +@findex vcs_info_setsys +@item @t{vcs_info_setsys} +Initializes @t{vcs_info}'s internal list of +available backends. With this function, you can add support for new VCSs +without restarting the shell. + +@end table + +@noindent +All functions named @t{VCS_INFO_*} are for internal use only. + +@noindent +@node vcs_info Variables, vcs_info Hooks, vcs_info API, Version Control Information + +@subsection Variable Description +@noindent + +@noindent +@table @asis +@item @t{$@{vcs_info_msg_}@var{N}@t{_@}} (Note the trailing underscore) +Where @var{N} is an integer, e.g., @t{vcs_info_msg_0_}. These variables +are the storage for the informational message the last @t{vcs_info} call +has assembled. These are strongly connected to the @t{formats}, +@t{actionformats} and @t{nvcsformats} styles described above. Those styles +are lists. The first member of that list gets expanded into +@t{$@{vcs_info_msg_0_@}}, the second into @t{$@{vcs_info_msg_1_@}} +and the Nth into @t{$@{vcs_info_msg_N-1_@}}. (See the @t{max-exports} +style above.) + +@end table + +@noindent +All variables named @t{VCS_INFO_*} are for internal use only. + +@noindent +@node vcs_info Hooks, vcs_info Examples, vcs_info Variables, Version Control Information + +@subsection Hooks in vcs_info +@noindent + +@noindent +Hooks are places in @t{vcs_info} where you can run your own code. That +code can communicate with the code that called it and through that, +change the system's behaviour. + +@noindent +For configuration, hooks change the style context: +@example +:vcs_info:@var{vcs-string}+@var{hook-name}:@var{user-context}:@var{repo-root-name} +@end example + +@noindent +To register functions to a hook, you need to list them in the @t{hooks} +style in the appropriate context. + +@noindent +Example: +@example +zstyle ':vcs_info:*+foo:*' hooks bar baz +@end example + +@noindent +This registers functions to the hook `foo' for all backends. In order to +avoid namespace problems, all registered function names are prepended by +a `@t{+vi-}', so the actual functions called for the `foo' hook are +`@t{+vi-bar}' and `@t{+vi-baz}'. + +@noindent +If you would like to register a function to a hook regardless of the +current context, you may use the @t{vcs_info_hookadd} function. To remove +a function that was added like that, the @t{vcs_info_hookdel} function +can be used. + +@noindent +If something seems weird, you can enable the `debug' boolean style in +the proper context and the hook-calling code will print what it tried +to execute and whether the function in question existed. + +@noindent +When you register more than one function to a hook, all functions are +executed one after another until one function returns non-zero or until +all functions have been called. Context-sensitive hook functions are +executed @t{before} statically registered ones (the ones added by +@t{vcs_info_hookadd}). + +@noindent +You may pass data between functions via an associative array, @t{user_data}. +For example: +@example + ++vi-git-myfirsthook()@{ + user_data[myval]=$myval +@} ++vi-git-mysecondhook()@{ + # do something with $@{user_data[myval]@} +@} +@end example + +@noindent +There are a number of variables that are special in hook contexts: + +@noindent +@table @asis +@item @t{ret} +The return value that the hooks system will return to the caller. The +default is an integer `zero'. If and how a changed @t{ret} value changes +the execution of the caller depends on the specific hook. See the hook +documentation below for details. + +@item @t{hook_com} +An associated array which is used for bidirectional communication from +the caller to hook functions. The used keys depend on the specific hook. + +@item @t{context} +The active context of the hook. Functions that wish to change this +variable should make it local scope first. + +@item @t{vcs} +The current VCS after it was detected. The same values as in the +enable/disable style are used. Available in all hooks except @t{start-up}. + +@end table + +@noindent +Finally, the full list of currently available hooks: + +@noindent +@table @asis +@item @t{start-up} +Called after starting @t{vcs_info} but before the VCS in this directory is +determined. It can be used to deactivate @t{vcs_info} temporarily if +necessary. When @t{ret} is set to @t{1}, @t{vcs_info} aborts and does +nothing; when set to @t{2}, @t{vcs_info} sets up everything as if no +version control were active and exits. + +@item @t{pre-get-data} +Same as @t{start-up} but after the VCS was detected. + +@item @t{gen-hg-bookmark-string} +Called in the Mercurial backend when a bookmark string is generated; the +@t{get-revision} and @t{get-bookmarks} styles must be true. + +@noindent +This hook gets the names of the Mercurial bookmarks that +@t{vcs_info} collected from `hg'. + +@noindent +If a bookmark is active, the key @t{$@{hook_com[hg-active-bookmark]@}} is +set to its name. The key is otherwise unset. + +@noindent +When setting @t{ret} to non-zero, the string in +@t{$@{hook_com[hg-bookmark-string]@}} will be used in the @t{%m} escape in +@t{formats} and @t{actionformats} and will be available in the global +@t{backend_misc} array as @t{$@{backend_misc[bookmarks]@}}. + +@item @t{gen-applied-string} +Called in the @t{git} (with @t{stgit} or during rebase or merge), and @t{hg} +(with @t{mq}) backends and in @t{quilt} support when the @t{applied-string} +is generated; the @t{use-quilt} zstyle must be true for @t{quilt} (the @t{mq} +and @t{stgit} backends are active by default). + +@noindent +The arguments to this hook describe applied patches +in the opposite order, which means that the first argument is the +top-most patch and so forth. + +@noindent +When the patches' log messages can be extracted, those are embedded +within each argument after a space, so each argument is of the form +`@var{patch-name} @var{first line of the log message}', where @var{patch-name} +contains no whitespace. The @t{mq} backend passes arguments of +the form `@var{patch name}', with possible embedded spaces, but without +extracting the patch's log message. + +@noindent +When setting @t{ret} to non-zero, the string in +@t{$@{hook_com[applied-string]@}} will be +available as @t{%p} in the @t{patch-format} and @t{nopatch-format} styles. +This hook is, in concert with @t{set-patch-format}, responsible for +@t{%}-escaping that value for use in the prompt. +(See @ref{vcs_info Oddities}.) + +@noindent +The @t{quilt} backend passes to this hook the inputs +@t{$@{hook_com[quilt-patches-dir]@}} and, if it has been +determined, @t{$@{hook_com[quilt-pc-dir]@}}. + +@item @t{gen-unapplied-string} +Called in the @t{git} (with @t{stgit} or during rebase), and @t{hg} (with +@t{mq}) backend and in @t{quilt} support when the @t{unapplied-string} is +generated; the @t{get-unapplied} style must be true. + +@noindent +This hook gets the names of all unapplied patches which @t{vcs_info} +in order, which means that the first argument is +the patch next-in-line to be applied and so forth. + +@noindent +The format of each argument is as for @t{gen-applied-string}, above. + +@noindent +When setting @t{ret} to non-zero, the string in +@t{$@{hook_com[unapplied-string]@}} will be available as @t{%u} in the +@t{patch-format} and @t{nopatch-format} styles. +This hook is, in concert with @t{set-patch-format}, responsible for +@t{%}-escaping that value for use in the prompt. +(See @ref{vcs_info Oddities}.) + +@noindent +The @t{quilt} backend passes to this hook the inputs +@t{$@{hook_com[quilt-patches-dir]@}} and, if it has been +determined, @t{$@{hook_com[quilt-pc-dir]@}}. + +@item @t{gen-mqguards-string} +Called in the @t{hg} backend when @t{guards-string} is generated; the +@t{get-mq} style must be true (default). + +@noindent +This hook gets the names of any active @t{mq} guards. + +@noindent +When setting @t{ret} to non-zero, the string in +@t{$@{hook_com[guards-string]@}} will be used in the @t{%g} escape in the +@t{patch-format} and @t{nopatch-format} styles. + +@item @t{no-vcs} +This hooks is called when no version control system was detected. + +@noindent +The `@t{hook_com}' parameter is not used. + +@item @t{post-backend} +Called as soon as the backend has finished collecting information. + +@noindent +The `@t{hook_com}' keys available are as for the @t{set-message} hook. + +@item @t{post-quilt} +Called after the @t{quilt} support is done. The following information +is passed as arguments to the hook: 1. the quilt-support mode (`addon' or +`standalone'); 2. the directory that contains the patch series; 3. the +directory that holds quilt's status information (the `.pc' directory) or +the string @t{"-nopc-"} if that directory wasn't found. + +@noindent +The `hook_com' parameter is not used. + +@item @t{set-branch-format} +Called before `@t{branchformat}' is set. The only argument to the +hook is the format that is configured at this point. + +@noindent +The `@t{hook_com}' keys considered are `@t{branch}' and `@t{revision}'. +They are set to the values figured out so far by @t{vcs_info} and any +change will be used directly when the actual replacement is done. + +@noindent +If @t{ret} is set to non-zero, the string in +@t{$@{hook_com[branch-replace]@}} will be used unchanged as the +`@t{%b}' replacement in the variables set by @t{vcs_info}. + +@item @t{set-hgrev-format} +Called before a `@t{hgrevformat}' is set. The only argument to the +hook is the format that is configured at this point. + +@noindent +The `@t{hook_com}' keys considered are `@t{hash}' and `@t{localrev}'. +They are set to the values figured out so far by @t{vcs_info} and any +change will be used directly when the actual replacement is done. + +@noindent +If @t{ret} is set to non-zero, the string in +@t{$@{hook_com[rev-replace]@}} will be used unchanged as the +`@t{%i}' replacement in the variables set by @t{vcs_info}. + +@item @t{pre-addon-quilt} +This hook is used when @t{vcs_info}'s quilt functionality is active in "addon" +mode (quilt used on top of a real version control system). It is activated +right before any quilt specific action is taken. + +@noindent +Setting the `@t{ret}' variable in this hook to a non-zero value avoids any +quilt specific actions from being run at all. + +@item @t{set-patch-format} +This hook is used to control some of the possible expansions in +@t{patch-format} and @t{nopatch-format} styles with patch queue systems such as +quilt, mqueue and the like. + +@noindent +This hook is used in the @t{git}, @t{hg} and @t{quilt} backends. + +@noindent +The hook allows the control of the @t{%p} (@t{$@{hook_com[applied]@}}) and @t{%u} +(@t{$@{hook_com[unapplied]@}}) expansion in all backends that use the hook. With +the mercurial backend, the @t{%g} (@t{$@{hook_com[guards]@}}) expansion is +controllable in addition to that. + +@noindent +If @t{ret} is set to non-zero, the string in @t{$@{hook_com[patch-replace]@}} +will be used unchanged instead of an expanded format from @t{patch-format} or +@t{nopatch-format}. + +@noindent +This hook is, in concert with the @t{gen-applied-string} or +@t{gen-unapplied-string} hooks if they are defined, responsible for +@t{%}-escaping the final @t{patch-format} value for use in the prompt. +(See @ref{vcs_info Oddities}.) + +@noindent +The @t{quilt} backend passes to this hook the inputs +@t{$@{hook_com[quilt-patches-dir]@}} and, if it has been +determined, @t{$@{hook_com[quilt-pc-dir]@}}. + +@item @t{set-message} +Called each time before a `@t{vcs_info_msg_}@var{N}@t{_}' message is set. +It takes two arguments; the first being the `@var{N}' in the message +variable name, the second is the currently configured @t{formats} or +@t{actionformats}. + +@noindent +There are a number of `@t{hook_com}' keys, that are used here: +`@t{action}', `@t{branch}', `@t{base}', `@t{base-name}', `@t{subdir}', +`@t{staged}', `@t{unstaged}', `@t{revision}', `@t{misc}', `@t{vcs}' +and one `@t{miscN}' entry for each backend-specific data field (@t{N} +starting at zero). They are set to the values figured out so far by +@t{vcs_info} and any change will be used directly when the actual +replacement is done. + +@noindent +Since this hook is triggered multiple times (once for each configured +@t{formats} or @t{actionformats}), each of the `@t{hook_com}' keys mentioned +above (except for the @t{miscN} entries) has an `@t{_orig}' counterpart, +so even if you changed a value to your liking you can still get the +original value in the next run. Changing the `@t{_orig}' values is +probably not a good idea. + +@noindent +If @t{ret} is set to non-zero, the string in +@t{$@{hook_com[message]@}} will be used unchanged as the message by +@t{vcs_info}. + +@end table + +@noindent +If all of this sounds rather confusing, take a look at +@ref{vcs_info Examples} +and also in the @t{Misc/vcs_info-examples} file in the Zsh source. +They contain some explanatory code. + +@noindent +@node vcs_info Examples, , vcs_info Hooks, Version Control Information + +@subsection Examples +@noindent + +@noindent +Don't use @t{vcs_info} at all (even though it's in your prompt): +@example +zstyle ':vcs_info:*' enable NONE +@end example + +@noindent +Disable the backends for @t{bzr} and @t{svk}: +@example +zstyle ':vcs_info:*' disable bzr svk +@end example + +@noindent +Disable everything @emph{but} @t{bzr} and @t{svk}: +@example +zstyle ':vcs_info:*' enable bzr svk +@end example + +@noindent +Provide a special formats for @t{git}: +@example +zstyle ':vcs_info:git:*' formats ' GIT, BABY! [%b]' +zstyle ':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]' +@end example + +@noindent +All @t{%x} expansion in all sorts of formats (@t{formats}, @t{actionformats}, +@t{branchformat}, you name it) are done using the `@t{zformat}' builtin from +the `@t{zsh/zutil}' module. That means you can do everything with these +@t{%x} items what zformat supports. In particular, if you want something +that is really long to have a fixed width, like a hash in a mercurial +branchformat, you can do this: @t{%12.12i}. That'll shrink the 40 character +hash to its 12 leading characters. The form is actually +`@t{%}@var{min}@t{.}@var{max}@t{x}'. More is possible. +See @ref{The zsh/zutil Module} for details. + +@noindent +Use the quicker @t{bzr} backend +@example +zstyle ':vcs_info:bzr:*' use-simple true +@end example + +@noindent +If you do use @t{use-simple}, please report if it does `the-right-thing[tm]'. + +@noindent +Display the revision number in yellow for @t{bzr} and @t{svn}: +@example +zstyle ':vcs_info:(svn|bzr):*' \ + branchformat '%b%%F@{yellow@}:%r' +@end example + +@noindent +The doubled percent sign is explained in +@ref{vcs_info Oddities}. + +@noindent +Alternatively, one can use the raw colour codes directly: + +@noindent +@example +zstyle ':vcs_info:(svn|bzr):*' \ + branchformat '%b%@{'$@{fg[yellow]@}'%@}:%r' +@end example + +@noindent +Normally when a variable is interpolated into a format string, the variable +needs to be @t{%}-escaped. In this example we skipped that because we assume +the value of @t{$@{fg[yellow]@}} doesn't contain any @t{%} signs. + +@noindent +Make sure you enclose the color codes in @t{%@{}@var{...}@t{%@}} +if you want to use the string provided by @t{vcs_info} in prompts. + +@noindent +Here is how to print the VCS information as a command (not in a prompt): +@example +vcsi() @{ vcs_info interactive; vcs_info_lastmsg @} +@end example + +@noindent +This way, you can even define different formats for output via +@t{vcs_info_lastmsg} in the '@t{:vcs_info:*:interactive:*}' namespace. + +@noindent +Now as promised, some code that uses hooks: +say, you'd like to replace the string `svn' by `subversion' in +@t{vcs_info}'s @t{%s} @t{formats} replacement. + +@noindent +First, we will tell @t{vcs_info} to call a function when populating +the message variables with the gathered information: +@example +zstyle ':vcs_info:*+set-message:*' hooks svn2subversion +@end example + +@noindent +Nothing happens. Which is reasonable, since we didn't define the actual +function yet. To see what the hooks subsystem is trying to do, enable the +`@t{debug}' style: +@example +zstyle ':vcs_info:*+*:*' debug true +@end example + +@noindent +That should give you an idea what is going on. Specifically, the function +that we are looking for is `@t{+vi-svn2subversion}'. Note, the `@t{+vi-}' +prefix. So, everything is in order, just as documented. When you are done +checking out the debugging output, disable it again: +@example +zstyle ':vcs_info:*+*:*' debug false +@end example + +@noindent +Now, let's define the function: +@example + +function +vi-svn2subversion() @{ + [[ $@{hook_com[vcs_orig]@} == svn ]] && hook_com[vcs]=subversion +@} +@end example + +@noindent +Simple enough. And it could have even been simpler, if only we had +registered our function in a less generic context. If we do it only in +the `@t{svn}' backend's context, we don't need to test which the active +backend is: +@example +zstyle ':vcs_info:svn+set-message:*' hooks svn2subversion +@end example +@example + +function +vi-svn2subversion() @{ + hook_com[vcs]=subversion +@} +@end example + +@noindent +And finally a little more elaborate example, that uses a hook to create +a customised bookmark string for the @t{hg} backend. + +@noindent +Again, we start off by registering a function: +@example +zstyle ':vcs_info:hg+gen-hg-bookmark-string:*' hooks hgbookmarks +@end example + +@noindent +And then we define the `@t{+vi-hgbookmarks}' function: +@example + +function +vi-hgbookmarks() @{ + # The default is to connect all bookmark names by + # commas. This mixes things up a little. + # Imagine, there's one type of bookmarks that is + # special to you. Say, because it's *your* work. + # Those bookmarks look always like this: "sh/*" + # (because your initials are sh, for example). + # This makes the bookmarks string use only those + # bookmarks. If there's more than one, it + # concatenates them using commas. + # The bookmarks returned by `hg' are available in + # the function's positional parameters. + local s="$@{(Mj:,:)@@:#sh/*@}" + # Now, the communication with the code that calls + # the hook functions is done via the hook_com[] + # hash. The key at which the `gen-hg-bookmark-string' + # hook looks is `hg-bookmark-string'. So: + hook_com[hg-bookmark-string]=$s + # And to signal that we want to use the string we + # just generated, set the special variable `ret' to + # something other than the default zero: + ret=1 + return 0 +@} +@end example + +@noindent +Some longer examples and code snippets which might be useful are available in +the examples file located at Misc/vcs_info-examples in the Zsh source +directory. + +@noindent +This concludes our guided tour through zsh's @t{vcs_info}. + +@noindent +@node Prompt Themes, ZLE Functions, Version Control Information, User Contributions + +@section Prompt Themes +@noindent + +@noindent + +@subsection Installation +@noindent + +@noindent +You should make sure all the functions from the @t{Functions/Prompts} +directory of the source distribution are available; they all begin with +the string `@t{prompt_}' except for the special function `@t{promptinit}'. +You also need the `@t{colors}' and `@t{add-zsh-hook}' functions from +@t{Functions/Misc}. +All these functions may already be installed on your system; if not, +you will need to find them and copy them. The directory should appear as +one of the elements of the @t{fpath} array (this should already be the +case if they were installed), and at least the function @t{promptinit} +should be autoloaded; it will autoload the rest. Finally, to initialize +the use of the system you need to call the @t{promptinit} function. The +following code in your @t{.zshrc} will arrange for this; assume the +functions are stored in the directory @t{~/myfns}: + +@noindent +@example +fpath=(~/myfns $fpath) +autoload -U promptinit +promptinit +@end example + +@noindent + +@subsection Theme Selection +@noindent + +@noindent +Use the @t{prompt} command to select your preferred theme. This command +may be added to your @t{.zshrc} following the call to @t{promptinit} in +order to start zsh with a theme already selected. + +@noindent +@table @asis +@item @t{prompt} [ @t{-c} | @t{-l} ] +@itemx @t{prompt} [ @t{-p} | @t{-h} ] [ @var{theme} ... ] +@itemx @t{prompt} [ @t{-s} ] @var{theme} [ @var{arg} ... ] +Set or examine the prompt theme. With no options and a @var{theme} +argument, the theme with that name is set as the current theme. The +available themes are determined at run time; use the @t{-l} option to see +a list. The special @var{theme} `@t{random}' selects at random one of the +available themes and sets your prompt to that. + +@noindent +In some cases the @var{theme} may be modified by one or more arguments, +which should be given after the theme name. See the help for each theme +for descriptions of these arguments. + +@noindent +Options are: + +@noindent +@table @asis +@item @t{-c} +Show the currently selected theme and its parameters, if any. +@item @t{-l} +List all available prompt themes. +@item @t{-p} +Preview the theme named by @var{theme}, or all themes if no +@var{theme} is given. +@item @t{-h} +Show help for the theme named by @var{theme}, or for the +@t{prompt} function if no @var{theme} is given. +@item @t{-s} +Set @var{theme} as the current theme and save state. +@end table + +@item @t{prompt_}@var{theme}@t{_setup} +Each available @var{theme} has a setup function which is called by the +@t{prompt} function to install that theme. This function may define +other functions as necessary to maintain the prompt, including functions +used to preview the prompt or provide help for its use. You should not +normally call a theme's setup function directly. + +@end table + +@noindent + +@subsection Utility Themes +@noindent + +@noindent +@table @asis +@item @t{prompt off} +The theme `@t{off}' sets all the prompt variables to minimal values with +no special effects. + +@item @t{prompt default} +The theme `@t{default}' sets all prompt variables to the same state as +if an interactive zsh was started with no initialization files. + +@item @t{prompt restore} +The special theme `@t{restore}' erases all theme settings and sets prompt +variables to their state before the first time the `@t{prompt}' function +was run, provided each theme has properly defined its cleanup (see below). + +@noindent +Note that you can undo `@t{prompt off}' and `@t{prompt default}' with +`@t{prompt restore}', but a second restore does not undo the first. + +@end table + +@noindent + +@subsection Writing Themes +@noindent + +@noindent +The first step for adding your own theme is to choose a name for it, +and create a file `@t{prompt_@var{name}_setup}' in a directory in your +@t{fpath}, such as @t{~/myfns} in the example above. The file should +at minimum contain assignments for the prompt variables that your +theme wishes to modify. By convention, themes use @t{PS1}, @t{PS2}, +@t{RPS1}, etc., rather than the longer @t{PROMPT} and @t{RPROMPT}. + +@noindent +The file is autoloaded as a function in the current shell context, so +it may contain any necessary commands to customize your theme, including +defining additional functions. To make some complex tasks easier, your +setup function may also do any of the following: + +@noindent +@table @asis +@item Assign @t{prompt_opts} +The array @t{prompt_opts} may be assigned any of @t{"bang"}, @t{"cr"}, +@t{"percent"}, @t{"sp"}, and/or @t{"subst"} as values. The corresponding +setopts (@t{promptbang}, etc.) are turned on, all other prompt-related +options are turned off. The @t{prompt_opts} array preserves setopts even +beyond the scope of @t{localoptions}, should your function need that. + +@item Modify hooks +Use of @t{add-zsh-hook} and @t{add-zle-hook-widget} is recommended (see +the @cite{Manipulating Hook Functions} section above). +All hooks that follow the naming pattern @t{prompt_}@var{theme}@t{_}@var{hook} +are automatically removed when the prompt theme changes or is disabled. + +@item Declare cleanup +If your function makes any other changes that should be undone when the +theme is disabled, your setup function may call + +@noindent +@example +prompt_cleanup @var{command} +@end example + +@noindent +where @var{command} should be suitably quoted. If your theme is ever +disabled or replaced by another, @var{command} is executed with @t{eval}. +You may declare more than one such cleanup hook. + +@item Define preview +Define or autoload a function @t{prompt_}@var{name}@t{_preview} to display +a simulated version of your prompt. A simple default previewer is +defined by @t{promptinit} for themes that do not define their own. +This preview function is called by `@t{prompt -p}'. + +@item Provide help +Define or autoload a function @t{prompt_}@var{name}@t{_help} to display +documentation or help text for your theme. +This help function is called by `@t{prompt -h}'. + +@end table + +@noindent +@node ZLE Functions, Exception Handling, Prompt Themes, User Contributions + +@section ZLE Functions +@noindent + +@noindent + +@subsection Widgets +@noindent + +@noindent +These functions all implement user-defined ZLE widgets (see +@ref{Zsh Line Editor}) which can be bound to keystrokes in interactive shells. To use them, +your @t{.zshrc} should contain lines of the form + +@noindent +@example +autoload @var{function} +zle -N @var{function} +@end example + +@noindent +followed by an appropriate @t{bindkey} command to associate the function +with a key sequence. Suggested bindings are described below. + +@noindent +@table @asis +@item bash-style word functions +If you are looking for functions to implement moving over and editing +words in the manner of bash, where only alphanumeric characters are +considered word characters, you can use the functions described in +the next section. The following is sufficient: + +@noindent +@example +autoload -U select-word-style +select-word-style bash +@end example + +@noindent + +@tindex forward-word-match +@tindex backward-word-match +@tindex kill-word-match +@tindex backward-kill-word-match +@tindex transpose-words-match +@tindex capitalize-word-match +@tindex up-case-word-match +@tindex down-case-word-match +@tindex delete-whole-word-match +@tindex select-word-match +@tindex select-word-style +@tindex match-word-context +@tindex match-words-by-style +@item @t{forward-word-match}, @t{backward-word-match} +@itemx @t{kill-word-match}, @t{backward-kill-word-match} +@itemx @t{transpose-words-match}, @t{capitalize-word-match} +@itemx @t{up-case-word-match}, @t{down-case-word-match} +@itemx @t{delete-whole-word-match}, @t{select-word-match} +@itemx @t{select-word-style}, @t{match-word-context}, @t{match-words-by-style} +The first eight `@t{-match}' functions are drop-in replacements for the +builtin widgets without the suffix. By default they behave in a similar +way. However, by the use of styles and the function @t{select-word-style}, +the way words are matched can be altered. @t{select-word-match} is intended +to be used as a text object in vi mode but with custom word styles. For +comparison, the widgets described in @ref{Text Objects} use fixed definitions of words, compatible +with the @t{vim} editor. + +@noindent +The simplest way of configuring the functions is to use +@t{select-word-style}, which can either be called as a normal function with +the appropriate argument, or invoked as a user-defined widget that will +prompt for the first character of the word style to be used. The first +time it is invoked, the first eight @t{-match} functions will automatically +replace the builtin versions, so they do not need to be loaded explicitly. + +@noindent +The word styles available are as follows. Only the first character +is examined. + +@noindent +@table @asis +@item @t{bash} +Word characters are alphanumeric characters only. + +@item @t{normal} +As in normal shell operation: word characters are alphanumeric characters +plus any characters present in the string given by the parameter +@t{$WORDCHARS}. + +@item @t{shell} +Words are complete shell command arguments, possibly including complete +quoted strings, or any tokens special to the shell. + +@item @t{whitespace} +Words are any set of characters delimited by whitespace. + +@item @t{default} +Restore the default settings; this is usually the same as `@t{normal}'. + +@end table + +@noindent +All but `@t{default}' can be input as an upper case character, which has +the same effect but with subword matching turned on. In this case, words +with upper case characters are treated specially: each separate run of +upper case characters, or an upper case character followed by any number of +other characters, is considered a word. The style @t{subword-range} +can supply an alternative character range to the default `@t{[:upper:]}'; +the value of the style is treated as the contents of a `@t{[}@var{...}@t{]}' +pattern (note that the outer brackets should not be supplied, only +those surrounding named ranges). + +@noindent +More control can be obtained using the @t{zstyle} command, as described in +@ref{The zsh/zutil Module}. Each style is looked up in the +context @t{:zle:}@var{widget} where @var{widget} is the name of the +user-defined widget, not the name of the function implementing it, so in +the case of the definitions supplied by @t{select-word-style} the +appropriate contexts are @t{:zle:forward-word}, and so on. The function +@t{select-word-style} itself always defines styles for the context +`@t{:zle:*}' which can be overridden by more specific (longer) patterns as +well as explicit contexts. + +@noindent +The style @t{word-style} specifies the rules to use. This may have the +following values. + +@noindent +@table @asis +@item @t{normal} +Use the standard shell rules, i.e. alphanumerics and @t{$WORDCHARS}, unless +overridden by the styles @t{word-chars} or @t{word-class}. + +@item @t{specified} +Similar to @t{normal}, but @emph{only} the specified characters, and not also +alphanumerics, are considered word characters. + +@item @t{unspecified} +The negation of specified. The given characters are those which will +@emph{not} be considered part of a word. + +@item @t{shell} +Words are obtained by using the syntactic rules for generating shell +command arguments. In addition, special tokens which are never command +arguments such as `@t{()}' are also treated as words. + +@item @t{whitespace} +Words are whitespace-delimited strings of characters. + +@end table + +@noindent +The first three of those rules usually use @t{$WORDCHARS}, but the value +in the parameter can be overridden by the style @t{word-chars}, which works +in exactly the same way as @t{$WORDCHARS}. In addition, the style +@t{word-class} uses character class syntax to group characters and takes +precedence over @t{word-chars} if both are set. The @t{word-class} style +does not include the surrounding brackets of the character class; for +example, `@t{-:[:alnum:]}' is a valid @t{word-class} to include all +alphanumerics plus the characters `@t{-}' and `@t{:}'. Be careful +including `@t{]}', `@t{^}' and `@t{-}' as these are special inside +character classes. + +@noindent +@t{word-style} may also have `@t{-subword}' appended to its value to +turn on subword matching, as described above. + +@noindent +The style @t{skip-chars} is mostly useful for +@t{transpose-words} and similar functions. If set, it gives a count of +characters starting at the cursor position which will not be considered +part of the word and are treated as space, regardless of what they actually +are. For example, if + +@noindent +@example +zstyle ':zle:transpose-words' skip-chars 1 +@end example + +@noindent +has been set, and @t{transpose-words-match} is called with the cursor on +the @var{X} of @t{foo}@var{X}@t{bar}, where @var{X} can be any character, then +the resulting expression is @t{bar}@var{X}@t{foo}. + +@noindent +Finer grained control can be obtained by setting the style @t{word-context} +to an array of pairs of entries. Each pair of entries consists of a +@var{pattern} and a @var{subcontext}. The shell argument the cursor is on is +matched against each @var{pattern} in turn until one matches; if it does, +the context is extended by a colon and the corresponding @var{subcontext}. +Note that the test is made against the original word on the line, with no +stripping of quotes. Special handling is done between words: the current +context is examined and if it contains the string @t{between} the word +is set to a single space; else if it is contains the string @t{back}, +the word before the cursor is considered, else the word after cursor is +considered. Some examples are given below. + +@noindent +The style @t{skip-whitespace-first} is only used with the +@t{forward-word} widget. If it is set to true, then @t{forward-word} +skips any non-word-characters, followed by any non-word-characters: +this is similar to the behaviour of other word-orientated widgets, +and also that used by other editors, however it differs from the +standard zsh behaviour. When using @t{select-word-style} the widget +is set in the context @t{:zle:*} to @t{true} if the word style is +@t{bash} and @t{false} otherwise. It may be overridden by setting it in +the more specific context @t{:zle:forward-word*}. + +@noindent +It is possible to create widgets with specific behaviour by defining +a new widget implemented by the appropriate generic function, then +setting a style for the context of the specific widget. For example, +the following defines a widget @t{backward-kill-space-word} using +@t{backward-kill-word-match}, the generic widget implementing +@t{backward-kill-word} behaviour, and ensures that the new widget +always implements space-delimited behaviour. + +@noindent +@example +zle -N backward-kill-space-word backward-kill-word-match +zstyle :zle:backward-kill-space-word word-style space +@end example + +@noindent +The widget @t{backward-kill-space-word} can now be bound to a key. + +@noindent +Here are some further examples of use of the styles, actually taken from the +simplified interface in @t{select-word-style}: + +@noindent +@example +zstyle ':zle:*' word-style standard +zstyle ':zle:*' word-chars @value{dsq} +@end example + +@noindent +Implements bash-style word handling for all widgets, i.e. only +alphanumerics are word characters; equivalent to setting +the parameter @t{WORDCHARS} empty for the given context. + +@noindent +@example +style ':zle:*kill*' word-style space +@end example + +@noindent +Uses space-delimited words for widgets with the word `kill' in the name. +Neither of the styles @t{word-chars} nor @t{word-class} is used in this case. + +@noindent +Here are some examples of use of the @t{word-context} style to extend +the context. + +@noindent +@example +zstyle ':zle:*' word-context \ + "*/*" filename "[[:space:]]" whitespace +zstyle ':zle:transpose-words:whitespace' word-style shell +zstyle ':zle:transpose-words:filename' word-style normal +zstyle ':zle:transpose-words:filename' word-chars @value{dsq} +@end example + +@noindent +This provides two different ways of using @t{transpose-words} depending on +whether the cursor is on whitespace between words or on a filename, here +any word containing a @t{/}. On whitespace, complete arguments as defined +by standard shell rules will be transposed. In a filename, only +alphanumerics will be transposed. Elsewhere, words will be transposed +using the default style for @t{:zle:transpose-words}. + +@noindent +The word matching and all the handling of @t{zstyle} settings is actually +implemented by the function @t{match-words-by-style}. This can be used to +create new user-defined widgets. The calling function should set the local +parameter @t{curcontext} to @t{:zle:}@var{widget}, create the local +parameter @t{matched_words} and call @t{match-words-by-style} with no +arguments. On return, @t{matched_words} will be set to an array with the +elements: (1) the start of the line (2) the word before the cursor (3) any +non-word characters between that word and the cursor (4) any non-word +character at the cursor position plus any remaining non-word characters +before the next word, including all characters specified by the +@t{skip-chars} style, (5) the word at or following the cursor (6) any +non-word characters following that word (7) the remainder of the line. Any +of the elements may be an empty string; the calling function should test +for this to decide whether it can perform its function. + +@noindent +If the variable @t{matched_words} is defined by the caller to +@t{match-words-by-style} as an associative array (@t{local -A +matched_words}), then the seven values given above should be retrieved +from it as elements named @t{start}, @t{word-before-cursor}, +@t{ws-before-cursor}, @t{ws-after-cursor}, @t{word-after-cursor}, +@t{ws-after-word}, and @t{end}. In addition the element +@t{is-word-start} is 1 if the cursor is on the start of a word or +subword, or on white space before it (the cases can be distinguished by +testing the @t{ws-after-cursor} element) and 0 otherwise. This form is +recommended for future compatibility. + +@noindent +It is possible to pass options with arguments to @t{match-words-by-style} +to override the use of styles. The options are: +@table @asis +@item @t{-w} +@var{word-style} +@item @t{-s} +@var{skip-chars} +@item @t{-c} +@var{word-class} +@item @t{-C} +@var{word-chars} +@item @t{-r} +@var{subword-range} +@end table + +@noindent +For example, @t{match-words-by-style -w shell -c 0} may be used to +extract the command argument around the cursor. + +@noindent +The @t{word-context} style is implemented by the function +@t{match-word-context}. This should not usually need to be called +directly. + +@tindex bracketed-paste-magic +@item @t{bracketed-paste-magic} +The @t{bracketed-paste} widget (see @ref{Miscellaneous} in @ref{Standard Widgets}) +inserts pasted text literally into the editor buffer rather than interpret +it as keystrokes. This disables some common usages where the self-insert +widget is replaced in order to accomplish some extra processing. An +example is the contributed @t{url-quote-magic} widget described below. + +@noindent +The @t{bracketed-paste-magic} widget is meant to replace @t{bracketed-paste} +with a wrapper that re-enables these self-insert actions, and other +actions as selected by zstyles. Therefore this widget is installed with + +@example +autoload -Uz bracketed-paste-magic +zle -N bracketed-paste bracketed-paste-magic +@end example + +@noindent +Other than enabling some widget processing, @t{bracketed-paste-magic} +attempts to replicate @t{bracketed-paste} as faithfully as possible. + +@noindent +The following zstyles may be set to control processing of pasted text. +All are looked up in the context `@t{:bracketed-paste-magic}'. + +@noindent +@table @asis +@item @t{active-widgets} +A list of patterns matching widget names that should be activated during +the paste. All other key sequences are processed as self-insert-unmeta. +The default is `@t{self-*}' so any user-defined widgets named with that +prefix are active along with the builtin self-insert. + +@noindent +If this style is not set (explicitly deleted) or set to an empty value, +no widgets are active and the pasted text is inserted literally. If the +value includes `@t{undefined-key}', any unknown sequences are discarded +from the pasted text. + +@item @t{inactive-keys} +The inverse of @t{active-widgets}, a list of key sequences that always use +@t{self-insert-unmeta} even when bound to an active widget. Note that +this is a list of literal key sequences, not patterns. + +@item @t{paste-init} +A list of function names, called in widget context (but not as widgets). +The functions are called in order until one of them returns a non-zero +status. The parameter `@t{PASTED}' contains the initial state of the +pasted text. All other ZLE parameters such as `@t{BUFFER}' have their +normal values and side-effects, and full history is available, so for +example @t{paste-init} functions may move words from @t{BUFFER} into +@t{PASTED} to make those words visible to the @t{active-widgets}. + +@noindent +A non-zero return from a @t{paste-init} function does @emph{not} prevent the +paste itself from proceeding. + +@noindent +Loading @t{bracketed-paste-magic} defines @t{backward-extend-paste}, a +helper function for use in @t{paste-init}. + +@noindent +@example +zstyle :bracketed-paste-magic paste-init \ + backward-extend-paste +@end example + +@noindent +When a paste would insert into the middle of a word or append text to a +word already on the line, @t{backward-extend-paste} moves the prefix +from @t{LBUFFER} into @t{PASTED} so that the @t{active-widgets} see the +full word so far. This may be useful with @t{url-quote-magic}. + +@item @t{paste-finish} +Another list of function names called in order until one returns non-zero. +These functions are called @emph{after} the pasted text has been processed +by the @t{active-widgets}, but @emph{before} it is inserted into `@t{BUFFER}'. +ZLE parameters have their normal values and side-effects. + +@noindent +A non-zero return from a @t{paste-finish} function does @emph{not} prevent +the paste itself from proceeding. + +@noindent +Loading @t{bracketed-paste-magic} also defines @t{quote-paste}, a helper +function for use in @t{paste-finish}. + +@noindent +@example +zstyle :bracketed-paste-magic paste-finish \ + quote-paste +zstyle :bracketed-paste-magic:finish quote-style \ + qqq +@end example + +@noindent +When the pasted text is inserted into @t{BUFFER}, it is quoted per the +@t{quote-style} value. To forcibly turn off the built-in numeric prefix +quoting of @t{bracketed-paste}, use: + +@noindent +@example +zstyle :bracketed-paste-magic:finish quote-style \ + none +@end example + +@end table + +@noindent +@emph{Important:} During @t{active-widgets} processing of the paste (after +@t{paste-init} and before @t{paste-finish}), @t{BUFFER} starts empty and +history is restricted, so cursor motions, etc., may not pass outside of +the pasted content. Text assigned to @t{BUFFER} by the active widgets +is copied back into @t{PASTED} before @t{paste-finish}. + +@tindex copy-earlier-word +@item @t{copy-earlier-word} +This widget works like a combination of @t{insert-last-word} and +@t{copy-prev-shell-word}. Repeated invocations of the widget retrieve +earlier words on the relevant history line. With a numeric argument +@var{N}, insert the @var{N}th word from the history line; @var{N} may be +negative to count from the end of the line. + +@noindent +If @t{insert-last-word} has been used to retrieve the last word on a +previous history line, repeated invocations will replace that word with +earlier words from the same line. + +@noindent +Otherwise, the widget applies to words on the line currently being edited. +The @t{widget} style can be set to the name of another widget that should +be called to retrieve words. This widget must accept the same three +arguments as @t{insert-last-word}. + +@tindex cycle-completion-positions +@item @t{cycle-completion-positions} +After inserting an unambiguous string into the command line, the new +function based completion system may know about multiple places in +this string where characters are missing or differ from at least one +of the possible matches. It will then place the cursor on the +position it considers to be the most interesting one, i.e. the one +where one can disambiguate between as many matches as possible with as +little typing as possible. + +@noindent +This widget allows the cursor to be easily moved to the other interesting +spots. It can be invoked repeatedly to cycle between all positions +reported by the completion system. + +@tindex delete-whole-word-match +@item @t{delete-whole-word-match} +This is another function which works like the @t{-match} functions +described immediately above, i.e. using styles to decide the word +boundaries. However, it is not a replacement for any existing function. + +@noindent +The basic behaviour is to delete the word around the cursor. There is no +numeric argument handling; only the single word around the cursor is +considered. If the widget contains the string @t{kill}, the removed text +will be placed in the cutbuffer for future yanking. This can be obtained +by defining @t{kill-whole-word-match} as follows: + +@noindent +@example +zle -N kill-whole-word-match delete-whole-word-match +@end example + +@noindent +and then binding the widget @t{kill-whole-word-match}. + +@tindex down-line-or-beginning-search +@tindex up-line-or-beginning-search +@item @t{up-line-or-beginning-search}, @t{down-line-or-beginning-search} +These widgets are similar to the builtin functions @t{up-line-or-search} +and @t{down-line-or-search}: if in a multiline buffer they move up or +down within the buffer, otherwise they search for a history line matching +the start of the current line. In this case, however, they search for +a line which matches the current line up to the current cursor position, in +the manner of @t{history-beginning-search-backward} and @t{-forward}, rather +than the first word on the line. + +@tindex edit-command-line +@item @t{edit-command-line} +Edit the command line using your visual editor, as in @t{ksh}. + +@noindent +@example +bindkey -M vicmd v edit-command-line +@end example + +@noindent +The editor to be used can also be specified using the @t{editor} style in +the context of the widget. It is specified as an array of command and +arguments: + +@noindent +@example +zstyle :zle:edit-command-line editor gvim -f +@end example + +@tindex expand-absolute-path +@item @t{expand-absolute-path} +Expand the file name under the cursor to an absolute path, resolving +symbolic links. Where possible, the initial path segment is turned +into a named directory or reference to a user's home directory. + +@tindex history-beginning-search-backward-end +@tindex history-beginning-search-forward-end +@item @t{history-search-end} +This function implements the widgets +@t{history-beginning-search-backward-end} and +@t{history-beginning-search-forward-end}. These commands work by first +calling the corresponding builtin widget (see +@ref{History Control}) and then moving the cursor to the end of the line. The original cursor +position is remembered and restored before calling the builtin widget a +second time, so that the same search is repeated to look farther through +the history. + +@noindent +Although you @t{autoload} only one function, the commands to use it are +slightly different because it implements two widgets. + +@noindent +@example +zle -N history-beginning-search-backward-end \ + history-search-end +zle -N history-beginning-search-forward-end \ + history-search-end +bindkey '\e^P' history-beginning-search-backward-end +bindkey '\e^N' history-beginning-search-forward-end +@end example + +@tindex history-beginning-search-menu +@item @t{history-beginning-search-menu} +This function implements yet another form of history searching. The +text before the cursor is used to select lines from the history, +as for @t{history-beginning-search-backward} except that all matches are +shown in a numbered menu. Typing the appropriate digits inserts the +full history line. Note that leading zeroes must be typed (they are only +shown when necessary for removing ambiguity). The entire history is +searched; there is no distinction between forwards and backwards. + +@noindent +With a numeric argument, the search is not anchored to the start of +the line; the string typed by the use may appear anywhere in the line +in the history. + +@noindent +If the widget name contains `@t{-end}' the cursor is moved to the end of +the line inserted. If the widget name contains `@t{-space}' any space +in the text typed is treated as a wildcard and can match anything (hence +a leading space is equivalent to giving a numeric argument). Both +forms can be combined, for example: + +@noindent +@example +zle -N history-beginning-search-menu-space-end \ + history-beginning-search-menu +@end example + +@tindex history-pattern-search +@tindex history-pattern-search-backward +@tindex history-pattern-search-forward +@item @t{history-pattern-search} +The function @t{history-pattern-search} implements widgets which prompt +for a pattern with which to search the history backwards or forwards. The +pattern is in the usual zsh format, however the first character may be +@t{^} to anchor the search to the start of the line, and the last character +may be @t{$} to anchor the search to the end of the line. If the +search was not anchored to the end of the line the cursor is positioned +just after the pattern found. + +@noindent +The commands to create bindable widgets are similar to those in the +example immediately above: + +@noindent +@example +autoload -U history-pattern-search +zle -N history-pattern-search-backward history-pattern-search +zle -N history-pattern-search-forward history-pattern-search +@end example + +@tindex incarg +@vindex incarg, use of +@item @t{incarg} +Typing the keystrokes for this widget with the cursor placed on or to the +left of an integer causes that integer to be incremented by one. With a +numeric argument, the number is incremented by the amount of the +argument (decremented if the numeric argument is negative). The shell +parameter @t{incarg} may be set to change the default increment to +something other than one. + +@noindent +@example +bindkey '^X+' incarg +@end example + +@tindex incremental-complete-word +@item @t{incremental-complete-word} +This allows incremental completion of a word. After starting this +command, a list of completion choices can be shown after every character +you type, which you can delete with @t{^H} or @t{DEL}. Pressing return +accepts the completion so far and returns you to normal editing (that is, +the command line is @emph{not} immediately executed). You can hit @t{TAB} to +do normal completion, @t{^G} to abort back to the state when you started, +and @t{^D} to list the matches. + +@noindent +This works only with the new function based completion system. + +@noindent +@example +bindkey '^Xi' incremental-complete-word +@end example + +@tindex insert-composed-char +@item @t{insert-composed-char} +This function allows you to compose characters that don't appear on the +keyboard to be inserted into the command line. The command is followed by +two keys corresponding to ASCII characters (there is no prompt). For +accented characters, the two keys are a base character followed by a code +for the accent, while for other special characters the two characters +together form a mnemonic for the character to be inserted. The +two-character codes are a subset of those given by RFC 1345 (see for +example @t{@uref{http://www.faqs.org/rfcs/rfc1345.html}}). + +@noindent +The function may optionally be followed by up to two characters which +replace one or both of the characters read from the keyboard; if both +characters are supplied, no input is read. For example, +@t{insert-composed-char a:} can be used within a widget to insert an a with +umlaut into the command line. This has the advantages over use of a +literal character that it is more portable. + +@noindent +For best results zsh should have been built with support for multibyte +characters (configured with @t{--enable-multibyte}); however, the function +works for the limited range of characters available in single-byte +character sets such as ISO-8859-1. + +@noindent +The character is converted into the local representation and +inserted into the command line at the cursor position. +(The conversion is done within the shell, using whatever facilities +the C library provides.) With a numeric argument, the character and its +code are previewed in the status line + +@noindent +The function may be run outside zle in which case it prints the character +(together with a newline) to standard output. Input is still read from +keystrokes. + +@noindent +See @t{insert-unicode-char} for an alternative way of inserting Unicode +characters using their hexadecimal character number. + +@noindent +The set of accented characters is reasonably complete up to Unicode +character U+0180, the set of special characters less so. However, it +is very sporadic from that point. Adding new characters is easy, +however; see the function @t{define-composed-chars}. Please send any +additions to @t{zsh-workers@@zsh.org}. + +@noindent +The codes for the second character when used to accent the first are as +follows. Note that not every character can take every accent. +@table @asis +@item @t{!} +Grave. +@item @t{'} +Acute. +@item @t{>} +Circumflex. +@item @t{?} +Tilde. (This is not @t{~} as RFC 1345 does not assume that +character is present on the keyboard.) +@item @t{-} +Macron. (A horizontal bar over the base character.) +@item @t{(} +Breve. (A shallow dish shape over the base character.) +@item @t{.} +Dot above the base character, or in the case of @t{i} no dot, +or in the case of @t{L} and @t{l} a centered dot. +@item @t{:} +Diaeresis (Umlaut). +@item @t{c} +Cedilla. +@item @t{_} +Underline, however there are currently no underlined characters. +@item @t{/} +Stroke through the base character. +@item @t{"} +Double acute (only supported on a few letters). +@item @t{;} +Ogonek. (A little forward facing hook at the bottom right +of the character.) +@item @t{<} +Caron. (A little v over the letter.) +@item @t{0} +Circle over the base character. +@item @t{2} +Hook over the base character. +@item @t{9} +Horn over the base character. +@end table + +@noindent +The most common characters from the Arabic, Cyrillic, Greek and Hebrew +alphabets are available; consult RFC 1345 for the appropriate sequences. +In addition, a set of two letter codes not in RFC 1345 are available for +the double-width characters corresponding to ASCII characters from @t{!} +to @t{~} (0x21 to 0x7e) by preceding the character with @t{^}, for +example @t{^A} for a double-width @t{A}. + +@noindent +The following other two-character sequences are understood. + +@noindent +@table @asis +@item ASCII characters +These are already present on most keyboards: +@table @asis +@item @t{<(} +Left square bracket +@item @t{//} +Backslash (solidus) +@item @t{)>} +Right square bracket +@item @t{(!} +Left brace (curly bracket) +@item @t{!!} +Vertical bar (pipe symbol) +@item @t{!)} +Right brace (curly bracket) +@item @t{'?} +Tilde +@end table + +@item Special letters +Characters found in various variants of the Latin alphabet: +@table @asis +@item @t{ss} +Eszett (scharfes S) +@item @t{D-}, @t{d-} +Eth +@item @t{TH}, @t{th} +Thorn +@item @t{kk} +Kra +@item @t{'n} +'n +@item @t{NG}, @t{ng} +Ng +@item @t{OI}, @t{oi} +Oi +@item @t{yr} +yr +@item @t{ED} +ezh +@end table + +@item Currency symbols +@table @asis +@item @t{Ct} +Cent +@item @t{Pd} +Pound sterling (also lira and others) +@item @t{Cu} +Currency +@item @t{Ye} +Yen +@item @t{Eu} +Euro (N.B. not in RFC 1345) +@end table + +@item Punctuation characters +References to "right" quotes indicate the shape (like a 9 rather than 6) +rather than their grammatical use. (For example, a "right" low double +quote is used to open quotations in German.) +@table @asis +@item @t{!I} +Inverted exclamation mark +@item @t{BB} +Broken vertical bar +@item @t{SE} +Section +@item @t{Co} +Copyright +@item @t{-a} +Spanish feminine ordinal indicator +@item @t{<<} +Left guillemet +@item @t{-}@t{-} +Soft hyphen +@item @t{Rg} +Registered trade mark +@item @t{PI} +Pilcrow (paragraph) +@item @t{-o} +Spanish masculine ordinal indicator +@item @t{>>} +Right guillemet +@item @t{?I} +Inverted question mark +@item @t{-1} +Hyphen +@item @t{-N} +En dash +@item @t{-M} +Em dash +@item @t{-3} +Horizontal bar +@item @t{:3} +Vertical ellipsis +@item @t{.3} +Horizontal midline ellipsis +@item @t{!2} +Double vertical line +@item @t{=2} +Double low line +@item @t{'6} +Left single quote +@item @t{'9} +Right single quote +@item @t{.9} +"Right" low quote +@item @t{9'} +Reversed "right" quote +@item @t{"6} +Left double quote +@item @t{"9} +Right double quote +@item @t{:9} +"Right" low double quote +@item @t{9"} +Reversed "right" double quote +@item @t{/-} +Dagger +@item @t{/=} +Double dagger +@end table + +@item Mathematical symbols +@table @asis +@item @t{DG} +Degree +@item @t{-2}, @t{+-}, @t{-+} +- sign, +/- sign, -/+ sign +@item @t{2S} +Superscript 2 +@item @t{3S} +Superscript 3 +@item @t{1S} +Superscript 1 +@item @t{My} +Micro +@item @t{.M} +Middle dot +@item @t{14} +Quarter +@item @t{12} +Half +@item @t{34} +Three quarters +@item @t{*X} +Multiplication +@item @t{-:} +Division +@item @t{%0} +Per mille +@item @t{FA}, @t{TE}, @t{/0} +For all, there exists, empty set +@item @t{dP}, @t{DE}, @t{NB} +Partial derivative, delta (increment), del +(nabla) +@item @t{(-}, @t{-)} +Element of, contains +@item @t{*P}, @t{+Z} +Product, sum +@item @t{*-}, @t{Ob}, @t{Sb} +Asterisk, ring, bullet +@item @t{RT}, @t{0(}, @t{00} +Root sign, proportional to, infinity +@end table + +@item Other symbols +@table @asis +@item @t{cS}, @t{cH}, @t{cD}, @t{cC} +Card suits: spades, hearts, diamonds, +clubs +@item @t{Md}, @t{M8}, @t{M2}, @t{Mb}, @t{Mx}, @t{MX} +Musical notation: +crotchet (quarter note), quaver (eighth note), semiquavers (sixteenth +notes), flag sign, natural sign, sharp sign +@item @t{Fm}, @t{Ml} +Female, male +@end table + +@item Accents on their own +@table @asis +@item @t{'>} +Circumflex (same as caret, @t{^}) +@item @t{'!} +Grave (same as backtick, @t{`}) +@item @t{',} +Cedilla +@item @t{':} +Diaeresis (Umlaut) +@item @t{'m} +Macron +@item @t{''} +Acute +@end table + +@end table + +@tindex insert-files +@item @t{insert-files} +This function allows you type a file pattern, and see the results of the +expansion at each step. When you hit return, all expansions are inserted +into the command line. + +@noindent +@example +bindkey '^Xf' insert-files +@end example + +@tindex insert-unicode-char +@item @t{insert-unicode-char} +When first executed, the user inputs a set of hexadecimal digits. +This is terminated with another call to @t{insert-unicode-char}. +The digits are then turned into the corresponding Unicode character. +For example, if the widget is bound to @t{^XU}, the character sequence +`@t{^XU 4 c ^XU}' inserts @t{L} (Unicode U+004c). + +@noindent +See @t{insert-composed-char} for a way of inserting characters +using a two-character mnemonic. + +@tindex narrow-to-region +@tindex narrow-to-region-invisible + +@item @t{narrow-to-region }[ @t{-p} @var{pre} ] [ @t{-P} @var{post} ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ }[ @t{-S} @var{statepm} | @t{-R} @var{statepm} | [ @t{-l} @var{lbufvar} ] [ @t{-r} @var{rbufvar} ] ] +@itemx @t{@ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ }[ @t{-n} ] [ @var{start} @var{end} ] +@itemx @t{narrow-to-region-invisible} +Narrow the editable portion of the buffer to the region between the cursor +and the mark, which may be in either order. The region may not be empty. + +@noindent +@t{narrow-to-region} may be used as a widget or called as a function from a +user-defined widget; by default, the text outside the editable area remains +visible. A @t{recursive-edit} is performed and the original widening +status is then restored. Various options and arguments are available when +it is called as a function. + +@noindent +The options @t{-p} @var{pretext} and @t{-P} @var{posttext} may be +used to replace the text before and after the display for the duration of +the function; either or both may be an empty string. + +@noindent +If the option @t{-n} is also given, @var{pretext} or @var{posttext} will only +be inserted if there is text before or after the region respectively which +will be made invisible. + +@noindent +Two numeric arguments may be given which will be used instead of the cursor +and mark positions. + +@noindent +The option @t{-S} @var{statepm} is used to narrow according to the other +options while saving the original state in the parameter with name +@var{statepm}, while the option @t{-R} @var{statepm} is used to restore the +state from the parameter; note in both cases the @emph{name} of the parameter +is required. In the second case, other options and arguments are +irrelevant. When this method is used, no @t{recursive-edit} is performed; +the calling widget should call this function with the option @t{-S}, +perform its own editing on the command line or pass control to the user +via `@t{zle recursive-edit}', then call this function with the option +@t{-R}. The argument @var{statepm} must be a suitable name for an ordinary +parameter, except that parameters beginning with the prefix @t{_ntr_} are +reserved for use within @t{narrow-to-region}. Typically the parameter will +be local to the calling function. + +@noindent +The options @t{-l} @var{lbufvar} and @t{-r} @var{rbufvar} may be used to +specify parameters where the widget will store the resulting text from +the operation. The parameter @var{lbufvar} will contain @t{LBUFFER} +and @var{rbufvar} will contain @t{RBUFFER}. Neither of these two options +may be used with @t{-S} or @t{-R}. + +@noindent +@t{narrow-to-region-invisible} is a simple widget which calls +@t{narrow-to-region} with arguments which replace any text outside the +region with `@t{...}'. It does not take any arguments. + +@noindent +The display is restored (and the widget returns) upon any zle command +which would usually cause the line to be accepted or aborted. Hence an +additional such command is required to accept or abort the current line. + +@noindent +The return status of both widgets is zero if the line was accepted, else +non-zero. + +@noindent +Here is a trivial example of a widget using this feature. +@example +local state +narrow-to-region -p $'Editing restricted region\n' \ + -P @value{dsq} -S state +zle recursive-edit +narrow-to-region -R state +@end example + +@tindex predict-on +@tindex predict-off +@item @t{predict-on} +This set of functions implements predictive typing using history search. +After @t{predict-on}, typing characters causes the editor to look backward +in the history for the first line beginning with what you have typed so +far. After @t{predict-off}, editing returns to normal for the line found. +In fact, you often don't even need to use @t{predict-off}, because if the +line doesn't match something in the history, adding a key performs +standard completion, and then inserts itself if no completions were found. +However, editing in the middle of a line is liable to confuse prediction; +see the @t{toggle} style below. + +@noindent +With the function based completion system (which is needed for this), you +should be able to type @t{TAB} at almost any point to advance the cursor +to the next @value{dsbq}interesting@value{dsq} character position (usually the end of the +current word, but sometimes somewhere in the middle of the word). And of +course as soon as the entire line is what you want, you can accept with +return, without needing to move the cursor to the end first. + +@noindent +The first time @t{predict-on} is used, it creates several additional +widget functions: + +@noindent +@table @asis +@item @t{delete-backward-and-predict} +Replaces the @t{backward-delete-char} +widget. You do not need to bind this yourself. +@item @t{insert-and-predict} +Implements predictive typing by replacing the +@t{self-insert} widget. You do not need to bind this yourself. +@item @t{predict-off} +Turns off predictive typing. +@end table + +@noindent +Although you @t{autoload} only the @t{predict-on} function, it is +necessary to create a keybinding for @t{predict-off} as well. + +@noindent +@example +zle -N predict-on +zle -N predict-off +bindkey '^X^Z' predict-on +bindkey '^Z' predict-off +@end example + +@tindex read-from-minibuffer +@item @t{read-from-minibuffer} +This is most useful when called as a function from inside a widget, but will +work correctly as a widget in its own right. It prompts for a value +below the current command line; a value may be input using all of the +standard zle operations (and not merely the restricted set available +when executing, for example, @t{execute-named-cmd}). The value is then +returned to the calling function in the parameter @t{$REPLY} and the +editing buffer restored to its previous state. If the read was aborted +by a keyboard break (typically @t{^G}), the function returns status 1 +and @t{$REPLY} is not set. + +@noindent +If one argument is supplied to the function it is taken as a prompt, +otherwise `@t{? }' is used. If two arguments are supplied, they are the +prompt and the initial value of @t{$LBUFFER}, and if a third argument is +given it is the initial value of @t{$RBUFFER}. This provides a default +value and starting cursor placement. Upon return the entire buffer is the +value of @t{$REPLY}. + +@noindent +One option is available: `@t{-k} @var{num}' specifies that @var{num} +characters are to be read instead of a whole line. The line editor is not +invoked recursively in this case, so depending on the terminal settings +the input may not be visible, and only the input keys are placed in +@t{$REPLY}, not the entire buffer. Note that unlike the @t{read} builtin +@var{num} must be given; there is no default. + +@noindent +The name is a slight misnomer, as in fact the shell's own minibuffer is +not used. Hence it is still possible to call @t{executed-named-cmd} and +similar functions while reading a value. + +@tindex replace-argument +@tindex replace-argument-edit +@item @t{replace-argument}, @t{replace-argument-edit} +The function @t{replace-argument} can be used to replace a command +line argument in the current command line or, if the current command +line is empty, in the last command line executed (the new command line +is not executed). Arguments are as delimited by standard shell syntax, + +@noindent +If a numeric argument is given, that specifies the argument to be +replaced. 0 means the command name, as in history expansion. +A negative numeric argument counts backward from the last word. + +@noindent +If no numeric argument is given, the current argument is replaced; +this is the last argument if the previous history line is being used. + +@noindent +The function prompts for a replacement argument. + +@noindent +If the widget contains the string @t{edit}, for example is defined as + +@noindent +@example +zle -N replace-argument-edit replace-argument +@end example + +@noindent +then the function presents the current value of the argument for +editing, otherwise the editing buffer for the replacement is +initially empty. + +@tindex replace-string +@tindex replace-string-again +@tindex replace-pattern +@item @t{replace-string}, @t{replace-pattern} +@itemx @t{replace-string-again}, @t{replace-pattern-again} +The function @t{replace-string} implements three widgets. +If defined under the same name as the function, it prompts for two +strings; the first (source) string will be replaced by the second +everywhere it occurs in the line editing buffer. + +@noindent +If the widget name contains the word `@t{pattern}', for example by +defining the widget using the command `@t{zle -N replace-pattern +replace-string}', then the matching is performed using zsh patterns. All +zsh extended globbing patterns can be used in the source string; note +that unlike filename generation the pattern does not need to match an +entire word, nor do glob qualifiers have any effect. In addition, the +replacement string can contain parameter or command substitutions. +Furthermore, a `@t{&}' in the replacement string will be replaced with +the matched source string, and a backquoted digit `@t{\}@var{N}' will be +replaced by the @var{N}th parenthesised expression matched. The form +`@t{\@{}@var{N}@t{@}}' may be used to protect the digit from following +digits. + +@noindent +If the widget instead contains the word `@t{regex}' (or `@t{regexp}'), +then the matching is performed using regular expressions, respecting +the setting of the option @t{RE_MATCH_PCRE} (see the description of the +function @t{regexp-replace} below). The special replacement facilities +described above for pattern matching are available. + +@noindent +By default the previous source or replacement string will not be offered +for editing. However, this feature can be activated by setting the style +@t{edit-previous} in the context @t{:zle:}@var{widget} (for example, +@t{:zle:replace-string}) to @t{true}. In addition, a positive +numeric argument forces the previous values to be offered, a negative or +zero argument forces them not to be. + +@noindent +The function @t{replace-string-again} can be used to repeat the previous +replacement; no prompting is done. As with @t{replace-string}, if the name +of the widget contains the word `@t{pattern}' or `@t{regex}', pattern or +regular expression matching is performed, else a literal string +replacement. Note that the previous source and replacement text are the +same whether pattern, regular expression or string matching is used. + +@noindent +In addition, @t{replace-string} shows the previous replacement above +the prompt, so long as there was one during the current session; if the +source string is empty, that replacement will be repeated without +the widget prompting for a replacement string. + +@noindent +For example, starting from the line: + +@noindent +@example +print This line contains fan and fond +@end example + +@noindent +and invoking @t{replace-pattern} with the source string +`@t{f(?)n}' and +the replacement string `@t{c\1r}' produces the not very useful line: + +@noindent +@example +print This line contains car and cord +@end example + +@noindent +The range of the replacement string can be limited by using the +@t{narrow-to-region-invisible} widget. One limitation of the current +version is that @t{undo} will cycle through changes to the replacement +and source strings before undoing the replacement itself. + +@tindex send-invisible +@item @t{send-invisible} +This is similar to read-from-minibuffer in that it may be called as a +function from a widget or as a widget of its own, and interactively reads +input from the keyboard. However, the input being typed is concealed and +a string of asterisks (`@t{*}') is shown instead. The value is saved in +the parameter @t{$INVISIBLE} to which a reference is inserted into the +editing buffer at the restored cursor position. If the read was aborted +by a keyboard break (typically @t{^G}) or another escape from editing such +as @t{push-line}, @t{$INVISIBLE} is set to empty and the original buffer +is restored unchanged. + +@noindent +If one argument is supplied to the function it is taken as a prompt, +otherwise `@t{Non-echoed text: }' is used (as in emacs). If a second and +third argument are supplied they are used to begin and end the reference +to @t{$INVISIBLE} that is inserted into the buffer. The default is to +open with @t{$@{}, then @t{INVISIBLE}, and close with @t{@}}, but many +other effects are possible. + +@tindex smart-insert-last-word +@item @t{smart-insert-last-word} +This function may replace the @t{insert-last-word} widget, like so: + +@noindent +@example +zle -N insert-last-word smart-insert-last-word +@end example + +@noindent +With a numeric argument, or when passed command line arguments in a call +from another widget, it behaves like @t{insert-last-word}, except that +words in comments are ignored when @t{INTERACTIVE_COMMENTS} is set. + +@noindent +Otherwise, the rightmost @value{dsbq}interesting@value{dsq} word from the previous command is +found and inserted. The default definition of @value{dsbq}interesting@value{dsq} is that the +word contains at least one alphabetic character, slash, or backslash. +This definition may be overridden by use of the @t{match} style. The +context used to look up the style is the widget name, so usually the +context is @t{:insert-last-word}. However, you can bind this function to +different widgets to use different patterns: + +@noindent +@example +zle -N insert-last-assignment smart-insert-last-word +zstyle :insert-last-assignment match '[[:alpha:]][][[:alnum:]]#=*' +bindkey '\e=' insert-last-assignment +@end example + +@noindent +If no interesting word is found and the @t{auto-previous} style is set to +a true value, the search continues upward through the history. When +@t{auto-previous} is unset or false (the default), the widget must be +invoked repeatedly in order to search earlier history lines. + +@tindex transpose-lines +@item @t{transpose-lines} +Only useful with a multi-line editing buffer; the lines here are +lines within the current on-screen buffer, not history lines. +The effect is similar to the function of the same name in Emacs. + +@noindent +Transpose the current line with the previous line and move the cursor +to the start of the next line. Repeating this (which can be done by +providing a positive numeric argument) has the effect of moving +the line above the cursor down by a number of lines. + +@noindent +With a negative numeric argument, requires two lines above the +cursor. These two lines are transposed and the cursor moved to the +start of the previous line. Using a numeric argument less than -1 +has the effect of moving the line above the cursor up by minus that +number of lines. + +@tindex url-quote-magic +@item @t{url-quote-magic} +This widget replaces the built-in @t{self-insert} to make it easier to +type URLs as command line arguments. As you type, the input character is +analyzed and, if it may need quoting, the current word is checked for a +URI scheme. If one is found and the current word is not already in +quotes, a backslash is inserted before the input character. + +@noindent +Styles to control quoting behavior: + +@noindent +@table @asis +@item @t{url-metas} +This style is looked up in the context `@t{:url-quote-magic:}@var{scheme}' +(where @var{scheme} is that of the current URL, e.g. "@t{ftp}"). The value +is a string listing the characters to be treated as globbing +metacharacters when appearing in a URL using that scheme. The default is +to quote all zsh extended globbing characters, excluding '@t{<}' and +'@t{>}' but including braces (as in brace expansion). See also +@t{url-seps}. + +@item @t{url-seps} +Like @t{url-metas}, but lists characters that should be considered command +separators, redirections, history references, etc. The default is to +quote the standard set of shell separators, excluding those that overlap +with the extended globbing characters, but including '@t{<}' and +'@t{>}' and the first character of @t{$histchars}. + +@item @t{url-globbers} +This style is looked up in the context `@t{:url-quote-magic}'. The values +form a list of command names that are expected to do their own globbing +on the URL string. This implies that they are aliased to use the +`@t{noglob}' modifier. When the first word on the line matches one of the +values @emph{and} the URL refers to a local file (see @t{url-local-schema}), +only the @t{url-seps} characters are quoted; the @t{url-metas} are left +alone, allowing them to affect command-line parsing, completion, etc. The +default values are a literal `@t{noglob}' plus (when the @t{zsh/parameter} +module is available) any commands aliased to the helper function +`@t{urlglobber}' or its alias `@t{globurl}'. + +@item @t{url-local-schema} +This style is always looked up in the context `@t{:urlglobber}', even +though it is used by both url-quote-magic and urlglobber. The values form +a list of URI schema that should be treated as referring to local files by +their real local path names, as opposed to files which are specified +relative to a web-server-defined document root. The defaults are +"@t{ftp}" and "@t{file}". + +@item @t{url-other-schema} +Like @t{url-local-schema}, but lists all other URI schema upon which +@t{urlglobber} and @t{url-quote-magic} should act. If the URI on the +command line does not have a scheme appearing either in this list or in +@t{url-local-schema}, it is not magically quoted. The default values are +"@t{http}", "@t{https}", and "@t{ftp}". When a scheme appears both here +and in @t{url-local-schema}, it is quoted differently depending on whether +the command name appears in @t{url-globbers}. + +@end table + +@noindent +Loading @t{url-quote-magic} also defines a helper function `@t{urlglobber}' +and aliases `@t{globurl}' to `@t{noglob urlglobber}'. This function takes +a local URL apart, attempts to pattern-match the local file portion of the +URL path, and then puts the results back into URL format again. + +@tindex vi-pipe +@item @t{vi-pipe} +This function reads a movement command from the keyboard and then +prompts for an external command. The part of the buffer covered by +the movement is piped to the external command and then replaced by +the command's output. If the movement command is bound to vi-pipe, +the current line is used. + +@noindent +The function serves as an example for reading a vi movement command +from within a user-defined widget. + +@tindex which-command +@item @t{which-command} +This function is a drop-in replacement for the builtin widget +@t{which-command}. It has enhanced behaviour, in that it correctly +detects whether or not the command word needs to be expanded as an +alias; if so, it continues tracing the command word from the expanded +alias until it reaches the command that will be executed. + +@noindent +The style @t{whence} is available in the context @t{:zle:$WIDGET}; this +may be set to an array to give the command and options that will be used to +investigate the command word found. The default is @t{whence -c}. + +@tindex zcalc-auto-insert +@item @t{zcalc-auto-insert} +This function is useful together with the @t{zcalc} function described in +@ref{Mathematical Functions}. +It should be bound to a key representing a binary operator such +as `@t{+}', `@t{-}', `@t{*}' or `@t{/}'. When running in zcalc, +if the key occurs at the start of the line or immediately following +an open parenthesis, the text @t{"ans "} is inserted before the +representation of the key itself. This allows easy use of the +answer from the previous calculation in the current line. The +text to be inserted before the symbol typed can be modified by setting +the variable @t{ZCALC_AUTO_INSERT_PREFIX}. + +@noindent +Hence, for example, typing `@t{+12}' followed by return adds 12 +to the previous result. + +@noindent +If zcalc is in RPN mode (@t{-r} option) the effect of this binding is +automatically suppressed as operators alone on a line are meaningful. + +@noindent +When not in zcalc, the key simply inserts the symbol itself. + +@end table + +@noindent + +@subsection Utility Functions +@noindent + +@noindent +These functions are useful in constructing widgets. They +should be loaded with `@t{autoload -U} @var{function}' and called +as indicated from user-defined widgets. + +@noindent +@table @asis +@tindex split-shell-arguments +@item @t{split-shell-arguments} +This function splits the line currently being edited into shell arguments +and whitespace. The result is stored in the array @t{reply}. The array +contains all the parts of the line in order, starting with any whitespace +before the first argument, and finishing with any whitespace after the last +argument. Hence (so long as the option @t{KSH_ARRAYS} is not set) +whitespace is given by odd indices in the array and arguments by +even indices. Note that no stripping of quotes is done; joining together +all the elements of @t{reply} in order is guaranteed to produce the +original line. + +@noindent +The parameter @t{REPLY} is set to the index of the word in @t{reply} which +contains the character after the cursor, where the first element has index +1. The parameter @t{REPLY2} is set to the index of the character under the +cursor in that word, where the first character has index 1. + +@noindent +Hence @t{reply}, @t{REPLY} and @t{REPLY2} should all be made local to +the enclosing function. + +@noindent +See the function @t{modify-current-argument}, described below, for +an example of how to call this function. + +@tindex modify-current-argument +@item @t{modify-current-argument} [ @var{expr-using-}@t{$ARG} | @var{func} ] +This function provides a simple method of allowing user-defined widgets +to modify the command line argument under the cursor (or immediately to the +left of the cursor if the cursor is between arguments). + +@noindent +The argument can be an expression which when evaluated operates on the shell +parameter @t{ARG}, which will have been set to the command line argument +under the cursor. The expression should be suitably quoted to prevent +it being evaluated too early. + +@noindent +Alternatively, if the argument does not contain the string @t{ARG}, it +is assumed to be a shell function, to which the current command line +argument is passed as the only argument. The function should set the +variable @t{REPLY} to the new value for the command line argument. +If the function returns non-zero status, so does the calling function. + +@noindent +For example, a user-defined widget containing the following code +converts the characters in the argument under the cursor into all upper +case: + +@noindent +@example +modify-current-argument '$@{(U)ARG@}' +@end example + +@noindent +The following strips any quoting from the current word (whether backslashes +or one of the styles of quotes), and replaces it with single quoting +throughout: + +@noindent +@example +modify-current-argument '$@{(qq)$@{(Q)ARG@}@}' +@end example + +@noindent +The following performs directory expansion on the command line +argument and replaces it by the absolute path: + +@noindent +@example +expand-dir() @{ + REPLY=$@{~1@} + REPLY=$@{REPLY:a@} +@} +modify-current-argument expand-dir +@end example + +@noindent +In practice the function @t{expand-dir} would probably not be defined +within the widget where @t{modify-current-argument} is called. + +@end table + +@noindent + +@subsection Styles +@noindent + +@noindent +The behavior of several of the above widgets can be controlled by the use +of the @t{zstyle} mechanism. In particular, widgets that interact with +the completion system pass along their context to any completions that +they invoke. + +@noindent +@table @asis +@kindex break-keys, widget style +@item @t{break-keys} +This style is used by the @t{incremental-complete-word} widget. Its value +should be a pattern, and all keys matching this pattern will cause the +widget to stop incremental completion without the key having any further +effect. Like all styles used directly by +@t{incremental-complete-word}, this style is looked up using the +context `@t{:incremental}'. + +@kindex completer, completion style +@item @t{completer} +The @t{incremental-complete-word} and @t{insert-and-predict} widgets set +up their top-level context name before calling completion. This allows +one to define different sets of completer functions for normal completion +and for these widgets. For example, to use completion, approximation and +correction for normal completion, completion and correction for +incremental completion and only completion for prediction one could use: + +@noindent +@example +zstyle ':completion:*' completer \ + _complete _correct _approximate +zstyle ':completion:incremental:*' completer \ + _complete _correct +zstyle ':completion:predict:*' completer \ + _complete +@end example + +@noindent +It is a good idea to restrict the completers used in prediction, because +they may be automatically invoked as you type. The @t{_list} and +@t{_menu} completers should never be used with prediction. The +@t{_approximate}, @t{_correct}, @t{_expand}, and @t{_match} completers may +be used, but be aware that they may change characters anywhere in the word +behind the cursor, so you need to watch carefully that the result is what +you intended. + +@kindex cursor, completion style +@item @t{cursor} +The @t{insert-and-predict} widget uses this style, in the context +`@t{:predict}', to decide where to place the cursor after completion has +been tried. Values are: + +@noindent +@table @asis +@item @t{complete} +The cursor is left where it was when completion finished, but only if +it is after a character equal to the one just inserted by the user. If +it is after another character, this value is the same as `@t{key}'. + +@item @t{key} +The cursor is left +after the @var{n}th occurrence of the character just inserted, where +@var{n} is the number of times that character appeared in the word +before completion was attempted. In short, this has the effect of +leaving the cursor after the character just typed even if the +completion code found out that no other characters need to be inserted +at that position. + +@end table + +@noindent +Any other value for this style unconditionally leaves the cursor at the +position where the completion code left it. + +@kindex list, widget style +@item @t{list} +When using the @t{incremental-complete-word} widget, this style says +if the matches should be listed on every key press (if they fit on the +screen). Use the context prefix `@t{:completion:incremental}'. + +@noindent +The @t{insert-and-predict} widget uses this style to decide if the +completion should be shown even if there is only one possible completion. +This is done if the value of this style is the string @t{always}. In this +case the context is `@t{:predict}' (@emph{not} `@t{:completion:predict}'). + +@kindex match, widget style +@item @t{match} +This style is used by @t{smart-insert-last-word} to provide a pattern +(using full @t{EXTENDED_GLOB} syntax) that matches an interesting word. +The context is the name of the widget to which @t{smart-insert-last-word} +is bound (see above). The default behavior of @t{smart-insert-last-word} +is equivalent to: + +@noindent +@example +zstyle :insert-last-word match '*[[:alpha:]/\\]*' +@end example + +@noindent +However, you might want to include words that contain spaces: + +@noindent +@example +zstyle :insert-last-word match '*[[:alpha:][:space:]/\\]*' +@end example + +@noindent +Or include numbers as long as the word is at least two characters long: + +@noindent +@example +zstyle :insert-last-word match '*([[:digit:]]?|[[:alpha:]/\\])*' +@end example + +@noindent +The above example causes redirections like "2>" to be included. + +@kindex prompt, widget style +@item @t{prompt} +The @t{incremental-complete-word} widget shows the value of this +style in the status line during incremental completion. The string +value may contain any of the following substrings in the manner of +the @t{PS1} and other prompt parameters: + +@noindent +@table @asis +@item @t{%c} +Replaced by the name of the completer function that generated the +matches (without the leading underscore). + +@item @t{%l} +When the @t{list} style is set, +replaced by `@t{...}' if the list of matches is too long to fit on the +screen and with an empty string otherwise. If the @t{list} style is +`false' or not set, `@t{%l}' is always removed. + +@item @t{%n} +Replaced by the number of matches generated. + +@item @t{%s} +Replaced by `@t{-no match-}', `@t{-no prefix-}', or an empty string +if there is no completion matching the word on the line, if the +matches have no common prefix different from the word on the line, or +if there is such a common prefix, respectively. + +@item @t{%u} +Replaced by the unambiguous part of all matches, if there +is any, and if it is different from the word on the line. + +@end table + +@noindent +Like `@t{break-keys}', this uses the `@t{:incremental}' context. + +@kindex stop-keys, widget style +@item @t{stop-keys} +This style is used by the @t{incremental-complete-word} widget. Its value +is treated similarly to the one for the @t{break-keys} style (and uses +the same context: `@t{:incremental}'). However, in +this case all keys matching the pattern given as its value will stop +incremental completion and will then execute their usual function. + +@kindex toggle, widget style +@item @t{toggle} +This boolean style is used by @t{predict-on} and its related widgets in +the context `@t{:predict}'. If set to one of the standard `true' values, +predictive typing is automatically toggled off in situations where it is +unlikely to be useful, such as when editing a multi-line buffer or after +moving into the middle of a line and then deleting a character. The +default is to leave prediction turned on until an explicit call to +@t{predict-off}. + +@kindex verbose, widget style +@item @t{verbose} +This boolean style is used by @t{predict-on} and its related widgets in +the context `@t{:predict}'. If set to one of the standard `true' values, +these widgets display a message below the prompt when the predictive state +is toggled. This is most useful in combination with the @t{toggle} style. +The default does not display these messages. + +@kindex widget, widget style +@item @t{widget} +This style is similar to the @t{command} style: For widget functions that +use @t{zle} to call other widgets, this style can sometimes be used to +override the widget which is called. The context for this style is the +name of the calling widget (@emph{not} the name of the calling function, +because one function may be bound to multiple widget names). + +@noindent +@example +zstyle :copy-earlier-word widget smart-insert-last-word +@end example + +@noindent +Check the documentation for the calling widget or function to determine +whether the @t{widget} style is used. + +@end table + +@noindent +@node Exception Handling, MIME Functions, ZLE Functions, User Contributions + +@section Exception Handling +@noindent + +@noindent +Two functions are provided to enable zsh to provide exception handling in a +form that should be familiar from other languages. + +@noindent +@table @asis +@findex throw +@item @t{throw} @var{exception} +The function @t{throw} throws the named @var{exception}. The name is +an arbitrary string and is only used by the @t{throw} and @t{catch} +functions. An exception is for the most part treated the same as a +shell error, i.e. an unhandled exception will cause the shell to abort all +processing in a function or script and to return to the top level in an +interactive shell. + +@item @t{catch} @var{exception-pattern} +The function @t{catch} returns status zero if an exception was thrown and +the pattern @var{exception-pattern} matches its name. Otherwise it +returns status 1. @var{exception-pattern} is a standard +shell pattern, respecting the current setting of the @t{EXTENDED_GLOB} +option. An alias @t{catch} is also defined to prevent the argument to the +function from matching filenames, so patterns may be used unquoted. Note +that as exceptions are not fundamentally different from other shell errors +it is possible to catch shell errors by using an empty string as the +exception name. The shell variable @t{CAUGHT} is set by @t{catch} to the +name of the exception caught. It is possible to rethrow an exception by +calling the @t{throw} function again once an exception has been caught. +@findex catch + +@end table + +@noindent +The functions are designed to be used together with the @t{always} construct +described in +@ref{Complex Commands}. This is important as only this +construct provides the required support for exceptions. A typical example +is as follows. + +@noindent +@example +@{ + # "try" block + # ... nested code here calls "throw MyExcept" +@} always @{ + # "always" block + if catch MyExcept; then + print "Caught exception MyExcept" + elif catch @value{dsq}; then + print "Caught a shell error. Propagating..." + throw @value{dsq} + fi + # Other exceptions are not handled but may be caught further + # up the call stack. +@} +@end example + +@noindent +If all exceptions should be caught, the following idiom might be +preferable. + +@noindent +@example +@{ + # ... nested code here throws an exception +@} always @{ + if catch *; then + case $CAUGHT in + (MyExcept) + print "Caught my own exception" + ;; + (*) + print "Caught some other exception" + ;; + esac + fi +@} +@end example + +@noindent +In common with exception handling in other languages, the exception may be +thrown by code deeply nested inside the `try' block. However, note that it +must be thrown inside the current shell, not in a subshell forked for a +pipeline, parenthesised current-shell construct, or some form of +command or process substitution. + +@noindent +The system internally uses the shell variable @t{EXCEPTION} to record the +name of the exception between throwing and catching. One drawback of this +scheme is that if the exception is not handled the variable @t{EXCEPTION} +remains set and may be incorrectly recognised as the name of an exception +if a shell error subsequently occurs. Adding @t{unset EXCEPTION} at the +start of the outermost layer of any code that uses exception handling will +eliminate this problem. + +@noindent +@node MIME Functions, Mathematical Functions, Exception Handling, User Contributions + +@section MIME Functions +@noindent + +@noindent +Three functions are available to provide handling of files recognised by +extension, for example to dispatch a file @t{text.ps} when executed as a +command to an appropriate viewer. + +@noindent +@table @asis +@findex zsh-mime-setup +@findex zsh-mime-handler +@item @t{zsh-mime-setup} [ @t{-fv} ] [ @t{-l} [ @var{suffix} ... ] ] +@itemx @t{zsh-mime-handler} [ @t{-l} ] @var{command argument} ... +These two functions use the files @t{~/.mime.types} and @t{/etc/mime.types}, +which associate types and extensions, as well as @t{~/.mailcap} and +@t{/etc/mailcap} files, which associate types and the programs that +handle them. These are provided on many systems with the Multimedia +Internet Mail Extensions. + +@noindent +To enable the system, the function @t{zsh-mime-setup} should be +autoloaded and run. This allows files with extensions to be treated +as executable; such files be completed by the function completion system. +The function @t{zsh-mime-handler} should not need to be called by the +user. + +@noindent +The system works by setting up suffix aliases with `@t{alias -s}'. +Suffix aliases already installed by the user will not be overwritten. + +@noindent +For suffixes defined in lower case, upper case variants will also +automatically be handled (e.g. @t{PDF} is automatically handled if +handling for the suffix @t{pdf} is defined), but not vice versa. + +@noindent +Repeated calls to @t{zsh-mime-setup} do not override the existing +mapping between suffixes and executable files unless the option @t{-f} +is given. Note, however, that this does not override existing suffix +aliases assigned to handlers other than @t{zsh-mime-handler}. + +@noindent +Calling @t{zsh-mime-setup} with the option @t{-l} lists the existing +mappings without altering them. Suffixes to list (which may contain +pattern characters that should be quoted from immediate interpretation +on the command line) may be given as additional arguments, otherwise +all suffixes are listed. + +@noindent +Calling @t{zsh-mime-setup} with the option +@t{-v} causes verbose output to be shown during the setup operation. + +@noindent +The system respects the @t{mailcap} flags @t{needsterminal} and +@t{copiousoutput}; see mailcap(4) or mailcap(5) +(the man page's name varies across platforms). + +@noindent +The functions use the following styles, which are defined with the +@t{zstyle} builtin command (@ref{The zsh/zutil Module}). They should be defined +before @t{zsh-mime-setup} is run. The contexts used all +start with @t{:mime:}, with additional components in some cases. +It is recommended that a trailing @t{*} (suitably quoted) be appended +to style patterns in case the system is extended in future. Some +examples are given below. + +@noindent +For files that have multiple suffixes, e.g. @t{.pdf.gz}, where the +context includes the suffix it will be looked up starting with the +longest possible suffix until a match for the style is found. +For example, if @t{.pdf.gz} produces a match for the handler, that +will be used; otherwise the handler for @t{.gz} will be used. Note +that, owing to the way suffix aliases work, it is always required that +there be a handler for the shortest possible suffix, so in this example +@t{.pdf.gz} can only be handled if @t{.gz} is also handled (though +not necessarily in the same way). Alternatively, if no handling +for @t{.gz} on its own is needed, simply adding the command + +@noindent +@example +alias -s gz=zsh-mime-handler +@end example + +@noindent +to the initialisation code is sufficient; @t{.gz} will not be handled +on its own, but may be in combination with other suffixes. + +@noindent +@table @asis +@kindex current-shell, MIME style +@item @t{current-shell} +If this boolean style is true, the mailcap handler for the context in +question is run using the @t{eval} builtin instead of by starting a new +@t{sh} process. This is more efficient, but may not work in the occasional +cases where the mailcap handler uses strict POSIX syntax. + +@kindex disown, MIME style +@item @t{disown} +If this boolean style is true, mailcap handlers started in the +background will be disowned, i.e. not subject to job control within +the parent shell. Such handlers nearly always produce their own +windows, so the only likely harmful side effect of setting the style is +that it becomes harder to kill jobs from within the shell. + +@kindex execute-as-is, MIME style +@item @t{execute-as-is} +This style gives a list of patterns to be matched against files +passed for execution with a handler program. If the file matches +the pattern, the entire command line is executed in its current form, +with no handler. This is useful for files which might have suffixes +but nonetheless be executable in their own right. If the style +is not set, the pattern @t{*(*) *(/)} is used; +hence executable files are executed directly and not passed to a +handler, and the option @t{AUTO_CD} may be used to change to directories +that happen to have MIME suffixes. + +@kindex execute-never, MIME style +@item @t{execute-never} +This style is useful in combination with @t{execute-as-is}. It is +set to an array of patterns corresponding to full paths to files that +should never be treated as executable, even if the file passed to +the MIME handler matches @t{execute-as-is}. This is useful for file +systems that don't handle execute permission or that contain executables +from another operating system. For example, if @t{/mnt/windows} is a +Windows mount, then + +@noindent +@example +zstyle ':mime:*' execute-never '/mnt/windows/*' +@end example + +@noindent +will ensure that any files found in that area will be executed as MIME +types even if they are executable. As this example shows, the complete +file name is matched against the pattern, regardless of how the file +was passed to the handler. The file is resolved to a full path using +the @t{:P} modifier described in +@ref{Modifiers}; +this means that symbolic links are resolved where possible, so that +links into other file systems behave in the correct fashion. + +@kindex file-path, MIME style +@item @t{file-path} +Used if the style @t{find-file-in-path} is true for the same context. +Set to an array of directories that are used for searching for the +file to be handled; the default is the command path given by the +special parameter @t{path}. The shell option @t{PATH_DIRS} is respected; +if that is set, the appropriate path will be searched even if the +name of the file to be handled as it appears on the command line contains +a `@t{/}'. +The full context is @t{:mime:.}@var{suffix}@t{:}, as described for the style +@t{handler}. + +@kindex find-file-in-path, MIME style +@item @t{find-file-in-path} +If set, allows files whose names do not contain absolute paths +to be searched for in the command path or the path specified by the +@t{file-path} style. If the file is not found in the path, it is looked +for locally (whether or not the current directory is in the path); if it is +not found locally, the handler will abort unless the @t{handle-nonexistent} +style is set. Files found in the path are tested as described for +the style @t{execute-as-is}. +The full context is @t{:mime:.}@var{suffix}@t{:}, as described for the style +@t{handler}. + +@kindex flags, MIME style +@item @t{flags} +Defines flags to go with a handler; the context is as for the +@t{handler} style, and the format is as for the flags in @t{mailcap}. + +@kindex handle-nonexistent, MIME style +@item @t{handle-nonexistent} +By default, arguments that don't correspond to files are not passed +to the MIME handler in order to prevent it from intercepting commands found +in the path that happen to have suffixes. This style may be set to +an array of extended glob patterns for arguments that will be passed to the +handler even if they don't exist. If it is not explicitly set it +defaults to @t{[[:alpha:]]#:/*} which allows URLs to be passed to the MIME +handler even though they don't exist in that format in the file system. +The full context is @t{:mime:.}@var{suffix}@t{:}, as described for the style +@t{handler}. + +@kindex handler, MIME style +@item @t{handler} +Specifies a handler for a suffix; the suffix is given by the context as +@t{:mime:.}@var{suffix}@t{:}, and the format of the handler is exactly +that in @t{mailcap}. Note in particular the `@t{.}' and trailing colon +to distinguish this use of the context. This overrides any handler +specified by the @t{mailcap} files. If the handler requires a terminal, +the @t{flags} style should be set to include the word @t{needsterminal}, +or if the output is to be displayed through a pager (but not if the +handler is itself a pager), it should include @t{copiousoutput}. + +@kindex mailcap, MIME style +@item @t{mailcap} +A list of files in the format of @t{~/.mailcap} and +@t{/etc/mailcap} to be read during setup, replacing the default list +which consists of those two files. The context is @t{:mime:}. +A @t{+} in the list will be replaced by the default files. + +@kindex mailcap-priorities, MIME style +@item @t{mailcap-priorities} +This style is used to resolve multiple mailcap entries for the same MIME +type. It consists of an array of the following elements, in descending +order of priority; later entries will be used if earlier entries are +unable to resolve the entries being compared. If none of the tests +resolve the entries, the first entry encountered is retained. + +@noindent +@table @asis +@item @t{files} +The order of files (entries in the @t{mailcap} style) read. Earlier +files are preferred. (Note this does not resolve entries in the same file.) + +@item @t{priority} +The priority flag from the mailcap entry. The priority is an integer +from 0 to 9 with the default value being 5. + +@item @t{flags} +The test given by the @t{mailcap-prio-flags} option is used to resolve +entries. + +@item @t{place} +Later entries are preferred; as the entries are strictly ordered, this +test always succeeds. + +@end table + +@noindent +Note that as this style is handled during initialisation, the context +is always @t{:mime:}, with no discrimination by suffix. + +@kindex mailcap-prio-flags, MIME style +@item @t{mailcap-prio-flags} +This style is used when the keyword @t{flags} is encountered in the +list of tests specified by the @t{mailcap-priorities} style. +It should be set to a list of patterns, each of which is tested against +the flags specified in the mailcap entry (in other words, the sets of +assignments found with some entries in the mailcap file). Earlier +patterns in the list are preferred to later ones, and matched patterns +are preferred to unmatched ones. + +@kindex mime-types, MIME style +@item @t{mime-types} +A list of files in the format of @t{~/.mime.types} and +@t{/etc/mime.types} to be read during setup, replacing the default list +which consists of those two files. The context is @t{:mime:}. +A @t{+} in the list will be replaced by the default files. + +@kindex never-background, MIME style +@item @t{never-background} +If this boolean style is set, the handler for the given context is +always run in the foreground, even if the flags provided in the mailcap +entry suggest it need not be (for example, it doesn't require a +terminal). + +@kindex pager, MIME style +@item @t{pager} +If set, will be used instead of @t{$PAGER} or @t{more} to handle +suffixes where the @t{copiousoutput} flag is set. The context is +as for @t{handler}, i.e. @t{:mime:.}@var{suffix}@t{:} for handling +a file with the given @var{suffix}. + +@end table + +@noindent +Examples: + +@noindent +@example +zstyle ':mime:*' mailcap ~/.mailcap /usr/local/etc/mailcap +zstyle ':mime:.txt:' handler less %s +zstyle ':mime:.txt:' flags needsterminal +@end example + +@noindent +When @t{zsh-mime-setup} is subsequently run, it will look for +@t{mailcap} entries in the two files given. Files of suffix @t{.txt} +will be handled by running `@t{less} @var{file.txt}'. The flag +@t{needsterminal} is set to show that this program must run attached to a +terminal. + +@noindent +As there are several steps to dispatching a command, the following +should be checked if attempting to execute a file by extension +@t{.}@var{ext} does not have the expected effect. + +@noindent +The command `@t{alias -s} @var{ext}' should show +`@t{ps=zsh-mime-handler}'. If it shows something else, another suffix +alias was already installed and was not overwritten. If it shows +nothing, no handler was installed: this is most likely because no +handler was found in the @t{.mime.types} and @t{mailcap} combination for +@t{.ext} files. In that case, appropriate handling should be added to +@t{~/.mime.types} and @t{mailcap}. + +@noindent +If the extension is handled by @t{zsh-mime-handler} but the file is +not opened correctly, either the handler defined for the type is +incorrect, or the flags associated with it are in appropriate. Running +@t{zsh-mime-setup -l} will show the handler and, if there are any, the +flags. A @t{%s} in the handler is replaced by the file (suitably quoted +if necessary). Check that the handler program listed lists and can +be run in the way shown. Also check that the flags @t{needsterminal} or +@t{copiousoutput} are set if the handler needs to be run under a +terminal; the second flag is used if the output should be sent to a pager. +An example of a suitable @t{mailcap} entry for such a program is: + +@noindent +@example +text/html; /usr/bin/lynx '%s'; needsterminal +@end example + +@noindent +Running `@t{zsh-mime-handler -l} @var{command line}' prints the command +line that would be executed, simplified to remove the effect of any +flags, and quoted so that the output can be run as a complete zsh +command line. This is used by the completion system to decide how to +complete after a file handled by @t{zsh-mime-setup}. + +@findex pick-web-browser +@item @t{pick-web-browser} +This function is separate from the two MIME functions described above +and can be assigned directly to a suffix: + +@noindent +@example +autoload -U pick-web-browser +alias -s html=pick-web-browser +@end example + +@noindent +It is provided as an intelligent front end to dispatch a web browser. +It may be run as either a function or a shell script. The status +255 is returned if no browser could be started. + +@noindent +Various styles are available to customize the choice of browsers: + +@noindent +@table @asis +@item @t{browser-style} +The value of the style is an array giving preferences in decreasing order +for the type of browser to use. The values of elements may be + +@noindent +@table @asis +@item @t{running} +Use a GUI browser that is already running when an X Window display is +available. The browsers listed in the @t{x-browsers} style are tried +in order until one is found; if it is, the file will be displayed in +that browser, so the user may need to check whether it has appeared. +If no running browser is found, one is not started. Browsers other than +Firefox, Opera and Konqueror are assumed to understand the Mozilla +syntax for opening a URL remotely. + +@item @t{x} +Start a new GUI browser when an X Window display is available. Search for +the availability of one of the browsers listed in the @t{x-browsers} style +and start the first one that is found. No check is made for an already +running browser. + +@item @t{tty} +Start a terminal-based browser. Search for the availability of one +of the browsers listed in the @t{tty-browsers} style and start the +first one that is found. + +@end table + +@noindent +If the style is not set the default @t{running x tty} is used. + +@item @t{x-browsers} +An array in decreasing order +of preference of browsers to use when running under the X Window System. +The array consists of the command name under which to start the +browser. They are looked up in the context @t{:mime:} (which may +be extended in future, so appending `@t{*}' is recommended). For +example, + +@noindent +@example +zstyle ':mime:*' x-browsers opera konqueror firefox +@end example + +@noindent +specifies that @t{pick-web-browser} should first look for a running +instance of Opera, Konqueror or Firefox, in that order, and if it +fails to find any should attempt to start Opera. The default is +@t{firefox mozilla netscape opera konqueror}. + +@item @t{tty-browsers} +An array similar to @t{x-browsers}, except that it gives browsers to +use when no X Window display is available. The default is +@t{elinks links lynx}. + +@item @t{command} +If it is set this style is used to pick the command +used to open a page for a browser. The context is +@t{:mime:browser:new:$browser:} to start a new browser or +@t{:mime:browser:running:$browser:} to open a URL in a browser already +running on the current X display, where @t{$browser} is the value matched +in the @t{x-browsers} or @t{tty-browsers} style. The escape sequence +@t{%b} in the style's value will be replaced by the browser, while @t{%u} +will be replaced by the URL. If the style is not set, the default for all +new instances is equivalent to @t{%b %u} and the defaults for using running +browsers are equivalent to the values @t{kfmclient openURL %u} for +Konqueror, @t{firefox -new-tab %u} for Firefox, @t{opera -newpage %u} +for Opera, and @t{%b -remote "openUrl(%u)"} for all others. + +@end table + +@end table + +@noindent +@node Mathematical Functions, User Configuration Functions, MIME Functions, User Contributions + +@section Mathematical Functions +@noindent + +@noindent +@table @asis +@findex zcalc +@item @t{zcalc} [ @t{-erf} ] [ @var{expression} ... ] +A reasonably powerful calculator based on zsh's arithmetic evaluation +facility. The syntax is similar to that of formulae in most programming +languages; see +@ref{Arithmetic Evaluation} for details. + +@noindent +Non-programmers should note that, as in many other programming +languages, expressions involving only integers (whether constants +without a `@t{.}', variables containing such constants as strings, or +variables declared to be integers) are by default evaluated using +integer arithmetic, which is not how an ordinary desk calculator +operates. To force floating point operation, pass the option @t{-f}; +see further notes below. + +@noindent +If the file @t{~/.zcalcrc} exists it will be sourced inside the function +once it is set up and about to process the command line. This +can be used, for example, to set shell options; @t{emulate -L zsh} +and @t{setopt extendedglob} are in effect at this point. Any +failure to source the file if it exists is treated as fatal. +As with other initialisation files, the directory @t{$ZDOTDIR} is used +instead of @t{$HOME} if it is set. + +@noindent +The mathematical library @t{zsh/mathfunc} will be loaded if it is +available; see +@ref{The zsh/mathfunc Module}. The mathematical functions +correspond to the raw system libraries, so trigonometric functions are +evaluated using radians, and so on. + +@noindent +Each line typed is evaluated as an expression. The prompt shows a number, +which corresponds to a positional parameter where the result of that +calculation is stored. For example, the result of the calculation on the +line preceded by `@t{4> }' is available as @t{$4}. The last value +calculated is available as @t{ans}. Full command line editing, including +the history of previous calculations, is available; the history is saved in +the file @t{~/.zcalc_history}. To exit, enter a blank line or type `@t{:q}' +on its own (`@t{q}' is allowed for historical compatibility). + +@noindent +A line ending with a single backslash is treated in the same fashion +as it is in command line editing: the backslash is removed, the +function prompts for more input (the prompt is preceded by `@t{...}' +to indicate this), and the lines are combined into one to get the final +result. In addition, if the input so far contains more open than +close parentheses @t{zcalc} will prompt for more input. + +@noindent +If arguments are given to @t{zcalc} on start up, they are used to prime the +first few positional parameters. A visual indication of this is given when +the calculator starts. + +@noindent +The constants @t{PI} (3.14159...) and @t{E} (2.71828...) are provided. +Parameter assignment is possible, but note that all parameters will be +put into the global namespace unless the @t{:local} special command is +used. The function creates local variables whose names start with +@t{_}, so users should avoid doing so. The variables @t{ans} (the last +answer) and @t{stack} (the stack in RPN mode) may be referred to +directly; @t{stack} is an array but elements of it are numeric. Various +other special variables are used locally with their standard meaning, +for example @t{compcontext}, @t{match}, @t{mbegin}, @t{mend}, @t{psvar}. + +@noindent +The output base can be initialised by passing the option `@t{-#}@var{base}', +for example `@t{zcalc -#16}' (the `@t{#}' may have to be quoted, depending +on the globbing options set). + +@noindent +If the option `@t{-e}' is set, the function runs non-interactively: +the arguments are treated as expressions to be evaluated as if entered +interactively line by line. + +@noindent +If the option `@t{-f}' is set, all numbers are treated as floating +point, hence for example the expression `@t{3/4}' evaluates to 0.75 +rather than 0. Options must appear in separate words. + +@noindent +If the option `@t{-r}' is set, RPN (Reverse Polish Notation) mode is +entered. This has various additional properties: +@table @asis +@item Stack +Evaluated values are maintained in a stack; this is contained in +an array named @t{stack} with the most recent value in @t{$@{stack[1]@}}. + +@item Operators and functions +If the line entered matches an operator (@t{+}, @t{-}, @t{*}, +@t{/}, @t{**}, @t{^}, @t{|} or @t{&}) or a function supplied by the +@t{zsh/mathfunc} library, the bottom element or elements of the stack +are popped to use as the argument or arguments. The higher elements +of stack (least recent) are used as earlier arguments. The result is +then pushed into @t{$@{stack[1]@}}. + +@item Expressions +Other expressions are evaluated normally, printed, and added to the +stack as numeric values. The syntax within expressions on a single line +is normal shell arithmetic (not RPN). + +@item Stack listing +If an integer follows the option @t{-r} with no space, then +on every evaluation that many elements of the stack, where available, +are printed instead of just the most recent result. Hence, for example, +@t{zcalc -r4} shows @t{$stack[4]} to @t{$stack[1]} each time results +are printed. + +@item Duplication: @t{=} +The pseudo-operator @t{=} causes the most recent element of +the stack to be duplicated onto the stack. + +@item @t{pop} +The pseudo-function @t{pop} causes the most recent element of +the stack to be popped. A `@t{>}' on its own has the same effect. + +@item @t{>}@var{ident} +The expression @t{>} followed (with no space) by a shell identifier +causes the most recent element of the stack to be popped and +assigned to the variable with that name. The variable is +local to the @t{zcalc} function. + +@item @t{<}@var{ident} +The expression @t{<} followed (with no space) by a shell identifier +causes the value of the variable with that name to be pushed +onto the stack. @var{ident} may be an integer, in which +case the previous result with that number (as shown before +the @t{>} in the standard @t{zcalc} prompt) is put on the stack. + +@item Exchange: @t{xy} +The pseudo-function @t{xy} causes the most recent two elements of +the stack to be exchanged. `@t{<>}' has the same effect. + +@end table + +@noindent +The prompt is configurable via the parameter @t{ZCALCPROMPT}, which +undergoes standard prompt expansion. The index of the current entry is +stored locally in the first element of the array @t{psvar}, which can be +referred to in @t{ZCALCPROMPT} as `@t{%1v}'. The default prompt is +`@t{%1v> }'. + +@noindent +The variable @t{ZCALC_ACTIVE} is set within the function and can +be tested by nested functions; it has the value @t{rpn} if RPN mode is +active, else 1. + +@noindent +A few special commands are available; these are introduced by a colon. +For backward compatibility, the colon may be omitted for certain +commands. Completion is available if @t{compinit} has been run. + +@noindent +The output precision may be specified within zcalc by special commands +familiar from many calculators. +@table @asis +@item @t{:norm} +The default output format. It corresponds to the printf @t{%g} +specification. Typically this shows six decimal digits. + +@item @t{:sci} @var{digits} +Scientific notation, corresponding to the printf @t{%g} output format with +the precision given by @var{digits}. This produces either fixed point or +exponential notation depending on the value output. + +@item @t{:fix} @var{digits} +Fixed point notation, corresponding to the printf @t{%f} output format with +the precision given by @var{digits}. + +@item @t{:eng} @var{digits} +Exponential notation, corresponding to the printf @t{%E} output format with +the precision given by @var{digits}. + +@item @t{:raw} +Raw output: this is the default form of the output from a math +evaluation. This may show more precision than the number actually +possesses. + +@end table + +@noindent +Other special commands: +@table @asis +@item @t{:!}@var{line...} +Execute @var{line...} as a normal shell command line. Note that it +is executed in the context of the function, i.e. with local variables. +Space is optional after @t{:!}. + +@item @t{:local} @var{arg} ... +Declare variables local to the function. Other variables +may be used, too, but they will be taken from or put into the global +scope. + +@item @t{:function} @var{name} [ @var{body} ] +Define a mathematical function or (with no @var{body}) delete it. +@t{:function} may be abbreviated to @t{:func} or simply @t{:f}. +The @var{name} may contain the same characters as a shell function name. +The function is defined using @t{zmathfuncdef}, see below. + +@noindent +Note that @t{zcalc} takes care of all quoting. Hence for example: + +@noindent +@example +:f cube $1 * $1 * $1 +@end example + +@noindent +defines a function to cube the sole argument. Functions so defined, or +indeed any functions defined directly or indirectly using @t{functions +-M}, are available to execute by typing only the name on the line in RPN +mode; this pops the appropriate number of arguments off the stack +to pass to the function, i.e. 1 in the case of the example @t{cube} +function. If there are optional arguments only the mandatory +arguments are supplied by this means. + +@item @t{[#}@var{base}@t{]} +This is not a special command, rather part of normal arithmetic +syntax; however, when this form appears on a line by itself the default +output radix is set to @var{base}. Use, for example, `@t{[#16]}' to display +hexadecimal output preceded by an indication of the base, or `@t{[##16]}' +just to display the raw number in the given base. Bases themselves are +always specified in decimal. `@t{[#]}' restores the normal output format. +Note that setting an output base suppresses floating point output; use +`@t{[#]}' to return to normal operation. + +@item @t{$}@var{var} +Print out the value of var literally; does not affect the calculation. +To use the value of var, omit the leading `@t{$}'. + +@end table + +@noindent +See the comments in the function for a few extra tips. + +@findex max +@findex min +@findex sum +@findex zmathfunc +@item @t{min(}@var{arg}@t{, ...)} +@itemx @t{max(}@var{arg}@t{, ...)} +@itemx @t{sum(}@var{arg}@t{, ...)} +@itemx @t{zmathfunc} +The function @t{zmathfunc} defines the three mathematical functions +@t{min}, @t{max}, and @t{sum}. The functions @t{min} and @t{max} take +one or more arguments. The function @t{sum} takes zero or more arguments. +Arguments can be of different types (ints and floats). + +@noindent +Not to be confused with the @t{zsh/mathfunc} module, described in +@ref{The zsh/mathfunc Module}. + +@findex zmathfuncdef +@item @t{zmathfuncdef} [ @var{mathfunc} [ @var{body} ] ] +A convenient front end to @t{functions -M}. + +@noindent +With two arguments, define a mathematical function named @var{mathfunc} +which can be used in any form of arithmetic evaluation. @var{body} +is a mathematical expression to implement the function. It may +contain references to position parameters @t{$1}, @t{$2}, ... +to refer to mandatory parameters and @t{$@{1:-}@var{defvalue}@t{@}} ... +to refer to optional parameters. Note that the forms must be +strictly adhered to for the function to calculate the correct number +of arguments. The implementation is held in a shell function named +@t{zsh_math_func_}@var{mathfunc}; usually the user will not need +to refer to the shell function directly. Any existing function +of the same name is silently replaced. + +@noindent +With one argument, remove the mathematical function @var{mathfunc} +as well as the shell function implementation. + +@noindent +With no arguments, list all @var{mathfunc} functions in a form +suitable for restoring the definition. +The functions have not necessarily been defined by @t{zmathfuncdef}. + +@end table + +@noindent +@node User Configuration Functions, Other Functions, Mathematical Functions, User Contributions + +@section User Configuration Functions +@noindent + +@noindent +The @t{zsh/newuser} module comes with a function to aid in configuring +shell options for new users. If the module is installed, this function can +also be run by hand. It is available even if the module's default +behaviour, namely running the function for a new user logging in without +startup files, is inhibited. + +@noindent +@table @asis +@item @t{zsh-newuser-install} [ @t{-f} ] +The function presents the user with various options for customizing +their initialization scripts. Currently only @t{~/.zshrc} is handled. +@t{$ZDOTDIR/.zshrc} is used instead if the parameter @t{ZDOTDIR} is +set; this provides a way for the user to configure a file without +altering an existing @t{.zshrc}. + +@noindent +By default the function exits immediately if it finds any of the files +@t{.zshenv}, @t{.zprofile}, @t{.zshrc}, or @t{.zlogin} in the appropriate +directory. The option @t{-f} is required in order to force the function +to continue. Note this may happen even if @t{.zshrc} itself does not +exist. + +@noindent +As currently configured, the function will exit immediately if the +user has root privileges; this behaviour cannot be overridden. + +@noindent +Once activated, the function's behaviour is supposed to be +self-explanatory. Menus are present allowing the user to alter +the value of options and parameters. Suggestions for improvements are +always welcome. + +@noindent +When the script exits, the user is given the opportunity to save the new +file or not; changes are not irreversible until this point. However, +the script is careful to restrict changes to the file only to a group +marked by the lines `@t{# Lines configured by zsh-newuser-install}' and +`@t{# End of lines configured by zsh-newuser-install}'. In addition, +the old version of @t{.zshrc} is saved to a file with the suffix +@t{.zni} appended. + +@noindent +If the function edits an existing @t{.zshrc}, it is up to the user +to ensure that the changes made will take effect. For example, if +control usually returns early from the existing @t{.zshrc} the lines +will not be executed; or a later initialization file may override +options or parameters, and so on. The function itself does not attempt to +detect any such conflicts. + +@end table + +@noindent +@node Other Functions, , User Configuration Functions, User Contributions + +@section Other Functions +@noindent + +@noindent +There are a large number of helpful functions in the @t{Functions/Misc} +directory of the zsh distribution. Most are very simple and do not +require documentation here, but a few are worthy of special mention. + +@noindent + +@subsection Descriptions +@noindent + +@noindent +@table @asis +@findex colors +@item @t{colors} +This function initializes several associative arrays to map color names to +(and from) the ANSI standard eight-color terminal codes. These are used +by the prompt theme system (@ref{Prompt Themes}). You seldom should need to run +@t{colors} more than once. + +@noindent +The eight base colors are: @t{black}, @t{red}, @t{green}, @t{yellow}, +@t{blue}, @t{magenta}, @t{cyan}, and @t{white}. Each of these has codes for +foreground and background. In addition there are seven intensity attributes: +@t{bold}, @t{faint}, @t{standout}, @t{underline}, @t{blink}, @t{reverse}, +and @t{conceal}. Finally, there are seven codes used to negate attributes: +@t{none} (reset all attributes to the defaults), @t{normal} +(neither bold nor faint), @t{no-standout}, @t{no-underline}, @t{no-blink}, +@t{no-reverse}, and @t{no-conceal}. + +@noindent +Some terminals do not support all combinations of colors and intensities. + +@noindent +The associative arrays are: + +@noindent +@table @asis +@item @t{color} +@itemx @t{colour} +Map all the color names to their integer codes, and integer codes to the +color names. The eight base names map to the foreground color codes, as +do names prefixed with `@t{fg-}', such as `@t{fg-red}'. Names prefixed +with `@t{bg-}', such as `@t{bg-blue}', refer to the background codes. The +reverse mapping from code to color yields base name for foreground codes +and the @t{bg-} form for backgrounds. + +@noindent +Although it is a misnomer to call them `colors', these arrays also map the +other fourteen attributes from names to codes and codes to names. + +@item @t{fg} +@itemx @t{fg_bold} +@itemx @t{fg_no_bold} +Map the eight basic color names to ANSI terminal escape sequences that set +the corresponding foreground text properties. The @t{fg} sequences change +the color without changing the eight intensity attributes. + +@item @t{bg} +@itemx @t{bg_bold} +@itemx @t{bg_no_bold} +Map the eight basic color names to ANSI terminal escape sequences that set +the corresponding background properties. The @t{bg} sequences change the +color without changing the eight intensity attributes. + +@end table + +@noindent +In addition, the scalar parameters @t{reset_color} and @t{bold_color} are +set to the ANSI terminal escapes that turn off all attributes and turn on +bold intensity, respectively. + +@findex fned +@item @t{fned} [ @t{-x} @var{num} ] @var{name} +Same as @t{zed -f}. This function does not appear in the zsh +distribution, but can be created by linking @t{zed} to the name @t{fned} +in some directory in your @t{fpath}. + +@findex histed +@item @t{histed} [ [ @var{name} ] @var{size} ] +Same as @t{zed -h}. This function does not appear in the zsh +distribution, but can be created by linking @t{zed} to the name @t{histed} +in some directory in your @t{fpath}. + +@findex is-at-least +@item @t{is-at-least} @var{needed} [ @var{present} ] +Perform a greater-than-or-equal-to comparison of two strings having the +format of a zsh version number; that is, a string of numbers and text with +segments separated by dots or dashes. If the @var{present} string is not +provided, @t{$ZSH_VERSION} is used. Segments are paired left-to-right in +the two strings with leading non-number parts ignored. If one string has +fewer segments than the other, the missing segments are considered zero. + +@noindent +This is useful in startup files to set options and other state that are +not available in all versions of zsh. + +@noindent +@example +is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS +is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS +is-at-least 2.6-17 || print "You can't use is-at-least here." +@end example + +@findex nslookup +@item @t{nslookup} [ @var{arg} ... ] +This wrapper function for the @t{nslookup} command requires the +@t{zsh/zpty} module (see +@ref{The zsh/zpty Module}). It behaves exactly like the standard @t{nslookup} +except that it provides customizable prompts (including a right-side +prompt) and completion of nslookup commands, host names, etc. (if you use +the function-based completion system). Completion styles may be set with +the context prefix `@t{:completion:nslookup}'. + +@noindent +See also the @t{pager}, @t{prompt} and @t{rprompt} styles below. + +@findex regexp-replace +@item @t{regexp-replace} @var{var} @var{regexp} @var{replace} +Use regular expressions to perform a global search and replace operation +on a variable. POSIX extended regular expressions (ERE) are used, +unless the option @t{RE_MATCH_PCRE} has been set, in which case +Perl-compatible regular expressions are used +(this requires the shell to be linked against the @t{pcre} +library). + +@noindent +@var{var} is the name of the variable containing the string to be matched. +The variable will be modified directly by the function. The +variables @t{MATCH}, @t{MBEGIN}, @t{MEND}, @t{match}, @t{mbegin}, @t{mend} +should be avoided as these are used by the regular expression code. + +@noindent +@var{regexp} is the regular expression to match against the string. + +@noindent +@var{replace} is the replacement text. This can contain parameter, command +and arithmetic expressions which will be replaced: in particular, a +reference to @t{$MATCH} will be replaced by the text matched by the pattern. + +@noindent +The return status is 0 if at least one match was performed, else 1. + +@noindent +Note that if using POSIX EREs, the @t{^} or word boundary operators +(where available) may not work properly. + +@findex run-help +@item @t{run-help} @var{cmd} +This function is designed to be invoked by the @t{run-help} ZLE widget, +in place of the default alias. See `Accessing On-Line Help' +(@ref{Utilities}) for setup instructions. + +@noindent +In the discussion which follows, if @var{cmd} is a file system path, it is +first reduced to its rightmost component (the file name). + +@noindent +Help is first sought by looking for a file named @var{cmd} in the directory +named by the @t{HELPDIR} parameter. If no file is found, an assistant +function, alias, or command named @t{run-help-@var{cmd}} is sought. If +found, the assistant is executed with the rest of the current command line +(everything after the command name @var{cmd}) as its arguments. When +neither file nor assistant is found, the external command +`@t{man} @var{cmd}' is run. + +@noindent +An example assistant for the "ssh" command: + +@noindent +@example +run-help-ssh() @{ + emulate -LR zsh + local -a args + # Delete the "-l username" option + zparseopts -D -E -a args l: + # Delete other options, leaving: host command + args=($@{@@:#-*@}) + if [[ $@{#args@} -lt 2 ]]; then + man ssh + else + run-help $args[2] + fi +@} +@end example + +@noindent +Several of these assistants are provided in the @t{Functions/Misc} +directory. These must be autoloaded, or placed as executable scripts in +your search path, in order to be found and used by @t{run-help}. + +@noindent +@table @asis +@findex run-help-btrfs +@findex run-help-git +@findex run-help-ip +@findex run-help-openssl +@findex run-help-p4 +@findex run-help-sudo +@findex run-help-svk +@findex run-help-svn +@item @t{run-help-btrfs} +@itemx @t{run-help-git} +@itemx @t{run-help-ip} +@itemx @t{run-help-openssl} +@itemx @t{run-help-p4} +@itemx @t{run-help-sudo} +@itemx @t{run-help-svk} +@itemx @t{run-help-svn} +Assistant functions for the +@t{btrfs}, +@t{git}, +@t{ip}, +@t{openssl}, +@t{p4}, +@t{sudo}, +@t{svk}, +and +@t{svn}, +commands. + +@end table + +@item @t{tetris} +Zsh was once accused of not being as complete as Emacs, +because it lacked a Tetris game. This function was written to +refute this vicious slander. + +@noindent +This function must be used as a ZLE widget: + +@noindent +@example +autoload -U tetris +zle -N tetris +bindkey @var{keys} tetris +@end example + +@noindent +To start a game, execute the widget by typing the @var{keys}. Whatever command +line you were editing disappears temporarily, and your keymap is also +temporarily replaced by the Tetris control keys. The previous editor state +is restored when you quit the game (by pressing `@t{q}') or when you lose. + +@noindent +If you quit in the middle of a game, the next invocation of the @t{tetris} +widget will continue where you left off. If you lost, it will start a new +game. + +@item @t{tetriscurses} +This is a port of the above to zcurses. The input handling is improved +a bit so that moving a block sideways doesn't automatically advance a +timestep, and the graphics use unicode block graphics. + +@noindent +This version does not save the game state between invocations, and is not +invoked as a widget, but rather as: + +@noindent +@example +autoload -U tetriscurses +tetriscurses +@end example + +@findex zargs +@item @t{zargs} [ @var{option} ... @t{-}@t{-} ] [ @var{input} ... ] [ @t{-}@t{-} @var{command} [ @var{arg} ... ] ] +This function has a similar purpose to GNU xargs. Instead of +reading lines of arguments from the standard input, it takes them from +the command line. This is useful because zsh, especially with recursive +glob operators, often can construct a command line for a shell function +that is longer than can be accepted by an external command. + +@noindent +The @var{option} list represents options of the @t{zargs} command itself, +which are the same as those of @t{xargs}. The @var{input} list is the +collection of strings (often file names) that become the arguments of the +@t{command}, analogous to the standard input of @t{xargs}. Finally, the +@var{arg} list consists of those arguments (usually options) that are +passed to the @var{command} each time it runs. The @var{arg} list precedes +the elements from the @t{input} list in each run. If no @var{command} is +provided, then no @var{arg} list may be provided, and in that event the +default command is `@t{print}' with arguments `@t{-r -}@t{-}'. + +@noindent +For example, to get a long @t{ls} listing of all non-hidden plain files +in the current directory or its subdirectories: + +@noindent +@example +autoload -U zargs +zargs -- **/*(.) -- ls -ld -- +@end example + +@noindent +The first and third occurrences of `@t{-}@t{-}' are used to mark the end +of options for @t{zargs} and @t{ls} respectively to guard against +filenames starting with `@t{-}', while the second is used to separate the +list of files from the command to run (`@t{ls -ld --}'). + +@noindent +The first `@t{-}@t{-}' would also be needed if there was a chance the +list might be empty as in: + +@noindent +@example +zargs -r -- ./*.back(#qN) -- rm -f +@end example + +@noindent +In the event that the string `@t{-}@t{-}' is or may be an @var{input}, the +@t{-e} option may be used to change the end-of-inputs marker. Note that +this does @emph{not} change the end-of-options marker. For example, to use +`@t{..}' as the marker: + +@noindent +@example +zargs -e.. -- **/*(.) .. ls -ld -- +@end example + +@noindent +This is a good choice in that example because no plain file can be named +`@t{..}', but the best end-marker depends on the circumstances. + +@noindent +The options @t{-i}, @t{-I}, @t{-l}, @t{-L}, and @t{-n} differ slightly +from their usage in @t{xargs}. There are no input lines for @t{zargs} to +count, so @t{-l} and @t{-L} count through the @var{input} list, and @t{-n} +counts the number of arguments passed to each execution of @var{command}, +@emph{including} any @var{arg} list. Also, any time @t{-i} or @t{-I} is used, +each @var{input} is processed separately as if by `@t{-L} @t{1}'. + +@noindent +For details of the other @t{zargs} options, see the xargs(1) man page (but note +the difference in function between @t{zargs} and @t{xargs}) or run +@t{zargs} with the @t{-}@t{-help} option. + +@findex zed +@item @t{zed} [ @t{-f} [ @t{-x} @var{num} ] ] @var{name} +@itemx @t{zed} [ @t{-h} [ @var{name} ] @var{size} ] +@itemx @t{zed -b} +This function uses the ZLE editor to edit a file or function. + +@noindent +Only one @var{name} argument is allowed. +If the @t{-f} option is given, the name is taken to be that of +a function; if the function is marked for autoloading, @t{zed} searches +for it in the @t{fpath} and loads it. Note that functions edited this way +are installed into the current shell, but @emph{not} written back to the +autoload file. In this case the @t{-x} option specifies that leading +tabs indenting the function according to syntax should be converted into +the given number of spaces; `@t{-x 2}' is consistent with the layout +of functions distributed with the shell. + +@noindent +Without @t{-f}, @var{name} is the path name of the file to edit, which need +not exist; it is created on write, if necessary. With @t{-h}, the file is +presumed to contain history events. + +@noindent +When no file name is provided for @t{-h} the current shell history is edited +in place. The history is renumbered when zed exits successfully. + +@noindent +When editing history, multi-line events must have a trailing backslash on +every line before the last. + +@noindent +While editing, the function sets the main keymap to @t{zed} and the +vi command keymap to @t{zed-vicmd}. These will be copied from the existing +@t{main} and @t{vicmd} keymaps if they do not exist the first time @t{zed} +is run. They can be used to provide special key bindings used only in zed. + +@noindent +If it creates the keymap, @t{zed} rebinds the return key to insert a line +break and `@t{^X^W}' to accept the edit in the @t{zed} keymap, and binds +`@t{ZZ}' to accept the edit in the @t{zed-vicmd} keymap. + +@noindent +The bindings alone can be installed by running `@t{zed -b}'. This is +suitable for putting into a startup file. Note that, if rerun, +this will overwrite the existing @t{zed} and @t{zed-vicmd} keymaps. + +@noindent +Completion is available, and styles may be set with the context prefix +`@t{:completion:zed:}'. + +@noindent +@findex zed-set-file-name +A zle widget @t{zed-set-file-name} is available. This can be called +by name from within zed using `@t{\ex zed-set-file-name}' or can be +bound to a key in either of the @t{zed} or @t{zed-vicmd} keymaps after +`@t{zed -b}' has been run. When the widget is called, it prompts for +a new name for the file being edited. When zed exits the file will be +written under that name and the original file will be left alone. The +widget has no effect when invoked from `@t{zed -f}'. The completion +context is changed to `@t{:completion:zed-set-file-name:}'. When editing +the current history with `@t{zed -h}', the history is first updated and +then the file is written, but the global setting of @t{HISTFILE} is not +altered. + +@noindent +While @t{zed-set-file-name} is running, zed uses the keymap +@t{zed-normal-keymap}, which is linked from the main keymap in effect +at the time zed initialised its bindings. (This is to make the return key +operate normally.) The result is that if the main keymap has been changed, +the widget won't notice. This is not a concern for most users. + +@findex zcp +@findex zln +@item @t{zcp} [ @t{-finqQvwW} ] @var{srcpat} @var{dest} +@itemx @t{zln} [ @t{-finqQsvwW} ] @var{srcpat} @var{dest} +Same as @t{zmv -C} and @t{zmv -L}, respectively. These functions do not +appear in the zsh distribution, but can be created by linking @t{zmv} to +the names @t{zcp} and @t{zln} in some directory in your @t{fpath}. + +@item @t{zkbd} +See `Keyboard Definition' +(@ref{Utilities}). + +@findex zmv + +@item @t{zmv} [ @t{-finqQsvwW} ] [ @t{-C} | @t{-L} | @t{-M} | -@{@t{p}|@t{P}@} @var{program} ] [ @t{-o} @var{optstring} ] +@itemx @t{@ @ @ @ }@var{srcpat} @var{dest} +Move (usually, rename) files matching the pattern @var{srcpat} to +corresponding files having names of the form given by @var{dest}, where +@var{srcpat} contains parentheses surrounding patterns which will be +replaced in turn by @t{$1}, @t{$2}, ... in @var{dest}. For example, + +@noindent +@example +zmv '(*).lis' '$1.txt' +@end example + +@noindent +renames `@t{foo.lis}' to `@t{foo.txt}', `@t{my.old.stuff.lis}' to +`@t{my.old.stuff.txt}', and so on. + +@noindent +The pattern is always treated as an @t{EXTENDED_GLOB} pattern. Any file +whose name is not changed by the substitution is simply ignored. Any +error (a substitution resulted in an empty string, two substitutions gave +the same result, the destination was an existing regular file and @t{-f} +was not given) causes the entire function to abort without doing +anything. + +@noindent +In addition to pattern replacement, the variable @t{$f} can be referred +to in the second (replacement) argument. This makes it possible to +use variable substitution to alter the argument; see examples below. + +@noindent +Options: + +@noindent +@table @asis +@item @t{-f} +Force overwriting of destination files. Not currently +passed down to the @t{mv}/@t{cp}/@t{ln} command due to vagaries of +implementations (but you can use @t{-o-f} to do that). +@item @t{-i} +Interactive: show each line to be executed and ask the user +whether to execute it. `@t{Y}' or `@t{y}' will execute it, anything else will +skip it. Note that you just need to type one character. +@item @t{-n} +No execution: print what would happen, but don't do it. +@item @t{-q} +Turn bare glob qualifiers off: now assumed by default, so +this has no effect. +@item @t{-Q} +Force bare glob qualifiers on. Don't turn this on unless +you are actually using glob qualifiers in a pattern. +@item @t{-s} +Symbolic, passed down to @t{ln}; only works with @t{-L}. +@item @t{-v} +Verbose: print each command as it's being executed. +@item @t{-w} +Pick out wildcard parts of the pattern, as described above, +and implicitly add parentheses for referring to them. +@item @t{-W} +Just like @t{-w}, with the addition of turning wildcards in +the replacement pattern into sequential @t{$@{1@}} .. @t{$@{N@}} references. +@item @t{-C} +@itemx @t{-L} +@itemx @t{-M} +Force @t{cp}, @t{ln} or @t{mv}, respectively, regardless of +the name of the function. +@item @t{-p} @var{program} +Call @var{program} instead of @t{cp}, @t{ln} or +@t{mv}. Whatever it does, it should at least understand the form +@example +@var{program} @t{-}@t{-} @var{oldname} @var{newname} +@end example +where @var{oldname} and @var{newname} are filenames generated by @t{zmv}. +@var{program} will be split into words, so might be e.g. the name +of an archive tool plus a copy or rename subcommand. +@item @t{-P} @var{program} +As @t{-p} @var{program}, except that +@var{program} does not accept a following @t{-}@t{-} to indicate the +end of options. In this case filenames must already be in a sane +form for the program in question. +@item @t{-o} @var{optstring} +The @var{optstring} is split into words and +passed down verbatim to the @t{cp}, @t{ln} or @t{mv} command called to +perform the work. It should probably begin with a `@t{-}'. +@end table + +@noindent +Further examples: + +@noindent +@example +zmv -v '(* *)' '$@{1// /_@}' +@end example + +@noindent +For any file in the current directory with at least one space in the name, +replace every space by an underscore and display the commands executed. + +@noindent +@example +zmv -v '* *' '$@{f// /_@}' +@end example + +@noindent +This does exactly the same by referring to the file name stored in @t{$f}. + +@noindent +For more complete examples and other implementation details, see the +@t{zmv} source file, usually located in one of the directories named in +your @t{fpath}, or in @t{Functions/Misc/zmv} in the zsh distribution. + +@item @t{zrecompile} +See `Recompiling Functions' +(@ref{Utilities}). + +@findex zstyle+ +@item @t{zstyle+} @var{context} @var{style} @var{value} [ @t{+} @var{subcontext} @var{style} @var{value} ... ] +This makes defining styles a bit simpler by using a single `@t{+}' as a +special token that allows you to append a context name to the previously +used context name. Like this: + +@noindent +@example +zstyle+ ':foo:bar' @var{style1} @var{value1} \ + +':baz' @var{style2} @var{value2} \ + +':frob' @var{style3} @var{value3} +@end example + +@noindent +This defines @var{style1} with @var{value1} for the context @t{:foo:bar} as usual, +but it also defines @var{style2} with @var{value2} for the context +@t{:foo:bar:baz} and @var{style3} with @var{value3} for @t{:foo:bar:frob}. Any +@var{subcontext} may be the empty string to re-use the first context +unchanged. + +@end table + +@noindent + +@subsection Styles +@noindent + +@noindent +@table @asis +@kindex insert-tab, completion style +@item @t{insert-tab} +The @t{zed} function @emph{sets} this style in context `@t{:completion:zed:*}' +to turn off completion when @t{TAB} is typed at the beginning of a line. +You may override this by setting your own value for this context and style. + +@kindex pager, nslookup style +@item @t{pager} +The @t{nslookup} function looks up this style in the context +`@t{:nslookup}' to determine the program used to display output that does +not fit on a single screen. + +@kindex prompt, nslookup style +@kindex rprompt, nslookup style +@item @t{prompt} +@itemx @t{rprompt} +The @t{nslookup} function looks up this style in the context +`@t{:nslookup}' to set the prompt and the right-side prompt, respectively. +The usual expansions for the @t{PS1} and @t{RPS1} parameters may be used +(see +@ref{Prompt Expansion}). + +@end table +@c (avoiding a yodl bug) +@c (avoiding a yodl bug) +@c (avoiding a yodl bug) +@c Yodl file: Zsh/index.yo +@node Concept Index, Variables Index, Top, Top +@page +@unnumbered Concept Index + +@printindex cp + +@noindent +@node Variables Index, Options Index, Concept Index, Top +@page +@unnumbered Variables Index + +@printindex vr + +@noindent +@node Options Index, Functions Index, Variables Index, Top +@page +@unnumbered Options Index + +@printindex pg + +@noindent +@node Functions Index, Editor Functions Index, Options Index, Top +@page +@unnumbered Functions Index + +@printindex fn + +@noindent +@node Editor Functions Index, Style and Tag Index, Functions Index, Top +@page +@unnumbered Editor Functions Index + +@printindex tp + +@noindent +@node Style and Tag Index, , Editor Functions Index, Top +@page +@unnumbered Style and Tag Index + +@printindex ky +@c (avoiding a yodl bug) + +@bye diff --git a/Doc/zshall.1 b/Doc/zshall.1 new file mode 100644 index 000000000..23e556c42 --- /dev/null +++ b/Doc/zshall.1 @@ -0,0 +1,528 @@ +.TH "ZSHALL" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshall \- the Z shell meta\-man page +.\" Yodl file: Zsh/intro.yo +.SH "OVERVIEW" +Because zsh contains many features, the zsh manual has been split into +a number of sections\&. This manual page includes all the separate manual pages in the +following order: +.PP +.PD 0 +.TP +\fIzsh\fP Zsh overview +.TP +\fIzshroadmap\fP Informal introduction to the manual +.TP +\fIzshmisc\fP Anything not fitting into the other sections +.TP +\fIzshexpn\fP Zsh command and parameter expansion +.TP +\fIzshparam\fP Zsh parameters +.TP +\fIzshoptions\fP Zsh options +.TP +\fIzshbuiltins\fP Zsh built\-in functions +.TP +\fIzshzle\fP Zsh command line editing +.TP +\fIzshcompwid\fP Zsh completion widgets +.TP +\fIzshcompsys\fP Zsh completion system +.TP +\fIzshcompctl\fP Zsh completion control +.TP +\fIzshmodules\fP Zsh loadable modules +.TP +\fIzshcalsys\fP Zsh built\-in calendar functions +.TP +\fIzshtcpsys\fP Zsh built\-in TCP functions +.TP +\fIzshzftpsys\fP Zsh built\-in FTP client +.TP +\fIzshcontrib\fP Additional zsh functions and utilities +.PD +.SH "DESCRIPTION" +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 \fBksh\fP but includes many enhancements\&. It +does not provide compatibility with POSIX or other shells in its +default operating mode: see +the section `Compatibility' below\&. +.PP +Zsh has command line editing, builtin spelling correction, programmable +command completion, shell functions (with autoloading), a history +mechanism, and a host of other features\&. +.\" Yodl file: Zsh/metafaq.yo +.SH "AUTHOR" +Zsh was originally written by Paul Falstad\&. Zsh is now maintained by +the members of the zsh\-workers mailing list \fB<zsh\-workers@zsh\&.org>\fP\&. +The development is currently coordinated by Peter Stephenson +\fB<pws@zsh\&.org>\fP\&. The coordinator can be contacted at +\fB<coordinator@zsh\&.org>\fP, but matters relating to the code should +generally go to the mailing list\&. +.SH "AVAILABILITY" +Zsh is available from the following HTTP and anonymous FTP site\&. +.PP +.nf +\fBftp://ftp\&.zsh\&.org/pub/\fP +\fBhttps://www\&.zsh\&.org/pub/\fP +.fi +.PP +The up\-to\-date source code is available via Git from Sourceforge\&. See +\fBhttps://sourceforge\&.net/projects/zsh/\fP for details\&. A summary of +instructions for the archive can be found at +\fBhttps://zsh\&.sourceforge\&.io/\fP\&. +.PP +.SH "MAILING LISTS" +Zsh has several mailing lists: +.PP +.PD 0 +.TP +.PD +\fB<zsh\-announce@zsh\&.org>\fP +Announcements about releases, major changes in the shell and the +monthly posting of the Zsh FAQ\&. (moderated) +.TP +\fB<zsh\-users@zsh\&.org>\fP +User discussions\&. +.TP +\fB<zsh\-workers@zsh\&.org>\fP +Hacking, development, bug reports and patches\&. +.TP +\fB<zsh\-security@zsh\&.org>\fP +Private mailing list (the general public cannot subscribe to it) for discussing +bug reports with security implications, i\&.e\&., potential vulnerabilities\&. +.RS +.PP +If you find a security problem in zsh itself, please mail this address\&. +.RE +.PP +To subscribe or unsubscribe, send mail +to the associated administrative address for the mailing list\&. +.PP +.PD 0 +.TP +\fB<zsh\-announce\-subscribe@zsh\&.org>\fP +.TP +\fB<zsh\-users\-subscribe@zsh\&.org>\fP +.TP +\fB<zsh\-workers\-subscribe@zsh\&.org>\fP +.PP +.TP +\fB<zsh\-announce\-unsubscribe@zsh\&.org>\fP +.TP +\fB<zsh\-users\-unsubscribe@zsh\&.org>\fP +.TP +\fB<zsh\-workers\-unsubscribe@zsh\&.org>\fP +.PD +.PP +YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED\&. +All submissions to \fBzsh\-announce\fP are automatically forwarded to +\fBzsh\-users\fP\&. All submissions to \fBzsh\-users\fP are automatically +forwarded to \fBzsh\-workers\fP\&. +.PP +If you have problems subscribing/unsubscribing to any of the mailing +lists, send mail to \fB<listmaster@zsh\&.org>\fP\&. +.PP +The mailing lists are archived; the archives can be accessed via the +administrative addresses listed above\&. There is also a hypertext +archive available at +\fBhttps://www\&.zsh\&.org/mla/\fP\&. +.SH "THE ZSH FAQ" +Zsh has a list of Frequently Asked Questions (FAQ), maintained by +Peter Stephenson \fB<pws@zsh\&.org>\fP\&. It is regularly posted to the +newsgroup \fBcomp\&.unix\&.shell\fP and the \fBzsh\-announce\fP mailing list\&. +The latest version can be found at any of the Zsh FTP sites, or at +\fBhttps://www\&.zsh\&.org/FAQ/\fP\&. The contact address for FAQ\-related matters +is \fB<faqmaster@zsh\&.org>\fP\&. +.SH "THE ZSH WEB PAGE" +Zsh has a web page which is located at \fBhttps://www\&.zsh\&.org/\fP\&. +The contact address for web\-related matters is \fB<webmaster@zsh\&.org>\fP\&. +.SH "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 +\fBhttps://zsh\&.sourceforge\&.io/Guide/\fP\&. At the time of writing, chapters +dealing with startup files and their contents and the new completion system +were essentially complete\&. +.\" Yodl file: Zsh/invoke.yo +.SH "INVOCATION" +The following flags are interpreted by the shell when invoked to determine +where the shell will read commands from: +.PP +.PD 0 +.TP +.PD +\fB\-c\fP +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 \fB$0\fP, rather than being used as a positional +parameter\&. +.TP +\fB\-i\fP +Force shell to be interactive\&. It is still possible to specify a +script to execute\&. +.TP +\fB\-s\fP +Force shell to read commands from the standard input\&. +If the \fB\-s\fP flag is not present and an argument is given, +the first argument is taken to be the pathname of a script to +execute\&. +.PP +If there are any remaining arguments after option processing, and neither +of the options \fB\-c\fP or \fB\-s\fP was supplied, the first argument is taken +as the file name of a script containing shell commands to be executed\&. If +the option \fBPATH_SCRIPT\fP is set, and the file name does not contain a +directory path (i\&.e\&. there is no `\fB/\fP' in the name), first the current +directory and then the command path given by the variable \fBPATH\fP are +searched for the script\&. If the option is not set or the file name +contains a `\fB/\fP' it is used directly\&. +.PP +After the first one or two arguments have been appropriated as described above, +the remaining arguments are assigned to the positional parameters\&. +.PP +For further options, which are common to invocation and the \fBset\fP +builtin, see +\fIzshoptions\fP(1)\&. +.PP +The long option `\fB\-\fP\fB\-emulate\fP' followed (in a separate word) by an +emulation mode may be passed to the shell\&. +The emulation modes are those described for the \fBemulate\fP builtin, +see +\fIzshbuiltins\fP(1)\&. +The `\fB\-\fP\fB\-emulate\fP' 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 \fBemulate\fP command within the shell: for +example, variables that conflict with POSIX usage such as \fBpath\fP are +not defined within the shell\&. +.PP +Options may be specified by name using the \fB\-o\fP option\&. \fB\-o\fP acts like +a single\-letter option, but takes a following string as the option name\&. +For example, +.PP +.RS +.nf +\fBzsh \-x \-o shwordsplit scr\fP +.fi +.RE +.PP +runs the script \fBscr\fP, setting the \fBXTRACE\fP option by the corresponding +letter `\fB\-x\fP' and the \fBSH_WORD_SPLIT\fP option by name\&. +Options may be turned \fIoff\fP by name by using \fB+o\fP instead of \fB\-o\fP\&. +\fB\-o\fP can be stacked up with preceding single\-letter options, so for example +`\fB\-xo shwordsplit\fP' or `\fB\-xoshwordsplit\fP' is equivalent to +`\fB\-x \-o shwordsplit\fP'\&. +.PP +Options may also be specified by name in GNU long option style, +`\fB\-\fP\fB\-\fP\fIoption\-name\fP'\&. When this is done, `\fB\-\fP' characters in the +option name are permitted: they are translated into `\fB_\fP', and thus ignored\&. +So, for example, `\fBzsh \-\fP\fB\-sh\-word\-split\fP' invokes zsh with the +\fBSH_WORD_SPLIT\fP option turned on\&. Like other option syntaxes, options can +be turned off by replacing the initial `\fB\-\fP' with a `\fB+\fP'; thus +`\fB+\-sh\-word\-split\fP' is equivalent to `\fB\-\fP\fB\-no\-sh\-word\-split\fP'\&. +Unlike other option syntaxes, GNU\-style long options cannot be stacked with +any other options, so for example `\fB\-x\-shwordsplit\fP' is an error, +rather than being treated like `\fB\-x \-\fP\fB\-shwordsplit\fP'\&. +.PP +The special GNU\-style option `\fB\-\fP\fB\-version\fP' is handled; it sends to +standard output the shell's version information, then exits successfully\&. +`\fB\-\fP\fB\-help\fP' is also handled; it sends to standard output a list of +options that can be used when invoking the shell, then exits successfully\&. +.PP +Option processing may be finished, allowing following arguments that start with +`\fB\-\fP' or `\fB+\fP' to be treated as normal arguments, in two ways\&. +Firstly, a lone `\fB\-\fP' (or `\fB+\fP') as an argument by itself ends +option processing\&. Secondly, a special option `\fB\-\fP\fB\-\fP' (or +`\fB+\-\fP'), which may be specified on its own (which is the standard +POSIX usage) or may be stacked with preceding options (so `\fB\-x\-\fP' is +equivalent to `\fB\-x \-\fP\fB\-\fP')\&. Options are not permitted to be stacked +after `\fB\-\fP\fB\-\fP' (so `\fB\-x\-f\fP' is an error), but note the GNU\-style +option form discussed above, where `\fB\-\fP\fB\-shwordsplit\fP' is permitted +and does not end option processing\&. +.PP +Except when the \fBsh\fP/\fBksh\fP emulation single\-letter options are in effect, +the option `\fB\-b\fP' (or `\fB+b\fP') ends option processing\&. +`\fB\-b\fP' is like `\fB\-\fP\fB\-\fP', except that further single\-letter options +can be stacked after the `\fB\-b\fP' and will take effect as normal\&. +.PP +.PP +.\" Yodl file: Zsh/compat.yo +.SH "COMPATIBILITY" +Zsh tries to emulate \fBsh\fP or \fBksh\fP when it is invoked as +\fBsh\fP or \fBksh\fP respectively; more precisely, it looks at the first +letter of the name by which it was invoked, excluding any initial `\fBr\fP' +(assumed to stand for `restricted'), and if that is `\fBb\fP', `\fBs\fP' or `\fBk\fP' it +will emulate \fBsh\fP or \fBksh\fP\&. Furthermore, if invoked as \fBsu\fP (which +happens on certain systems when the shell is executed by the \fBsu\fP +command), the shell will try to find an alternative name from the \fBSHELL\fP +environment variable and perform emulation based on that\&. +.PP +In \fBsh\fP and \fBksh\fP compatibility modes the following +parameters are not special and not initialized by the shell: +\fBARGC\fP, +\fBargv\fP, +\fBcdpath\fP, +\fBfignore\fP, +\fBfpath\fP, +\fBHISTCHARS\fP, +\fBmailpath\fP, +\fBMANPATH\fP, +\fBmanpath\fP, +\fBpath\fP, +\fBprompt\fP, +\fBPROMPT\fP, +\fBPROMPT2\fP, +\fBPROMPT3\fP, +\fBPROMPT4\fP, +\fBpsvar\fP, +\fBstatus\fP\&. +.PP +The usual zsh startup/shutdown scripts are not executed\&. Login shells +source \fB/etc/profile\fP followed by \fB$HOME/\&.profile\fP\&. If the +\fBENV\fP environment variable is set on invocation, \fB$ENV\fP is sourced +after the profile scripts\&. The value of \fBENV\fP is subjected to +parameter expansion, command substitution, and arithmetic expansion +before being interpreted as a pathname\&. Note that the \fBPRIVILEGED\fP +option also affects the execution of startup files\&. +.PP +The following options are set if the shell is invoked as \fBsh\fP or +\fBksh\fP: +\fBNO_BAD_PATTERN\fP, +\fBNO_BANG_HIST\fP, +\fBNO_BG_NICE\fP, +\fBNO_EQUALS\fP, +\fBNO_FUNCTION_ARGZERO\fP, +\fBGLOB_SUBST\fP, +\fBNO_GLOBAL_EXPORT\fP, +\fBNO_HUP\fP, +\fBINTERACTIVE_COMMENTS\fP, +\fBKSH_ARRAYS\fP, +\fBNO_MULTIOS\fP, +\fBNO_NOMATCH\fP, +\fBNO_NOTIFY\fP, +\fBPOSIX_BUILTINS\fP, +\fBNO_PROMPT_PERCENT\fP, +\fBRM_STAR_SILENT\fP, +\fBSH_FILE_EXPANSION\fP, +\fBSH_GLOB\fP, +\fBSH_OPTION_LETTERS\fP, +\fBSH_WORD_SPLIT\fP\&. +Additionally the \fBBSD_ECHO\fP and \fBIGNORE_BRACES\fP +options are set if zsh is invoked as \fBsh\fP\&. +Also, the +\fBKSH_OPTION_PRINT\fP, +\fBLOCAL_OPTIONS\fP, +\fBPROMPT_BANG\fP, +\fBPROMPT_SUBST\fP +and +\fBSINGLE_LINE_ZLE\fP +options are set if zsh is invoked as \fBksh\fP\&. +.PP +Please note that, whilst reasonable efforts are taken to address +incompatibilities when they arise, zsh does not guarantee complete +emulation of other shells, nor POSIX compliance\&. For more information on +the differences between zsh and other shells, please refer to chapter 2 +of the shell FAQ, \fBhttps://www\&.zsh\&.org/FAQ/\fP\&. +.\" Yodl file: Zsh/restricted.yo +.SH "RESTRICTED SHELL" +When the basename of the command used to invoke zsh starts with the letter +`\fBr\fP' or the `\fB\-r\fP' command line option is supplied at invocation, the +shell becomes restricted\&. Emulation mode is determined after stripping the +letter `\fBr\fP' from the invocation name\&. The following are disabled in +restricted mode: +.PP +.PD 0 +.TP +.PD +\(bu +changing directories with the \fBcd\fP builtin +.TP +\(bu +changing or unsetting the \fBEGID\fP, \fBEUID\fP, \fBGID\fP, +\fBHISTFILE\fP, \fBHISTSIZE\fP, \fBIFS\fP, \fBLD_AOUT_LIBRARY_PATH\fP, +\fBLD_AOUT_PRELOAD\fP, \fBLD_LIBRARY_PATH\fP, \fBLD_PRELOAD\fP, +\fBMODULE_PATH\fP, \fBmodule_path\fP, \fBPATH\fP, \fBpath\fP, \fBSHELL\fP, +\fBUID\fP and \fBUSERNAME\fP parameters +.TP +\(bu +specifying command names containing \fB/\fP +.TP +\(bu +specifying command pathnames using \fBhash\fP +.TP +\(bu +redirecting output to files +.TP +\(bu +using the \fBexec\fP builtin command to replace the shell with another +command +.TP +\(bu +using \fBjobs \-Z\fP to overwrite the shell process' argument and +environment space +.TP +\(bu +using the \fBARGV0\fP parameter to override \fBargv[0]\fP for external +commands +.TP +\(bu +turning off restricted mode with \fBset +r\fP or \fBunsetopt +RESTRICTED\fP +.PP +These restrictions are enforced after processing the startup files\&. The +startup files should set up \fBPATH\fP 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\&. +.PP +Restricted mode can also be activated any time by setting the +\fBRESTRICTED\fP option\&. This immediately enables all the restrictions +described above even if the shell still has not processed all startup +files\&. +.PP +A shell \fIRestricted Mode\fP 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 \fIchroot jails\fP, \fIcontainers\fP and +\fIzones\fP\&. +.PP +A restricted shell is very difficult to implement safely\&. The feature +may be removed in a future version of zsh\&. +.PP +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 `\fBPATH\fP' variable, it does not prevent those +commands from running any other command\&. +.PP +As an example, if `\fBenv\fP' is among the list of \fIallowed\fP commands, +then it allows the user to run any command as `\fBenv\fP' is not a shell +builtin command and can run arbitrary executables\&. +.PP +So when implementing a restricted shell framework it is important to be +fully aware of what actions each of the \fIallowed\fP commands or features +(which may be regarded as \fImodules\fP) can perform\&. +.PP +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\&. +.PP +If a `\fBperl\fP', `\fBpython\fP', `\fBbash\fP', or other general purpose +interpreted script it treated as a restricted +command, the user can work around the restriction by +setting specially crafted `\fBPERL5LIB\fP', `\fBPYTHONPATH\fP', +`\fBBASHENV\fP' (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 `\fBGCONV_PATH\fP' +environment variable\&. Those are only a few examples\&. +.PP +Bear in mind that, contrary to some other shells, `\fBreadonly\fP' is not a +security feature in zsh as it can be undone and so cannot be used to +mitigate the above\&. +.PP +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 `\fBzsh/system\fP', `\fBzsh/mapfile\fP' and +`\fBzsh/files\fP', allow bypassing most of the restrictions\&. +.\" Yodl file: Zsh/files.yo +.SH "STARTUP/SHUTDOWN FILES" +Commands are first read from \fB/etc/zshenv\fP; this cannot be overridden\&. +Subsequent behaviour is modified by the \fBRCS\fP and +\fBGLOBAL_RCS\fP options; the former affects all startup files, while the +second only affects global startup files (those shown here with an +path starting with a \fB/\fP)\&. 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 \fB$ZDOTDIR\fP to +re\-enable \fBGLOBAL_RCS\fP\&. Both \fBRCS\fP and \fBGLOBAL_RCS\fP are set by +default\&. +.PP +Commands are then read from \fB$ZDOTDIR/\&.zshenv\fP\&. +If the shell is a login shell, commands +are read from \fB/etc/zprofile\fP and then \fB$ZDOTDIR/\&.zprofile\fP\&. +Then, if the shell is interactive, +commands are read from \fB/etc/zshrc\fP and then \fB$ZDOTDIR/\&.zshrc\fP\&. +Finally, if the shell is a login shell, \fB/etc/zlogin\fP and +\fB$ZDOTDIR/\&.zlogin\fP are read\&. +.PP +When a login shell exits, the files \fB$ZDOTDIR/\&.zlogout\fP and then +\fB/etc/zlogout\fP are read\&. This happens with either an explicit exit +via the \fBexit\fP or \fBlogout\fP commands, or an implicit exit by reading +end\-of\-file from the terminal\&. However, if the shell terminates due +to \fBexec\fP'ing another process, the logout files are not read\&. +These are also affected by the \fBRCS\fP and \fBGLOBAL_RCS\fP options\&. +Note also that the \fBRCS\fP option affects the saving of history files, +i\&.e\&. if \fBRCS\fP is unset when the shell exits, no history file will be +saved\&. +.PP +If \fBZDOTDIR\fP is unset, \fBHOME\fP is used instead\&. +Files listed above as being in \fB/etc\fP may be in another +directory, depending on the installation\&. +.PP +As \fB/etc/zshenv\fP 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 `\fBif [[ \-o rcs ]]; then \&.\&.\&.\fP' so that it will not +be executed when zsh is invoked with the `\fB\-f\fP' option\&. +.PP +Any of these files may be pre\-compiled with the \fBzcompile\fP builtin +command (see \fIzshbuiltins\fP(1))\&. If a compiled file exists (named for the original file plus the +\fB\&.zwc\fP extension) and it is newer than the original file, the compiled +file will be used instead\&. +.so man1/zshroadmap.1 +.so man1/zshmisc.1 +.so man1/zshexpn.1 +.so man1/zshparam.1 +.so man1/zshoptions.1 +.so man1/zshbuiltins.1 +.so man1/zshzle.1 +.so man1/zshcompwid.1 +.so man1/zshcompsys.1 +.so man1/zshcompctl.1 +.so man1/zshmodules.1 +.so man1/zshcalsys.1 +.so man1/zshtcpsys.1 +.so man1/zshzftpsys.1 +.so man1/zshcontrib.1 +.TH "ZSHALL" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3\-test" +.\" Yodl file: Zsh/filelist.yo +.SH "FILES" +.PD 0 +.TP +\fB$ZDOTDIR/\&.zshenv\fP +.TP +\fB$ZDOTDIR/\&.zprofile\fP +.TP +\fB$ZDOTDIR/\&.zshrc\fP +.TP +\fB$ZDOTDIR/\&.zlogin\fP +.TP +\fB$ZDOTDIR/\&.zlogout\fP +.TP +\fB${TMPPREFIX}*\fP (default is /tmp/zsh*) +.TP +\fB/etc/zshenv\fP +.TP +\fB/etc/zprofile\fP +.TP +\fB/etc/zshrc\fP +.TP +\fB/etc/zlogin\fP +.TP +\fB/etc/zlogout\fP (installation\-specific \- \fB/etc\fP is the default) +.PD +.\" Yodl file: Zsh/seealso.yo +.SH "SEE ALSO" +\fIsh\fP(1), +\fIcsh\fP(1), +\fItcsh\fP(1), +\fIrc\fP(1), +\fIbash\fP(1), +\fIksh\fP(1) +.PP +\fBIEEE Standard for information Technology \- +Portable Operating System Interface (POSIX) \- +Part 2: Shell and Utilities\fP, +IEEE Inc, 1993, ISBN 1\-55937\-255\-9\&. diff --git a/Doc/zshbuiltins.1 b/Doc/zshbuiltins.1 new file mode 100644 index 000000000..b420791a5 --- /dev/null +++ b/Doc/zshbuiltins.1 @@ -0,0 +1,3287 @@ +.TH "ZSHBUILTINS" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshbuiltins \- zsh built\-in commands +.\" Yodl file: Zsh/builtins.yo +.SH "SHELL BUILTIN COMMANDS" + +Some shell builtin commands take options as described in individual +entries; these are often referred to in the list below as `\fBflags\fP\&' to +avoid confusion with shell options, which may also have an effect on the +behaviour of builtin commands\&. In this introductory section, +`\fBoption\fP\&' always has the meaning of an option to a command that should +be familiar to most command line users\&. +.PP +Typically, options are single letters preceded by a hyphen (\fB\-\fP)\&. +Options that take an argument accept it either immediately following the +option letter or after white space, for example `\fBprint \-C3 {1\&.\&.9}\fP\&' or +`\fBprint \-C 3 {1\&.\&.9}\fP\&' are equivalent\&. Arguments to options are not the +same as arguments to the command; the documentation indicates which is +which\&. Options that do not take an argument may be combined in a single +word, for example `\fBprint \-rca \-\- *\fP\&' and `\fBprint \-r \-c \-a \-\- *\fP' are +equivalent\&. +.PP +Some shell builtin commands also take options that begin with `\fB+\fP\&' +instead of `\fB\-\fP\&'\&. The list below makes clear which commands these +are\&. +.PP +Options (together with their individual arguments, if any) must appear +in a group before any non\-option arguments; once the first non\-option +argument has been found, option processing is terminated\&. +.PP +All builtin commands other than `\fBecho\fP\&' and precommand modifiers, +even those that have no options, can be given the argument `\fB\-\fP\fB\-\fP\&' +to terminate option processing\&. This indicates that the following words +are non\-option arguments, but is otherwise ignored\&. This is useful in +cases where arguments to the command may begin with `\fB\-\fP\&'\&. For +historical reasons, most builtin commands (including `\fBecho\fP\&') also +recognize a single `\fB\-\fP\&' in a separate word for this purpose; note +that this is less standard and use of `\fB\-\fP\fB\-\fP\&' is recommended\&. +.PP +.PD 0 +.TP +.PD +\fB\-\fP \fIsimple command\fP +See the section `Precommand Modifiers\&' in \fIzshmisc\fP(1)\&. +.TP +\fB\&.\fP \fIfile\fP [ \fIarg\fP \&.\&.\&. ] +Read commands from \fIfile\fP and execute them in the current shell +environment\&. +.RS +.PP +If \fIfile\fP does not contain a slash, or if \fBPATH_DIRS\fP is set, +the shell looks in the components of \fB$path\fP to find the directory +containing \fIfile\fP\&. Files in the current directory are not read +unless `\fB\&.\fP\&' appears somewhere in \fB$path\fP\&. If a file named +`\fIfile\fP\fB\&.zwc\fP\&' is found, is newer than \fIfile\fP, and is the +compiled form (created with the \fBzcompile\fP builtin) of \fIfile\fP, +then commands are read from that file instead of \fIfile\fP\&. +.PP +If any arguments \fIarg\fP are given, +they become the positional parameters; the old positional +parameters are restored when the \fIfile\fP is done executing\&. +However, if no arguments are given, +the positional parameters remain those of the calling context, +and no restoring is done\&. +.PP +If \fIfile\fP was not found the return status is 127; if \fIfile\fP was found +but contained a syntax error the return status is 126; else the return +status is the exit status of the last command executed\&. +.RE +.TP +\fB:\fP [ \fIarg\fP \&.\&.\&. ] +This command does nothing, although normal argument expansions is performed +which may have effects on shell parameters\&. A zero exit status is returned\&. +.TP +\fBalias\fP [ {\fB+\fP|\fB\-\fP}\fBgmrsL\fP ] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ] +For each \fIname\fP with a corresponding \fIvalue\fP, define an alias +with that value\&. A trailing space in \fIvalue\fP causes the next word +to be checked for alias expansion\&. If the \fB\-g\fP flag is present, +define a global alias; global aliases are expanded even if they do not +occur in command position: +.RS +.PP +.RS +.nf +\fB% perldoc \-\-help 2>&1 | grep \&'built\-in functions' + \-f Search Perl built\-in functions +% alias \-g HG=\&'\-\-help 2>&1 | grep' +% perldoc HG \&'built\-in functions' + \-f Search Perl built\-in functions\fP +.fi +.RE +.PP +If the \fB\-s\fP flag is present, define a suffix alias: if the command +word on a command line is in the form `\fItext\fP\fB\&.\fP\fIname\fP\&', where +\fItext\fP is any non\-empty string, it is replaced by the text +`\fIvalue\fP \fItext\fP\fB\&.\fP\fIname\fP\&'\&. Note that \fIname\fP is treated as +a literal string, not a pattern\&. A trailing space in \fIvalue\fP is not +special in this case\&. For example, +.PP +.RS +.nf +\fBalias \-s ps=\&'gv \-\-'\fP +.fi +.RE +.PP +will cause the command `\fB*\&.ps\fP\&' to be expanded to `\fBgv \-\- *\&.ps\fP'\&. As +alias expansion is carried out earlier than globbing, the `\fB*\&.ps\fP\&' will +then be expanded\&. Suffix aliases constitute a different name space from +other aliases (so in the above example it is still possible +to create an alias for the command \fBps\fP) and the two sets are never +listed together\&. +.PP +For each \fIname\fP with no \fIvalue\fP, +print the value of \fIname\fP, if any\&. With no arguments, print all +currently defined aliases other than suffix aliases\&. If the \fB\-m\fP flag +is given the arguments are taken as patterns (they should be quoted to +preserve them from being interpreted as glob patterns), and the aliases +matching these patterns are printed\&. When printing aliases and one of +the \fB\-g\fP, \fB\-r\fP or \fB\-s\fP flags is present, restrict the printing to +global, regular or suffix aliases, respectively; a regular alias is one +which is neither a global nor a suffix alias\&. Using `\fB+\fP\&' +instead of `\fB\-\fP\&', or ending the option list with a single +`\fB+\fP\&', prevents the values of the aliases from being printed\&. +.PP +If the \fB\-L\fP flag is present, then print each +alias in a manner suitable for putting in a startup script\&. The exit +status is nonzero if a \fIname\fP (with no \fIvalue\fP) is given for +which no alias has been defined\&. +.PP +For more on aliases, include common problems, see +the section ALIASING in \fIzshmisc\fP(1)\&. +.RE +.TP +\fBautoload\fP [ {\fB+\fP|\fB\-\fP}\fBRTUXdkmrtWz\fP ] [ \fB\-w\fP ] [ \fIname\fP \&.\&.\&. ] +See the section `Autoloading Functions\&' in \fIzshmisc\fP(1) for full details\&. The \fBfpath\fP parameter +will be searched to find the function definition when the function is +first referenced\&. +.RS +.PP +If \fIname\fP consists of an absolute path, the function is defined to +load from the file given (searching as usual for dump files in the given +location)\&. The name of the function is the basename (non\-directory +part) of the file\&. It is normally an error if the function is not found +in the given location; however, if the option \fB\-d\fP is given, searching +for the function defaults to \fB$fpath\fP\&. If a function is loaded by +absolute path, any functions loaded from it that are marked for +\fBautoload\fP without an absolute path have the load path of the parent +function temporarily prepended to \fB$fpath\fP\&. +.PP +If the option \fB\-r\fP or \fB\-R\fP is given, the function is searched for +immediately and the location is recorded internally for use when the +function is executed; a relative path is expanded using the value of +\fB$PWD\fP\&. This protects against a change to \fB$fpath\fP after the call +to \fBautoload\fP\&. With \fB\-r\fP, if the function is not found, it is +silently left unresolved until execution; with \fB\-R\fP, an error message +is printed and command processing aborted immediately the search fails, +i\&.e\&. at the \fBautoload\fP command rather than at function execution\&.\&. +.PP +The flag \fB\-X\fP may be used only inside a shell function\&. It causes the +calling function to be marked for autoloading and then immediately +loaded and executed, with the current array of positional parameters as +arguments\&. This replaces the previous definition of the function\&. If +no function definition is found, an error is printed and the function +remains undefined and marked for autoloading\&. If an argument is given, +it is used as a directory (i\&.e\&. it does not include the name of the +function) in which the function is to be found; this may be combined +with the \fB\-d\fP option to allow the function search to default to \fB$fpath\fP +if it is not in the given location\&. +.PP +The flag \fB+X\fP attempts to load each \fIname\fP as an autoloaded function, +but does \fInot\fP execute it\&. The exit status is zero (success) if the +function was not previously defined \fIand\fP a definition for it was found\&. +This does \fInot\fP replace any existing definition of the function\&. The +exit status is nonzero (failure) if the function was already defined or +when no definition was found\&. In the latter case the function remains +undefined and marked for autoloading\&. If ksh\-style autoloading is +enabled, the function created will contain the contents of the file +plus a call to the function itself appended to it, thus giving normal +ksh autoloading behaviour on the first call to the function\&. +If the \fB\-m\fP flag is also given each \fIname\fP is treated as a +pattern and all functions already marked for autoload that match the +pattern are loaded\&. +.PP +With the \fB\-t\fP flag, turn on execution tracing; with \fB\-T\fP, turn on +execution tracing only for the current function, turning it off on entry +to any called functions that do not also have tracing enabled\&. +.PP +With the \fB\-U\fP flag, alias expansion is suppressed when the function is +loaded\&. +.PP +With the \fB\-w\fP flag, the \fIname\fPs are taken as names of files compiled +with the \fBzcompile\fP builtin, and all functions defined in them are +marked for autoloading\&. +.PP +The flags \fB\-z\fP and \fB\-k\fP mark the function to be autoloaded using the +zsh or ksh style, as if the option \fBKSH_AUTOLOAD\fP were unset or were +set, respectively\&. The flags override the setting of the option at the +time the function is loaded\&. +.PP +Note that the \fBautoload\fP command makes no attempt to ensure the +shell options set during the loading or execution of the file have +any particular value\&. For this, the \fBemulate\fP command can be used: +.PP +.RS +.nf +\fBemulate zsh \-c \&'autoload \-Uz \fIfunc\fP'\fP +.fi +.RE +.PP +arranges that when \fIfunc\fP is loaded the shell is in native \fBzsh\fP +emulation, and this emulation is also applied when \fIfunc\fP is run\&. +.PP +Some of the functions of \fBautoload\fP are also provided by \fBfunctions +\-u\fP or \fBfunctions \-U\fP, but \fBautoload\fP is a more comprehensive +interface\&. +.RE +.TP +.PD 0 +\fBbg\fP [ \fIjob\fP \&.\&.\&. ] +.TP +.PD +\fIjob\fP \&.\&.\&. \fB&\fP +Put each specified \fIjob\fP in the background, +or the current job if none is specified\&. +.TP +\fBbindkey\fP +See the section `Zle Builtins\&' in \fIzshzle\fP(1)\&. +.TP +\fBbreak\fP [ \fIn\fP ] +Exit from an enclosing \fBfor\fP, \fBwhile\fP, +\fBuntil\fP, \fBselect\fP or \fBrepeat\fP loop\&. If an arithmetic expression \fIn\fP +is specified, then break \fIn\fP levels instead of just one\&. +.TP +\fBbuiltin\fP \fIname\fP [ \fIargs\fP \&.\&.\&. ] +Executes the builtin \fIname\fP, with the given \fIargs\fP\&. +.TP +\fBbye\fP +Same as \fBexit\fP\&. +.TP +\fBcap\fP +See the section `The zsh/cap Module\&' in \fIzshmodules\fP(1)\&. +.TP +.PD 0 +\fBcd\fP [ \fB\-qsLP\fP ] [ \fIarg\fP ] +.TP +.PD 0 +\fBcd\fP [ \fB\-qsLP\fP ] \fIold\fP \fInew\fP +.TP +.PD +\fBcd\fP [ \fB\-qsLP\fP ] {\fB+\fP|\fB\-\fP}\fIn\fP +Change the current directory\&. In the first form, change the +current directory to \fIarg\fP, or to the value of \fB$HOME\fP if +\fIarg\fP is not specified\&. If \fIarg\fP is `\fB\-\fP\&', change to the +previous directory\&. +.RS +.PP +Otherwise, if \fIarg\fP begins with a slash, attempt to change to the +directory given by \fIarg\fP\&. +.PP +If \fIarg\fP does not begin with a slash, the behaviour depends on whether +the current directory `\fB\&.\fP\&' occurs in the list of directories contained +in the shell parameter \fBcdpath\fP\&. If it does not, first attempt to change +to the directory \fIarg\fP under the current directory, and if that fails +but \fBcdpath\fP is set and contains at least one element attempt to change +to the directory \fIarg\fP under each component of \fBcdpath\fP in turn until +successful\&. If `\fB\&.\fP\&' occurs in \fBcdpath\fP, then \fBcdpath\fP is searched +strictly in order so that `\fB\&.\fP\&' is only tried at the appropriate point\&. +.PP +The order of testing \fBcdpath\fP is modified if the option \fBPOSIX_CD\fP +is set, as described in the documentation for the option\&. +.PP +If no directory is found, the option \fBCDABLE_VARS\fP is set, and a +parameter named \fIarg\fP exists whose value begins with a slash, treat its +value as the directory\&. In that case, the parameter is added to the named +directory hash table\&. +.PP +The second form of \fBcd\fP substitutes the string \fInew\fP +for the string \fIold\fP in the name of the current directory, +and tries to change to this new directory\&. +.PP +The third form of \fBcd\fP extracts an entry from the directory +stack, and changes to that directory\&. An argument of the form +`\fB+\fP\fIn\fP\&' identifies a stack entry by counting from the left +of the list shown by the \fBdirs\fP command, starting with zero\&. +An argument of the form `\fB\-\fP\fIn\fP\&' counts from the right\&. +If the \fBPUSHD_MINUS\fP option is set, the meanings of `\fB+\fP\&' +and `\fB\-\fP\&' in this context are swapped\&. +If the \fBPOSIX_CD\fP option is set, this form of \fBcd\fP is not recognised +and will be interpreted as the first form\&. +.PP +If the \fB\-q\fP (quiet) option is specified, the hook function \fBchpwd\fP +and the functions in the array \fBchpwd_functions\fP are not called\&. +This is useful for calls to \fBcd\fP that do not change the environment +seen by an interactive user\&. +.PP +If the \fB\-s\fP option is specified, \fBcd\fP refuses to change the current +directory if the given pathname contains symlinks\&. If the \fB\-P\fP option +is given or the \fBCHASE_LINKS\fP option is set, symbolic links are resolved +to their true values\&. If the \fB\-L\fP option is given symbolic links are +retained in the directory (and not resolved) regardless of the state of +the \fBCHASE_LINKS\fP option\&. +.RE +.TP +\fBchdir\fP +Same as \fBcd\fP\&. +.TP +\fBclone\fP +See the section `The zsh/clone Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBcommand\fP [ \fB\-pvV\fP ] \fIsimple command\fP +The simple command argument is taken as an external command instead of +a function or builtin and is executed\&. If the \fBPOSIX_BUILTINS\fP option +is set, builtins will also be executed but certain special properties +of them are suppressed\&. The \fB\-p\fP flag causes a default path to be +searched instead of that in \fB$path\fP\&. With the \fB\-v\fP flag, \fBcommand\fP +is similar to \fBwhence\fP and with \fB\-V\fP, it is equivalent to \fBwhence +\-v\fP\&. +.RS +.PP +See also the section `Precommand Modifiers\&' in \fIzshmisc\fP(1)\&. +.RE +.TP +\fBcomparguments\fP +See the section `The zsh/computil Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBcompcall\fP +See the section `The zsh/compctl Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBcompctl\fP +See the section `The zsh/compctl Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBcompdescribe\fP +See the section `The zsh/computil Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBcompfiles\fP +See the section `The zsh/computil Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBcompgroups\fP +See the section `The zsh/computil Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBcompquote\fP +See the section `The zsh/computil Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBcomptags\fP +See the section `The zsh/computil Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBcomptry\fP +See the section `The zsh/computil Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBcompvalues\fP +See the section `The zsh/computil Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBcontinue\fP [ \fIn\fP ] +Resume the next iteration of the enclosing +\fBfor\fP, \fBwhile\fP, \fBuntil\fP, \fBselect\fP or +\fBrepeat\fP loop\&. If an arithmetic expression \fIn\fP is specified, break out of +\fIn\fP\-1 loops and resume at the \fIn\fPth enclosing loop\&. +.TP +\fBdeclare\fP +Same as \fBtypeset\fP\&. +.TP +.PD 0 +\fBdirs\fP [ \fB\-c\fP ] [ \fIarg\fP \&.\&.\&. ] +.TP +.PD +\fBdirs\fP [ \fB\-lpv\fP ] +With no arguments, print the contents of the directory stack\&. +Directories are added to this stack with the \fBpushd\fP command, +and removed with the \fBcd\fP or \fBpopd\fP commands\&. +If arguments are specified, load them onto the directory stack, +replacing anything that was there, and push the current directory +onto the stack\&. +.RS +.PP +.PD 0 +.TP +.PD +\fB\-c\fP +clear the directory stack\&. +.TP +\fB\-l\fP +print directory names in full instead of using of using \fB~\fP expressions (see \fIDynamic\fP and \fIStatic named directories\fP in \fIzshexpn\fP(1))\&. +.TP +\fB\-p\fP +print directory entries one per line\&. +.TP +\fB\-v\fP +number the directories in the stack when printing\&. +.PP +.RE +.TP +\fBdisable\fP [ \fB\-afmprs\fP ] \fIname\fP \&.\&.\&. +Temporarily disable the \fIname\fPd hash table elements or patterns\&. The default +is to disable builtin commands\&. This allows you to use an external +command with the same name as a builtin command\&. The \fB\-a\fP option +causes \fBdisable\fP to act on regular or global aliases\&. The \fB\-s\fP +option causes \fBdisable\fP to act on suffix aliases\&. The \fB\-f\fP option causes +\fBdisable\fP to act on shell functions\&. The \fB\-r\fP options causes +\fBdisable\fP to act on reserved words\&. Without arguments all disabled +hash table elements from the corresponding hash table are printed\&. +With the \fB\-m\fP flag the arguments are taken as patterns (which should be +quoted to prevent them from undergoing filename expansion), and all hash +table elements from the corresponding hash table matching these patterns +are disabled\&. Disabled objects can be enabled with the \fBenable\fP +command\&. +.RS +.PP +With the option \fB\-p\fP, \fIname\fP \&.\&.\&. refer to elements of the +shell\&'s pattern syntax as described in the section `Filename Generation'\&. +Certain elements can be disabled separately, as given below\&. +.PP +Note that patterns +not allowed by the current settings for the options \fBEXTENDED_GLOB\fP, +\fBKSH_GLOB\fP and \fBSH_GLOB\fP are never enabled, regardless of the +setting here\&. For example, if \fBEXTENDED_GLOB\fP is not active, +the pattern \fB^\fP is ineffective even if `\fBdisable \-p "^"\fP\&' has +not been issued\&. The list below indicates any option settings +that restrict the use of the pattern\&. It should be noted that +setting \fBSH_GLOB\fP has a wider effect than merely disabling patterns +as certain expressions, in particular those involving parentheses, +are parsed differently\&. +.PP +The following patterns may be disabled; all +the strings need quoting on the command line to prevent them from +being interpreted immediately as patterns and the patterns are +shown below in single quotes as a reminder\&. +.PP +.PD 0 +.TP +.PD +\fB\&'?'\fP +The pattern character \fB?\fP wherever it occurs, including when preceding +a parenthesis with \fBKSH_GLOB\fP\&. +.TP +\fB\&'*'\fP +The pattern character \fB*\fP wherever it occurs, including recursive +globbing and when preceding a parenthesis with \fBKSH_GLOB\fP\&. +.TP +\fB\&'['\fP +Character classes\&. +.TP +\fB\&'<'\fP (\fBNO_SH_GLOB\fP) +Numeric ranges\&. +.TP +\fB\&'|'\fP (\fBNO_SH_GLOB\fP) +Alternation in grouped patterns, case statements, or KSH_GLOB +parenthesised expressions\&. +.TP +\fB\&'('\fP (\fBNO_SH_GLOB\fP) +Grouping using single parentheses\&. Disabling this does not disable the +use of parentheses for \fBKSH_GLOB\fP where they are introduced by a +special character, nor for glob qualifiers (use `\fBsetopt +NO_BARE_GLOB_QUAL\fP\&' to disable glob qualifiers that use parentheses +only)\&. +.TP +\fB\&'~'\fP (\fBEXTENDED_GLOB\fP) +Exclusion in the form \fIA\fP\fB~\fP\fIB\fP\&. +.TP +\fB\&'^'\fP (\fBEXTENDED_GLOB\fP) +Exclusion in the form \fIA\fP\fB^\fP\fIB\fP\&. +.TP +\fB\&'#'\fP (\fBEXTENDED_GLOB\fP) +The pattern character \fB#\fP wherever it occurs, both for +repetition of a previous pattern and for indicating globbing flags\&. +.TP +\fB\&'?('\fP (\fBKSH_GLOB\fP) +The grouping form \fB?(\fP\fI\&.\&.\&.\fP\fB)\fP\&. Note this is also +disabled if \fB\&'?'\fP is disabled\&. +.TP +\fB\&'*('\fP (\fBKSH_GLOB\fP) +The grouping form \fB*(\fP\fI\&.\&.\&.\fP\fB)\fP\&. Note this is also +disabled if \fB\&'*'\fP is disabled\&. +.TP +\fB\&'+('\fP (\fBKSH_GLOB\fP) +The grouping form \fB+(\fP\fI\&.\&.\&.\fP\fB)\fP\&. +.TP +\fB\&'!('\fP (\fBKSH_GLOB\fP) +The grouping form \fB!(\fP\fI\&.\&.\&.\fP\fB)\fP\&. +.TP +\fB\&'@('\fP (\fBKSH_GLOB\fP) +The grouping form \fB@(\fP\fI\&.\&.\&.\fP\fB)\fP\&. +.RE +.TP +.PD 0 +\fBdisown\fP [ \fIjob\fP \&.\&.\&. ] +.TP +.PD 0 +\fIjob\fP \&.\&.\&. \fB&|\fP +.TP +.PD +\fIjob\fP \&.\&.\&. \fB&!\fP +Remove the specified \fIjob\fPs from the job table; the shell will +no longer report their status, and will not complain if you +try to exit an interactive shell with them running or stopped\&. +If no \fIjob\fP is specified, disown the current job\&. +.RS +.PP +If the \fIjob\fPs are currently stopped and the \fBAUTO_CONTINUE\fP option +is not set, a warning is printed containing information about how to +make them running after they have been disowned\&. If one of the latter +two forms is used, the \fIjob\fPs will automatically be made running, +independent of the setting of the \fBAUTO_CONTINUE\fP option\&. +.RE +.TP +\fBecho\fP [ \fB\-neE\fP ] [ \fIarg\fP \&.\&.\&. ] +Write each \fIarg\fP on the standard output, with a space separating +each one\&. +If the \fB\-n\fP flag is not present, print a newline at the end\&. +\fBecho\fP recognizes the following escape sequences: +.RS +.PP +.PD 0 +.TP +\fB\ea\fP +bell character +.TP +\fB\eb\fP +backspace +.TP +\fB\ec\fP +suppress subsequent characters and final newline +.TP +\fB\ee\fP +escape +.TP +\fB\ef\fP +form feed +.TP +\fB\en\fP +linefeed (newline) +.TP +\fB\er\fP +carriage return +.TP +\fB\et\fP +horizontal tab +.TP +\fB\ev\fP +vertical tab +.TP +\fB\e\e\fP +backslash +.TP +\fB\e0\fP\fINNN\fP +character code in octal +.TP +\fB\ex\fP\fINN\fP +character code in hexadecimal +.TP +\fB\eu\fP\fINNNN\fP +unicode character code in hexadecimal +.TP +\fB\eU\fP\fINNNNNNNN\fP +unicode character code in hexadecimal +.PD +.PP +The \fB\-E\fP flag, or the \fBBSD_ECHO\fP option, can be used to disable +these escape sequences\&. In the latter case, \fB\-e\fP flag can be used to +enable them\&. +.PP +Note that for standards compliance a double dash does not terminate +option processing; instead, it is printed directly\&. However, a +single dash does terminate option processing, so the first dash, +possibly following options, is not printed, but everything following it +is printed as an argument\&. The single dash behaviour is different +from other shells\&. For a more portable way of printing text, see +\fBprintf\fP, and for a more controllable way of printing text within zsh, +see \fBprint\fP\&. +.RE +.TP +\fBechotc\fP +See the section `The zsh/termcap Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBechoti\fP +See the section `The zsh/terminfo Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBemulate\fP [ \fB\-lLR\fP ] [ {\fBzsh\fP|\fBsh\fP|\fBksh\fP|\fBcsh\fP} [ \fIflags\fP \&.\&.\&. ] ] +Without any argument print current emulation mode\&. +.RS +.PP +With single argument set up zsh options to emulate the specified shell +as much as possible\&. +\fBcsh\fP will never be fully emulated\&. +If the argument is not one of the shells listed above, \fBzsh\fP +will be used as a default; more precisely, the tests performed on the +argument are the same as those used to determine the emulation at startup +based on the shell name, see +the section COMPATIBILITY in \fIzsh\fP(1) +\&. In addition to setting shell options, the command also restores +the pristine state of pattern enables, as if all patterns had been +enabled using \fBenable \-p\fP\&. +.PP +If the \fBemulate\fP command occurs inside a function that has been +marked for execution tracing with \fBfunctions \-t\fP then the \fBxtrace\fP +option will be turned on regardless of emulation mode or other options\&. +Note that code executed inside the function by the \fB\&.\fP, \fBsource\fP, or +\fBeval\fP commands is not considered to be running directly from the +function, hence does not provoke this behaviour\&. +.PP +If the \fB\-R\fP switch is given, all settable options +are reset to their default value corresponding to the specified emulation +mode, except for certain options describing the interactive +environment; otherwise, only those options likely to cause portability +problems in scripts and functions are altered\&. If the \fB\-L\fP switch is given, +the options \fBLOCAL_OPTIONS\fP, \fBLOCAL_PATTERNS\fP and \fBLOCAL_TRAPS\fP +will be set as +well, causing the effects of the \fBemulate\fP command and any \fBsetopt\fP, +\fBdisable \-p\fP or \fBenable \-p\fP, and \fBtrap\fP commands to be local to +the immediately surrounding shell +function, if any; normally these options are turned off in all emulation +modes except \fBksh\fP\&. The \fB\-L\fP switch is mutually exclusive with the +use of \fB\-c\fP in \fIflags\fP\&. +.PP +If there is a single argument and the \fB\-l\fP switch is given, the +options that would be set or unset (the latter indicated with the prefix +`\fBno\fP\&') are listed\&. \fB\-l\fP can be combined with \fB\-L\fP or \fB\-R\fP and +the list will be modified in the appropriate way\&. Note the list does +not depend on the current setting of options, i\&.e\&. it includes all +options that may in principle change, not just those that would actually +change\&. +.PP +The \fIflags\fP may be any of the invocation\-time flags described in +the section INVOCATION in \fIzsh\fP(1), +except that `\fB\-o EMACS\fP\&' and `\fB\-o VI\fP' may not be used\&. Flags such +as `\fB+r\fP\&'/`\fB+o RESTRICTED\fP' may be prohibited in some circumstances\&. +.PP +If \fB\-c\fP \fIarg\fP appears in \fIflags\fP, \fIarg\fP is evaluated while the +requested emulation is temporarily in effect\&. In this case the emulation +mode and all options are restored to their previous values before +\fBemulate\fP returns\&. The \fB\-R\fP switch may precede the name of the shell +to emulate; note this has a meaning distinct from including \fB\-R\fP in +\fIflags\fP\&. +.PP +Use of \fB\-c\fP enables `sticky\&' emulation mode for functions defined +within the evaluated expression: the emulation mode is associated +thereafter with the function so that whenever the function is executed +the emulation (respecting the \fB\-R\fP switch, if present) and all +options are set (and pattern disables cleared) +before entry to the function, and the state is restored after exit\&. +If the function is called when the sticky emulation is already in +effect, either within an `\fBemulate\fP \fIshell\fP \fB\-c\fP\&' expression or +within another function with the same sticky emulation, entry and exit +from the function do not cause options to be altered (except due to +standard processing such as the \fBLOCAL_OPTIONS\fP option)\&. This also +applies to functions marked for autoload within the sticky emulation; +the appropriate set of options will be applied at the point the +function is loaded as well as when it is run\&. +.PP +For example: +.PP +.RS +.nf +\fBemulate sh \-c \&'fni() { setopt cshnullglob; } +fno() { fni; }\&' +fno\fP +.fi +.RE +.PP +The two functions \fBfni\fP and \fBfno\fP are defined with sticky \fBsh\fP +emulation\&. \fBfno\fP is then executed, causing options associated +with emulations to be set to their values in \fBsh\fP\&. \fBfno\fP then +calls \fBfni\fP; because \fBfni\fP is also marked for sticky \fBsh\fP +emulation, no option changes take place on entry to or exit from it\&. +Hence the option \fBcshnullglob\fP, turned off by \fBsh\fP emulation, will +be turned on within \fBfni\fP and remain on return to \fBfno\fP\&. On exit +from \fBfno\fP, the emulation mode and all options will be restored to the +state they were in before entry to the temporary emulation\&. +.PP +The documentation above is typically sufficient for the intended +purpose of executing code designed for other shells in a suitable +environment\&. More detailed rules follow\&. +.PD 0 +.TP +1\&. +The sticky emulation environment provided by `\fBemulate\fP +\fIshell\fP \fB\-c\fP\&' is identical to that provided by entry to +a function marked for sticky emulation as a consequence of being +defined in such an environment\&. Hence, for example, the sticky +emulation is inherited by subfunctions defined within functions +with sticky emulation\&. +.TP +2\&. +No change of options takes place on entry to or exit from +functions that are not marked for sticky emulation, other than those +that would normally take place, even if those functions are called +within sticky emulation\&. +.TP +3\&. +No special handling is provided for functions marked for +\fBautoload\fP nor for functions present in wordcode created by +the \fBzcompile\fP command\&. +.TP +4\&. +The presence or absence of the \fB\-R\fP switch to \fBemulate\fP +corresponds to different sticky emulation modes, so for example +`\fBemulate sh \-c\fP\&', `\fBemulate \-R sh \-c\fP' and `\fBemulate csh \-c\fP' +are treated as three distinct sticky emulations\&. +.TP +5\&. +Difference in shell options supplied in addition to the +basic emulation also mean the sticky emulations are different, so for +example `\fBemulate zsh \-c\fP\&' and `\fBemulate zsh \-o cbases \-c\fP' are +treated as distinct sticky emulations\&. +.PD +.RE +.TP +\fBenable\fP [ \fB\-afmprs\fP ] \fIname\fP \&.\&.\&. +Enable the \fIname\fPd hash table elements, presumably disabled +earlier with \fBdisable\fP\&. The default is to enable builtin commands\&. +The \fB\-a\fP option causes \fBenable\fP to act on regular or global aliases\&. +The \fB\-s\fP option causes \fBenable\fP to act on suffix aliases\&. +The \fB\-f\fP option causes \fBenable\fP to act on shell functions\&. The \fB\-r\fP +option causes \fBenable\fP to act on reserved words\&. Without arguments +all enabled hash table elements from the corresponding hash table are +printed\&. With the \fB\-m\fP flag the arguments are taken as patterns +(should be quoted) and all hash table elements from the corresponding +hash table matching these patterns are enabled\&. Enabled objects can be +disabled with the \fBdisable\fP builtin command\&. +.RS +.PP +\fBenable \-p\fP reenables patterns disabled with \fBdisable \-p\fP\&. Note +that it does not override globbing options; for example, `\fBenable \-p +"~"\fP\&' does not cause the pattern character \fB~\fP to be active unless +the \fBEXTENDED_GLOB\fP option is also set\&. To enable all possible +patterns (so that they may be individually disabled with \fBdisable \-p\fP), +use `\fBsetopt EXTENDED_GLOB KSH_GLOB NO_SH_GLOB\fP\&'\&. +.RE +.TP +\fBeval\fP [ \fIarg\fP \&.\&.\&. ] +Read the arguments as input to the shell and execute the resulting +command(s) in the current shell process\&. The return status is +the same as if the commands had been executed directly by the shell; +if there are no \fIargs\fP or they contain no commands (i\&.e\&. are +an empty string or whitespace) the return status is zero\&. +.TP +\fBexec\fP [ \fB\-cl\fP ] [ \fB\-a\fP \fIargv0\fP ] [ \fIcommand\fP [ \fIarg\fP \&.\&.\&. ] ] +Replace the current shell with \fIcommand\fP rather than forking\&. +If \fIcommand\fP is a shell builtin command or a shell function, +the shell executes it, and exits when the command is complete\&. +.RS +.PP +With \fB\-c\fP clear the environment; with \fB\-l\fP prepend \fB\-\fP to the +\fBargv[0]\fP string of the command executed (to simulate a login shell); +with \fB\-a\fP \fIargv0\fP set the \fBargv[0]\fP string of the command +executed\&. +See the section `Precommand Modifiers\&' in \fIzshmisc\fP(1)\&. +.PP +If the option \fBPOSIX_BUILTINS\fP is set, \fIcommand\fP is never +interpreted as a shell builtin command or shell function\&. This +means further precommand modifiers such as \fBbuiltin\fP and +\fBnoglob\fP are also not interpreted within the shell\&. Hence +\fIcommand\fP is always found by searching the command path\&. +.PP +If \fIcommand\fP is omitted but any redirections are specified, +then the redirections will take effect in the current shell\&. +.RE +.TP +\fBexit\fP [ \fIn\fP ] +Exit the shell with the exit status specified by an arithmetic +expression \fIn\fP; if none +is specified, use the exit status from the last command executed\&. +An EOF condition will also cause the shell to exit, unless +the \fBIGNORE_EOF\fP option is set\&. +.RS +.PP +See notes at the end of +the section JOBS in \fIzshmisc\fP(1) for some possibly unexpected interactions +of the \fBexit\fP command with jobs\&. +.RE +.TP +\fBexport\fP [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ] +The specified \fIname\fPs are marked for automatic export +to the environment of subsequently executed commands\&. +Equivalent to \fBtypeset \-gx\fP\&. +If a parameter specified does not +already exist, it is created in the global scope\&. +.TP +\fBfalse\fP [ \fIarg\fP \&.\&.\&. ] +Do nothing and return an exit status of 1\&. + +.TP +.PD 0 +\fBfc\fP [ \fB\-e\fP \fIename\fP ] [ \fB\-s\fP ] [ \fB\-LI\fP ] [ \fB\-m\fP \fImatch\fP ] [ \fIold\fP\fB=\fP\fInew\fP \&.\&.\&. ] [ \fIfirst\fP [ \fIlast\fP ] ] +.TP +.PD 0 +\fBfc \-l \fP[ \fB\-LI\fP ] [ \fB\-nrdfEiD\fP ] [ \fB\-t\fP \fItimefmt\fP ] [ \fB\-m\fP \fImatch\fP ] +.TP +.PD 0 +\fB \fP[ \fIold\fP\fB=\fP\fInew\fP \&.\&.\&. ] [ \fIfirst\fP [ \fIlast\fP ] ] +.TP +.PD 0 +\fBfc \-p \fP[ \fB\-a\fP ] [ \fIfilename\fP [ \fIhistsize\fP [ \fIsavehistsize\fP ] ] ] +.TP +.PD 0 +\fBfc\fP \fB\-P\fP +.TP +.PD +\fBfc\fP \fB\-ARWI\fP [ \fIfilename\fP ] +The \fBfc\fP command controls the interactive history mechanism\&. Note +that reading and writing of history options is only performed if the +shell is interactive\&. Usually this is detected automatically, but +it can be forced by setting the \fBinteractive\fP option when starting the +shell\&. +.RS +.PP +The first two forms of this command select a range of events from +\fIfirst\fP to \fIlast\fP from the history list\&. The arguments \fIfirst\fP +and \fIlast\fP may be specified as a number or as a string\&. A negative +number is used as an offset to the current history event number\&. A string +specifies the most recent event beginning with the given string\&. All +substitutions \fIold\fP\fB=\fP\fInew\fP, if any, are then performed on the +text of the events\&. +.PP +The range of events selected by numbers can be narrowed further by the +following flags\&. +.PD 0 +.TP +\fB\-I\fP +restricts to only internal events (not from \fB$HISTFILE\fP) +.TP +\fB\-L\fP +restricts to only local events (not from other shells, see +\fBSHARE_HISTORY\fP in \fIzshoptions\fP(1) \-\- note that \fB$HISTFILE\fP is +considered local when read at startup) +.TP +\fB\-m\fP +takes the first argument as a pattern (which should be +quoted) and only the history events matching this pattern are considered +.PD +.PP +If \fIfirst\fP is not specified, it will be set to \-1 (the most recent +event), or to \-16 if the \fB\-l\fP flag is given\&. +If \fIlast\fP is not specified, it will be set to \fIfirst\fP, +or to \-1 if the \fB\-l\fP flag is given\&. +However, if the current event has added entries to the history with +`\fBprint \-s\fP\&' or `\fBfc \-R\fP', then the default \fIlast\fP for \fB\-l\fP +includes all new history entries since the current event began\&. +.PP +When the \fB\-l\fP flag is given, the resulting events are listed on +standard output\&. Otherwise the editor program specified by \fB\-e\fP \fIename\fP +is invoked on a file containing these history events\&. If \fB\-e\fP is not given, the +value of the parameter \fBFCEDIT\fP is used; if that is not set the value of +the parameter \fBEDITOR\fP is used; if that is not set a builtin default, +usually `\fBvi\fP\&' is used\&. If \fIename\fP is `\fB\-\fP', no editor is invoked\&. +When editing is complete, the edited command is executed\&. +.PP +The flag `\fB\-s\fP\&' is equivalent to `\fB\-e \-\fP'\&. +The flag \fB\-r\fP reverses the order of the events and the +flag \fB\-n\fP suppresses event numbers when listing\&. +.PP +Also when listing, +.PD 0 +.TP +\fB\-d\fP +prints timestamps for each event +.TP +\fB\-f\fP +prints full time\-date stamps in the US +`\fIMM\fP\fB/\fP\fIDD\fP\fB/\fP\fIYY\fP \fIhh\fP\fB:\fP\fImm\fP\&' format +.TP +\fB\-E\fP +prints full time\-date stamps in the European +`\fIdd\fP\fB\&.\fP\fImm\fP\fB\&.\fP\fIyyyy\fP \fIhh\fP\fB:\fP\fImm\fP\&' format +.TP +\fB\-i\fP +prints full time\-date stamps in ISO8601 +`\fIyyyy\fP\fB\-\fP\fImm\fP\fB\-\fP\fIdd\fP \fIhh\fP\fB:\fP\fImm\fP\&' format +.TP +\fB\-t\fP \fIfmt\fP +prints time and date stamps in the given format; +\fIfmt\fP is formatted with the strftime function with the zsh extensions +described for the \fB%D{\fP\fIstring\fP\fB}\fP prompt format in +the section EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)\&. The resulting formatted string must be +no more than 256 characters or will not be printed +.PP +.TP +\fB\-D\fP +prints elapsed times; may be combined with one of the +options above +.PD +.PP +`\fBfc \-p\fP\&' pushes the current history list onto a stack and switches to a +new history list\&. If the \fB\-a\fP option is also specified, this history list +will be automatically popped when the current function scope is exited, which +is a much better solution than creating a trap function to call `\fBfc \-P\fP\&' +manually\&. If no arguments are specified, the history list is left empty, +\fB$HISTFILE\fP is unset, and \fB$HISTSIZE\fP & \fB$SAVEHIST\fP are set to their +default values\&. If one argument is given, \fB$HISTFILE\fP is set to that +filename, \fB$HISTSIZE\fP & \fB$SAVEHIST\fP are left unchanged, and the history +file is read in (if it exists) to initialize the new list\&. If a second +argument is specified, \fB$HISTSIZE\fP & \fB$SAVEHIST\fP are instead set to the +single specified numeric value\&. Finally, if a third argument is specified, +\fB$SAVEHIST\fP is set to a separate value from \fB$HISTSIZE\fP\&. You are free to +change these environment values for the new history list however you desire +in order to manipulate the new history list\&. +.PP +`\fBfc \-P\fP\&' pops the history list back to an older list saved by `\fBfc \-p\fP'\&. +The current list is saved to its \fB$HISTFILE\fP before it is destroyed +(assuming that \fB$HISTFILE\fP and \fB$SAVEHIST\fP are set appropriately, of +course)\&. The values of \fB$HISTFILE\fP, \fB$HISTSIZE\fP, and \fB$SAVEHIST\fP are +restored to the values they had when `\fBfc \-p\fP\&' was called\&. Note that this +restoration can conflict with making these variables "local", so your best +bet is to avoid local declarations for these variables in functions that use +`\fBfc \-p\fP\&'\&. The one other guaranteed\-safe combination is declaring these +variables to be local at the top of your function and using the automatic +option (\fB\-a\fP) with `\fBfc \-p\fP\&'\&. Finally, note that it is legal to manually +pop a push marked for automatic popping if you need to do so before the +function exits\&. +.PP +`\fBfc \-R\fP\&' reads the history from the given file, +`\fBfc \-W\fP\&' writes the history out to the given file, +and `\fBfc \-A\fP\&' appends the history out to the given file\&. +If no filename is specified, the \fB$HISTFILE\fP is assumed\&. +If the \fB\-I\fP option is added to \fB\-R\fP, only those events that are +not already contained within the internal history list are added\&. +If the \fB\-I\fP option is added to \fB\-A\fP or \fB\-W\fP, only those +events that are new since last incremental append/write to +the history file are appended/written\&. +In any case, the created file will have no more than \fB$SAVEHIST\fP +entries\&. +.RE +.TP +.PD 0 +\fBfg\fP [ \fIjob\fP \&.\&.\&. ] +.TP +.PD +\fIjob\fP \&.\&.\&. +Bring each specified \fIjob\fP in turn to the foreground\&. +If no \fIjob\fP is specified, resume the current job\&. +.TP +\fBfloat\fP [ {\fB+\fP|\fB\-\fP}\fBHghlprtux\fP ] [ {\fB+\fP|\fB\-\fP}\fBEFLRZ\fP [ \fIn\fP ] ] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ] +Equivalent to \fBtypeset \-E\fP, except that options irrelevant to floating +point numbers are not permitted\&. +.TP +.PD 0 +\fBfunctions\fP [ {\fB+\fP|\fB\-\fP}\fBUkmtTuWz\fP ] [ \fB\-x\fP \fInum\fP ] [ \fIname\fP \&.\&.\&. ] +.TP +.PD 0 +\fBfunctions \-c\fP \fIoldfn\fP \fInewfn\fP +.TP +.PD 0 +\fBfunctions \-M\fP [\fB\-s\fP] \fImathfn\fP [ \fImin\fP [ \fImax\fP [ \fIshellfn\fP ] ] ] +.TP +.PD 0 +\fBfunctions \-M\fP [ \fB\-m\fP \fIpattern\fP \&.\&.\&. ] +.TP +.PD +\fBfunctions +M\fP [ \fB\-m\fP ] \fImathfn\fP \&.\&.\&. +Equivalent to \fBtypeset \-f\fP, with the exception of the \fB\-c\fP, \fB\-x\fP, +\fB\-M\fP and \fB\-W\fP options\&. For \fBfunctions \-u\fP and \fBfunctions \-U\fP, +see \fBautoload\fP, which provides additional options\&. +.RS +.PP +The \fB\-x\fP option indicates that any functions output will have +each leading tab for indentation, added by the shell to show syntactic +structure, expanded to the given number \fInum\fP of spaces\&. \fInum\fP +can also be 0 to suppress all indentation\&. +.PP +The \fB\-W\fP option turns on the option \fBWARN_NESTED_VAR\fP for the named +function or functions only\&. The option is turned off at the start of +nested functions (apart from anonoymous functions) unless the called +function also has the \fB\-W\fP attribute\&. +.PP +The \fB\-c\fP option causes \fIoldfn\fP to be copied to \fInewfn\fP\&. The +copy is efficiently handled internally by reference counting\&. If +\fIoldfn\fP was marked for autoload it is first loaded and if this +fails the copy fails\&. Either function may subsequently be redefined +without affecting the other\&. A typical idiom is that \fIoldfn\fP is the +name of a library shell function which is then redefined to call +\fBnewfn\fP, thereby installing a modified version of the function\&. +.PP +\fIThe \fP\fB\-M\fP\fI and \fP\fB+M\fP\fI flags\fP +.PP +Use of the \fB\-M\fP option may not be combined with any of the options +handled by \fBtypeset \-f\fP\&. +.PP +\fBfunctions \-M\fP \fImathfn\fP defines \fImathfn\fP as the name of +a mathematical function recognised in all forms of arithmetical expressions; +see +the section `Arithmetic Evaluation\&' in \fIzshmisc\fP(1)\&. By default \fImathfn\fP may take +any number of comma\-separated arguments\&. If \fImin\fP is given, +it must have exactly \fImin\fP args; if \fImin\fP and \fImax\fP are +both given, it must have at least \fImin\fP and at most \fImax\fP +args\&. \fImax\fP may be \-1 to indicate that there is no upper limit\&. +.PP +By default the function is implemented by a shell function of the same +name; if \fIshellfn\fP is specified it gives the name of the corresponding +shell function while \fImathfn\fP remains the name used in arithmetical +expressions\&. The name of the function in \fB$0\fP is \fImathfn\fP (not +\fIshellfn\fP as would usually be the case), provided the option +\fBFUNCTION_ARGZERO\fP is in effect\&. The positional parameters in the shell +function correspond to the arguments of the mathematical function call\&. +.PP +The result of the last arithmetical expression evaluated inside the shell +function gives the result of the mathematical function\&. This is not limited to +arithmetic substitutions of the form \fB$((\fP\fI\&.\&.\&.\fP\fB))\fP, +but also includes arithmetical expressions evaluated in any other way, including +by the \fBlet\fP builtin, +by \fB((\fP\fI\&.\&.\&.\fP\fB))\fP statements, +and even +by the \fBreturn\fP builtin +and +by array subscripts\&. +Therefore, care must be taken not to use syntactical constructs that perform +arithmetic evaluation after evaluating what is to be the result of the function\&. +For example: +.PP +.RS +.nf +\fB# WRONG +zmath_cube() { + (( $1 * $1 * $1 )) + return 0 +} +functions \-M cube 1 1 zmath_cube +print $(( cube(3) ))\fP +.fi +.RE +.PP +This will print `\fB0\fP\&' because of the \fBreturn\fP\&. +.PP +Commenting the \fBreturn\fP out would lead to a different problem: the +\fB((\fP\fI\&.\&.\&.\fP\fB))\fP statement would become +the last statement in the function, so the \fIreturn status\fP (\fB$?\fP) of the +function would be non\-zero (indicating failure) whenever the \fIarithmetic +result\fP of the function would happen to be zero (numerically): +.PP +.RS +.nf +\fB# WRONG +zmath_cube() { + (( $1 * $1 * $1 )) +} +functions \-M cube 1 1 zmath_cube +print $(( cube(0) ))\fP +.fi +.RE +.PP +Instead, the \fBtrue\fP builtin can be used: +.PP +.RS +.nf +\fB# RIGHT +zmath_cube() { + (( $1 * $1 * $1 )) + true +} +functions \-M cube 1 1 zmath_cube +print $(( cube(3) ))\fP +.fi +.RE +.PP +If the additional option \fB\-s\fP is given to \fBfunctions \-M\fP, the +argument to the function is a single string: anything between the +opening and matching closing parenthesis is passed to the function as a +single argument, even if it includes commas or white space\&. The minimum +and maximum argument specifiers must therefore be 1 if given\&. An empty +argument list is passed as a zero\-length string\&. +Thus, the following string function takes a single argument, including +the commas, and prints 11: +.PP +.RS +.nf +\fBstringfn() { (( $#1 )); true } +functions \-Ms stringfn +print $(( stringfn(foo,bar,rod) ))\fP +.fi +.RE +.PP +\fBfunctions \-M\fP with no arguments lists all such user\-defined functions in +the same form as a definition\&. With the additional option \fB\-m\fP and +a list of arguments, all functions whose \fImathfn\fP matches one of +the pattern arguments are listed\&. +.PP +\fBfunction +M\fP removes the list of mathematical functions; with the +additional option \fB\-m\fP the arguments are treated as patterns and +all functions whose \fImathfn\fP matches the pattern are removed\&. Note +that the shell function implementing the behaviour is not removed +(regardless of whether its name coincides with \fImathfn\fP)\&. +.RE +.TP +\fBgetcap\fP +See the section `The zsh/cap Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBgetln\fP [ \fB\-AclneE\fP ] \fIname\fP \&.\&.\&. +Read the top value from the buffer stack and put it in +the shell parameter \fIname\fP\&. Equivalent to +\fBread \-zr\fP\&. +.TP +\fBgetopts\fP \fIoptstring\fP \fIname\fP [ \fIarg\fP \&.\&.\&. ] +Checks the \fIarg\fPs for legal options\&. If the \fIarg\fPs are omitted, +use the positional parameters\&. A valid option argument +begins with a `\fB+\fP\&' or a `\fB\-\fP'\&. An argument not beginning with +a `\fB+\fP\&' or a `\fB\-\fP', or the argument `\fB\-\fP\fB\-\fP', ends the options\&. +Note that a single `\fB\-\fP\&' is not considered a valid option argument\&. +\fIoptstring\fP contains the letters that \fBgetopts\fP +recognizes\&. If a letter is followed by a `\fB:\fP\&', that option +requires an argument\&. The options can be +separated from the argument by blanks\&. +.RS +.PP +Each time it is invoked, \fBgetopts\fP places the option letter it finds +in the shell parameter \fIname\fP, prepended with a `\fB+\fP\&' when +\fIarg\fP begins with a `\fB+\fP\&'\&. The index of the next \fIarg\fP +is stored in \fBOPTIND\fP\&. The option argument, if any, +is stored in \fBOPTARG\fP\&. +.PP +The first option to be examined may be changed by explicitly assigning +to \fBOPTIND\fP\&. \fBOPTIND\fP has an initial value of \fB1\fP, and is +normally set to \fB1\fP upon entry to a shell function and restored +upon exit\&. (The \fBPOSIX_BUILTINS\fP option disables this, and also changes +the way the value is calculated to match other shells\&.) \fBOPTARG\fP +is not reset and retains its value from the most recent call to +\fBgetopts\fP\&. If either of \fBOPTIND\fP or \fBOPTARG\fP is explicitly +unset, it remains unset, and the index or option argument is not +stored\&. The option itself is still stored in \fIname\fP in this case\&. +.PP +A leading `\fB:\fP\&' in \fIoptstring\fP causes \fBgetopts\fP to store the +letter of any invalid option in \fBOPTARG\fP, and to set \fIname\fP to +`\fB?\fP\&' for an unknown option and to `\fB:\fP' when a required argument is +missing\&. Otherwise, \fBgetopts\fP sets \fIname\fP to `\fB?\fP\&' and prints +an error message when an option is invalid\&. The exit status is +nonzero when there are no more options\&. +.RE +.TP +\fBhash\fP [ \fB\-Ldfmrv\fP ] [ \fIname\fP[\fB=\fP\fIvalue\fP] ] \&.\&.\&. +\fBhash\fP can be used to directly modify the contents of the command +hash table, and the named directory hash table\&. Normally one would +modify these tables by modifying one\&'s \fBPATH\fP +(for the command hash table) or by creating appropriate shell parameters +(for the named directory hash table)\&. +The choice of hash table to work on is determined by the \fB\-d\fP option; +without the option the command hash table is used, and with the option the +named directory hash table is used\&. +.RS +.PP +A command \fIname\fP starting with a \fB/\fP is never hashed, whether by +explicit use of the \fBhash\fP command or otherwise\&. Such a command +is always found by direct look up in the file system\&. +.PP +Given no arguments, and neither the \fB\-r\fP or \fB\-f\fP options, +the selected hash table will be listed in full\&. +.PP +The \fB\-r\fP option causes the selected hash table to be emptied\&. +It will be subsequently rebuilt in the normal fashion\&. +The \fB\-f\fP option causes the selected hash table to be fully +rebuilt immediately\&. For the command hash table this hashes +all the absolute directories in the \fBPATH\fP, +and for the named directory hash table this adds all users\&' home directories\&. +These two options cannot be used with any arguments\&. +.PP +The \fB\-m\fP option causes the arguments to be taken as patterns +(which should be quoted) and the elements of the hash table +matching those patterns are printed\&. This is the only way to display +a limited selection of hash table elements\&. +.PP +For each \fIname\fP with a corresponding \fIvalue\fP, put `\fIname\fP\&' in +the selected hash table, associating it with the pathname `\fIvalue\fP\&'\&. +In the command hash table, this means that +whenever `\fIname\fP\&' is used as a command argument, the shell will try +to execute the file given by `\fIvalue\fP\&'\&. +In the named directory hash table, this means +that `\fIvalue\fP\&' may be referred to as `\fB~\fP\fIname\fP'\&. +.PP +For each \fIname\fP with no +corresponding \fIvalue\fP, attempt to add \fIname\fP to the hash table, +checking what the appropriate \fBvalue\fP is in the normal manner for +that hash table\&. If an appropriate \fBvalue\fP can\&'t be found, then +the hash table will be unchanged\&. +.PP +The \fB\-v\fP option causes hash table entries to be listed as they are +added by explicit specification\&. If has no effect if used with \fB\-f\fP\&. +.PP +If the \fB\-L\fP flag is present, then each hash table entry is printed in +the form of a call to hash\&. +.RE +.TP +\fBhistory\fP +Same as \fBfc \-l\fP\&. +.TP +\fBinteger\fP [ {\fB+\fP|\fB\-\fP}\fBHghlprtux\fP ] [ {\fB+\fP|\fB\-\fP}\fBLRZi\fP [ \fIn\fP ] ] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ] +Equivalent to \fBtypeset \-i\fP, except that options irrelevant to +integers are not permitted\&. +.TP +.PD 0 +\fBjobs\fP [ \fB\-dlprs\fP ] [ \fIjob\fP \&.\&.\&. ] +.TP +.PD +\fBjobs \-Z\fP \fIstring\fP +Lists information about each given job, or all jobs +if \fIjob\fP is omitted\&. The \fB\-l\fP flag lists process +IDs, and the \fB\-p\fP flag lists process groups\&. +If the \fB\-r\fP flag is specified only running jobs will be listed +and if the \fB\-s\fP flag is given only stopped jobs are shown\&. +If the \fB\-d\fP flag is given, the directory from which the job was +started (which may not be the current directory of the job) will also +be shown\&. +.RS +.PP +The \fB\-Z\fP option replaces the shell\&'s argument and environment space with +the given string, truncated if necessary to fit\&. This will normally be +visible in \fBps\fP (\fIps\fP(1)) listings\&. This feature is typically +used by daemons, to indicate their state\&. +.PP +Full job control is only available in the top\-level interactive shell, +not in commands run in the left hand side of pipelines or within +the \fB(\fP\fI\&.\&.\&.\fP\fB)\fP construct\&. However, a snapshot +of the job state at that point is taken, so it is still possible +to use the \fBjobs\fP builtin, or any parameter providing job information\&. +This gives information about the state of jobs at the point the subshell +was created\&. If background processes are created within the subshell, +then instead information about those processes is provided\&. +.PP +For example, +.PP +.RS +.nf +\fBsleep 10 & # Job in background +( # Shell forks +jobs # Shows information about "sleep 10 &" +sleep 5 & # Process in background (no job control) +jobs # Shows information about "sleep 5 &" +)\fP +.fi +.RE +.RE +.TP +.PD 0 +\fBkill\fP [ \fB\-s\fP \fIsignal_name\fP | \fB\-n\fP \fIsignal_number\fP | \fB\-\fP\fIsig\fP ] \fIjob\fP \&.\&.\&. +.TP +.PD +\fBkill\fP \fB\-l\fP [ \fIsig\fP \&.\&.\&. ] +Sends either \fBSIGTERM\fP or the specified signal to the given +jobs or processes\&. +Signals are given by number or by names, with or without the `\fBSIG\fP\&' +prefix\&. +If the signal being sent is not `\fBKILL\fP\&' or `\fBCONT\fP', then the job +will be sent a `\fBCONT\fP\&' signal if it is stopped\&. +The argument \fIjob\fP can be the process ID of a job +not in the job list\&. +In the second form, \fBkill \-l\fP, if \fIsig\fP is not +specified the signal names are listed\&. Otherwise, for each +\fIsig\fP that is a name, the corresponding signal number is +listed\&. For each \fIsig\fP that is a signal number or a number +representing the exit status of a process which was terminated or +stopped by a signal the name of the signal is printed\&. +.RS +.PP +On some systems, alternative signal names are allowed for a few signals\&. +Typical examples are \fBSIGCHLD\fP and \fBSIGCLD\fP or \fBSIGPOLL\fP and +\fBSIGIO\fP, assuming they correspond to the same signal number\&. \fBkill +\-l\fP will only list the preferred form, however \fBkill \-l\fP \fIalt\fP will +show if the alternative form corresponds to a signal number\&. For example, +under Linux \fBkill \-l IO\fP and \fBkill \-l POLL\fP both output 29, hence +\fBkill \-IO\fP and \fBkill \-POLL\fP have the same effect\&. +.PP +Many systems will allow process IDs to be negative to kill a process +group or zero to kill the current process group\&. +.RE +.TP +\fBlet\fP \fIarg\fP \&.\&.\&. +Evaluate each \fIarg\fP as an arithmetic expression\&. +See +the section `Arithmetic Evaluation\&' in \fIzshmisc\fP(1) +for a description of arithmetic expressions\&. The exit status is 0 if the +value of the last expression is nonzero, 1 if it is zero, and 2 if +an error occurred\&. +.TP +\fBlimit\fP [ \fB\-hs\fP ] [ \fIresource\fP [ \fIlimit\fP ] ] \&.\&.\&. +Set or display resource limits\&. Unless the \fB\-s\fP flag is given, +the limit applies only the children of the shell\&. If \fB\-s\fP is +given without other arguments, the resource limits of the current +shell is set to the previously set resource limits of the children\&. +.RS +.PP +If \fIlimit\fP is not specified, print the current limit placed +on \fIresource\fP, otherwise +set the limit to the specified value\&. If the \fB\-h\fP flag +is given, use hard limits instead of soft limits\&. +If no \fIresource\fP is given, print all limits\&. +.PP +When looping over multiple resources, the shell will abort immediately if +it detects a badly formed argument\&. However, if it fails to set a limit +for some other reason it will continue trying to set the remaining limits\&. +.PP +\fIresource\fP can be one of: +.PP +.PD 0 +.TP +\fBaddressspace\fP +Maximum amount of address space used\&. +.TP +\fBaiomemorylocked\fP +Maximum amount of memory locked in RAM for AIO operations\&. +.TP +\fBaiooperations\fP +Maximum number of AIO operations\&. +.TP +\fBcachedthreads\fP +Maximum number of cached threads\&. +.TP +\fBcoredumpsize\fP +Maximum size of a core dump\&. +.TP +\fBcputime\fP +Maximum CPU seconds per process\&. +.TP +\fBdatasize\fP +Maximum data size (including stack) for each process\&. +.TP +\fBdescriptors\fP +Maximum value for a file descriptor\&. +.TP +\fBfilesize\fP +Largest single file allowed\&. +.TP +\fBkqueues\fP +Maximum number of kqueues allocated\&. +.TP +\fBmaxproc\fP +Maximum number of processes\&. +.TP +\fBmaxpthreads\fP +Maximum number of threads per process\&. +.TP +\fBmemorylocked\fP +Maximum amount of memory locked in RAM\&. +.TP +\fBmemoryuse\fP +Maximum resident set size\&. +.TP +\fBmsgqueue\fP +Maximum number of bytes in POSIX message queues\&. +.TP +\fBposixlocks\fP +Maximum number of POSIX locks per user\&. +.TP +\fBpseudoterminals\fP +Maximum number of pseudo\-terminals\&. +.TP +\fBresident\fP +Maximum resident set size\&. +.TP +\fBsigpending\fP +Maximum number of pending signals\&. +.TP +\fBsockbufsize\fP +Maximum size of all socket buffers\&. +.TP +\fBstacksize\fP +Maximum stack size for each process\&. +.TP +\fBswapsize\fP +Maximum amount of swap used\&. +.TP +\fBvmemorysize\fP +Maximum amount of virtual memory\&. +.PD +.PP +Which of these resource limits are available depends on the system\&. +\fIresource\fP can be abbreviated to any unambiguous prefix\&. It +can also be an integer, which corresponds to the integer defined +for the resource by the operating system\&. +.PP +If argument corresponds to a number which is out of the range of the +resources configured into the shell, the shell will try to read or write +the limit anyway, and will report an error if this fails\&. As the shell +does not store such resources internally, an attempt to set the limit will +fail unless the \fB\-s\fP option is present\&. +.PP +\fIlimit\fP is a number, with an optional scaling factor, as follows: +.PP +.PD 0 +.TP +\fIn\fP\fBh\fP +hours +.TP +\fIn\fP\fBk\fP +kilobytes (default) +.TP +\fIn\fP\fBm\fP +megabytes or minutes +.TP +\fIn\fP\fBg\fP +gigabytes +.TP +[\fImm\fP\fB:\fP]\fIss\fP +minutes and seconds +.PD +.PP +The \fBlimit\fP command is not made available by default when the +shell starts in a mode emulating another shell\&. It can be made available +with the command `\fBzmodload \-F zsh/rlimits b:limit\fP\&'\&. +.RE +.TP +\fBlocal\fP [ {\fB+\fP|\fB\-\fP}\fBAHUahlprtux\fP ] [ {\fB+\fP|\fB\-\fP}\fBEFLRZi\fP [ \fIn\fP ] ] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ] +Same as \fBtypeset\fP, except that the options \fB\-g\fP, and +\fB\-f\fP are not permitted\&. In this case the \fB\-x\fP option does not force +the use of \fB\-g\fP, i\&.e\&. exported variables will be local to functions\&. +.TP +\fBlogout\fP [ \fIn\fP ] +Same as \fBexit\fP, except that it only works in a login shell\&. +.TP +\fBnoglob\fP \fIsimple command\fP +See the section `Precommand Modifiers\&' in \fIzshmisc\fP(1)\&. +.TP +\fBpopd\fP [ \fB\-q\fP ] [ {\fB+\fP|\fB\-\fP}\fIn\fP ] +Remove an entry from the directory stack, and perform a \fBcd\fP to +the new top directory\&. With no argument, the current top entry is +removed\&. An argument of the form `\fB+\fP\fIn\fP\&' identifies a stack +entry by counting from the left of the list shown by the \fBdirs\fP command, +starting with zero\&. An argument of the form \fB\-\fP\fIn\fP counts from the right\&. +If the \fBPUSHD_MINUS\fP option is set, the meanings of `\fB+\fP\&' and +`\fB\-\fP\&' in this context are swapped\&. +.RS +.PP +If the \fB\-q\fP (quiet) option is specified, the hook function \fBchpwd\fP +and the functions in the array \fB$chpwd_functions\fP are not called, +and the new directory stack is not printed\&. This is useful for calls to +\fBpopd\fP that do not change the environment seen by an interactive user\&. +.RE +.TP +.PD 0 +\fBprint \fP[ \fB\-abcDilmnNoOpPrsSz\fP ] [ \fB\-u\fP \fIn\fP ] [ \fB\-f\fP \fIformat\fP ] [ \fB\-C\fP \fIcols\fP ] +.TP +.PD +\fB \fP[ \fB\-v\fP \fIname\fP ] [ \fB\-xX\fP \fItabstop\fP ] [ \fB\-R\fP [ \fB\-en\fP ]] [ \fIarg\fP \&.\&.\&. ] +With the `\fB\-f\fP\&' option the arguments are printed as described by \fBprintf\fP\&. +With no flags or with the flag `\fB\-\fP\&', the arguments are printed on +the standard output as described by \fBecho\fP, with the following differences: +the escape sequence `\fB\eM\-\fP\fIx\fP\&' (or `\fB\eM\fP\fIx\fP') metafies the character +\fIx\fP (sets the highest bit), +`\fB\eC\-\fP\fIx\fP\&' (or `\fB\eC\fP\fIx\fP') produces a control character +(`\fB\eC\-@\fP\&' and `\fB\eC\-?\fP' give the characters NULL and delete), +a character code in octal is represented by `\fB\e\fP\fINNN\fP\&' +(instead of `\fB\e0\fP\fINNN\fP\&'), +and `\fB\eE\fP\&' is a synonym for `\fB\ee\fP'\&. +Finally, if not in an escape +sequence, `\fB\e\fP\&' escapes the following character and is not printed\&. +.RS +.PP +.PD 0 +.TP +.PD +\fB\-a\fP +Print arguments with the column incrementing first\&. Only useful with the +\fB\-c\fP and \fB\-C\fP options\&. +.TP +\fB\-b\fP +Recognize all the escape sequences defined for the \fBbindkey\fP command, +see +the section `Zle Builtins\&' in \fIzshzle\fP(1)\&. +.TP +\fB\-c\fP +Print the arguments in columns\&. Unless \fB\-a\fP is also given, arguments are +printed with the row incrementing first\&. +.TP +\fB\-C\fP \fIcols\fP +Print the arguments in \fIcols\fP columns\&. Unless \fB\-a\fP is also given, +arguments are printed with the row incrementing first\&. +.TP +\fB\-D\fP +Treat the arguments as paths, replacing directory prefixes with \fB~\fP +expressions corresponding to directory names, as appropriate\&. +.TP +\fB\-i\fP +If given together with \fB\-o\fP or \fB\-O\fP, sorting is performed +case\-independently\&. +.TP +\fB\-l\fP +Print the arguments separated by newlines instead of spaces\&. Note: if +the list of arguments is empty, \fBprint \-l\fP will still output one empty +line\&. To print a possibly\-empty list of arguments one per line, use +\fBprint \-C1\fP, as in `\fBprint \-rC1 \-\- "$list[@]"\fP\&'\&. +.TP +\fB\-m\fP +Take the first argument as a pattern (should be quoted), and remove +it from the argument list together with subsequent arguments that +do not match this pattern\&. +.TP +\fB\-n\fP +Do not add a newline to the output\&. +.TP +\fB\-N\fP +Print the arguments separated and terminated by nulls\&. Again, +\fBprint \-rNC1 \-\- "$list[@]"\fP is a canonical way to print an +arbitrary list as null\-delimited records\&. +.TP +\fB\-o\fP +Print the arguments sorted in ascending order\&. +.TP +\fB\-O\fP +Print the arguments sorted in descending order\&. +.TP +\fB\-p\fP +Print the arguments to the input of the coprocess\&. +.TP +\fB\-P\fP +Perform prompt expansion (see +EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1))\&. +In combination with `\fB\-f\fP\&', +prompt escape sequences are parsed only within interpolated arguments, +not within the format string\&. +.TP +\fB\-r\fP +Ignore the escape conventions of \fBecho\fP\&. +.TP +\fB\-R\fP +Emulate the BSD \fBecho\fP command, which does not process escape sequences +unless the \fB\-e\fP flag is given\&. The \fB\-n\fP flag suppresses the trailing +newline\&. Only the \fB\-e\fP and \fB\-n\fP flags are recognized after +\fB\-R\fP; all other arguments and options are printed\&. +.TP +\fB\-s\fP +Place the results in the history list instead of on the standard output\&. +Each argument to the \fBprint\fP command is treated as a single word in the +history, regardless of its content\&. +.TP +\fB\-S\fP +Place the results in the history list instead of on the standard output\&. +In this case only a single argument is allowed; it will be split into +words as if it were a full shell command line\&. The effect is +similar to reading the line from a history file with the +\fBHIST_LEX_WORDS\fP option active\&. +.TP +\fB\-u\fP \fIn\fP +Print the arguments to file descriptor \fIn\fP\&. +.TP +\fB\-v\fP \fIname\fP +Store the printed arguments as the value of the parameter \fIname\fP\&. +.TP +\fB\-x\fP \fItab\-stop\fP +Expand leading tabs on each line of output in the printed string +assuming a tab stop every \fItab\-stop\fP characters\&. This is appropriate +for formatting code that may be indented with tabs\&. Note that leading +tabs of any argument to print, not just the first, are expanded, even if +\fBprint\fP is using spaces to separate arguments (the column count +is maintained across arguments but may be incorrect on output +owing to previous unexpanded tabs)\&. +.RS +.PP +The start of the output of each print command is assumed to be aligned +with a tab stop\&. Widths of multibyte characters are handled if the +option \fBMULTIBYTE\fP is in effect\&. This option is ignored if other +formatting options are in effect, namely column alignment or +\fBprintf\fP style, or if output is to a special location such as shell +history or the command line editor\&. +.RE +.TP +\fB\-X\fP \fItab\-stop\fP +This is similar to \fB\-x\fP, except that all tabs in the printed string +are expanded\&. This is appropriate if tabs in the arguments are +being used to produce a table format\&. +.TP +\fB\-z\fP +Push the arguments onto the editing buffer stack, separated by spaces\&. +.PP +If any of `\fB\-m\fP\&', `\fB\-o\fP' or `\fB\-O\fP' are used in combination with +`\fB\-f\fP\&' and there are no arguments (after the removal process in the +case of `\fB\-m\fP\&') then nothing is printed\&. +.RE +.TP +\fBprintf\fP [ \fB\-v\fP \fIname\fP ] \fIformat\fP [ \fIarg\fP \&.\&.\&. ] +Print the arguments according to the format specification\&. Formatting +rules are the same as used in C\&. The same escape sequences as for \fBecho\fP +are recognised in the format\&. All C conversion specifications ending in +one of \fBcsdiouxXeEfgGn\fP are handled\&. In addition to this, `\fB%b\fP\&' can be +used instead of `\fB%s\fP\&' to cause escape sequences in the argument to be +recognised and `\fB%q\fP\&' can be used to quote the argument in such a way +that allows it to be reused as shell input\&. With the numeric format +specifiers, if the corresponding argument starts with a quote character, +the numeric value of the following character is used as the number to +print; otherwise the argument is evaluated as an arithmetic expression\&. See +the section `Arithmetic Evaluation\&' in \fIzshmisc\fP(1) +for a description of arithmetic +expressions\&. With `\fB%n\fP\&', the corresponding argument is taken as an +identifier which is created as an integer parameter\&. +.RS +.PP +Normally, conversion specifications are applied to each argument in order +but they can explicitly specify the \fIn\fPth argument is to be used by +replacing `\fB%\fP\&' by `\fB%\fP\fIn\fP\fB$\fP' and `\fB*\fP' by `\fB*\fP\fIn\fP\fB$\fP'\&. +It is recommended that you do not mix references of this explicit style +with the normal style and the handling of such mixed styles may be subject +to future change\&. +.PP +If arguments remain unused after formatting, the format string is reused +until all arguments have been consumed\&. With the \fBprint\fP builtin, this +can be suppressed by using the \fB\-r\fP option\&. If more arguments are +required by the format than have been specified, the behaviour is as if +zero or an empty string had been specified as the argument\&. +.PP +The \fB\-v\fP option causes the output to be stored as the value of the +parameter \fIname\fP, instead of printed\&. If \fIname\fP is an array and +the format string is reused when consuming arguments then one +array element will be used for each use of the format string\&. +.RE +.TP +.PD 0 +\fBpushd\fP [ \fB\-qsLP\fP ] [ \fIarg\fP ] +.TP +.PD 0 +\fBpushd\fP [ \fB\-qsLP\fP ] \fIold\fP \fInew\fP +.TP +.PD +\fBpushd\fP [ \fB\-qsLP\fP ] {\fB+\fP|\fB\-\fP}\fIn\fP +Change the current directory, and push the old current directory +onto the directory stack\&. In the first form, change the +current directory to \fIarg\fP\&. +If \fIarg\fP is not specified, change to the second directory +on the stack (that is, exchange the top two entries), or +change to \fB$HOME\fP if the \fBPUSHD_TO_HOME\fP +option is set or if there is only one entry on the stack\&. +Otherwise, \fIarg\fP is interpreted as it would be by \fBcd\fP\&. +The meaning of \fIold\fP and \fInew\fP in the second form is also +the same as for \fBcd\fP\&. +.RS +.PP +The third form of \fBpushd\fP changes directory by rotating the +directory list\&. An argument of the form `\fB+\fP\fIn\fP\&' identifies a stack +entry by counting from the left of the list shown by the \fBdirs\fP +command, starting with zero\&. An argument of the form `\fB\-\fP\fIn\fP\&' counts +from the right\&. If the \fBPUSHD_MINUS\fP option is set, the meanings +of `\fB+\fP\&' and `\fB\-\fP' in this context are swapped\&. +.PP +If the \fB\-q\fP (quiet) option is specified, the hook function \fBchpwd\fP +and the functions in the array \fB$chpwd_functions\fP are not called, +and the new directory stack is not printed\&. This is useful for calls to +\fBpushd\fP that do not change the environment seen by an interactive user\&. +.PP +If the option \fB\-q\fP is not specified and the shell option \fBPUSHD_SILENT\fP +is not set, the directory stack will be printed after a \fBpushd\fP is +performed\&. +.PP +The options \fB\-s\fP, \fB\-L\fP and \fB\-P\fP have the same meanings as for the +\fBcd\fP builtin\&. +.RE +.TP +\fBpushln\fP [ \fIarg\fP \&.\&.\&. ] +Equivalent to \fBprint \-nz\fP\&. +.TP +\fBpwd\fP [ \fB\-rLP\fP ] +Print the absolute pathname of the current working directory\&. +If the \fB\-r\fP or the \fB\-P\fP flag is specified, or the \fBCHASE_LINKS\fP +option is set and the \fB\-L\fP flag is not given, the printed path will not +contain symbolic links\&. +.TP +\fBr\fP +Same as \fBfc \-e \-\fP\&. + +.TP +.PD 0 +\fBread \fP[ \fB\-rszpqAclneE\fP ] [ \fB\-t\fP [ \fInum\fP ] ] [ \fB\-k\fP [ \fInum\fP ] ] [ \fB\-d\fP \fIdelim\fP ] +.TP +.PD +\fB \fP[ \fB\-u\fP \fIn\fP ] [ [\fIname\fP][\fB?\fP\fIprompt\fP] ] [ \fIname\fP \&.\&.\&. ] +Read one line and break it into fields using the characters +in \fB$IFS\fP as separators, except as noted below\&. +The first field is assigned to the first \fIname\fP, the second field +to the second \fIname\fP, etc\&., with leftover +fields assigned to the last \fIname\fP\&. +If \fIname\fP is omitted then +\fBREPLY\fP is used for scalars and \fBreply\fP for arrays\&. +.RS +.PP +.PD 0 +.TP +.PD +\fB\-r\fP +Raw mode: a `\fB\e\fP\&' at the end of a line does not signify line +continuation and backslashes in the line don\&'t quote the following +character and are not removed\&. +.TP +\fB\-s\fP +Don\&'t echo back characters if reading from the terminal\&. +.TP +\fB\-q\fP +Read only one character from the terminal and set \fIname\fP to +`\fBy\fP\&' if this character was `\fBy\fP' or `\fBY\fP' and to `\fBn\fP' otherwise\&. +With this flag set the return status is zero only if the character was +`\fBy\fP\&' or `\fBY\fP'\&. This option may be used with a timeout (see \fB\-t\fP); if +the read times out, or encounters end of file, status 2 is returned\&. Input is +read from the terminal unless one of \fB\-u\fP or \fB\-p\fP is present\&. This option +may also be used within zle widgets\&. +.TP +\fB\-k\fP [ \fInum\fP ] +Read only one (or \fInum\fP) characters\&. All are assigned to the first +\fIname\fP, without word splitting\&. This flag is ignored when \fB\-q\fP is +present\&. Input is read from the terminal unless one of \fB\-u\fP or \fB\-p\fP +is present\&. This option may also be used within zle widgets\&. +.RS +.PP +Note that despite the mnemonic `key\&' this option does read full +characters, which may consist of multiple bytes if the option +\fBMULTIBYTE\fP is set\&. +.RE +.TP +\fB\-z\fP +Read one entry from the editor buffer stack and assign it to the first +\fIname\fP, without word splitting\&. Text is pushed onto the stack with +`\fBprint \-z\fP\&' or with \fBpush\-line\fP from the line editor (see +\fIzshzle\fP(1))\&. This flag is ignored when the \fB\-k\fP or \fB\-q\fP flags are present\&. +.TP +.PD 0 +\fB\-e\fP +.TP +.PD +\fB\-E\fP +The input read is printed (echoed) to the standard output\&. If the \fB\-e\fP +flag is used, no input is assigned to the parameters\&. +.TP +\fB\-A\fP +The first \fIname\fP is taken as the name of an array and all words are +assigned to it\&. +.TP +.PD 0 +\fB\-c\fP +.TP +.PD +\fB\-l\fP +These flags are allowed only if called inside a +function used for completion (specified with the \fB\-K\fP flag to +\fBcompctl\fP)\&. If the \fB\-c\fP flag is given, the words of the +current command are read\&. If the \fB\-l\fP flag is given, the whole +line is assigned as a scalar\&. If both flags are present, \fB\-l\fP +is used and \fB\-c\fP is ignored\&. +.TP +\fB\-n\fP +Together with \fB\-c\fP, the number of the word the cursor is on is +read\&. With \fB\-l\fP, the index of the character the cursor is on is +read\&. Note that the command name is word number 1, not word 0, +and that when the cursor is at the end of the line, its character +index is the length of the line plus one\&. +.TP +\fB\-u\fP \fIn\fP +Input is read from file descriptor \fIn\fP\&. +.TP +\fB\-p\fP +Input is read from the coprocess\&. +.TP +\fB\-d\fP \fIdelim\fP +Input is terminated by the first character of \fIdelim\fP instead of +by newline\&. +.TP +\fB\-t\fP [ \fInum\fP ] +Test if input is available before attempting to read\&. If \fInum\fP +is present, it must begin with a digit and will be evaluated +to give a number of seconds, which may be a floating point number; +in this case the read times out if input is not available within this +time\&. If \fInum\fP is not present, it is taken to be zero, so that +\fBread\fP returns immediately if no input is available\&. +If no input is available, return status 1 and do not set any variables\&. + +This option is not available when reading from the editor buffer with +\fB\-z\fP, when called from within completion with \fB\-c\fP or \fB\-l\fP, with +\fB\-q\fP which clears the input queue before reading, or within zle where +other mechanisms should be used to test for input\&. + +Note that read does not attempt to alter the input processing mode\&. The +default mode is canonical input, in which an entire line is read at a time, +so usually `\fBread \-t\fP\&' will not read anything until an entire line has +been typed\&. However, when reading from the terminal with \fB\-k\fP +input is processed one key at a time; in this case, only availability of +the first character is tested, so that e\&.g\&. `\fBread \-t \-k 2\fP\&' can still +block on the second character\&. Use two instances of `\fBread \-t \-k\fP\&' if +this is not what is wanted\&. +.PP +If the first argument contains a `\fB?\fP\&', the remainder of this +word is used as a \fIprompt\fP on standard error when the shell +is interactive\&. +.PP +The value (exit status) of \fBread\fP is 1 when an end\-of\-file is +encountered, or when \fB\-c\fP or \fB\-l\fP is present and the command is +not called from a \fBcompctl\fP function, or as described for \fB\-q\fP\&. +Otherwise the value is 0\&. +.PP +The behavior of some combinations of the \fB\-k\fP, \fB\-p\fP, \fB\-q\fP, \fB\-u\fP +and \fB\-z\fP flags is undefined\&. Presently \fB\-q\fP cancels all the others, +\fB\-p\fP cancels \fB\-u\fP, \fB\-k\fP cancels \fB\-z\fP, and otherwise \fB\-z\fP +cancels both \fB\-p\fP and \fB\-u\fP\&. +.PP +The \fB\-c\fP or \fB\-l\fP flags cancel any and all of \fB\-kpquz\fP\&. +.RE +.TP +\fBreadonly\fP +Same as \fBtypeset \-r\fP\&. With the \fBPOSIX_BUILTINS\fP option set, same +as \fBtypeset \-gr\fP\&. +.TP +\fBrehash\fP +Same as \fBhash \-r\fP\&. +.TP +\fBreturn\fP [ \fIn\fP ] +Causes a shell function or `\fB\&.\fP\&' script to return to +the invoking script with the return status specified by +an arithmetic expression \fIn\fP\&. +For example, the following prints `\fB42\fP\&': +.RS +.PP +.RS +.nf +\fB() { integer foo=40; return "foo + 2" } +echo $?\fP +.fi +.RE +.PP +If \fIn\fP +is omitted, the return status is that of the last command +executed\&. +.PP +If \fBreturn\fP was executed from a trap in a \fBTRAP\fP\fINAL\fP function, +the effect is different for zero and non\-zero return status\&. With zero +status (or after an implicit return at the end of the trap), the shell +will return to whatever it was previously processing; with a non\-zero +status, the shell will behave as interrupted except that the return +status of the trap is retained\&. Note that the numeric value of the signal +which caused the trap is passed as the first argument, so the statement +`\fBreturn "128+$1"\fP\&' will return the same status as if the signal +had not been trapped\&. +.RE +.TP +\fBsched\fP +See the section `The zsh/sched Module\&' in \fIzshmodules\fP(1)\&. + +.TP +.PD 0 +\fBset \fP[ {\fB+\fP|\fB\-\fP}\fIoptions\fP | {\fB+\fP|\fB\-\fP}\fBo\fP [ \fIoption_name\fP ] ] \&.\&.\&. [ {\fB+\fP|\fB\-\fP}\fBA\fP [ \fIname\fP ] ] +.TP +.PD +\fB \fP[ \fIarg\fP \&.\&.\&. ] +Set the options for the shell and/or set the positional parameters, or +declare and set an array\&. If the \fB\-s\fP option is given, it causes the +specified arguments to be sorted before assigning them to the positional +parameters (or to the array \fIname\fP if \fB\-A\fP is used)\&. With \fB+s\fP +sort arguments in descending order\&. For the meaning of the other flags, see +\fIzshoptions\fP(1)\&. Flags may be specified by name using the \fB\-o\fP option\&. If no option +name is supplied with \fB\-o\fP, the current option states are printed: see +the description of \fBsetopt\fP below for more information on the format\&. +With \fB+o\fP they are printed in a form that can be used as input +to the shell\&. +.RS +.PP +If the \fB\-A\fP flag is specified, \fIname\fP is set to an array containing +the given \fIarg\fPs; if no \fIname\fP is specified, all arrays are printed +together with their values\&. +.PP +If \fB+A\fP is used and \fIname\fP is an array, the +given arguments will replace the initial elements of that array; if no +\fIname\fP is specified, all arrays are printed without their values\&. +.PP +The behaviour of arguments after \fB\-A\fP \fIname\fP or \fB+A\fP \fIname\fP +depends on whether the option \fBKSH_ARRAYS\fP is set\&. If it is not set, all +arguments following \fIname\fP are treated as values for the array, +regardless of their form\&. If the option is set, normal option processing +continues at that point; only regular arguments are treated as values for +the array\&. This means that +.PP +.RS +.nf +\fBset \-A array \-x \-\- foo\fP +.fi +.RE +.PP +sets \fBarray\fP to `\fB\-x \-\fP\fB\- foo\fP\&' if \fBKSH_ARRAYS\fP is not set, but sets +the array to \fBfoo\fP and turns on the option `\fB\-x\fP\&' if it is set\&. +.PP +If the \fB\-A\fP flag is not present, but there are arguments beyond the +options, the positional parameters are set\&. If the option list (if any) +is terminated by `\fB\-\fP\fB\-\fP\&', and there are no further arguments, the +positional parameters will be unset\&. +.PP +If no arguments and no `\fB\-\fP\fB\-\fP\&' are given, then the names and values of +all parameters are printed on the standard output\&. If the only argument is +`\fB+\fP\&', the names of all parameters are printed\&. +.PP +For historical reasons, `\fBset \-\fP\&' is treated as `\fBset +xv\fP' +and `\fBset \-\fP \fIargs\fP\&' as `\fBset +xv \-\-\fP \fIargs\fP' when in +any other emulation mode than zsh\&'s native mode\&. +.RE +.TP +\fBsetcap\fP +See the section `The zsh/cap Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBsetopt\fP [ {\fB+\fP|\fB\-\fP}\fIoptions\fP | {\fB+\fP|\fB\-\fP}\fBo\fP \fIoption_name\fP ] [ \fB\-m\fP ] [ \fIname\fP \&.\&.\&. ] +Set the options for the shell\&. All options specified either +with flags or by name are set\&. +.RS +.PP +If no arguments are supplied, the names of all options currently set are +printed\&. The form is chosen so as to minimize the differences from the +default options for the current emulation (the default emulation being +native \fBzsh\fP, shown as \fB<Z>\fP in +\fIzshoptions\fP(1))\&. +Options that are on by default for the emulation are +shown with the prefix \fBno\fP only if they are off, while other options are +shown without the prefix \fBno\fP and only if they are on\&. In addition to +options changed from the default state by the user, any options activated +automatically by the shell (for example, \fBSHIN_STDIN\fP or \fBINTERACTIVE\fP) +will be shown in the list\&. The format is further modified by the option +\fBKSH_OPTION_PRINT\fP, however the rationale for choosing options with +or without the \fBno\fP prefix remains the same in this case\&. +.PP +If the \fB\-m\fP flag is given the arguments are taken as patterns +(which should be quoted to protect them from filename expansion), and all +options with names matching these patterns are set\&. +.PP +Note that a bad option name does not cause execution of subsequent shell +code to be aborted; this is behaviour is different from that of `\fBset +\-o\fP\&'\&. This is because \fBset\fP is regarded as a special builtin by the +POSIX standard, but \fBsetopt\fP is not\&. +.RE +.TP +\fBshift\fP [ \fB\-p\fP ] [ \fIn\fP ] [ \fIname\fP \&.\&.\&. ] +The positional parameters \fB${\fP\fIn\fP+1\fB}\fP \&.\&.\&. are renamed +to \fB$1\fP \&.\&.\&., where \fIn\fP is an arithmetic expression that +defaults to 1\&. +If any \fIname\fPs are given then the arrays with these names are +shifted instead of the positional parameters\&. +.RS +.PP +If the option \fB\-p\fP is given arguments are instead removed (popped) +from the end rather than the start of the array\&. +.RE +.TP +\fBsource\fP \fIfile\fP [ \fIarg\fP \&.\&.\&. ] +Same as `\fB\&.\fP\&', except that the current directory is always searched and +is always searched first, before directories in \fB$path\fP\&. +.TP +\fBstat\fP +See the section `The zsh/stat Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBsuspend\fP [ \fB\-f\fP ] +Suspend the execution of the shell (send it a \fBSIGTSTP\fP) +until it receives a \fBSIGCONT\fP\&. +Unless the \fB\-f\fP option is given, this will refuse to suspend a login shell\&. +.TP +.PD 0 +\fBtest\fP [ \fIarg\fP \&.\&.\&. ] +.TP +.PD +\fB[\fP [ \fIarg\fP \&.\&.\&. ] \fB]\fP +Like the system version of \fBtest\fP\&. Added for compatibility; +use conditional expressions instead (see the section `Conditional Expressions\&')\&. +The main differences between the conditional expression syntax and the +\fBtest\fP and \fB[\fP builtins are: these commands are not handled +syntactically, so for example an empty variable expansion may cause an +argument to be omitted; syntax errors cause status 2 to be returned instead +of a shell error; and arithmetic operators expect integer arguments rather +than arithmetic expressions\&. +.RS +.PP +The command attempts to implement POSIX and its extensions where these +are specified\&. Unfortunately there are intrinsic ambiguities in +the syntax; in particular there is no distinction between test operators +and strings that resemble them\&. The standard attempts to resolve these +for small numbers of arguments (up to four); for five or more arguments +compatibility cannot be relied on\&. Users are urged wherever possible to +use the `\fB[[\fP\&' test syntax which does not have these ambiguities\&. +.RE +.TP +\fBtimes\fP +Print the accumulated user and system times for the shell +and for processes run from the shell\&. +.TP +\fBtrap\fP [ \fIarg\fP ] [ \fIsig\fP \&.\&.\&. ] +\fIarg\fP is a series of commands (usually quoted to protect it from +immediate evaluation by the shell) to be read and executed when the shell +receives any of the signals specified by one or more \fIsig\fP args\&. +Each \fIsig\fP can be given as a number, +or as the name of a signal either with or without the string \fBSIG\fP +in front (e\&.g\&. 1, HUP, and SIGHUP are all the same signal)\&. +.RS +.PP +If \fIarg\fP is `\fB\-\fP\&', then the specified signals are reset to their +defaults, or, if no \fIsig\fP args are present, all traps are reset\&. +.PP +If \fIarg\fP is an empty string, then the specified signals +are ignored by the shell (and by the commands it invokes)\&. +.PP +If \fIarg\fP is omitted but one or more \fIsig\fP args are provided (i\&.e\&. +the first argument is a valid signal number or name), the effect is the +same as if \fIarg\fP had been specified as `\fB\-\fP\&'\&. +.PP +The \fBtrap\fP command with no arguments prints a list of commands +associated with each signal\&. +.PP +If \fIsig\fP is \fBZERR\fP then \fIarg\fP will be executed +after each command with a nonzero exit status\&. \fBERR\fP is an alias +for \fBZERR\fP on systems that have no \fBSIGERR\fP signal (this is the +usual case)\&. +.PP +If \fIsig\fP is \fBDEBUG\fP then \fIarg\fP will be executed +before each command if the option \fBDEBUG_BEFORE_CMD\fP is set +(as it is by default), else after each command\&. Here, a `command\&' is +what is described as a `sublist\&' in the shell grammar, see +the section SIMPLE COMMANDS & PIPELINES in \fIzshmisc\fP(1)\&. +If \fBDEBUG_BEFORE_CMD\fP is set various additional features are available\&. +First, it is possible to skip the next command by setting the option +\fBERR_EXIT\fP; see the description of the \fBERR_EXIT\fP option in +\fIzshoptions\fP(1)\&. Also, the shell parameter +\fBZSH_DEBUG_CMD\fP is set to the string corresponding to the command +to be executed following the trap\&. Note that this string is reconstructed +from the internal format and may not be formatted the same way as the +original text\&. The parameter is unset after the trap is executed\&. +.PP +If \fIsig\fP is \fB0\fP or \fBEXIT\fP +and the \fBtrap\fP statement is executed inside the body of a function, +then the command \fIarg\fP is executed after the function completes\&. +The value of \fB$?\fP at the start of execution is the exit status of the +shell or the return status of the function exiting\&. +If \fIsig\fP is \fB0\fP or \fBEXIT\fP +and the \fBtrap\fP statement is not executed inside the body of a function, +then the command \fIarg\fP is executed when the shell terminates; the +trap runs before any \fBzshexit\fP hook functions\&. +.PP +\fBZERR\fP, \fBDEBUG\fP, and \fBEXIT\fP traps are not executed inside other +traps\&. \fBZERR\fP and \fBDEBUG\fP traps are kept within subshells, while +other traps are reset\&. +.PP +Note that traps defined with the \fBtrap\fP builtin are slightly different +from those defined as `\fBTRAP\fP\fINAL\fP () { \&.\&.\&. }\&', as the latter have +their own function environment (line numbers, local variables, etc\&.) while +the former use the environment of the command in which they were called\&. +For example, +.PP +.RS +.nf +\fBtrap \&'print $LINENO' DEBUG\fP +.fi +.RE +.PP +will print the line number of a command executed after it has run, while +.PP +.RS +.nf +\fBTRAPDEBUG() { print $LINENO; }\fP +.fi +.RE +.PP +will always print the number zero\&. +.PP +Alternative signal names are allowed as described under \fBkill\fP above\&. +Defining a trap under either name causes any trap under an alternative +name to be removed\&. However, it is recommended that for consistency +users stick exclusively to one name or another\&. +.RE +.TP +\fBtrue\fP [ \fIarg\fP \&.\&.\&. ] +Do nothing and return an exit status of 0\&. +.TP +\fBttyctl\fP [ \fB\-fu\fP ] +The \fB\-f\fP option freezes the tty (i\&.e\&. terminal or terminal emulator), and +\fB\-u\fP unfreezes it\&. +When the tty is frozen, no changes made to the tty settings by +external programs will be honored by the shell, except for changes in the +size of the screen; the shell will +simply reset the settings to their previous values as soon as each +command exits or is suspended\&. Thus, \fBstty\fP and similar programs have +no effect when the tty is frozen\&. Freezing the tty does not cause +the current state to be remembered: instead, it causes future changes +to the state to be blocked\&. +.RS +.PP +Without options it reports whether the terminal is frozen or not\&. +.PP +Note that, regardless of whether the tty is frozen or not, the +shell needs to change the settings when the line editor starts, so +unfreezing the tty does not guarantee settings made on the +command line are preserved\&. Strings of commands run between +editing the command line will see a consistent tty state\&. +See also the shell variable \fBSTTY\fP for a means of initialising +the tty before running external commands and/or freezing the tty +around a single command\&. +.RE +.TP +\fBtype\fP [ \fB\-wfpamsS\fP ] \fIname\fP \&.\&.\&. +Equivalent to \fBwhence \-v\fP\&. + +.TP +.PD 0 +\fBtypeset \fP[ {\fB+\fP|\fB\-\fP}\fBAHUaghlmrtux\fP ] [ {\fB+\fP|\fB\-\fP}\fBEFLRZip\fP [ \fIn\fP ] ] +.TP +.PD 0 +\fB \fP[ \fB+\fP ] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ] +.TP +.PD 0 +\fBtypeset \fP\fB\-T\fP [ {\fB+\fP|\fB\-\fP}\fBUglrux\fP ] [ {\fB+\fP|\fB\-\fP}\fBLRZp\fP [ \fIn\fP ] ] +.TP +.PD 0 +\fB \fP[ \fB+\fP | \fISCALAR\fP[\fB=\fP\fIvalue\fP] \fIarray\fP[\fB=(\fP\fIvalue\fP \&.\&.\&.\fB)\fP] [ \fIsep\fP ] ] +.TP +.PD +\fBtypeset\fP \fB\-f\fP [ {\fB+\fP|\fB\-\fP}\fBTUkmtuz\fP ] [ \fB+\fP ] [ \fIname\fP \&.\&.\&. ] +Set or display attributes and values for shell parameters\&. +.RS +.PP +Except as noted below for control flags that change the behavior, +a parameter is created for each \fIname\fP that does not already refer +to one\&. When inside a function, a new parameter is created for every +\fIname\fP (even those that already exist), and is unset again when the +function completes\&. See +`Local Parameters\&' in \fIzshparam\fP(1)\&. The same rules apply to special shell parameters, which +retain their special attributes when made local\&. +.PP +For each \fIname\fP\fB=\fP\fIvalue\fP assignment, the parameter +\fIname\fP is set to \fIvalue\fP\&. If the assignment is omitted and \fIname\fP +does \fInot\fP refer to an existing parameter, a new parameter is intialized +to empty string, zero, or empty array (as appropriate), \fIunless\fP the +shell option \fBTYPESET_TO_UNSET\fP is set\&. When that option is set, +the parameter attributes are recorded but the parameter remains unset\&. +.PP +If the shell option \fBTYPESET_SILENT\fP is not set, for each remaining +\fIname\fP that refers to a parameter that is already set, the name and +value of the parameter are printed in the form of an assignment\&. +Nothing is printed for newly\-created parameters, or when any attribute +flags listed below are given along with the \fIname\fP\&. Using +`\fB+\fP\&' instead of minus to introduce an attribute turns it off\&. +.PP +If no \fIname\fP is present, the names and values of all parameters are +printed\&. In this case the attribute flags restrict the display to only +those parameters that have the specified attributes, and using `\fB+\fP\&' +rather than `\fB\-\fP\&' to introduce the flag suppresses printing of the values +of parameters when there is no parameter name\&. +.PP +All forms of the command handle scalar assignment\&. Array assignment is +possible if any of the reserved words \fBdeclare\fP, \fBexport\fP, \fBfloat\fP, +\fBinteger\fP, \fBlocal\fP, \fBreadonly\fP or \fBtypeset\fP is matched when the +line is parsed (N\&.B\&. not when it is executed)\&. In this case the arguments +are parsed as assignments, except that the `\fB+=\fP\&' syntax and the +\fBGLOB_ASSIGN\fP option are not supported, and scalar values after \fB=\fP +are \fInot\fP split further into words, even if expanded (regardless of the +setting of the \fBKSH_TYPESET\fP option; this option is obsolete)\&. +.PP +Examples of the differences between command and reserved word parsing: +.PP +.RS +.nf +\fB# Reserved word parsing +typeset svar=$(echo one word) avar=(several words)\fP +.fi +.RE +.PP +The above creates a scalar parameter \fBsvar\fP and an array +parameter \fBavar\fP as if the assignments had been +.PP +.RS +.nf +\fBsvar="one word" +avar=(several words)\fP +.fi +.RE +.PP +On the other hand: +.PP +.RS +.nf +\fB# Normal builtin interface +builtin typeset svar=$(echo two words)\fP +.fi +.RE +.PP +The \fBbuiltin\fP keyword causes the above to use the standard builtin +interface to \fBtypeset\fP in which argument parsing is performed in the same +way as for other commands\&. This example creates a scalar \fBsvar\fP +containing the value \fBtwo\fP and another scalar parameter \fBwords\fP with +no value\&. An array value in this case would either cause an error or be +treated as an obscure set of glob qualifiers\&. +.PP +Arbitrary arguments are allowed if they take the form of assignments +after command line expansion; however, these only perform scalar +assignment: +.PP +.RS +.nf +\fBvar=\&'svar=val' +typeset $var\fP +.fi +.RE +.PP +The above sets the scalar parameter \fBsvar\fP to the value \fBval\fP\&. +Parentheses around the value within \fBvar\fP would not cause array +assignment as they will be treated as ordinary characters when \fB$var\fP +is substituted\&. Any non\-trivial expansion in the name part of the +assignment causes the argument to be treated in this fashion: +.PP +.RS +.nf +\fBtypeset {var1,var2,var3}=name\fP +.fi +.RE +.PP +The above syntax is valid, and has the expected effect of setting the +three parameters to the same value, but the command line is parsed as +a set of three normal command line arguments to \fBtypeset\fP after +expansion\&. Hence it is not possible to assign to multiple arrays by +this means\&. +.PP +Note that each interface to any of the commands may be disabled +separately\&. For example, `\fBdisable \-r typeset\fP\&' disables the reserved +word interface to \fBtypeset\fP, exposing the builtin interface, while +`\fBdisable typeset\fP\&' disables the builtin\&. Note that disabling the +reserved word interface for \fBtypeset\fP may cause problems with the +output of `\fBtypeset \-p\fP\&', which assumes the reserved word interface is +available in order to restore array and associative array values\&. +.PP +Unlike parameter assignment statements, \fBtypeset\fP\&'s exit status on an +assignment that involves a command substitution does not reflect the exit +status of the command substitution\&. Therefore, to test for an error in +a command substitution, separate the declaration of the parameter from its +initialization: +.PP +.RS +.nf +\fB# WRONG +typeset var1=$(exit 1) || echo "Trouble with var1" + +# RIGHT +typeset var1 && var1=$(exit 1) || echo "Trouble with var1" +\fP +.fi +.RE +.PP +To initialize a parameter \fIparam\fP to a command output and mark it readonly, +use \fBtypeset \-r \fP\fIparam\fP or \fBreadonly \fP\fIparam\fP after the parameter +assignment statement\&. +.PP +If no attribute flags are given, and either no \fIname\fP arguments are +present or the flag \fB+m\fP is used, then each parameter name printed is +preceded by a list of the attributes of that parameter (\fBarray\fP, +\fBassociation\fP, \fBexported\fP, \fBfloat\fP, \fBinteger\fP, \fBreadonly\fP, +or \fBundefined\fP for autoloaded parameters not yet loaded)\&. If \fB+m\fP is +used with attribute flags, and all those flags are introduced with +\fB+\fP, the matching parameter names are printed but their values +are not\&. +.PP +The following control flags change the behavior of \fBtypeset\fP: +.PP +.PD 0 +.TP +.PD +\fB+\fP +If `\fB+\fP\&' appears by itself in a separate word as the last option, +then the names of all parameters (functions with \fB\-f\fP) are printed, but +the values (function bodies) are not\&. No \fIname\fP arguments may appear, +and it is an error for any other options to follow `\fB+\fP\&'\&. The +effect of `\fB+\fP\&' is as if all attribute flags which precede it were +given with a `\fB+\fP\&' prefix\&. For example, `\fBtypeset \-U +\fP' is +equivalent to `\fBtypeset +U\fP\&' and displays the names of all arrays having +the uniqueness attribute, whereas `\fBtypeset \-f \-U +\fP\&' displays the +names of all autoloadable functions\&. If \fB+\fP is the only option, +then type information (array, readonly, etc\&.) is also printed for each +parameter, in the same manner as `\fBtypeset +m "*"\fP\&'\&. +.TP +\fB\-g\fP +The \fB\-g\fP (global) means that any resulting parameter will not be +restricted to local scope\&. Note that this does not necessarily mean that +the parameter will be global, as the flag will apply to any existing +parameter (even if unset) from an enclosing function\&. This flag does not +affect the parameter after creation, hence it has no effect when listing +existing parameters, nor does the flag \fB+g\fP have any effect except in +combination with \fB\-m\fP (see below)\&. +.TP +\fB\-m\fP +If the \fB\-m\fP flag is given the \fIname\fP arguments are taken as patterns +(use quoting to prevent these from being interpreted as file patterns)\&. +With no attribute flags, all parameters (or functions with the \fB\-f\fP +flag) with matching names are printed (the shell option \fBTYPESET_SILENT\fP +is not used in this case)\&. +.RS +.PP +If the \fB+g\fP flag is combined with \fB\-m\fP, a new local parameter is +created for every matching parameter that is not already local\&. Otherwise +\fB\-m\fP applies all other flags or assignments to the existing parameters\&. +.PP +Except when assignments are made with \fIname\fP\fB=\fP\fIvalue\fP, using +\fB+m\fP forces the matching parameters and their attributes to be printed, +even inside a function\&. Note that \fB\-m\fP is ignored if no patterns are +given, so `\fBtypeset \-m\fP\&' displays attributes but `\fBtypeset \-a +m\fP' +does not\&. +.RE +.TP +\fB\-p\fP [ \fIn\fP ] +If the \fB\-p\fP option is given, parameters and values are printed in the +form of a typeset command with an assignment, regardless of other flags +and options\&. Note that the \fB\-H\fP flag on parameters is respected; no +value will be shown for these parameters\&. +.RS +.PP +\fB\-p\fP may be followed by an optional integer argument\&. Currently +only the value \fB1\fP is supported\&. In this case arrays and associative +arrays are printed with newlines between indented elements for +readability\&. +.RE +.TP +\fB\-T\fP [ \fIscalar\fP[\fB=\fP\fIvalue\fP] \fIarray\fP[\fB=(\fP\fIvalue\fP \&.\&.\&.\fB)\fP] [ \fIsep\fP ] ] +This flag has a different meaning when used with \fB\-f\fP; see below\&. +Otherwise the \fB\-T\fP option requires zero, two, or three arguments to be +present\&. With no arguments, the list of parameters created in this +fashion is shown\&. With two or three arguments, the first two are the name +of a scalar and of an array parameter (in that order) that will be tied +together in the manner of \fB$PATH\fP and \fB$path\fP\&. The optional third +argument is a single\-character separator which will be used to join the +elements of the array to form the scalar; if absent, a colon is used, as +with \fB$PATH\fP\&. Only the first character of the separator is significant; +any remaining characters are ignored\&. Multibyte characters are not +yet supported\&. +.RS +.PP +Only one of the scalar and array parameters may be assigned an initial +value (the restrictions on assignment forms described above also apply)\&. +.PP +Both the scalar and the array may be manipulated as normal\&. If one is +unset, the other will automatically be unset too\&. There is no way of +untying the variables without unsetting them, nor of converting the type +of one of them with another \fBtypeset\fP command; \fB+T\fP does not work, +assigning an array to \fIscalar\fP is an error, and assigning a scalar to +\fIarray\fP sets it to be a single\-element array\&. +.PP +Note that both `\fBtypeset \-xT \&.\&.\&.\fP\&' and `\fBexport \-T \&.\&.\&.\fP' work, but +only the scalar will be marked for export\&. Setting the value using the +scalar version causes a split on all separators (which cannot be quoted)\&. +It is possible to apply \fB\-T\fP to two previously tied variables but with a +different separator character, in which case the variables remain joined +as before but the separator is changed\&. +.PP +When an existing scalar is tied to a new array, the value of the scalar +is preserved but no attribute other than export will be preserved\&. +.RE +.PP +Attribute flags that transform the final value (\fB\-L\fP, \fB\-R\fP, \fB\-Z\fP, +\fB\-l\fP, \fB\-u\fP) are only applied to the expanded value at the point +of a parameter expansion expression using `\fB$\fP\&'\&. They are not applied +when a parameter is retrieved internally by the shell for any purpose\&. +.PP +The following attribute flags may be specified: +.PP +.PD 0 +.TP +.PD +\fB\-A\fP +The names refer to associative array parameters; see +`Array Parameters\&' in \fIzshparam\fP(1)\&. +.TP +\fB\-L\fP [ \fIn\fP ] +Left justify and remove leading blanks from the value when the parameter +is expanded\&. +If \fIn\fP is nonzero, it defines the width of the field\&. +If \fIn\fP is zero, the width is determined by the width of the value of +the first assignment\&. In the case of numeric parameters, the length of the +complete value assigned to the parameter is used to determine the width, +not the value that would be output\&. +.RS +.PP +The width is the count of characters, which may be multibyte characters +if the \fBMULTIBYTE\fP option is in effect\&. Note that the screen +width of the character is not taken into account; if this is required, +use padding with parameter expansion flags +\fB${(ml\fP\fI\&.\&.\&.\fP\fB)\fP\fI\&.\&.\&.\fP\fB}\fP as described in +`Parameter Expansion Flags\&' in +\fIzshexpn\fP(1)\&. +.PP +When the parameter is expanded, it is filled on the right with +blanks or truncated if necessary to fit the field\&. +Note truncation can lead to unexpected results with numeric parameters\&. +Leading zeros are removed if the \fB\-Z\fP flag is also set\&. +.RE +.TP +\fB\-R\fP [ \fIn\fP ] +Similar to \fB\-L\fP, except that right justification is used; +when the parameter is expanded, the field is left filled with +blanks or truncated from the end\&. May not be combined with the \fB\-Z\fP +flag\&. +.TP +\fB\-U\fP +For arrays (but not for associative arrays), keep only the first +occurrence of each duplicated value\&. This may also be set for tied +parameters (see \fB\-T\fP) or colon\-separated special parameters like +\fBPATH\fP or \fBFIGNORE\fP, etc\&. Note the flag takes effect on assignment, +and the type of the variable being assigned to is determinative; for +variables with shared values it is therefore recommended to set the flag +for all interfaces, e\&.g\&. `\fBtypeset \-U PATH path\fP\&'\&. +.RS +.PP +This flag has a different meaning when used with \fB\-f\fP; see below\&. +.RE +.TP +\fB\-Z\fP [ \fIn\fP ] +Specially handled if set along with the \fB\-L\fP flag\&. +Otherwise, similar to \fB\-R\fP, except that leading zeros are used for +padding instead of blanks if the first non\-blank character is a digit\&. +Numeric parameters are specially handled: they are always eligible +for padding with zeroes, and the zeroes are inserted at an appropriate +place in the output\&. +.TP +\fB\-a\fP +The names refer to array parameters\&. An array parameter may be +created this way, but it may be assigned to in the \fBtypeset\fP +statement only if the reserved word form of \fBtypeset\fP is enabled +(as it is by default)\&. When displaying, both normal and associative +arrays are shown\&. +.TP +\fB\-f\fP +The names refer to functions rather than parameters\&. No assignments +can be made, and the only other valid flags are \fB\-t\fP, \fB\-T\fP, \fB\-k\fP, +\fB\-u\fP, \fB\-U\fP and \fB\-z\fP\&. The flag \fB\-t\fP turns on execution tracing +for this function; the flag \fB\-T\fP does the same, but turns off tracing +for any named (not anonymous) function called from the present one, +unless that function also +has the \fB\-t\fP or \fB\-T\fP flag\&. The \fB\-u\fP and \fB\-U\fP flags cause the +function to be marked for autoloading; \fB\-U\fP also causes alias +expansion to be suppressed when the function is loaded\&. See the +description of the `\fBautoload\fP\&' builtin for details\&. +.RS +.PP +Note that the builtin \fBfunctions\fP provides the same basic capabilities +as \fBtypeset \-f\fP but gives access to a few extra options; \fBautoload\fP +gives further additional options for the case \fBtypeset \-fu\fP and +\fBtypeset \-fU\fP\&. +.RE +.TP +\fB\-h\fP +Hide: only useful for special parameters (those marked `<S>\&' in the table in +\fIzshparam\fP(1)), and for local parameters with the same name as a special parameter, +though harmless for others\&. A special parameter with this attribute will +not retain its special effect when made local\&. Thus after `\fBtypeset \-h +PATH\fP\&', a function containing `\fBtypeset PATH\fP' will create an ordinary +local parameter without the usual behaviour of \fBPATH\fP\&. Alternatively, +the local parameter may itself be given this attribute; hence inside a +function `\fBtypeset \-h PATH\fP\&' creates an ordinary local parameter and the +special \fBPATH\fP parameter is not altered in any way\&. It is also possible +to create a local parameter using `\fBtypeset +h \fP\fIspecial\fP\&', where the +local copy of \fIspecial\fP will retain its special properties regardless of +having the \fB\-h\fP attribute\&. Global special parameters loaded from shell +modules (currently those in \fBzsh/mapfile\fP and \fBzsh/parameter\fP) are +automatically given the \fB\-h\fP attribute to avoid name clashes\&. +.TP +\fB\-H\fP +Hide value: specifies that \fBtypeset\fP will not display the value of the +parameter when listing parameters; the display for such parameters is +always as if the `\fB+\fP\&' flag had been given\&. Use of the parameter is +in other respects normal, and the option does not apply if the parameter is +specified by name, or by pattern with the \fB\-m\fP option\&. This is on by +default for the parameters in the \fBzsh/parameter\fP and \fBzsh/mapfile\fP +modules\&. Note, however, that unlike the \fB\-h\fP flag this is also useful +for non\-special parameters\&. +.TP +\fB\-i\fP [ \fIn\fP ] +Use an internal integer representation\&. If \fIn\fP is nonzero it +defines the output arithmetic base, otherwise it is determined by the +first assignment\&. Bases from 2 to 36 inclusive are allowed\&. +.TP +\fB\-E\fP [ \fIn\fP ] +Use an internal double\-precision floating point representation\&. On output +the variable will be converted to scientific notation\&. If \fIn\fP is +nonzero it defines the number of significant figures to display; the +default is ten\&. +.TP +\fB\-F\fP [ \fIn\fP ] +Use an internal double\-precision floating point representation\&. On output +the variable will be converted to fixed\-point decimal notation\&. If \fIn\fP +is nonzero it defines the number of digits to display after the decimal +point; the default is ten\&. +.TP +\fB\-l\fP +Convert the result to lower case whenever the parameter is expanded\&. +The value is \fInot\fP converted when assigned\&. +.TP +\fB\-r\fP +The given \fIname\fPs are marked readonly\&. Note that if \fIname\fP is a +special parameter, the readonly attribute can be turned on, but cannot then +be turned off\&. +.RS +.PP +If the \fBPOSIX_BUILTINS\fP option is set, the readonly attribute is +more restrictive: unset variables can be marked readonly and cannot then +be set; furthermore, the readonly attribute cannot be removed from any +variable\&. +.PP +It is still possible to change other attributes of the variable though, +some of which like \fB\-U\fP or \fB\-Z\fP would affect the value\&. More generally, +the readonly attribute should not be relied on as a security mechanism\&. +.PP +Note that in zsh (like in pdksh but unlike most other shells) it is +still possible to create a local variable of the same name as this is +considered a different variable (though this variable, too, can be marked +readonly)\&. Special variables that have been made readonly retain their value +and readonly attribute when made local\&. +.RE +.TP +\fB\-t\fP +Tags the named parameters\&. Tags have no special meaning to the shell\&. +This flag has a different meaning when used with \fB\-f\fP; see above\&. +.TP +\fB\-u\fP +Convert the result to upper case whenever the parameter is expanded\&. +The value is \fInot\fP converted when assigned\&. +This flag has a different meaning when used with \fB\-f\fP; see above\&. +.TP +\fB\-x\fP +Mark for automatic export to the environment of subsequently +executed commands\&. If the option \fBGLOBAL_EXPORT\fP is set, this implies +the option \fB\-g\fP, unless \fB+g\fP is also explicitly given; in other words +the parameter is not made local to the enclosing function\&. This is for +compatibility with previous versions of zsh\&. +.RE +.TP +\fBulimit\fP [ \fB\-HSa\fP ] [ { \fB\-bcdfiklmnpqrsTtvwx\fP | \fB\-N\fP \fIresource\fP } [ \fIlimit\fP ] \&.\&.\&. ] +Set or display resource limits of the shell and the processes started by +the shell\&. The value of \fIlimit\fP can be a number in the unit specified +below or one of the values `\fBunlimited\fP\&', which removes the limit on the +resource, or `\fBhard\fP\&', which uses the current value of the hard limit on +the resource\&. +.RS +.PP +By default, only soft limits are manipulated\&. If the \fB\-H\fP flag +is given use hard limits instead of soft limits\&. If the \fB\-S\fP flag is given +together with the \fB\-H\fP flag set both hard and soft limits\&. +.PP +If no options are used, the file size limit (\fB\-f\fP) is assumed\&. +.PP +If \fIlimit\fP is omitted the current value of the specified resources are +printed\&. When more than one resource value is printed, the limit name and +unit is printed before each value\&. +.PP +When looping over multiple resources, the shell will abort immediately if +it detects a badly formed argument\&. However, if it fails to set a limit +for some other reason it will continue trying to set the remaining limits\&. +.PP +Not all the following resources are supported on all systems\&. Running +\fBulimit \-a\fP will show which are supported\&. +.PP +.PD 0 +.TP +\fB\-a\fP +Lists all of the current resource limits\&. +.TP +\fB\-b\fP +Socket buffer size in bytes (N\&.B\&. not kilobytes) +.TP +\fB\-c\fP +512\-byte blocks on the size of core dumps\&. +.TP +\fB\-d\fP +Kilobytes on the size of the data segment\&. +.TP +\fB\-f\fP +512\-byte blocks on the size of files written\&. +.TP +\fB\-i\fP +The number of pending signals\&. +.TP +\fB\-k\fP +The number of kqueues allocated\&. +.TP +\fB\-l\fP +Kilobytes on the size of locked\-in memory\&. +.TP +\fB\-m\fP +Kilobytes on the size of physical memory\&. +.TP +\fB\-n\fP +open file descriptors\&. +.TP +\fB\-p\fP +The number of pseudo\-terminals\&. +.TP +\fB\-q\fP +Bytes in POSIX message queues\&. +.TP +\fB\-r\fP +Maximum real time priority\&. On some systems where this +is not available, such as NetBSD, this has the same effect as \fB\-T\fP +for compatibility with \fBsh\fP\&. +.TP +\fB\-s\fP +Kilobytes on the size of the stack\&. +.TP +\fB\-T\fP +The number of simultaneous threads available to the user\&. +.TP +\fB\-t\fP +CPU seconds to be used\&. +.TP +\fB\-u\fP +The number of processes available to the user\&. +.TP +\fB\-v\fP +Kilobytes on the size of virtual memory\&. On some systems this +refers to the limit called `address space\&'\&. +.TP +\fB\-w\fP +Kilobytes on the size of swapped out memory\&. +.TP +\fB\-x\fP +The number of locks on files\&. +.PD +.PP +A resource may also be specified by integer in the form `\fB\-N\fP +\fIresource\fP\&', where \fIresource\fP corresponds to the integer defined for +the resource by the operating system\&. This may be used to set the limits +for resources known to the shell which do not correspond to option letters\&. +Such limits will be shown by number in the output of `\fBulimit \-a\fP\&'\&. +.PP +The number may alternatively be out of the range of limits compiled into +the shell\&. The shell will try to read or write the limit anyway, and +will report an error if this fails\&. +.RE +.TP +\fBumask\fP [ \fB\-S\fP ] [ \fImask\fP ] +The umask is set to \fImask\fP\&. \fImask\fP can be either +an octal number or a symbolic value as described in the \fIchmod\fP(1) man page\&. +If \fImask\fP is omitted, the current value is printed\&. The \fB\-S\fP +option causes the mask to be printed as a symbolic value\&. Otherwise, +the mask is printed as an octal number\&. Note that in +the symbolic form the permissions you specify are those which are to be +allowed (not denied) to the users specified\&. +.TP +\fBunalias\fP [ \fB\-ams\fP ] \fIname\fP \&.\&.\&. +Removes aliases\&. This command works the same as \fBunhash \-a\fP, except that +the \fB\-a\fP option removes all regular or global aliases, or with \fB\-s\fP +all suffix aliases: in this case no \fIname\fP arguments may appear\&. The +options \fB\-m\fP (remove by pattern) and \fB\-s\fP without \fB\-a\fP (remove +listed suffix aliases) behave as for \fBunhash \-a\fP\&. Note that +the meaning of \fB\-a\fP is different between \fBunalias\fP and \fBunhash\fP\&. +.TP +\fBunfunction\fP +Same as \fBunhash \-f\fP\&. +.TP +\fBunhash\fP [ \fB\-adfms\fP ] \fIname\fP \&.\&.\&. +Remove the element named \fIname\fP from an internal hash table\&. The +default is remove elements from the command hash table\&. The \fB\-a\fP +option causes \fBunhash\fP to remove regular or global aliases; note +when removing a global aliases that the argument must be quoted to prevent +it from being expanded before being passed to the command\&. +The \fB\-s\fP option causes \fBunhash\fP to remove suffix aliases\&. +The \fB\-f\fP option causes +\fBunhash\fP to remove shell functions\&. The \fB\-d\fP options causes +\fBunhash\fP to remove named directories\&. If the \fB\-m\fP flag is given +the arguments are taken as patterns (should be quoted) and all elements +of the corresponding hash table with matching names will be removed\&. +.TP +\fBunlimit\fP [ \fB\-hs\fP ] \fIresource\fP \&.\&.\&. +The resource limit for each \fIresource\fP is set to the hard limit\&. +If the \fB\-h\fP flag is given and the shell has appropriate privileges, +the hard resource limit for each \fIresource\fP is removed\&. +The resources of the shell process are only changed if the \fB\-s\fP +flag is given\&. +.RS +.PP +The \fBunlimit\fP command is not made available by default when the +shell starts in a mode emulating another shell\&. It can be made available +with the command `\fBzmodload \-F zsh/rlimits b:unlimit\fP\&'\&. +.RE +.TP +\fBunset\fP [ \fB\-fmv\fP ] \fIname\fP \&.\&.\&. +Each named parameter is unset\&. +Local parameters remain local even if unset; they appear unset within scope, +but the previous value will still reappear when the scope ends\&. +.RS +.PP +Individual elements of associative array parameters may be unset by using +subscript syntax on \fIname\fP, which should be quoted (or the entire command +prefixed with \fBnoglob\fP) to protect the subscript from filename generation\&. +.PP +If the \fB\-m\fP flag is specified the arguments are taken as patterns (should +be quoted) and all parameters with matching names are unset\&. Note that this +cannot be used when unsetting associative array elements, as the subscript +will be treated as part of the pattern\&. +.PP +The \fB\-v\fP flag specifies that \fIname\fP refers to parameters\&. This is the +default behaviour\&. +.PP +\fBunset \-f\fP is equivalent to \fBunfunction\fP\&. +.RE +.TP +\fBunsetopt\fP [ {\fB+\fP|\fB\-\fP}\fIoptions\fP | {\fB+\fP|\fB\-\fP}\fBo\fP \fIoption_name\fP ] [ \fIname\fP \&.\&.\&. ] +Unset the options for the shell\&. All options specified either +with flags or by name are unset\&. If no arguments are supplied, +the names of all options currently unset are printed\&. +If the \fB\-m\fP flag is given the arguments are taken as patterns +(which should be quoted to preserve them from being interpreted as glob +patterns), and all options with names matching these patterns are unset\&. +.TP +\fBvared\fP +See the section `Zle Builtins\&' in \fIzshzle\fP(1)\&. +.TP +\fBwait\fP [ \fIjob\fP \&.\&.\&. ] +Wait for the specified jobs or processes\&. If \fIjob\fP is not given +then all currently active child processes are waited for\&. +Each \fIjob\fP can be either a job specification or the process ID +of a job in the job table\&. +The exit status from this command is that of the job waited for\&. +If \fIjob\fP represents an unknown job or process ID, a warning is printed +(unless the \fBPOSIX_BUILTINS\fP option is set) and the exit status is 127\&. +.RS +.PP +It is possible to wait for recent processes (specified by process ID, +not by job) that were running in the background even if the process has +exited\&. Typically the process ID will be recorded by capturing the +value of the variable \fB$!\fP immediately after the process has been +started\&. There is a limit on the number of process IDs remembered by +the shell; this is given by the value of the system configuration +parameter \fBCHILD_MAX\fP\&. When this limit is reached, older process IDs +are discarded, least recently started processes first\&. +.PP +Note there is no protection against the process ID wrapping, i\&.e\&. if the +wait is not executed soon enough there is a chance the process waited +for is the wrong one\&. A conflict implies both process IDs have been +generated by the shell, as other processes are not recorded, and that +the user is potentially interested in both, so this problem is intrinsic +to process IDs\&. +.RE +.TP +\fBwhence\fP [ \fB\-vcwfpamsS\fP ] [ \fB\-x\fP \fInum\fP ] \fIname\fP \&.\&.\&. +For each \fIname\fP, indicate how it would be interpreted if used as a +command name\&. +.RS +.PP +If \fIname\fP is not an alias, built\-in command, external command, shell +function, hashed command, or a reserved word, the exit status shall be +non\-zero, and \-\- if \fB\-v\fP, \fB\-c\fP, or \fB\-w\fP was passed \-\- a message +will be written to standard output\&. (This is different from other shells that +write that message to standard error\&.) +.PP +\fBwhence\fP is most useful when \fIname\fP is only the last path component +of a command, i\&.e\&. does not include a `\fB/\fP\&'; in particular, pattern +matching only succeeds if just the non\-directory component of the command is +passed\&. +.PP +.PD 0 +.TP +.PD +\fB\-v\fP +Produce a more verbose report\&. +.TP +\fB\-c\fP +Print the results in a \fBcsh\fP\-like format\&. +This takes precedence over \fB\-v\fP\&. +.TP +\fB\-w\fP +For each \fIname\fP, print `\fIname\fP\fB:\fP \fIword\fP\&' where \fIword\fP +is one of \fBalias\fP, \fBbuiltin\fP, \fBcommand\fP, \fBfunction\fP, +\fBhashed\fP, \fBreserved\fP or \fBnone\fP, according as \fIname\fP +corresponds to an alias, a built\-in command, an external command, a +shell function, a command defined with the \fBhash\fP builtin, a +reserved word, or is not recognised\&. This takes precedence over +\fB\-v\fP and \fB\-c\fP\&. +.TP +\fB\-f\fP +Causes the contents of a shell function to be +displayed, which would otherwise not happen unless the \fB\-c\fP +flag were used\&. +.TP +\fB\-p\fP +Do a path search for \fIname\fP +even if it is an alias, reserved word, shell function or builtin\&. +.TP +\fB\-a\fP +Do a search for all occurrences of \fIname\fP +throughout the command path\&. +Normally only the first occurrence is printed\&. +.TP +\fB\-m\fP +The arguments are taken as patterns (pattern characters should be +quoted), and the information is displayed for each command matching one +of these patterns\&. +.TP +\fB\-s\fP +If a pathname contains symlinks, print the symlink\-free pathname as well\&. +.TP +\fB\-S\fP +As \fB\-s\fP, but if the pathname had to be resolved by following +multiple symlinks, the intermediate steps are printed, too\&. The +symlink resolved at each step might be anywhere in the path\&. +.TP +\fB\-x\fP \fInum\fP +Expand tabs when outputting shell functions using the \fB\-c\fP option\&. +This has the same effect as the \fB\-x\fP option to the \fBfunctions\fP +builtin\&. +.RE +.TP +\fBwhere\fP [ \fB\-wpmsS\fP ] [ \fB\-x\fP \fInum\fP ] \fIname\fP \&.\&.\&. +Equivalent to \fBwhence \-ca\fP\&. +.TP +\fBwhich\fP [ \fB\-wpamsS\fP ] [ \fB\-x\fP \fInum\fP ] \fIname\fP \&.\&.\&. +Equivalent to \fBwhence \-c\fP\&. +.TP +.PD 0 +\fBzcompile\fP [ \fB\-U\fP ] [ \fB\-z\fP | \fB\-k\fP ] [ \fB\-R\fP | \fB\-M\fP ] \fIfile\fP [ \fIname\fP \&.\&.\&. ] +.TP +.PD 0 +\fBzcompile\fP \fB\-ca\fP [ \fB\-m\fP ] [ \fB\-R\fP | \fB\-M\fP ] \fIfile\fP [ \fIname\fP \&.\&.\&. ] +.TP +.PD +\fBzcompile \-t\fP \fIfile\fP [ \fIname\fP \&.\&.\&. ] +This builtin command can be used to compile functions or scripts, +storing the compiled form in a file, and to examine files containing +the compiled form\&. This allows faster autoloading of functions and +sourcing of scripts by avoiding parsing of the text when the files +are read\&. +.RS +.PP +The first form (without the \fB\-c\fP, \fB\-a\fP or \fB\-t\fP options) creates a +compiled file\&. If only the \fIfile\fP argument is given, the +output file has the name `\fIfile\fP\fB\&.zwc\fP\&' and will be placed in +the same directory as the \fIfile\fP\&. The shell will load the compiled +file instead of the normal function file when the function +is autoloaded; see +the section `Autoloading Functions\&' in \fIzshmisc\fP(1) +for a description of how autoloaded functions are searched\&. The +extension \fB\&.zwc\fP stands for `zsh word code\&'\&. +.PP +If there is at least one \fIname\fP argument, all the named files +are compiled into the output \fIfile\fP given as the first argument\&. If +\fIfile\fP does not end in \fB\&.zwc\fP, this extension is automatically +appended\&. Files containing multiple compiled functions are called `digest\&' +files, and are intended to be used as elements of the \fBFPATH\fP/\fBfpath\fP +special array\&. +.PP +The second form, with the \fB\-c\fP or \fB\-a\fP options, writes the compiled +definitions for all the named functions into \fIfile\fP\&. For \fB\-c\fP, the +names must be functions currently defined in the shell, not those marked +for autoloading\&. Undefined functions that are marked for autoloading +may be written by using the \fB\-a\fP option, in which case the \fBfpath\fP +is searched and the contents of the definition files for those +functions, if found, are compiled into \fIfile\fP\&. If both \fB\-c\fP and +\fB\-a\fP are given, names of both defined functions and functions marked +for autoloading may be given\&. In either case, the functions in files +written with the \fB\-c\fP or \fB\-a\fP option will be autoloaded as if the +\fBKSH_AUTOLOAD\fP option were unset\&. +.PP +The reason for handling loaded and not\-yet\-loaded functions with +different options is that some definition files for autoloading define +multiple functions, including the function with the same name as the +file, and, at the end, call that function\&. In such cases the output of +`\fBzcompile \-c\fP\&' does not include the additional functions defined in +the file, and any other initialization code in the file is lost\&. Using +`\fBzcompile \-a\fP\&' captures all this extra information\&. +.PP +If the \fB\-m\fP option is combined with \fB\-c\fP or \fB\-a\fP, +the \fIname\fPs are used as patterns and all functions whose names +match one of these patterns will be written\&. If no \fIname\fP is given, +the definitions of all functions currently defined or marked as +autoloaded will be written\&. +.PP +Note the second form cannot be used for compiling functions that +include redirections as part of the definition rather than within +the body of the function; for example +.PP +.RS +.nf +\fBfn1() { { \&.\&.\&. } >~/logfile }\fP +.fi +.RE +.PP +can be compiled but +.PP +.RS +.nf +\fBfn1() { \&.\&.\&. } >~/logfile\fP +.fi +.RE +.PP +cannot\&. It is possible to use the first form of \fBzcompile\fP to compile +autoloadable functions that include the full function definition instead +of just the body of the function\&. +.PP +The third form, with the \fB\-t\fP option, examines an existing +compiled file\&. Without further arguments, the names of the original +files compiled into it are listed\&. The first line of output shows +the version of the shell which compiled the file and how the file +will be used (i\&.e\&. by reading it directly or by mapping it into memory)\&. +With arguments, nothing is output and the return status is set to zero if +definitions for \fIall\fP \fIname\fPs were found in the compiled +file, and non\-zero if the definition for at least one \fIname\fP was not +found\&. +.PP +Other options: +.PP +.PD 0 +.TP +.PD +\fB\-U\fP +Aliases are not expanded when compiling the \fIname\fPd files\&. +.TP +\fB\-R\fP +When the compiled file is read, its contents are copied into the +shell\&'s memory, rather than memory\-mapped (see \fB\-M\fP)\&. This +happens automatically on systems that do not support memory mapping\&. +.RS +.PP +When compiling scripts instead of autoloadable functions, it is +often desirable to use this option; otherwise the whole file, including the +code to define functions which have already been defined, will +remain mapped, consequently wasting memory\&. +.RE +.TP +\fB\-M\fP +The compiled file is mapped into the shell\&'s memory when read\&. This +is done in such a way that multiple instances of the shell running +on the same host will share this mapped file\&. If neither \fB\-R\fP nor +\fB\-M\fP is given, the \fBzcompile\fP builtin decides what to do based +on the size of the compiled file\&. +.TP +.PD 0 +\fB\-k\fP +.TP +.PD +\fB\-z\fP +These options are used when the compiled file contains functions which +are to be autoloaded\&. If \fB\-z\fP is given, the +function will be autoloaded as if the \fBKSH_AUTOLOAD\fP option is +\fInot\fP set, even if it is set at the time the compiled file is +read, while if the \fB\-k\fP is given, the function will be loaded as if +\fBKSH_AUTOLOAD\fP \fIis\fP set\&. These options also take precedence over +any \fB\-k\fP or \fB\-z\fP options specified to the \fBautoload\fP builtin\&. If +neither of these options is given, the function will be loaded as +determined by the setting of the \fBKSH_AUTOLOAD\fP option at the time +the compiled file is read\&. + +These options may also appear as many times as necessary between the listed +\fIname\fPs to specify the loading style of all following functions, up to +the next \fB\-k\fP or \fB\-z\fP\&. + +The created file always contains two versions of the compiled +format, one for big\-endian machines and one for small\-endian +machines\&. The upshot of this is that the compiled file is machine +independent and if it is read or mapped, only one half of the file +is actually used (and mapped)\&. +.RE +.TP +\fBzformat\fP +See the section `The zsh/zutil Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBzftp\fP +See the section `The zsh/zftp Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBzle\fP +See the section `Zle Builtins\&' in \fIzshzle\fP(1)\&. +.TP +.PD 0 +\fBzmodload\fP [ \fB\-dL\fP ] [ \fB\-s\fP ] [ \&.\&.\&. ] +.TP +.PD 0 +\fBzmodload \-F\fP [ \fB\-alLme\fP \fB\-P\fP \fIparam\fP ] \fImodule\fP [ [\fB+\-\fP]\fIfeature\fP \&.\&.\&. ] +.TP +.PD 0 +\fBzmodload \-e\fP [ \fB\-A\fP ] [ \&.\&.\&. ] +.TP +.PD 0 +\fBzmodload\fP [ \fB\-a\fP [ \fB\-bcpf\fP [ \fB\-I\fP ] ] ] [ \fB\-iL\fP ] \&.\&.\&. +.TP +.PD 0 +\fBzmodload\fP \fB\-u\fP [ \fB\-abcdpf\fP [ \fB\-I\fP ] ] [ \fB\-iL\fP ] \&.\&.\&. +.TP +.PD 0 +\fBzmodload\fP \fB\-A\fP [ \fB\-L\fP ] [ \fImodalias\fP[\fB=\fP\fImodule\fP] \&.\&.\&. ] +.TP +.PD +\fBzmodload\fP \fB\-R\fP \fImodalias\fP \&.\&.\&. +Performs operations relating to zsh\&'s loadable modules\&. +Loading of modules while the shell is running (`dynamical loading\&') is not +available on all operating systems, or on all installations on a particular +operating system, although the \fBzmodload\fP command itself is always +available and can be used to manipulate modules built into versions of the +shell executable without dynamical loading\&. +.RS +.PP +Without arguments the names of all currently loaded binary modules are +printed\&. The \fB\-L\fP option causes this list to be in the form of a +series of \fBzmodload\fP commands\&. Forms with arguments are: +.PP +.PD 0 +.TP +.PD 0 +\fBzmodload\fP [ \fB\-is\fP ] \fIname\fP \&.\&.\&. +.TP +.PD +\fBzmodload\fP \fB\-u\fP [ \fB\-i\fP ] \fIname\fP \&.\&.\&. +In the simplest case, \fBzmodload\fP loads a binary module\&. The module must +be in a file with a name consisting of the specified \fIname\fP followed by +a standard suffix, usually `\fB\&.so\fP\&' (`\fB\&.sl\fP' on HPUX)\&. +If the module to be loaded is already loaded the duplicate module is +ignored\&. If \fBzmodload\fP detects an inconsistency, such as an +invalid module name or circular dependency list, the current code block is +aborted\&. If it is available, the module is loaded if necessary, while if it +is not available, non\-zero status is silently returned\&. The option +\fB\-i\fP is accepted for compatibility but has no effect\&. +.RS +.PP +The \fIname\fPd module is searched for in the same way a command is, using +\fB$module_path\fP instead of \fB$path\fP\&. However, the path search is +performed even when the module name contains a `\fB/\fP\&', which it usually does\&. +There is no way to prevent the path search\&. +.PP +If the module supports features (see below), \fBzmodload\fP tries to +enable all features when loading a module\&. If the module was successfully +loaded but not all features could be enabled, \fBzmodload\fP returns status 2\&. +.PP +If the option \fB\-s\fP is given, no error is printed if the module was not +available (though other errors indicating a problem with the module are +printed)\&. The return status indicates if the module was loaded\&. This +is appropriate if the caller considers the module optional\&. +.PP +With \fB\-u\fP, \fBzmodload\fP unloads modules\&. The same \fIname\fP +must be given that was given when the module was loaded, but it is not +necessary for the module to exist in the file system\&. +The \fB\-i\fP option suppresses the error if the module is already +unloaded (or was never loaded)\&. +.PP +Each module has a boot and a cleanup function\&. The module +will not be loaded if its boot function fails\&. Similarly a module +can only be unloaded if its cleanup function runs successfully\&. +.RE +.TP +\fBzmodload \-F\fP [ \fB\-almLe\fP \fB\-P\fP \fIparam\fP ] \fImodule\fP [ [\fB+\-\fP]\fIfeature\fP \&.\&.\&. ] +\fBzmodload \-F\fP allows more selective control over the features provided +by modules\&. With no options apart from \fB\-F\fP, the module named +\fImodule\fP is loaded, if it was not already loaded, and the list of +\fIfeature\fPs is set to the required state\&. If no +\fIfeature\fPs are specified, the module is loaded, if it was not already +loaded, but the state of features is unchanged\&. Each feature +may be preceded by a \fB+\fP to turn the feature on, or \fB\-\fP to turn it +off; the \fB+\fP is assumed if neither character is present\&. +Any feature not explicitly mentioned is left in its current state; +if the module was not previously loaded this means any such features will +remain disabled\&. The return status is zero if all features were +set, 1 if the module failed to load, and 2 if some features could +not be set (for example, a parameter couldn\&'t be added because there +was a different parameter of the same name) but the module was loaded\&. +.RS +.PP +The standard features are builtins, conditions, parameters and math +functions; these are indicated by the prefix `\fBb:\fP\&', `\fBc:\fP' +(`\fBC:\fP\&' for an infix condition), `\fBp:\fP' and `\fBf:\fP', respectively, +followed by the name that the corresponding feature would have in the +shell\&. For example, `\fBb:strftime\fP\&' indicates a builtin named +\fBstrftime\fP and \fBp:EPOCHSECONDS\fP indicates a parameter named +\fBEPOCHSECONDS\fP\&. The module may provide other (`abstract\&') features of +its own as indicated by its documentation; these have no prefix\&. +.PP +With \fB\-l\fP or \fB\-L\fP, features provided by the module are listed\&. With +\fB\-l\fP alone, a list of features together with their states is shown, one +feature per line\&. With \fB\-L\fP alone, a \fBzmodload \-F\fP command that would +cause enabled features of the module to be turned on is shown\&. With +\fB\-lL\fP, a \fBzmodload \-F\fP command that would cause all the features to be +set to their current state is shown\&. If one of these combinations is given +with the option \fB\-P\fP \fIparam\fP then the parameter \fIparam\fP is set to an +array of features, either features together with their state or (if +\fB\-L\fP alone is given) enabled features\&. +.PP +With the option \fB\-L\fP the module name may be omitted; then a list +of all enabled features for all modules providing features is printed +in the form of \fBzmodload \-F\fP commands\&. If \fB\-l\fP is also given, +the state of both enabled and disabled features is output in that form\&. +.PP +A set of features may be provided together with \fB\-l\fP or \fB\-L\fP and a +module name; in that case only the state of those features is +considered\&. Each feature may be preceded by \fB+\fP or \fB\-\fP but the +character has no effect\&. If no set of features is provided, all +features are considered\&. +.PP +With \fB\-e\fP, the command first tests that the module is loaded; +if it is not, status 1 is returned\&. If the module is loaded, +the list of features given as an argument is examined\&. Any feature +given with no prefix is simply tested to see if the module provides it; +any feature given with a prefix \fB+\fP or \fB\-\fP is tested to +see if is provided and in the given state\&. If the tests on all features +in the list succeed, status 0 is returned, else status 1\&. +.PP +With \fB\-m\fP, each entry in the given list of features is taken +as a pattern to be matched against the list of features provided +by the module\&. An initial \fB+\fP or \fB\-\fP must be given explicitly\&. +This may not be combined with the \fB\-a\fP option as autoloads must +be specified explicitly\&. +.PP +With \fB\-a\fP, the given list of features is marked for autoload from +the specified module, which may not yet be loaded\&. An optional \fB+\fP +may appear before the feature name\&. If the feature is prefixed with +\fB\-\fP, any existing autoload is removed\&. The options \fB\-l\fP and \fB\-L\fP +may be used to list autoloads\&. Autoloading is specific to individual +features; when the module is loaded only the requested feature is +enabled\&. Autoload requests are preserved if the module is +subsequently unloaded until an explicit `\fBzmodload \-Fa\fP \fImodule\fP +\fB\-\fP\fIfeature\fP\&' is issued\&. It is not an error to request an autoload +for a feature of a module that is already loaded\&. +.PP +When the module is loaded each autoload is checked against the features +actually provided by the module; if the feature is not provided the +autoload request is deleted\&. A warning message is output; if the +module is being loaded to provide a different feature, and that autoload +is successful, there is no effect on the status of the current command\&. +If the module is already loaded at the time when \fBzmodload \-Fa\fP is +run, an error message is printed and status 1 returned\&. +.PP +\fBzmodload \-Fa\fP can be used with the \fB\-l\fP, \fB\-L\fP, \fB\-e\fP and +\fB\-P\fP options for listing and testing the existence of autoloadable +features\&. In this case \fB\-l\fP is ignored if \fB\-L\fP is specified\&. +\fBzmodload \-FaL\fP with no module name lists autoloads for all modules\&. +.PP +Note that only standard features as described above can be autoloaded; +other features require the module to be loaded before enabling\&. +.RE +.TP +.PD 0 +\fBzmodload\fP \fB\-d\fP [ \fB\-L\fP ] [ \fIname\fP ] +.TP +.PD 0 +\fBzmodload\fP \fB\-d\fP \fIname\fP \fIdep\fP \&.\&.\&. +.TP +.PD +\fBzmodload\fP \fB\-ud\fP \fIname\fP [ \fIdep\fP \&.\&.\&. ] +The \fB\-d\fP option can be used to specify module dependencies\&. The modules +named in the second and subsequent arguments will be loaded before the +module named in the first argument\&. +.RS +.PP +With \fB\-d\fP and one argument, all dependencies for that module are listed\&. +With \fB\-d\fP and no arguments, all module dependencies are listed\&. This +listing is by default in a Makefile\-like format\&. The \fB\-L\fP option +changes this format to a list of \fBzmodload \-d\fP commands\&. +.PP +If \fB\-d\fP and \fB\-u\fP are both used, dependencies are removed\&. If only one +argument is given, all dependencies for that module are removed\&. +.RE +.TP +.PD 0 +\fBzmodload\fP \fB\-ab\fP [ \fB\-L\fP ] +.TP +.PD 0 +\fBzmodload\fP \fB\-ab\fP [ \fB\-i\fP ] \fIname\fP [ \fIbuiltin\fP \&.\&.\&. ] +.TP +.PD +\fBzmodload\fP \fB\-ub\fP [ \fB\-i\fP ] \fIbuiltin\fP \&.\&.\&. +The \fB\-ab\fP option defines autoloaded builtins\&. It defines the specified +\fIbuiltin\fPs\&. When any of those builtins is called, the module specified +in the first argument is loaded and all its features are enabled (for +selective control of features use `\fBzmodload \-F \-a\fP\&' as described +above)\&. If only the \fIname\fP is given, one builtin is defined, with +the same name as the module\&. \fB\-i\fP suppresses the error if the builtin +is already defined or autoloaded, but not if another builtin of the +same name is already defined\&. +.RS +.PP +With \fB\-ab\fP and no arguments, all autoloaded builtins are listed, with the +module name (if different) shown in parentheses after the builtin name\&. +The \fB\-L\fP option changes this format to a list of \fBzmodload \-a\fP +commands\&. +.PP +If \fB\-b\fP is used together with the \fB\-u\fP option, it removes builtins +previously defined with \fB\-ab\fP\&. This is only possible if the builtin is +not yet loaded\&. \fB\-i\fP suppresses the error if the builtin is already +removed (or never existed)\&. +.PP +Autoload requests are retained if the module is subsequently unloaded +until an explicit `\fBzmodload \-ub\fP \fIbuiltin\fP\&' is issued\&. +.RE +.TP +.PD 0 +\fBzmodload\fP \fB\-ac\fP [ \fB\-IL\fP ] +.TP +.PD 0 +\fBzmodload\fP \fB\-ac\fP [ \fB\-iI\fP ] \fIname\fP [ \fIcond\fP \&.\&.\&. ] +.TP +.PD +\fBzmodload\fP \fB\-uc\fP [ \fB\-iI\fP ] \fIcond\fP \&.\&.\&. +The \fB\-ac\fP option is used to define autoloaded condition codes\&. The +\fIcond\fP strings give the names of the conditions defined by the +module\&. The optional \fB\-I\fP option is used to define infix condition +names\&. Without this option prefix condition names are defined\&. +.RS +.PP +If given no condition names, all defined names are listed (as a series of +\fBzmodload\fP commands if the \fB\-L\fP option is given)\&. +.PP +The \fB\-uc\fP option removes definitions for autoloaded conditions\&. +.RE +.TP +.PD 0 +\fBzmodload\fP \fB\-ap\fP [ \fB\-L\fP ] +.TP +.PD 0 +\fBzmodload\fP \fB\-ap\fP [ \fB\-i\fP ] \fIname\fP [ \fIparameter\fP \&.\&.\&. ] +.TP +.PD +\fBzmodload\fP \fB\-up\fP [ \fB\-i\fP ] \fIparameter\fP \&.\&.\&. +The \fB\-p\fP option is like the \fB\-b\fP and \fB\-c\fP options, but makes +\fBzmodload\fP work on autoloaded parameters instead\&. +.TP +.PD 0 +\fBzmodload\fP \fB\-af\fP [ \fB\-L\fP ] +.TP +.PD 0 +\fBzmodload\fP \fB\-af\fP [ \fB\-i\fP ] \fIname\fP [ \fIfunction\fP \&.\&.\&. ] +.TP +.PD +\fBzmodload\fP \fB\-uf\fP [ \fB\-i\fP ] \fIfunction\fP \&.\&.\&. +The \fB\-f\fP option is like the \fB\-b\fP, \fB\-p\fP, and \fB\-c\fP options, but +makes \fBzmodload\fP work on autoloaded math functions instead\&. +.TP +.PD 0 +\fBzmodload\fP \fB\-a\fP [ \fB\-L\fP ] +.TP +.PD 0 +\fBzmodload\fP \fB\-a\fP [ \fB\-i\fP ] \fIname\fP [ \fIbuiltin\fP \&.\&.\&. ] +.TP +.PD +\fBzmodload\fP \fB\-ua\fP [ \fB\-i\fP ] \fIbuiltin\fP \&.\&.\&. +Equivalent to \fB\-ab\fP and \fB\-ub\fP\&. +.TP +\fBzmodload \-e\fP [ \fB\-A\fP ] [ \fIstring\fP \&.\&.\&. ] +The \fB\-e\fP option without arguments lists all loaded modules; if the \fB\-A\fP +option is also given, module aliases corresponding to loaded modules are +also shown\&. If arguments are provided, nothing is printed; +the return status is set to zero if all \fIstring\fPs given as arguments +are names of loaded modules and to one if at least on \fIstring\fP is not +the name of a loaded module\&. This can be used to test for the +availability of things implemented by modules\&. In this case, any +aliases are automatically resolved and the \fB\-A\fP flag is not used\&. +.TP +\fBzmodload\fP \fB\-A\fP [ \fB\-L\fP ] [ \fImodalias\fP[\fB=\fP\fImodule\fP] \&.\&.\&. ] +For each argument, if both \fImodalias\fP and \fImodule\fP are given, +define \fImodalias\fP to be an alias for the module \fImodule\fP\&. +If the module \fImodalias\fP is ever subsequently requested, either via a +call to \fBzmodload\fP or implicitly, the shell will attempt to load +\fImodule\fP instead\&. If \fImodule\fP is not given, show the definition of +\fImodalias\fP\&. If no arguments are given, list all defined module aliases\&. +When listing, if the \fB\-L\fP flag was also given, list the definition as a +\fBzmodload\fP command to recreate the alias\&. +.RS +.PP +The existence of aliases for modules is completely independent of whether +the name resolved is actually loaded as a module: while the alias exists, +loading and unloading the module under any alias has exactly the same +effect as using the resolved name, and does not affect the connection +between the alias and the resolved name which can be removed either by +\fBzmodload \-R\fP or by redefining the alias\&. Chains of aliases (i\&.e\&. where +the first resolved name is itself an alias) are valid so long as these are +not circular\&. As the aliases take the same format as module names, they +may include path separators: in this case, there is no requirement for any +part of the path named to exist as the alias will be resolved first\&. For +example, `\fBany/old/alias\fP\&' is always a valid alias\&. +.PP +Dependencies added to aliased modules are actually added to the resolved +module; these remain if the alias is removed\&. It is valid to create an +alias whose name is one of the standard shell modules and which resolves to +a different module\&. However, if a module has dependencies, it +will not be possible to use the module name as an alias as the module will +already be marked as a loadable module in its own right\&. +.PP +Apart from the above, aliases can be used in the \fBzmodload\fP command +anywhere module names are required\&. However, aliases will not be +shown in lists of loaded modules with a bare `\fBzmodload\fP\&'\&. +.RE +.TP +\fBzmodload\fP \fB\-R\fP \fImodalias\fP \&.\&.\&. +For each \fImodalias\fP argument that was previously defined as a module +alias via \fBzmodload \-A\fP, delete the alias\&. If any was not defined, an +error is caused and the remainder of the line is ignored\&. +.PP +Note that \fBzsh\fP makes no distinction between modules that were linked +into the shell and modules that are loaded dynamically\&. In both cases +this builtin command has to be used to make available the builtins and +other things defined by modules (unless the module is autoloaded on +these definitions)\&. This is true even for systems that don\&'t support +dynamic loading of modules\&. +.RE +.TP +\fBzparseopts\fP +See the section `The zsh/zutil Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBzprof\fP +See the section `The zsh/zprof Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBzpty\fP +See the section `The zsh/zpty Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBzregexparse\fP +See the section `The zsh/zutil Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBzsocket\fP +See the section `The zsh/net/socket Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBzstyle\fP +See the section `The zsh/zutil Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBztcp\fP +See the section `The zsh/net/tcp Module\&' in \fIzshmodules\fP(1)\&. diff --git a/Doc/zshcalsys.1 b/Doc/zshcalsys.1 new file mode 100644 index 000000000..c6bc64e4b --- /dev/null +++ b/Doc/zshcalsys.1 @@ -0,0 +1,1007 @@ +.TH "ZSHCALSYS" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshcalsys \- zsh calendar system +.\" Yodl file: Zsh/calsys.yo +.SH "DESCRIPTION" +.PP +The shell is supplied with a series of functions to replace and enhance the +traditional Unix \fBcalendar\fP programme, which warns the user of imminent +or future events, details of which are stored in a text file (typically +\fBcalendar\fP in the user\&'s home directory)\&. The version provided here +includes a mechanism for alerting the user when an event is due\&. +.PP +In addition functions \fBage\fP, \fBbefore\fP and \fBafter\fP are provided +that can be used in a glob qualifier; they allow files to be selected +based on their modification times\&. +.PP +The format of the \fBcalendar\fP file and the dates used there in and in +the \fBage\fP function are described first, then the functions that can +be called to examine and modify the \fBcalendar\fP file\&. +.PP +The functions here depend on the availability of the \fBzsh/datetime\fP +module which is usually installed with the shell\&. The library function +\fBstrptime()\fP must be available; it is present on most recent +operating systems\&. +.PP +.PP +.SH "FILE AND DATE FORMATS" +.PP +.SS "Calendar File Format" +.PP +The calendar file is by default \fB~/calendar\fP\&. This can be configured +by the \fBcalendar\-file\fP style, see +the section STYLES below\&. The basic format consists +of a series of separate lines, with no indentation, each including +a date and time specification followed by a description of the event\&. +.PP +Various enhancements to this format are supported, based on the syntax +of Emacs calendar mode\&. An indented line indicates a continuation line +that continues the description of the event from the preceding line +(note the date may not be continued in this way)\&. An initial ampersand +(\fB&\fP) is ignored for compatibility\&. +.PP +An indented line on which the first non\-whitespace character is \fB#\fP +is not displayed with the calendar entry, but is still scanned for +information\&. This can be used to hide information useful to the +calendar system but not to the user, such as the unique identifier +used by \fBcalendar_add\fP\&. +.PP +The Emacs extension that a date with no description may refer to a number +of succeeding events at different times is not supported\&. +.PP +Unless the \fBdone\-file\fP style has been altered, any events which +have been processed are appended to the file with the same name as the +calendar file with the suffix \fB\&.done\fP, hence \fB~/calendar\&.done\fP by +default\&. +.PP +An example is shown below\&. +.PP +.SS "Date Format" +.PP +The format of the date and time is designed to allow flexibility without +admitting ambiguity\&. (The words `date\&' and `time' are both used in the +documentation below; except where specifically noted this implies a string +that may include both a date and a time specification\&.) Note that there is +no localization support; month and day names must be in English and +separator characters are fixed\&. Matching is case insensitive, and only the +first three letters of the names are significant, although as a special +case a form beginning "month" does not match "Monday"\&. Furthermore, time +zones are not handled; all times are assumed to be local\&. +.PP +It is recommended that, rather than exploring the intricacies of the +system, users find a date format that is natural to them and stick to it\&. +This will avoid unexpected effects\&. Various key facts should be noted\&. +.PP +.PD 0 +.TP +.PD +\(bu +In particular, note the confusion between +\fImonth\fP\fB/\fP\fIday\fP\fB/\fP\fIyear\fP and +\fIday\fP\fB/\fP\fImonth\fP\fB/\fP\fIyear\fP when the month is numeric; these +formats should be avoided if at all possible\&. Many alternatives are +available\&. +.TP +\(bu +The year must be given in full to avoid confusion, and only years +from 1900 to 2099 inclusive are matched\&. +.PP +The following give some obvious examples; users finding here +a format they like and not subject to vagaries of style may skip +the full description\&. As dates and times are matched separately +(even though the time may be embedded in the date), any date format +may be mixed with any format for the time of day provide the +separators are clear (whitespace, colons, commas)\&. +.PP +.RS +.nf +\fB2007/04/03 13:13 +2007/04/03:13:13 +2007/04/03 1:13 pm +3rd April 2007, 13:13 +April 3rd 2007 1:13 p\&.m\&. +Apr 3, 2007 13:13 +Tue Apr 03 13:13:00 2007 +13:13 2007/apr/3\fP +.fi +.RE +.PP +More detailed rules follow\&. +.PP +Times are parsed and extracted before dates\&. They must use colons +to separate hours and minutes, though a dot is allowed before seconds +if they are present\&. This limits time formats to the following: +.PP +.PD 0 +.TP +.PD +\(bu +\fIHH\fP\fB:\fP\fIMM\fP[\fB:\fP\fISS\fP[\fB\&.\fP\fIFFFFF\fP]] [\fBam\fP|\fBpm\fP|\fBa\&.m\&.\fP|\fBp\&.m\&.\fP] +.TP +\(bu +\fIHH\fP\fB:\fP\fIMM\fP\fB\&.\fP\fISS\fP[\fB\&.\fP\fIFFFFF\fP] [\fBam\fP|\fBpm\fP|\fBa\&.m\&.\fP|\fBp\&.m\&.\fP] +.PP +Here, square brackets indicate optional elements, possibly with +alternatives\&. Fractions of a second are recognised but ignored\&. For +absolute times (the normal format require by the \fBcalendar\fP file and the +\fBage\fP, \fBbefore\fP and \fBafter\fP functions) a date is mandatory but a +time of day is not; the time returned is at the start of the date\&. One +variation is allowed: if \fBa\&.m\&.\fP or \fBp\&.m\&.\fP or one of their variants +is present, an hour without a minute is allowed, e\&.g\&. \fB3 p\&.m\&.\fP\&. +.PP +Time zones are not handled, though if one is matched following a time +specification it will be removed to allow a surrounding date to be +parsed\&. This only happens if the format of the timezone is not too +unusual\&. The following are examples of forms that are understood: +.PP +.RS +.nf +\fB+0100 +GMT +GMT\-7 +CET+1CDT\fP +.fi +.RE +.PP +Any part of the timezone that is not numeric must have exactly three +capital letters in the name\&. +.PP +Dates suffer from the ambiguity between \fIDD\fP\fB/\fP\fIMM\fP\fB/\fP\fIYYYY\fP +and \fIMM\fP\fB/\fP\fIDD\fP\fB/\fP\fIYYYY\fP\&. It is recommended this form is +avoided with purely numeric dates, but use of ordinals, +eg\&. \fB3rd/04/2007\fP, will resolve the ambiguity as the ordinal is always +parsed as the day of the month\&. Years must be four digits (and the first +two must be \fB19\fP or \fB20\fP); \fB03/04/08\fP is not recognised\&. Other +numbers may have leading zeroes, but they are not required\&. The following +are handled: +.PP +.PD 0 +.TP +.PD +\(bu +\fIYYYY\fP\fB/\fP\fIMM\fP\fB/\fP\fIDD\fP +.TP +\(bu +\fIYYYY\fP\fB\-\fP\fIMM\fP\fB\-\fP\fIDD\fP +.TP +\(bu +\fIYYYY\fP\fB/\fP\fIMNM\fP\fB/\fP\fIDD\fP +.TP +\(bu +\fIYYYY\fP\fB\-\fP\fIMNM\fP\fB\-\fP\fIDD\fP +.TP +\(bu +\fIDD\fP[\fBth\fP|\fBst\fP|\fBrd\fP] \fIMNM\fP[\fB,\fP] [ \fIYYYY\fP ] +.TP +\(bu +\fIMNM\fP \fIDD\fP[\fBth\fP|\fBst\fP|\fBrd\fP][\fB,\fP] [ \fIYYYY\fP ] +.TP +\(bu +\fIDD\fP[\fBth\fP|\fBst\fP|\fBrd\fP]\fB/\fP\fIMM\fP[\fB,\fP] \fIYYYY\fP +.TP +\(bu +\fIDD\fP[\fBth\fP|\fBst\fP|\fBrd\fP]\fB/\fP\fIMM\fP\fB/\fP\fIYYYY\fP +.TP +\(bu +\fIMM\fP\fB/\fP\fIDD\fP[\fBth\fP|\fBst\fP|\fBrd\fP][\fB,\fP] \fIYYYY\fP +.TP +\(bu +\fIMM\fP\fB/\fP\fIDD\fP[\fBth\fP|\fBst\fP|\fBrd\fP]\fB/\fP\fIYYYY\fP +.PP +Here, \fIMNM\fP is at least the first three letters of a month name, +matched case\-insensitively\&. The remainder of the month name may appear but +its contents are irrelevant, so janissary, febrile, martial, apricot, +maybe, junta, etc\&. are happily handled\&. +.PP +Where the year is shown as optional, the current year is assumed\&. There +are only two such cases, the form \fBJun 20\fP or \fB14 September\fP (the only +two commonly occurring forms, apart from a "the" in some forms of English, +which isn\&'t currently supported)\&. Such dates will of course become +ambiguous in the future, so should ideally be avoided\&. +.PP +Times may follow dates with a colon, e\&.g\&. \fB1965/07/12:09:45\fP; this is in +order to provide a format with no whitespace\&. A comma and whitespace are +allowed, e\&.g\&. \fB1965/07/12, 09:45\fP\&. Currently the order of these +separators is not checked, so illogical formats such as \fB1965/07/12, : +,09:45\fP will also be matched\&. For simplicity such variations are not shown +in the list above\&. Otherwise, a time is only recognised as being +associated with a date if there is only whitespace in between, or if the +time was embedded in the date\&. +.PP +Days of the week are not normally scanned, but will be ignored if they +occur at the start of the date pattern only\&. However, in contexts where it +is useful to specify dates relative to today, days of the week with no +other date specification may be given\&. The day is assumed to be either +today or within the past week\&. Likewise, the words \fByesterday\fP, +\fBtoday\fP and \fBtomorrow\fP are handled\&. All matches are case\-insensitive\&. +Hence if today is Monday, then \fBSunday\fP is equivalent to \fByesterday\fP, +\fBMonday\fP is equivalent to \fBtoday\fP, but \fBTuesday\fP gives a date six +days ago\&. This is not generally useful within the calendar file\&. +Dates in this format may be combined with a time specification; for +example \fBTomorrow, 8 p\&.m\&.\fP\&. +.PP +For example, the standard date format: +.PP +.RS +.nf +\fBFri Aug 18 17:00:48 BST 2006\fP +.fi +.RE +.PP +is handled by matching \fIHH\fP\fB:\fP\fIMM\fP\fB:\fP\fISS\fP and removing it +together with the matched (but unused) time zone\&. This leaves the following: +.PP +.RS +.nf +\fBFri Aug 18 2006\fP +.fi +.RE +.PP +\fBFri\fP is ignored and the rest is matched according to the standard rules\&. +.PP +.SS "Relative Time Format" +.PP +In certain places relative times are handled\&. Here, a date is not allowed; +instead a combination of various supported periods are allowed, together +with an optional time\&. The periods must be in order from most to +least significant\&. +.PP +In some cases, a more accurate calculation is possible when there is an +anchor date: offsets of months or years pick the correct day, rather than +being rounded, and it is possible to pick a particular day in a month as +`(1st Friday)\&', etc\&., as described in more detail below\&. +.PP +Anchors are available in the following cases\&. If one or two times are +passed to the function \fBcalendar\fP, the start time acts an anchor for the +end time when the end time is relative (even if the start time is +implicit)\&. When examining calendar files, the scheduled event being +examined anchors the warning time when it is given explicitly by means of +the \fBWARN\fP keyword; likewise, the scheduled event anchors a repetition +period when given by the \fBRPT\fP keyword, so that specifications such as +\fBRPT 2 months, 3rd Thursday\fP are handled properly\&. Finally, the \fB\-R\fP +argument to \fBcalendar_scandate\fP directly provides an anchor for relative +calculations\&. +.PP +The periods handled, with possible abbreviations are: +.PP +.PD 0 +.TP +.PD +Years +\fByears\fP, \fByrs\fP, \fBys\fP, \fByear\fP, \fByr\fP, \fBy\fP, \fByearly\fP\&. +A year is 365\&.25 days unless there is an anchor\&. +.TP +Months +\fBmonths\fP, \fBmons\fP, \fBmnths\fP, \fBmths\fP, \fBmonth\fP, \fBmon\fP, +\fBmnth\fP, \fBmth\fP, \fBmonthly\fP\&. Note that \fBm\fP, \fBms\fP, \fBmn\fP, \fBmns\fP +are ambiguous and are \fInot\fP handled\&. A month is a period +of 30 days rather than a calendar month unless there is an anchor\&. +.TP +Weeks +\fBweeks\fP, \fBwks\fP, \fBws\fP, \fBweek\fP, \fBwk\fP, \fBw\fP, \fBweekly\fP +.TP +Days +\fBdays\fP, \fBdys\fP, \fBds\fP, \fBday\fP, \fBdy\fP, \fBd\fP, \fBdaily\fP +.TP +Hours +\fBhours\fP, \fBhrs\fP, \fBhs\fP, \fBhour\fP, \fBhr\fP, \fBh\fP, \fBhourly\fP +.TP +Minutes +\fBminutes\fP, \fBmins\fP, \fBminute\fP, \fBmin\fP, but \fInot\fP \fBm\fP, +\fBms\fP, \fBmn\fP or \fBmns\fP +.TP +Seconds +\fBseconds\fP, \fBsecs\fP, \fBss\fP, \fBsecond\fP, \fBsec\fP, \fBs\fP +.PP +Spaces between the numbers are optional, but are required between items, +although a comma may be used (with or without spaces)\&. +.PP +The forms \fByearly\fP to \fBhourly\fP allow the number to be omitted; it is +assumed to be 1\&. For example, \fB1 d\fP and \fBdaily\fP are equivalent\&. Note +that using those forms with plurals is confusing; \fB2 yearly\fP is the same +as \fB2 years\fP, \fInot\fP twice yearly, so it is recommended they only +be used without numbers\&. +.PP +When an anchor time is present, there is an extension to handle regular +events in the form of the \fIn\fPth \fIsome\fPday of the month\&. Such a +specification must occur immediately after any year and month +specification, but before any time of day, and must be in the form +\fIn\fP(\fBth\fP|\fBst\fP|\fBrd\fP) \fIday\fP, for example \fB1st Tuesday\fP or +\fB3rd Monday\fP\&. As in other places, days are matched case insensitively, +must be in English, and only the first three letters are significant except +that a form beginning `month\&' does not match `Monday'\&. No attempt is made +to sanitize the resulting date; attempts to squeeze too many occurrences +into a month will push the day into the next month (but in the obvious +fashion, retaining the correct day of the week)\&. +.PP +Here are some examples: +.PP +.RS +.nf +\fB30 years 3 months 4 days 3:42:41 +14 days 5 hours +Monthly, 3rd Thursday +4d,10hr\fP +.fi +.RE +.PP +.SS "Example" +.PP +Here is an example calendar file\&. It uses a consistent date format, +as recommended above\&. +.PP +.RS +.nf +\fBFeb 1, 2006 14:30 Pointless bureaucratic meeting +Mar 27, 2006 11:00 Mutual recrimination and finger pointing + Bring water pistol and waterproofs +Mar 31, 2006 14:00 Very serious managerial pontification + # UID 12C7878A9A50 +Apr 10, 2006 13:30 Even more pointless blame assignment exercise WARN 30 mins +May 18, 2006 16:00 Regular moaning session RPT monthly, 3rd Thursday\fP +.fi +.RE +.PP +The second entry has a continuation line\&. The third entry has a +continuation line that will not be shown when the entry is displayed, but +the unique identifier will be used by the \fBcalendar_add\fP function when +updating the event\&. The fourth entry will produce a warning 30 minutes +before the event (to allow you to equip yourself appropriately)\&. The fifth +entry repeats after a month on the 3rd Thursday, i\&.e\&. June 15, 2006, at the +same time\&. +.PP +.SH "USER FUNCTIONS" +.PP +This section describes functions that are designed to be called +directly by the user\&. The first part describes those functions +associated with the user\&'s calendar; the second part describes +the use in glob qualifiers\&. +.PP +.SS "Calendar system functions" +.PP +.PD 0 + +.TP +.PD 0 +\fBcalendar \fP[ \fB\-abdDsv\fP ] [ \fB\-C\fP \fIcalfile\fP ] [ \fB\-n\fP \fInum\fP ] [ \fB\-S\fP \fIshowprog\fP ] +.TP +.PD 0 +\fB \fP[ [ \fIstart\fP ] \fIend\fP ] +.TP +.PD 0 +\fBcalendar \-r\fP [ \fB\-abdDrsv\fP ] [ \fB\-C\fP \fIcalfile\fP ] [ \fB\-n\fP \fInum\fP ] [ \fB\-S\fP \fIshowprog\fP ] +.TP +.PD +\fB \fP[ \fIstart\fP ] +Show events in the calendar\&. +.RS +.PP +With no arguments, show events from the start of today until the end of +the next working day after today\&. In other words, if today is Friday, +Saturday, or Sunday, show up to the end of the following Monday, otherwise +show today and tomorrow\&. +.PP +If \fIend\fP is given, show events from the start of today up to the time +and date given, which is in the format described in the previous section\&. +Note that if this is a date the time is assumed to be midnight at the +start of the date, so that effectively this shows all events before +the given date\&. +.PP +\fIend\fP may start with a \fB+\fP, in which case the remainder of the +specification is a relative time format as described in the previous +section indicating the range of time from the start time that is to +be included\&. +.PP +If \fIstart\fP is also given, show events starting from that time and date\&. +The word \fBnow\fP can be used to indicate the current time\&. +.PP +To implement an alert when events are due, include \fBcalendar \-s\fP in your +\fB~/\&.zshrc\fP file\&. +.PP +Options: +.PP +.PD 0 +.TP +.PD +\fB\-a\fP +Show all items in the calendar, regardless of the \fBstart\fP and +\fBend\fP\&. +.TP +\fB\-b\fP +Brief: don\&'t display continuation lines (i\&.e\&. indented lines following +the line with the date/time), just the first line\&. +.TP +\fB\-B\fP \fIlines\fP +Brief: display at most the first \fIlines\fP lines of the calendar +entry\&. `\fB\-B 1\fP\&' is equivalent to `\fB\-b\fP'\&. +.TP +\fB\-C\fP \fIcalfile\fP +Explicitly specify a calendar file instead of the value of +the \fBcalendar\-file\fP style or the default \fB~/calendar\fP\&. +.TP +\fB\-d\fP +Move any events that have passed from the calendar file to the +"done" file, as given by the \fBdone\-file\fP style or the default +which is the calendar file with \fB\&.done\fP appended\&. This option +is implied by the \fB\-s\fP option\&. +.TP +\fB\-D\fP +Turns off the option \fB\-d\fP, even if the \fB\-s\fP option is also present\&. +.TP +\fB\-n\fP \fInum\fP, \fB\-\fP\fInum\fP +Show at least \fInum\fP events, if present in the calendar file, regardless +of the \fBstart\fP and \fBend\fP\&. +.TP +\fB\-r\fP +Show all the remaining options in the calendar, ignoring the given \fIend\fP +time\&. The \fIstart\fP time is respected; any argument given is treated +as a \fIstart\fP time\&. +.TP +\fB\-s\fP +Use the shell\&'s \fBsched\fP command to schedule a timed event that +will warn the user when an event is due\&. Note that the \fBsched\fP command +only runs if the shell is at an interactive prompt; a foreground task +blocks the scheduled task from running until it is finished\&. +.RS +.PP +The timed event usually runs the programme \fBcalendar_show\fP to show +the event, as described in +the section UTILITY FUNCTIONS below\&. +.PP +By default, a warning of the event is shown five minutes before it is due\&. +The warning period can be configured by the style \fBwarn\-time\fP or +for a single calendar entry by including \fBWARN\fP \fIreltime\fP in the first +line of the entry, where \fIreltime\fP is one of the usual relative time +formats\&. +.PP +A repeated event may be indicated by including \fBRPT\fP \fIreldate\fP in the +first line of the entry\&. After the scheduled event has been displayed +it will be re\-entered into the calendar file at a time \fIreldate\fP +after the existing event\&. Note that this is currently the only use +made of the repeat count, so that it is not possible to query the schedule +for a recurrence of an event in the calendar until the previous event +has passed\&. +.PP +If \fBRPT\fP is used, it is also possible to specify that certain +recurrences of an event are rescheduled or cancelled\&. This is +done with the \fBOCCURRENCE\fP keyword, followed by whitespace and the +date and time of the occurrence in the regular sequence, followed by +whitespace and either the date and time of the rescheduled event or +the exact string \fBCANCELLED\fP\&. In this case the date and time must +be in exactly the "date with local time" format used by the +\fBtext/calendar\fP MIME type (RFC 2445), +\fI<YYYY><MM><DD>\fP\fBT\fP\fI<hh><mm><ss>\fP (note the presence of the literal +character \fBT\fP)\&. The first word (the regular recurrence) may be +something other than a proper date/time to indicate that the event +is additional to the normal sequence; a convention that retains +the formatting appearance is \fBXXXXXXXXTXXXXXX\fP\&. +.PP +Furthermore, it is useful to record the next regular recurrence +(as then the displayed date may be for a rescheduled event so cannot +be used for calculating the regular sequence)\&. This is specified by +\fBRECURRENCE\fP and a time or date in the same format\&. \fBcalendar_add\fP +adds such an indication when it encounters a recurring event that does not +include one, based on the headline date/time\&. +.PP +If \fBcalendar_add\fP is used to update occurrences the \fBUID\fP keyword +described there should be present in both the existing entry and the added +occurrence in order to identify recurring event sequences\&. +.PP +For example, +.PP +.RS +.nf +\fBThu May 6, 2010 11:00 Informal chat RPT 1 week + # RECURRENCE 20100506T110000 + # OCCURRENCE 20100513T110000 20100513T120000 + # OCCURRENCE 20100520T110000 CANCELLED\fP +.fi +.RE +.PP +The event that occurs at 11:00 on 13th May 2010 is rescheduled an hour +later\&. The event that occurs a week later is cancelled\&. The occurrences +are given on a continuation line starting with a \fB#\fP character so will +not usually be displayed as part of the event\&. As elsewhere, no account of +time zones is taken with the times\&. After the next event occurs the headline +date/time will be `\fBThu May 13, 2010 12:00\fP\&' while the \fBRECURRENCE\fP +date/time will be `\fB20100513T110000\fP\&' (note that cancelled and +moved events are not taken account of in the \fBRECURRENCE\fP, which +records what the next regular recurrence is, but they are accounted for in +the headline date/time)\&. +.PP +It is safe to run \fBcalendar \-s\fP to reschedule an existing event +(if the calendar file has changed, for example), and also to have it +running in multiples instances of the shell since the calendar file +is locked when in use\&. +.PP +By default, expired events are moved to the "done" file; see the \fB\-d\fP +option\&. Use \fB\-D\fP to prevent this\&. +.RE +.TP +\fB\-S\fP \fIshowprog\fP +Explicitly specify a programme to be used for showing events instead +of the value of the \fBshow\-prog\fP style or the default \fBcalendar_show\fP\&. +.TP +\fB\-v\fP +Verbose: show more information about stages of processing\&. This +is useful for confirming that the function has successfully parsed +the dates in the calendar file\&. +.RE +.TP +\fBcalendar_add\fP [ \fB\-BL\fP ] \fIevent\fP \&.\&.\&. +Adds a single event to the calendar in the appropriate location\&. +The event can contain multiple lines, as described in +the section `Calendar File Format\&' above\&. +Using this function ensures that the calendar file is sorted in date +and time order\&. It also makes special arrangements for locking +the file while it is altered\&. The old calendar is left in a file +with the suffix \fB\&.old\fP\&. +.RS +.PP +The option \fB\-B\fP indicates that backing up the calendar file will be +handled by the caller and should not be performed by \fBcalendar_add\fP\&. The +option \fB\-L\fP indicates that \fBcalendar_add\fP does not need to lock the +calendar file as it is already locked\&. These options will not usually be +needed by users\&. +.PP +If the style \fBreformat\-date\fP is true, the date and time of the +new entry will be rewritten into the standard date format: see +the descriptions of this style and the style \fBdate\-format\fP\&. +.PP +The function can use a unique identifier stored with each event to ensure +that updates to existing events are treated correctly\&. The entry +should contain the word \fBUID\fP, followed by whitespace, followed by +a word consisting entirely of hexadecimal digits of arbitrary length +(all digits are significant, including leading zeroes)\&. As the UID +is not directly useful to the user, it is convenient to hide it on +an indented continuation line starting with a \fB#\fP, for example: +.PP +.RS +.nf +\fBAug 31, 2007 09:30 Celebrate the end of the holidays + # UID 045B78A0\fP +.fi +.RE +.PP +The second line will not be shown by the \fBcalendar\fP function\&. +.PP +It is possible to specify the \fBRPT\fP keyword followed by \fBCANCELLED\fP +instead of a relative time\&. This causes any matched event or series +of events to be cancelled (the original event does not have to be marked +as recurring in order to be cancelled by this method)\&. A \fBUID\fP is +required in order to match an existing event in the calendar\&. +.PP +\fBcalendar_add\fP will attempt to manage recurrences and occurrences of +repeating events as described for event scheduling by \fBcalendar \-s\fP +above\&. To reschedule or cancel a single event \fBcalendar_add\fP should be +called with an entry that includes the correct \fBUID\fP but does \fInot\fP +include the \fBRPT\fP keyword as this is taken to mean the entry applies to a +series of repeating events and hence replaces all existing information\&. +Each rescheduled or cancelled occurrence must have an \fBOCCURRENCE\fP +keyword in the entry passed to \fBcalendar_add\fP which will be merged into +the calendar file\&. Any existing reference to the occurrence is replaced\&. +An occurrence that does not refer to a valid existing event is added as a +one\-off occurrence to the same calendar entry\&. +.RE +.TP +\fBcalendar_edit\fP +This calls the user\&'s editor to edit the calendar file\&. If +there are arguments, they are taken as the editor to use (the file name +is appended to the commands); otherwise, the editor is given by the +variable \fBVISUAL\fP, if set, else the variable \fBEDITOR\fP\&. +.RS +.PP +If the calendar scheduler was running, then after editing the file +\fBcalendar \-s\fP is called to update it\&. +.PP +This function locks out the calendar system during the edit\&. +Hence it should be used to edit the calendar file if there is any +possibility of a calendar event occurring meanwhile\&. Note this +can lead to another shell with calendar functions enabled hanging waiting +for a lock, so it is necessary to quit the editor as soon as possible\&. +.RE +.TP +\fBcalendar_parse\fP \fIcalendar\-entry\fP +This is the internal function that analyses the parts of a calendar +entry, which is passed as the only argument\&. The function returns +status 1 if the argument could not be parsed as a calendar entry +and status 2 if the wrong number of arguments were passed; it also sets the +parameter \fBreply\fP to an empty associative array\&. Otherwise, +it returns status 0 and sets elements of the associative +array \fBreply\fP as follows: +.RS +.PP +.PD 0 +.TP +\fBtime\fP +The time as a string of digits in the same units as +\fB$EPOCHSECONDS\fP +.TP +\fBschedtime\fP +The regularly scheduled time\&. This may differ from +the actual event time \fBtime\fP if this is a recurring event and the next +occurrence has been rescheduled\&. Then \fBtime\fP gives the actual time +and \fBschedtime\fP the time of the regular recurrence before modification\&. +.TP +\fBtext1\fP +The text from the line not including the date and time of the +event, but including any \fBWARN\fP or \fBRPT\fP keywords and values\&. +.TP +\fBwarntime\fP +Any warning time given by the \fBWARN\fP keyword as a string +of digits containing the time at which to warn in the same units as +\fB$EPOCHSECONDS\fP\&. (Note this is an absolute time, not the relative time +passed down\&.) Not set no \fBWARN\fP keyword and value were +matched\&. +.TP +\fBwarnstr\fP +The raw string matched after the \fBWARN\fP keyword, else unset\&. +.TP +\fBrpttime\fP +Any recurrence time given by the \fBRPT\fP keyword as a string +of digits containing the time of the recurrence in the same units +as \fB$EPOCHSECONDS\fP\&. (Note this is an absolute time\&.) Not set if +no \fBRPT\fP keyword and value were matched\&. +.TP +\fBschedrpttime\fP +The next regularly scheduled occurrence of a recurring +event before modification\&. This may differ from \fBrpttime\fP, which is the +actual time of the event that may have been rescheduled from the regular +time\&. +.TP +\fBrptstr\fP +The raw string matched after the \fBRPT\fP keyword, else unset\&. +.TP +\fBtext2\fP +The text from the line after removal of the date and any +keywords and values\&. +.RE +.PD +.PP +.TP +\fBcalendar_showdate\fP [ \fB\-r\fP ] [ \fB\-f\fP \fIfmt\fP ] \fIdate\-spec\fP \&.\&.\&. +The given \fIdate\-spec\fP is interpreted and the corresponding date and +time printed\&. If the initial \fIdate\-spec\fP begins with a \fB+\fP or +\fB\-\fP it is treated as relative to the current time; \fIdate\-spec\fPs after +the first are treated as relative to the date calculated so far and +a leading \fB+\fP is optional in that case\&. This allows one to +use the system as a date calculator\&. For example, \fBcalendar_showdate \&'+1 +month, 1st Friday\&'\fP shows the date of the first Friday of next month\&. +.RS +.PP +With the option \fB\-r\fP nothing is printed but the value of the date and +time in seconds since the epoch is stored in the parameter \fBREPLY\fP\&. +.PP +With the option \fB\-f\fP \fIfmt\fP the given date/time conversion format +is passed to \fBstrftime\fP; see notes on the \fBdate\-format\fP style below\&. +.PP +In order to avoid ambiguity with negative relative date specifications, +options must occur in separate words; in other words, \fB\-r\fP and \fB\-f\fP +should not be combined in the same word\&. +.RE +.TP +\fBcalendar_sort\fP +Sorts the calendar file into date and time order\&. The old calendar is +left in a file with the suffix \fB\&.old\fP\&. +.PP +.SS "Glob qualifiers" +.PP +.PD 0 +.TP +.PD +\fBage\fP +The function \fBage\fP can be autoloaded and use separately from +the calendar system, although it uses the function \fBcalendar_scandate\fP +for date formatting\&. It requires the \fBzsh/stat\fP builtin, but uses +only the builtin \fBzstat\fP\&. +.RS +.PP +\fBage\fP selects files having a given modification time for use +as a glob qualifier\&. The format of the date is the same as that +understood by the calendar system, described in +the section FILE AND DATE FORMATS above\&. +.PP +The function can take one or two arguments, which can be supplied either +directly as command or arguments, or separately as shell parameters\&. +.PP +.RS +.nf +\fBprint *(e:age 2006/10/04 2006/10/09:)\fP +.fi +.RE +.PP +The example above matches all files modified between the start of those +dates\&. The second argument may alternatively be a relative time +introduced by a \fB+\fP: +.PP +.RS +.nf +\fBprint *(e:age 2006/10/04 +5d:)\fP +.fi +.RE +.PP +The example above is equivalent to the previous example\&. +.PP +In addition to the special use of days of the week, \fBtoday\fP and +\fByesterday\fP, times with no date may be specified; these apply to today\&. +Obviously such uses become problematic around midnight\&. +.PP +.RS +.nf +\fBprint *(e\-age 12:00 13:30\-)\fP +.fi +.RE +.PP +The example above shows files modified between 12:00 and 13:00 today\&. +.PP +.RS +.nf +\fBprint *(e:age 2006/10/04:)\fP +.fi +.RE +.PP +The example above matches all files modified on that date\&. If the second +argument is omitted it is taken to be exactly 24 hours after the first +argument (even if the first argument contains a time)\&. +.PP +.RS +.nf +\fBprint *(e\-age 2006/10/04:10:15 2006/10/04:10:45\-)\fP +.fi +.RE +.PP +The example above supplies times\&. Note that whitespace within the time and +date specification must be quoted to ensure \fBage\fP receives the correct +arguments, hence the use of the additional colon to separate the date and +time\&. +.PP +.RS +.nf +\fBAGEREF=2006/10/04:10:15 +AGEREF2=2006/10/04:10:45 +print *(+age)\fP +.fi +.RE +.PP +This shows the same example before using another form of argument +passing\&. The dates and times in the parameters \fBAGEREF\fP and \fBAGEREF2\fP +stay in effect until unset, but will be overridden if any argument is +passed as an explicit argument to age\&. Any explicit argument +causes both parameters to be ignored\&. +.PP +Instead of an explicit date and time, it\&'s possible to use the +modification time of a file as the date and time for either argument +by introducing the file name with a colon: +.PP +.RS +.nf +\fBprint *(e\-age :file1\-)\fP +.fi +.RE +.PP +matches all files created on the same day (24 hours starting from +midnight) as \fBfile1\fP\&. +.PP +.RS +.nf +\fBprint *(e\-age :file1 :file2\-)\fP +.fi +.RE +.PP +matches all files modified no earlier than \fBfile1\fP and +no later than \fBfile2\fP; precision here is to the nearest second\&. +.RE +.TP +.PD 0 +\fBafter\fP +.TP +.PD +\fBbefore\fP +The functions \fBafter\fP and \fBbefore\fP are simpler versions of \fBage\fP +that take just one argument\&. The argument is parsed similarly to an +argument of \fBage\fP; if it is not given the variable \fBAGEREF\fP is +consulted\&. As the names of the functions suggest, a file matches if its +modification time is after or before the time and date specified\&. If +a time only is given the date is today\&. +.RS +.PP +The two following examples are therefore equivalent: +.RS +.nf +\fBprint *(e\-after 12:00\-) +print *(e\-after today:12:00\-)\fP +.fi +.RE +.RE +.PP +.SH "STYLES" +.PP +The zsh style mechanism using the \fBzstyle\fP command is describe in +\fIzshmodules\fP(1)\&. This is the same mechanism +used in the completion system\&. +.PP +The styles below are all examined in the context +\fB:datetime:\fP\fIfunction\fP\fB:\fP, for example \fB:datetime:calendar:\fP\&. +.PP +.PD 0 +.TP +.PD +\fBcalendar\-file\fP +The location of the main calendar\&. The default is \fB~/calendar\fP\&. +.TP +\fBdate\-format\fP +A \fBstrftime\fP format string (see \fIstrftime\fP(3)) with the zsh +extensions providing various numbers with no leading zero or space +if the number is a single digit as described for the +\fB%D{\fP\fIstring\fP\fB}\fP prompt format in +the section EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)\&. +.RS +.PP +This is used for outputting dates in \fBcalendar\fP, both to support +the \fB\-v\fP option and when adding recurring events back to the calendar +file, and in \fBcalendar_showdate\fP as the final output format\&. +.PP +If the style is not set, the default used is similar the standard system +format as output by the \fBdate\fP command (also known as `ctime format\&'): +`\fB%a %b %d %H:%M:%S %Z %Y\fP\&'\&. +.RE +.TP +\fBdone\-file\fP +The location of the file to which events which have passed are appended\&. +The default is the calendar file location with the suffix \fB\&.done\fP\&. +The style may be set to an empty string in which case a "done" file +will not be maintained\&. +.TP +\fBreformat\-date\fP +Boolean, used by \fBcalendar_add\fP\&. If it is true, the date and time +of new entries added to the calendar will be reformatted to the format +given by the style \fBdate\-format\fP or its default\&. Only the date and +time of the event itself is reformatted; any subsidiary dates and times +such as those associated with repeat and warning times are left alone\&. +.TP +\fBshow\-prog\fP +The programme run by \fBcalendar\fP for showing events\&. It will +be passed the start time and stop time of the events requested in seconds +since the epoch followed by the event text\&. Note that \fBcalendar \-s\fP uses +a start time and stop time equal to one another to indicate alerts +for specific events\&. +.RS +.PP +The default is the function \fBcalendar_show\fP\&. +.RE +.TP +\fBwarn\-time\fP +The time before an event at which a warning will be displayed, if the +first line of the event does not include the text \fBEVENT\fP \fIreltime\fP\&. +The default is 5 minutes\&. +.PP +.SH "UTILITY FUNCTIONS" +.PP +.PD 0 +.TP +.PD +\fBcalendar_lockfiles\fP +Attempt to lock the files given in the argument\&. To prevent +problems with network file locking this is done in an ad hoc fashion +by attempting to create a symbolic link to the file with the name +\fIfile\fP\fB\&.lockfile\fP\&. No other system level functions are used +for locking, i\&.e\&. the file can be accessed and modified by any +utility that does not use this mechanism\&. In particular, the user is not +prevented from editing the calendar file at the same time unless +\fBcalendar_edit\fP is used\&. +.RS +.PP +Three attempts are made to lock the file before giving up\&. If the module +\fBzsh/zselect\fP is available, the times of the attempts are jittered so that +multiple instances of the calling function are unlikely to retry at the +same time\&. +.PP +The files locked are appended to the array \fBlockfiles\fP, which should +be local to the caller\&. +.PP +If all files were successfully locked, status zero is returned, else status one\&. +.PP +This function may be used as a general file locking function, although +this will only work if only this mechanism is used to lock files\&. +.RE +.TP +\fBcalendar_read\fP +This is a backend used by various other functions to parse the +calendar file, which is passed as the only argument\&. The array +\fBcalendar_entries\fP is set to the list of events in the file; no +pruning is done except that ampersands are removed from the start of +the line\&. Each entry may contain multiple lines\&. +.TP +\fBcalendar_scandate\fP +This is a generic function to parse dates and times that may be +used separately from the calendar system\&. The argument is a date +or time specification as described in +the section FILE AND DATE FORMATS above\&. The parameter \fBREPLY\fP +is set to the number of seconds since the epoch corresponding to that date +or time\&. By default, the date and time may occur anywhere within the given +argument\&. +.RS +.PP +Returns status zero if the date and time were successfully parsed, +else one\&. +.PP +Options: +.PD 0 +.TP +.PD +\fB\-a\fP +The date and time are anchored to the start of the argument; they +will not be matched if there is preceding text\&. +.TP +\fB\-A\fP +The date and time are anchored to both the start and end of the argument; +they will not be matched if the is any other text in the argument\&. +.TP +\fB\-d\fP +Enable additional debugging output\&. +.TP +\fB\-m\fP +Minus\&. When \fB\-R\fP \fIanchor_time\fP is also given the relative time is +calculated backwards from \fIanchor_time\fP\&. +.TP +\fB\-r\fP +The argument passed is to be parsed as a relative time\&. +.TP +\fB\-R\fP \fIanchor_time\fP +The argument passed is to be parsed as a relative time\&. The time is +relative to \fIanchor_time\fP, a time in seconds since the epoch, +and the returned value is the absolute time corresponding to advancing +\fIanchor_time\fP by the relative time given\&. +This allows lengths of months to be correctly taken into account\&. If +the final day does not exist in the given month, the last day of the +final month is given\&. For example, if the anchor time is during 31st +January 2007 and the relative time is 1 month, the final time is the +same time of day during 28th February 2007\&. +.TP +\fB\-s\fP +In addition to setting \fBREPLY\fP, set \fBREPLY2\fP to the remainder of +the argument after the date and time have been stripped\&. This is +empty if the option \fB\-A\fP was given\&. +.TP +\fB\-t\fP +Allow a time with no date specification\&. The date is assumed to be +today\&. The behaviour is unspecified if the iron tongue of midnight +is tolling twelve\&. +.RE +.TP +\fBcalendar_show\fP +The function used by default to display events\&. It accepts a start time +and end time for events, both in epoch seconds, and an event description\&. +.RS +.PP +The event is always printed to standard output\&. If the command line editor +is active (which will usually be the case) the command line will be +redisplayed after the output\&. +.PP +If the parameter \fBDISPLAY\fP is set and the start and end times are +the same (indicating a scheduled event), the function uses the +command \fBxmessage\fP to display a window with the event details\&. +.RE +.PP +.SH "BUGS" +.PP +As the system is based entirely on shell functions (with a little support +from the \fBzsh/datetime\fP module) the mechanisms used are not as robust as +those provided by a dedicated calendar utility\&. Consequently the user +should not rely on the shell for vital alerts\&. +.PP +There is no \fBcalendar_delete\fP function\&. +.PP +There is no localization support for dates and times, nor any support +for the use of time zones\&. +.PP +Relative periods of months and years do not take into account the variable +number of days\&. +.PP +The \fBcalendar_show\fP function is currently hardwired to use \fBxmessage\fP +for displaying alerts on X Window System displays\&. This should be +configurable and ideally integrate better with the desktop\&. +.PP +\fBcalendar_lockfiles\fP hangs the shell while waiting for a lock on a file\&. +If called from a scheduled task, it should instead reschedule the event +that caused it\&. diff --git a/Doc/zshcompctl.1 b/Doc/zshcompctl.1 new file mode 100644 index 000000000..ec9f58fe6 --- /dev/null +++ b/Doc/zshcompctl.1 @@ -0,0 +1,743 @@ +.TH "ZSHCOMPCTL" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshcompctl \- zsh programmable completion +.\" Yodl file: Zsh/compctl.yo +.SH "DESCRIPTION" +This version of zsh has two ways of performing completion of words on the +command line\&. New users of the shell may prefer to use the newer +and more powerful system based on shell functions; this is described in +\fIzshcompsys\fP(1), and the basic shell mechanisms which support it are +described in \fIzshcompwid\fP(1)\&. This manual entry describes the older +\fBcompctl\fP command\&. + +.PD 0 +.TP +\fBcompctl\fP [ \fB\-CDT\fP ] \fIoptions\fP [ \fIcommand\fP \&.\&.\&. ] +.TP +\fBcompctl \fP[ \fB\-CDT\fP ] \fIoptions\fP [ \fB\-x\fP \fIpattern\fP \fIoptions\fP \fB\-\fP \&.\&.\&. \fB\-\fP\fB\-\fP ] +.TP +\fB \fP[ \fB+\fP \fIoptions\fP [ \fB\-x\fP \&.\&.\&. \fB\-\fP\fB\-\fP ] \&.\&.\&. [\fB+\fP] ] [ \fIcommand\fP \&.\&.\&. ] +.TP +\fBcompctl\fP \fB\-M\fP \fImatch\-specs\fP \&.\&.\&. +.TP +\fBcompctl\fP \fB\-L\fP [ \fB\-CDTM\fP ] [ \fIcommand\fP \&.\&.\&. ] +.TP +\fBcompctl\fP \fB+\fP \fIcommand\fP \&.\&.\&. +.PD +.PP +Control the editor\&'s completion behavior according to the supplied set +of \fIoptions\fP\&. Various editing commands, notably +\fBexpand\-or\-complete\-word\fP, usually bound to tab, will +attempt to complete a word typed by the user, while others, notably +\fBdelete\-char\-or\-list\fP, usually bound to ^D in EMACS editing +mode, list the possibilities; \fBcompctl\fP controls what those +possibilities are\&. They may for example be filenames (the most common +case, and hence the default), shell variables, or words from a +user\-specified list\&. +.PP +.SH "COMMAND FLAGS" +Completion of the arguments of a command may be different for each +command or may use the default\&. The behavior when completing the +command word itself may also be separately specified\&. These +correspond to the following flags and arguments, all of which (except +for \fB\-L\fP) may be combined with any combination of the +\fIoptions\fP described subsequently in the section `Option Flags\&': +.PP +.PD 0 +.TP +.PD +\fIcommand\fP \&.\&.\&. +controls completion for the named commands, which must be listed last +on the command line\&. If completion is attempted for a command with a +pathname containing slashes and no completion definition is found, the +search is retried with the last pathname component\&. If the command starts +with a \fB=\fP, completion is tried with the pathname of the command\&. +.RS +.PP +Any of the \fIcommand\fP strings may be patterns of the form normally +used for filename generation\&. These should be quoted to protect them +from immediate expansion; for example the command string \fB\&'foo*'\fP +arranges for completion of the words of any command beginning with +\fBfoo\fP\&. When completion is attempted, all pattern completions are +tried in the reverse order of their definition until one matches\&. By +default, completion then proceeds as normal, i\&.e\&. the shell will try to +generate more matches for the specific command on the command line; this +can be overridden by including \fB\-tn\fP in the flags for the pattern +completion\&. +.PP +Note that aliases +are expanded before the command name is determined unless the +\fBCOMPLETE_ALIASES\fP option is set\&. Commands may not be combined +with the \fB\-C\fP, \fB\-D\fP or \fB\-T\fP flags\&. +.RE +.TP +\fB\-C\fP +controls completion when the command word itself is being completed\&. +If no \fBcompctl \-C\fP command has been issued, the names of any +executable command (whether in the path or specific to the shell, such +as aliases or functions) are completed\&. +.TP +\fB\-D\fP +controls default completion behavior for the arguments of commands not +assigned any special behavior\&. If no \fBcompctl \-D\fP command has +been issued, filenames are completed\&. +.TP +\fB\-T\fP +supplies completion flags to be used before any other processing is +done, even before processing for \fBcompctl\fPs defined for specific +commands\&. This is especially useful when combined with extended +completion (the \fB\-x\fP flag, see the section `Extended Completion\&' below)\&. +Using this flag you can define default behavior +which will apply to all commands without exception, or you can alter +the standard behavior for all commands\&. For example, if your access +to the user database is too slow and/or it contains too many users (so +that completion after `\fB~\fP\&' is too slow to be usable), you can use +.RS +.PP +.RS +.nf +\fBcompctl \-T \-x \&'s[~] C[0,[^/]#]' \-k friends \-S/ \-tn\fP +.fi +.RE +.PP +to complete the strings in the array \fBfriends\fP after a `\fB~\fP\&'\&. +The \fBC[\fP\fI\&.\&.\&.\fP\fB]\fP argument is necessary so that this form of +\fB~\fP\-completion is +not tried after the directory name is finished\&. +.RE +.TP +\fB\-L\fP +lists the existing completion behavior in a manner suitable for +putting into a start\-up script; the existing behavior is not changed\&. +Any combination of the above forms, or the \fB\-M\fP flag (which must +follow the \fB\-L\fP flag), may be specified, otherwise all defined +completions are listed\&. Any other flags supplied are ignored\&. +.TP +\fIno argument\fP +If no argument is given, \fBcompctl\fP lists all defined completions +in an abbreviated form; with a list of \fIoptions\fP, all completions +with those flags set (not counting extended completion) are listed\&. +.PP +If the \fB+\fP flag is alone and followed immediately by the \fIcommand\fP +list, the completion behavior for all the commands in the list is reset to +the default\&. In other words, completion will subsequently use the +options specified by the \fB\-D\fP flag\&. +.PP +The form with \fB\-M\fP as the first and only option defines global +matching specifications (see +zshcompwid)\&. The match specifications given will be used for every completion +attempt (only when using \fBcompctl\fP, not with the new completion +system) and are tried in the order in which they are defined until one +generates at least one match\&. E\&.g\&.: +.PP +.RS +.nf +\fBcompctl \-M \&'' 'm:{a\-zA\-Z}={A\-Za\-z}'\fP +.fi +.RE +.PP +This will first try completion without any global match specifications +(the empty string) and, if that generates no matches, will try case +insensitive completion\&. +.PP +.SH "OPTION FLAGS" +.PD 0 +.TP +[ \fB\-fcFBdeaRGovNAIOPZEnbjrzu/12\fP ] +.TP +[ \fB\-k\fP \fIarray\fP ] [ \fB\-g\fP \fIglobstring\fP ] [ \fB\-s\fP \fIsubststring\fP ] +.TP +[ \fB\-K\fP \fIfunction\fP ] +.TP +[ \fB\-Q\fP ] [ \fB\-P\fP \fIprefix\fP ] [ \fB\-S\fP \fIsuffix\fP ] +.TP +[ \fB\-W\fP \fIfile\-prefix\fP ] [ \fB\-H\fP \fInum pattern\fP ] +.TP +[ \fB\-q\fP ] [ \fB\-X\fP \fIexplanation\fP ] [ \fB\-Y\fP \fIexplanation\fP ] +.TP +[ \fB\-y\fP \fIfunc\-or\-var\fP ] [ \fB\-l\fP \fIcmd\fP ] [ \fB\-h\fP \fIcmd\fP ] [ \fB\-U\fP ] +.TP +[ \fB\-t\fP \fIcontinue\fP ] [ \fB\-J\fP \fIname\fP ] [ \fB\-V\fP \fIname\fP ] +.TP +[ \fB\-M\fP \fImatch\-spec\fP ] +.PD +.PP +The remaining \fIoptions\fP specify the type of command arguments +to look for during completion\&. Any combination of these flags may be +specified; the result is a sorted list of all the possibilities\&. The +options are as follows\&. +.PP +.SS "Simple Flags" +These produce completion lists made up by the shell itself: +.PP +.PD 0 +.TP +.PD +\fB\-f\fP +Filenames and file system paths\&. +.TP +\fB\-/\fP +Just file system paths\&. +.TP +\fB\-c\fP +Command names, including aliases, shell functions, builtins +and reserved words\&. +.TP +\fB\-F\fP +Function names\&. +.TP +\fB\-B\fP +Names of builtin commands\&. +.TP +\fB\-m\fP +Names of external commands\&. +.TP +\fB\-w\fP +Reserved words\&. +.TP +\fB\-a\fP +Alias names\&. +.TP +\fB\-R\fP +Names of regular (non\-global) aliases\&. +.TP +\fB\-G\fP +Names of global aliases\&. +.TP +\fB\-d\fP +This can be combined with \fB\-F\fP, \fB\-B\fP, \fB\-w\fP, +\fB\-a\fP, \fB\-R\fP and \fB\-G\fP to get names of disabled +functions, builtins, reserved words or aliases\&. +.TP +\fB\-e\fP +This option (to show enabled commands) is in effect by default, but +may be combined with \fB\-d\fP; \fB\-de\fP in combination with +\fB\-F\fP, \fB\-B\fP, \fB\-w\fP, \fB\-a\fP, \fB\-R\fP and \fB\-G\fP +will complete names of functions, builtins, reserved words or aliases +whether or not they are disabled\&. +.TP +\fB\-o\fP +Names of shell options (see +\fIzshoptions\fP(1))\&. +.TP +\fB\-v\fP +Names of any variable defined in the shell\&. +.TP +\fB\-N\fP +Names of scalar (non\-array) parameters\&. +.TP +\fB\-A\fP +Array names\&. +.TP +\fB\-I\fP +Names of integer variables\&. +.TP +\fB\-O\fP +Names of read\-only variables\&. +.TP +\fB\-p\fP +Names of parameters used by the shell (including special parameters)\&. +.TP +\fB\-Z\fP +Names of shell special parameters\&. +.TP +\fB\-E\fP +Names of environment variables\&. +.TP +\fB\-n\fP +Named directories\&. +.TP +\fB\-b\fP +Key binding names\&. +.TP +\fB\-j\fP +Job names: the first word of the job leader\&'s command line\&. This is useful +with the \fBkill\fP builtin\&. +.TP +\fB\-r\fP +Names of running jobs\&. +.TP +\fB\-z\fP +Names of suspended jobs\&. +.TP +\fB\-u\fP +User names\&. +.PP +.SS "Flags with Arguments" +These have user supplied arguments to determine how the list of +completions is to be made up: +.PP +.PD 0 +.TP +.PD +\fB\-k\fP \fIarray\fP +Names taken from the elements of \fB$\fP\fIarray\fP (note that the `\fB$\fP\&' +does not appear on the command line)\&. +Alternatively, the argument \fIarray\fP itself may be a set +of space\- or comma\-separated values in parentheses, in which any +delimiter may be escaped with a backslash; in this case the argument +should be quoted\&. For example, +.RS +.PP +.RS +.nf +\fBcompctl \-k "(cputime filesize datasize stacksize + coredumpsize resident descriptors)" limit\fP +.fi +.RE +.RE +.TP +\fB\-g\fP \fIglobstring\fP +The \fIglobstring\fP is expanded using filename globbing; it should be +quoted to protect it from immediate expansion\&. The resulting +filenames are taken as the possible completions\&. Use `\fB*(/)\fP\&' instead of +`\fB*/\fP\&' for directories\&. The \fBfignore\fP special parameter is not +applied to the resulting files\&. More than one pattern may be given +separated by blanks\&. (Note that brace expansion is \fInot\fP part of +globbing\&. Use the syntax `\fB(either|or)\fP\&' to match alternatives\&.) +.TP +\fB\-s\fP \fIsubststring\fP +The \fIsubststring\fP is split into words and these words are than +expanded using all shell expansion mechanisms (see +\fIzshexpn\fP(1))\&. The resulting words are taken as possible +completions\&. The \fBfignore\fP special parameter is not applied to the +resulting files\&. Note that \fB\-g\fP is faster for filenames\&. +.TP +\fB\-K\fP \fIfunction\fP +Call the given function to get the completions\&. Unless the name +starts with an underscore, the function is +passed two arguments: the prefix and the suffix of the word on which +completion is to be attempted, in other words those characters before +the cursor position, and those from the cursor position onwards\&. The +whole command line can be accessed with the \fB\-c\fP and \fB\-l\fP flags +of the \fBread\fP builtin\&. The +function should set the variable \fBreply\fP to an array containing +the completions (one completion per element); note that \fBreply\fP +should not be made local to the function\&. From such a function the +command line can be accessed with the \fB\-c\fP and \fB\-l\fP flags to +the \fBread\fP builtin\&. For example, +.RS +.PP +.RS +.nf +\fBfunction whoson { reply=(`users`); } +compctl \-K whoson talk\fP +.fi +.RE +.PP +completes only logged\-on users after `\fBtalk\fP\&'\&. Note that `\fBwhoson\fP' must +return an array, so `\fBreply=`users`\fP\&' would be incorrect\&. +.RE +.TP +\fB\-H\fP \fInum pattern\fP +The possible completions are taken from the last \fInum\fP history +lines\&. Only words matching \fIpattern\fP are taken\&. If \fInum\fP is +zero or negative the whole history is searched and if \fIpattern\fP is +the empty string all words are taken (as with `\fB*\fP\&')\&. A typical +use is +.RS +.PP +.RS +.nf +\fBcompctl \-D \-f + \-H 0 \&''\fP +.fi +.RE +.PP +which forces completion to look back in the history list for a word if +no filename matches\&. +.RE +.PP +.SS "Control Flags" +These do not directly specify types of name to be completed, but +manipulate the options that do: +.PP +.PD 0 +.TP +.PD +\fB\-Q\fP +This instructs the shell not to quote any metacharacters in the possible +completions\&. Normally the results of a completion are inserted into +the command line with any metacharacters quoted so that they are +interpreted as normal characters\&. This is appropriate for filenames +and ordinary strings\&. However, for special effects, such as inserting +a backquoted expression from a completion array (\fB\-k\fP) so that +the expression will not be evaluated until the complete line is +executed, this option must be used\&. +.TP +\fB\-P\fP \fIprefix\fP +The \fIprefix\fP is inserted just before the completed string; any +initial part already typed will be completed and the whole \fIprefix\fP +ignored for completion purposes\&. For example, +.RS +.PP +.RS +.nf +\fBcompctl \-j \-P "%" kill\fP +.fi +.RE +.PP +inserts a `%\&' after the kill command and then completes job names\&. +.RE +.TP +\fB\-S\fP \fIsuffix\fP +When a completion is found the \fIsuffix\fP is inserted after +the completed string\&. In the case of menu completion the suffix is +inserted immediately, but it is still possible to cycle through the +list of completions by repeatedly hitting the same key\&. +.TP +\fB\-W\fP \fIfile\-prefix\fP +With directory \fIfile\-prefix\fP: for command, file, directory and +globbing completion (options \fB\-c\fP, \fB\-f\fP, \fB\-/\fP, \fB\-g\fP), the file +prefix is implicitly added in front of the completion\&. For example, +.RS +.PP +.RS +.nf +\fBcompctl \-/ \-W ~/Mail maildirs\fP +.fi +.RE +.PP +completes any subdirectories to any depth beneath the directory +\fB~/Mail\fP, although that prefix does not appear on the command line\&. +The \fIfile\-prefix\fP may also be of the form accepted by the \fB\-k\fP +flag, i\&.e\&. the name of an array or a literal list in parenthesis\&. In +this case all the directories in the list will be searched for +possible completions\&. +.RE +.TP +\fB\-q\fP +If used with a suffix as specified by the \fB\-S\fP option, this +causes the suffix to be removed if the next character typed is a blank +or does not insert anything or if the suffix consists of only one character +and the next character typed is the same character; this the same rule used +for the \fBAUTO_REMOVE_SLASH\fP option\&. The option is most useful for list +separators (comma, colon, etc\&.)\&. +.TP +\fB\-l\fP \fIcmd\fP +This option restricts the range +of command line words that are considered to be arguments\&. If +combined with one of the extended completion patterns `\fBp[\fP\&.\&.\&.\fB]\fP\&', +`\fBr[\fP\&.\&.\&.\fB]\fP\&', or `\fBR[\fP\&.\&.\&.\fB]\fP' (see the section `Extended Completion' +below) the range is restricted to the range of arguments +specified in the brackets\&. Completion is then performed as if these +had been given as arguments to the \fIcmd\fP supplied with the +option\&. If the \fIcmd\fP string is empty the first word in the range +is instead taken as the command name, and command name completion +performed on the first word in the range\&. For example, +.RS +.PP +.RS +.nf +\fBcompctl \-x \&'r[\-exec,;]' \-l '' \-\- find\fP +.fi +.RE +.PP +completes arguments between `\fB\-exec\fP\&' and the following `\fB;\fP' (or the end +of the command line if there is no such string) as if they were +a separate command line\&. +.RE +.TP +\fB\-h\fP \fIcmd\fP +Normally zsh completes quoted strings as a whole\&. With this option, +completion can be done separately on different parts of such +strings\&. It works like the \fB\-l\fP option but makes the completion code +work on the parts of the current word that are separated by +spaces\&. These parts are completed as if they were arguments to the +given \fIcmd\fP\&. If \fIcmd\fP is the empty string, the first part is +completed as a command name, as with \fB\-l\fP\&. +.TP +\fB\-U\fP +Use the whole list of possible completions, whether or not they +actually match the word on the command line\&. The word typed so far +will be deleted\&. This is most useful with a function (given by the +\fB\-K\fP option) which can examine the word components passed to it +(or via the \fBread\fP builtin\&'s \fB\-c\fP and \fB\-l\fP flags) and +use its own criteria to decide what matches\&. If there is no +completion, the original word is retained\&. Since the produced +possible completions seldom have interesting common prefixes +and suffixes, menu completion is started immediately if \fBAUTO_MENU\fP is +set and this flag is used\&. +.TP +\fB\-y\fP \fIfunc\-or\-var\fP +The list provided by \fIfunc\-or\-var\fP is displayed instead of the list +of completions whenever a listing is required; the actual completions +to be inserted are not affected\&. It can be provided in two +ways\&. Firstly, if \fIfunc\-or\-var\fP begins with a \fB$\fP it defines a +variable, or if it begins with a left parenthesis a literal +array, which contains the list\&. A variable may have been set by a +call to a function using the \fB\-K\fP option\&. Otherwise it contains the +name of a function which will be executed to create the list\&. The +function will be passed as an argument list all matching completions, +including prefixes and suffixes expanded in full, and should set the +array \fBreply\fP to the result\&. In both cases, the display list will +only be retrieved after a complete list of matches has been created\&. +.RS +.PP +Note that the returned list does not have to correspond, even in +length, to the original set of matches, and may be passed as a scalar +instead of an array\&. No special formatting of characters is +performed on the output in this case; in particular, newlines are +printed literally and if they appear output in columns is suppressed\&. +.RE +.TP +\fB\-X\fP \fIexplanation\fP +Print \fIexplanation\fP when trying completion on the current set of +options\&. A `\fB%n\fP\&' in this string is replaced by the number of +matches that were added for this explanation string\&. +The explanation only appears if completion was tried and there was +no unique match, or when listing completions\&. Explanation strings +will be listed together with the matches of the group specified +together with the \fB\-X\fP option (using the \fB\-J\fP or \fB\-V\fP +option)\&. If the same explanation string is given to multiple \fB\-X\fP +options, the string appears only once (for each group) and the number +of matches shown for the `\fB%n\fP\&' is the total number of all matches +for each of these uses\&. In any case, the explanation string will only +be shown if there was at least one match added for the explanation +string\&. +.RS +.PP +The sequences \fB%B\fP, \fB%b\fP, \fB%S\fP, \fB%s\fP, \fB%U\fP, and \fB%u\fP specify +output attributes (bold, standout, and underline), \fB%F\fP, \fB%f\fP, \fB%K\fP, +\fB%k\fP specify foreground and background colours, and \fB%{\fP\fI\&.\&.\&.\fP\fB%}\fP can +be used to include literal escape sequences as in prompts\&. +.RE +.TP +\fB\-Y\fP \fIexplanation\fP +Identical to \fB\-X\fP, except that the \fIexplanation\fP first undergoes +expansion following the usual rules for strings in double quotes\&. +The expansion will be carried out after any functions are called for +the \fB\-K\fP or \fB\-y\fP options, allowing them to set variables\&. +.TP +\fB\-t\fP \fIcontinue\fP +The \fIcontinue\fP\-string contains a character that specifies which set +of completion flags should be used next\&. It is useful: +.RS +.PP +(i) With \fB\-T\fP, or when trying a list of pattern completions, when +\fBcompctl\fP would usually continue with ordinary processing after +finding matches; this can be suppressed with `\fB\-tn\fP\&'\&. +.PP +(ii) With a list of alternatives separated by \fB+\fP, when \fBcompctl\fP +would normally stop when one of the alternatives generates matches\&. It +can be forced to consider the next set of completions by adding `\fB\-t+\fP\&' +to the flags of the alternative before the `\fB+\fP\&'\&. +.PP +(iii) In an extended completion list (see below), when \fBcompctl\fP would +normally continue until a set of conditions succeeded, then use only +the immediately following flags\&. With `\fB\-t\-\fP\&', \fBcompctl\fP will +continue trying extended completions after the next `\fB\-\fP\&'; with +`\fB\-tx\fP\&' it will attempt completion with the default flags, in other +words those before the `\fB\-x\fP\&'\&. +.RE +.TP +\fB\-J\fP \fIname\fP +This gives the name of the group the matches should be placed in\&. Groups +are listed and sorted separately; likewise, menu completion will offer +the matches in the groups in the order in which the groups were +defined\&. If no group name is explicitly given, the matches are stored in +a group named \fBdefault\fP\&. The first time a group name is encountered, +a group with that name is created\&. After that all matches with the same +group name are stored in that group\&. +.RS +.PP +This can be useful with non\-exclusive alternative completions\&. For +example, in +.PP +.RS +.nf +\fBcompctl \-f \-J files \-t+ + \-v \-J variables foo\fP +.fi +.RE +.PP +both files and variables are possible completions, as the \fB\-t+\fP forces +both sets of alternatives before and after the \fB+\fP to be considered at +once\&. Because of the \fB\-J\fP options, however, all files are listed +before all variables\&. +.RE +.TP +\fB\-V\fP \fIname\fP +Like \fB\-J\fP, but matches within the group will not be sorted in listings +nor in menu completion\&. These unsorted groups are in a different name +space from the sorted ones, so groups defined as \fB\-J files\fP and \fB\-V +files\fP are distinct\&. +.TP +\fB\-1\fP +If given together with the \fB\-V\fP option, makes +only consecutive duplicates in the group be removed\&. Note that groups +with and without this flag are in different name spaces\&. +.TP +\fB\-2\fP +If given together with the \fB\-J\fP or \fB\-V\fP option, makes all +duplicates be kept\&. Again, groups with and without this flag are in +different name spaces\&. +.TP +\fB\-M\fP \fImatch\-spec\fP +This defines additional matching control specifications that should be used +only when testing words for the list of flags this flag appears in\&. The format +of the \fImatch\-spec\fP string is described in +zshcompwid\&. +.PP +.SH "ALTERNATIVE COMPLETION" +.PD 0 +.TP +\fBcompctl\fP [ \fB\-CDT\fP ] \fIoptions\fP \fB+\fP \fIoptions\fP [ \fB+\fP \&.\&.\&. ] [ \fB+\fP ] \fIcommand\fP \&.\&.\&. +.PD +.PP +The form with `\fB+\fP\&' specifies alternative options\&. Completion is +tried with the options before the first `\fB+\fP\&'\&. If this produces no +matches completion is tried with the flags after the `\fB+\fP\&' and so on\&. If +there are no flags after the last `\fB+\fP\&' and a match has not been found +up to that point, default completion is tried\&. +If the list of flags contains a \fB\-t\fP with a \fB+\fP character, the next +list of flags is used even if the current list produced matches\&. +.PP +.PP +Additional options are available that restrict completion to some part +of the command line; this is referred to as `extended completion\&'\&. +.PP +.SH "EXTENDED COMPLETION" + +.PD 0 +.TP +\fBcompctl \fP[ \fB\-CDT\fP ] \fIoptions\fP \fB\-x\fP \fIpattern\fP \fIoptions\fP \fB\-\fP \&.\&.\&. \fB\-\fP\fB\-\fP +.TP +\fB \fP[ \fIcommand\fP \&.\&.\&. ] +.TP +\fBcompctl \fP[ \fB\-CDT\fP ] \fIoptions\fP [ \fB\-x\fP \fIpattern\fP \fIoptions\fP \fB\-\fP \&.\&.\&. \fB\-\fP\fB\-\fP ] +.TP +\fB \fP[ \fB+\fP \fIoptions\fP [ \fB\-x\fP \&.\&.\&. \fB\-\fP\fB\-\fP ] \&.\&.\&. [\fB+\fP] ] [ \fIcommand\fP \&.\&.\&. ] +.PD +.PP +The form with `\fB\-x\fP\&' specifies extended completion for the +commands given; as shown, it may be combined with alternative +completion using `\fB+\fP\&'\&. Each \fIpattern\fP is examined in turn; when a +match is found, the corresponding \fIoptions\fP, as described in +the section `Option Flags\&' above, are used to generate possible +completions\&. If no \fIpattern\fP matches, the \fIoptions\fP given +before the \fB\-x\fP are used\&. +.PP +Note that each pattern should be supplied as a single argument and +should be quoted to prevent expansion of metacharacters by the +shell\&. +.PP +A \fIpattern\fP is built of sub\-patterns separated by commas; it +matches if at least one of these sub\-patterns matches (they are +`or\&'ed)\&. These sub\-patterns are in turn composed of other +sub\-patterns separated by white spaces which match if all of the +sub\-patterns match (they are `and\&'ed)\&. An element of the +sub\-patterns is of the form `\fIc\fP\fB[\fP\&.\&.\&.\fB][\fP\&.\&.\&.\fB]\fP\&', where the pairs of +brackets may be repeated as often as necessary, and matches if any of +the sets of brackets match (an `or\&')\&. The example below makes this +clearer\&. +.PP +The elements may be any of the following: +.PP +.PD 0 +.TP +.PD +\fBs[\fP\fIstring\fP\fB]\fP\&.\&.\&. +Matches if the current word on the command line starts with +one of the strings given in brackets\&. The \fIstring\fP is not removed +and is not part of the completion\&. +.TP +\fBS[\fP\fIstring\fP\fB]\fP\&.\&.\&. +Like \fBs[\fP\fIstring\fP\fB]\fP except that the \fIstring\fP is part of the +completion\&. +.TP +\fBp[\fP\fIfrom\fP\fB,\fP\fIto\fP\fB]\fP\&.\&.\&. +Matches if the number of the current word is between one of +the \fIfrom\fP and \fIto\fP pairs inclusive\&. The comma and \fIto\fP +are optional; \fIto\fP defaults to the same value as \fIfrom\fP\&. The +numbers may be negative: \fB\-\fP\fIn\fP refers to the \fIn\fP\&'th last word +on the line\&. +.TP +\fBc[\fP\fIoffset\fP\fB,\fP\fIstring\fP\fB]\fP\&.\&.\&. +Matches if the \fIstring\fP matches the word offset by +\fIoffset\fP from the current word position\&. Usually \fIoffset\fP +will be negative\&. +.TP +\fBC[\fP\fIoffset\fP\fB,\fP\fIpattern\fP\fB]\fP\&.\&.\&. +Like \fBc\fP but using pattern matching instead\&. +.TP +\fBw[\fP\fIindex\fP\fB,\fP\fIstring\fP\fB]\fP\&.\&.\&. +Matches if the word in position \fIindex\fP is equal +to the corresponding \fIstring\fP\&. Note that the word count is made +after any alias expansion\&. +.TP +\fBW[\fP\fIindex\fP\fB,\fP\fIpattern\fP\fB]\fP\&.\&.\&. +Like \fBw\fP but using pattern matching instead\&. +.TP +\fBn[\fP\fIindex\fP\fB,\fP\fIstring\fP\fB]\fP\&.\&.\&. +Matches if the current word contains \fIstring\fP\&. Anything up to and +including the \fIindex\fPth occurrence of this string will not be +considered part of the completion, but the rest will\&. \fIindex\fP may +be negative to count from the end: in most cases, \fIindex\fP will be +1 or \-1\&. For example, +.RS +.PP +.RS +.nf +\fBcompctl \-s \&'`users`' \-x 'n[1,@]' \-k hosts \-\- talk\fP +.fi +.RE +.PP +will usually complete usernames, but if you insert an \fB@\fP after the +name, names from the array \fIhosts\fP (assumed to contain hostnames, +though you must make the array yourself) will be completed\&. Other +commands such as \fBrcp\fP can be handled similarly\&. +.RE +.TP +\fBN[\fP\fIindex\fP\fB,\fP\fIstring\fP\fB]\fP\&.\&.\&. +Like \fBn\fP except that the string will be +taken as a character class\&. Anything up to and including the +\fIindex\fPth occurrence of any of the characters in \fIstring\fP +will not be considered part of the completion\&. +.TP +\fBm[\fP\fImin\fP\fB,\fP\fImax\fP\fB]\fP\&.\&.\&. +Matches if the total number of words lies between \fImin\fP and +\fImax\fP inclusive\&. +.TP +\fBr[\fP\fIstr1\fP\fB,\fP\fIstr2\fP\fB]\fP\&.\&.\&. +Matches if the cursor is after a word with prefix \fIstr1\fP\&. If there +is also a word with prefix \fIstr2\fP on the command line after the one +matched by \fIstr1\fP it matches +only if the cursor is before this word\&. If the comma and \fIstr2\fP are +omitted, it matches if the cursor is after a word with prefix \fIstr1\fP\&. +.TP +\fBR[\fP\fIstr1\fP\fB,\fP\fIstr2\fP\fB]\fP\&.\&.\&. +Like \fBr\fP but using pattern matching instead\&. +.TP +\fBq[\fP\fIstr\fP\fB]\fP\&.\&.\&. +Matches the word currently being completed is in single quotes and the +\fIstr\fP begins with the letter `s\&', or if completion is done in +double quotes and \fIstr\fP starts with the letter `d\&', or if +completion is done in backticks and \fIstr\fP starts with a `b\&'\&. +.PP +.SH "EXAMPLE" +.PP +.RS +.nf +\fBcompctl \-u \-x \&'s[+] c[\-1,\-f],s[\-f+]' \e + \-g \&'~/Mail/*(:t)' \- 's[\-f],c[\-1,\-f]' \-f \-\- mail\fP +.fi +.RE +.PP +This is to be interpreted as follows: +.PP +If the current command is \fBmail\fP, then +.PP +.RS +.nf + +if ((the current word begins with \fB+\fP and the previous word is \fB\-f\fP) +or (the current word begins with \fB\-f+\fP)), then complete the +non\-directory part (the `\fB:t\fP\&' glob modifier) of files in the directory +\fB~/Mail\fP; else +.PP +if the current word begins with \fB\-f\fP or the previous word was \fB\-f\fP, then +complete any file; else +.PP +complete user names\&. + +.fi +.RE diff --git a/Doc/zshcompsys.1 b/Doc/zshcompsys.1 new file mode 100644 index 000000000..f43924b46 --- /dev/null +++ b/Doc/zshcompsys.1 @@ -0,0 +1,5788 @@ +.TH "ZSHCOMPSYS" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshcompsys \- zsh completion system +.\" Yodl file: Zsh/compsys.yo +.SH "DESCRIPTION" +.PP +This describes the shell code for the `new\&' completion system, referred +to as \fBcompsys\fP\&. It is written in shell functions based on the +features described in +\fIzshcompwid\fP(1)\&. +.PP +The features are contextual, sensitive to the point at which completion is +started\&. Many completions are already provided\&. +For this reason, a user can perform a great many tasks without +knowing any details beyond how to initialize the system, which is +described +below in INITIALIZATION\&. +.PP +The context that decides what completion is to be performed may be +.PD 0 +.TP +.PD +\(bu +an argument or option position: these describe the position on the +command line at which completion is requested\&. For example `first argument +to rmdir, the word being completed names a directory\&'; + +.TP +\(bu +a special context, denoting an element in the shell\&'s syntax\&. For example +`a word in command position\&' or `an array subscript'\&. + +.PP +A full context specification contains other elements, as we shall describe\&. +.PP +Besides commands names and contexts, the system employs two more +concepts, \fIstyles\fP and \fItags\fP\&. These provide ways for the user +to configure the system\&'s behaviour\&. +.PP +Tags play a dual role\&. They serve as a classification system for +the matches, typically indicating a class of object that the user +may need to distinguish\&. For example, when completing arguments of the +\fBls\fP command the user may prefer to try \fBfiles\fP before \fBdirectories\fP, +so both of these are tags\&. They also appear as the rightmost +element in a context specification\&. +.PP +Styles modify various operations of the completion system, such as +output formatting, but also what kinds of completers are used (and in +what order), or which tags are examined\&. Styles may accept arguments +and are manipulated using the \fBzstyle\fP command described in +\fIzshmodules\fP(1)\&. +.PP +In summary, tags describe \fIwhat\fP the completion objects are, and style +\fBhow\fP they are to be completed\&. At various points of execution, the +completion system checks what styles and/or tags are defined for the +current context, and uses that to modify its behavior\&. The full +description of context handling, which determines how tags and other +elements of the context influence the behaviour of styles, is described +below in COMPLETION SYSTEM CONFIGURATION\&. +.PP +When a completion is requested, a dispatcher function is called; +see the description of \fB_main_complete\fP in the list of control functions +below\&. This dispatcher decides which function should +be called to produce the completions, and calls it\&. The result is +passed to one or more \fIcompleters\fP, functions that implement +individual completion strategies: simple completion, error correction, +completion with error correction, menu selection, etc\&. +.PP +More generally, the shell functions contained in the completion system are +of two types: +.PD 0 +.TP +.PD +\(bu +those beginning `\fBcomp\fP\&' are to be called directly; there are only +a few of these; + +.TP +\(bu +those beginning `\fB_\fP\&' are called by the +completion code\&. The shell functions of this set, which implement +completion behaviour and may be bound to keystrokes, are referred to +as `widgets\&'\&. These proliferate as new completions are required\&. + +.PP +.PP +.SH "INITIALIZATION" +.PP +If the system was installed completely, it should be enough to +call the shell function \fBcompinit\fP from your initialization file; see the +next section\&. However, the function \fBcompinstall\fP can be run by a user +to configure various aspects of the completion system\&. +.PP +Usually, \fBcompinstall\fP will insert code into \fB\&.zshrc\fP, although if +that is not writable it will save it in another file and tell you that +file\&'s location\&. Note that it is up to you to make sure that the lines +added to \fB\&.zshrc\fP are actually run; you may, for example, need to move +them to an earlier place in the file if \fB\&.zshrc\fP usually returns early\&. +So long as you keep them all together (including the comment lines at the +start and finish), you can rerun \fBcompinstall\fP and it will correctly +locate and modify these lines\&. Note, however, that any code you add to +this section by hand is likely to be lost if you rerun \fBcompinstall\fP, +although lines using the command `\fBzstyle\fP\&' should be gracefully handled\&. +.PP +The new code will take effect next time you start the shell, or run +\fB\&.zshrc\fP by hand; there is also an option to make them take effect +immediately\&. However, if \fBcompinstall\fP has removed definitions, you will +need to restart the shell to see the changes\&. +.PP +To run \fBcompinstall\fP you will need to make sure it is in a directory +mentioned in your \fBfpath\fP parameter, which should already be the case if +zsh was properly configured as long as your startup files do not remove the +appropriate directories from \fBfpath\fP\&. Then it must be autoloaded +(`\fBautoload \-U compinstall\fP\&' is recommended)\&. You can abort the +installation any time you are being prompted for information, and your +\fB\&.zshrc\fP will not be altered at all; changes only take place right at the +end, where you are specifically asked for confirmation\&. +.PP +.SS "Use of compinit" +.PP +This section describes the use of \fBcompinit\fP to initialize completion for +the current session when called directly; if you have run +\fBcompinstall\fP it will be called automatically from your \fB\&.zshrc\fP\&. +.PP +To initialize the system, the function \fBcompinit\fP should be in a +directory mentioned in the \fBfpath\fP parameter, and should be autoloaded +(`\fBautoload \-U compinit\fP\&' is recommended), and then run simply as +`\fBcompinit\fP\&'\&. This will define a +few utility functions, arrange for all the necessary shell functions to be +autoloaded, and will then re\-define all widgets that do completion to use the +new system\&. If you use the \fBmenu\-select\fP widget, which is part of the +\fBzsh/complist\fP module, you should make sure that that module is loaded +before the call to \fBcompinit\fP so that that widget is also +re\-defined\&. If completion styles (see below) are set up to perform +expansion as well as completion by default, and the TAB key is bound to +\fBexpand\-or\-complete\fP, \fBcompinit\fP will rebind it to \fBcomplete\-word\fP; +this is necessary to use the correct form of expansion\&. +.PP +Should you need to use the original completion commands, you can still +bind keys to the old widgets by putting a `\fB\&.\fP\&' in front of the +widget name, e\&.g\&. `\fB\&.expand\-or\-complete\fP\&'\&. +.PP +To speed up the running of \fBcompinit\fP, it can be made to produce a dumped +configuration that will be read in on future invocations; this is the +default, but can be turned off by calling \fBcompinit\fP with the +option \fB\-D\fP\&. The dumped file is \fB\&.zcompdump\fP in the same +directory as the startup files (i\&.e\&. \fB$ZDOTDIR\fP or \fB$HOME\fP); +alternatively, an explicit file name can be given by `\fBcompinit \-d\fP +\fIdumpfile\fP\&'\&. The next invocation of \fBcompinit\fP will read the dumped +file instead of performing a full initialization\&. +.PP +If the number of completion files changes, \fBcompinit\fP will recognise this +and produce a new dump file\&. However, if the name of a function or the +arguments in the first line of a \fB#compdef\fP function (as described below) +change, it is easiest to delete the dump file by hand so that +\fBcompinit\fP will re\-create it the next time it is run\&. The check +performed to see if there are new functions can be omitted by giving +the option \fB\-C\fP\&. In this case the dump file will only be created if +there isn\&'t one already\&. +.PP +The dumping is actually done by another function, \fBcompdump\fP, but you +will only need to run this yourself if you change the configuration +(e\&.g\&. using \fBcompdef\fP) and then want to dump the new one\&. The name of +the old dumped file will be remembered for this purpose\&. +.PP +If the parameter \fB_compdir\fP is set, \fBcompinit\fP uses it as a directory +where completion functions can be found; this is only necessary if they are +not already in the function search path\&. +.PP +For security reasons \fBcompinit\fP also checks if the completion system +would use files not owned by root or by the current user, or files in +directories that are world\- or group\-writable or that are not owned by +root or by the current user\&. If such files or directories are found, +\fBcompinit\fP will ask if the completion system should really be used\&. To +avoid these tests and make all files found be used without asking, use the +option \fB\-u\fP, and to make \fBcompinit\fP silently ignore all insecure files +and directories use the option \fB\-i\fP\&. This security check is skipped +entirely when the \fB\-C\fP option is given, provided the dumpfile exists\&. +.PP +The security check can be retried at any time by running the function +\fBcompaudit\fP\&. This is the same check used by \fBcompinit\fP, but when it +is executed directly any changes to \fBfpath\fP are made local to the +function so they do not persist\&. The directories to be checked may be +passed as arguments; if none are given, \fBcompaudit\fP uses \fBfpath\fP and +\fB_compdir\fP to find completion system directories, adding missing ones +to \fBfpath\fP as necessary\&. To force a check of exactly the directories +currently named in \fBfpath\fP, set \fB_compdir\fP to an empty string before +calling \fBcompaudit\fP or \fBcompinit\fP\&. +.PP +The function \fBbashcompinit\fP provides compatibility with bash\&'s programmable +completion system\&. When run it will define the functions, \fBcompgen\fP and +\fBcomplete\fP which correspond to the bash builtins with the same names\&. +It will then be possible to use completion specifications and functions +written for bash\&. +.PP +.SS "Autoloaded files" +.PP +The convention for autoloaded functions used in completion is that they +start with an underscore; as already mentioned, the \fBfpath/FPATH\fP +parameter must contain the directory in which they are stored\&. If \fBzsh\fP +was properly installed on your system, then \fBfpath/FPATH\fP automatically +contains the required directories for the standard functions\&. +.PP +For incomplete installations, if \fBcompinit\fP does not find enough files +beginning with an underscore (fewer than twenty) in the search path, it +will try to find more by adding the directory \fB_compdir\fP to the search +path\&. If that directory has a subdirectory named \fBBase\fP, all +subdirectories will be added to the path\&. Furthermore, if the subdirectory +\fBBase\fP has a subdirectory named \fBCore\fP, \fBcompinit\fP will add all +subdirectories of the subdirectories to the path: this allows +the functions to be in the same format as in the \fBzsh\fP source +distribution\&. +.PP +When \fBcompinit\fP is run, it searches all such files accessible via +\fBfpath/FPATH\fP and reads the first line of each of them\&. This line should +contain one of the tags described below\&. Files whose first line does not +start with one of these tags are not considered to be part of the +completion system and will not be treated specially\&. +.PP +The tags are: +.PP +.PD 0 +.TP +.PD +\fB#compdef\fP \fIname\fP \&.\&.\&. [ \fB\-\fP{\fBp\fP|\fBP\fP} \fIpattern\fP \&.\&.\&. [ \fB\-N\fP \fIname\fP \&.\&.\&. ] ] +The file will be made autoloadable and the function defined +in it will be called when completing \fIname\fPs, each of which is +either the name of a command whose arguments are to be completed or one of +a number of special contexts in the form \fB\-\fP\fIcontext\fP\fB\-\fP described +below\&. +.RS +.PP +Each \fIname\fP may also be of the form `\fIcmd\fP\fB=\fP\fIservice\fP\&'\&. +When completing the command \fIcmd\fP, the function typically behaves as +if the command (or special context) \fIservice\fP was being completed +instead\&. This provides a way of altering the behaviour of functions +that can perform many different completions\&. It is implemented +by setting the parameter \fB$service\fP when calling the function; +the function may choose to interpret this how it wishes, and simpler +functions will probably ignore it\&. +.PP +If the \fB#compdef\fP line contains one of the options \fB\-p\fP or \fB\-P\fP, +the words following are taken to be patterns\&. The function will be +called when completion is attempted for a command or context that matches +one of the patterns\&. The options \fB\-p\fP and \fB\-P\fP are used to specify +patterns to be tried before or after other completions respectively\&. +Hence \fB\-P\fP may be used to specify default actions\&. +.PP +The option \fB\-N\fP is used after a list following \fB\-p\fP or \fB\-P\fP; it +specifies that remaining words no longer define patterns\&. It is +possible to toggle between the three options as many times as necessary\&. +.RE +.TP +\fB#compdef \-k\fP \fIstyle key\-sequence\fP \&.\&.\&. +This option creates a widget behaving like the +builtin widget \fIstyle\fP and binds it to the given \fIkey\-sequence\fPs, +if any\&. The \fIstyle\fP must be one of the builtin widgets that perform +completion, namely \fBcomplete\-word\fP, \fBdelete\-char\-or\-list\fP, +\fBexpand\-or\-complete\fP, \fBexpand\-or\-complete\-prefix\fP, \fBlist\-choices\fP, +\fBmenu\-complete\fP, \fBmenu\-expand\-or\-complete\fP, or +\fBreverse\-menu\-complete\fP\&. If the \fBzsh/complist\fP module is loaded (see +\fIzshmodules\fP(1)) the widget \fBmenu\-select\fP is also available\&. +.RS +.PP +When one of the \fIkey\-sequence\fPs is typed, the function in the file will +be invoked to generate the matches\&. Note that a key will not be re\-bound +if it already was (that is, was bound to something other than +\fBundefined\-key\fP)\&. The widget created has the same name as the file and +can be bound to any other keys using \fBbindkey\fP as usual\&. +.RE +.TP +\fB#compdef \-K\fP \fIwidget\-name\fP \fIstyle\fP \fIkey\-sequence\fP [ \fIname\fP \fIstyle\fP \fIseq\fP \&.\&.\&. ] +This is similar to \fB\-k\fP except that only one \fIkey\-sequence\fP +argument may be given for each \fIwidget\-name\fP \fIstyle\fP pair\&. +However, the entire set of three arguments may be repeated with a +different set of arguments\&. Note in particular that the +\fIwidget\-name\fP must be distinct in each set\&. If it does not begin with +`\fB_\fP\&' this will be added\&. The \fIwidget\-name\fP should not clash with +the name of any existing widget: names based on the name of the function +are most useful\&. For example, +.RS +.PP +.RS +.nf +\fB#compdef \-K _foo_complete complete\-word "^X^C" \e + _foo_list list\-choices "^X^D"\fP +.fi +.RE +.PP +(all on one line) defines a widget \fB_foo_complete\fP for completion, bound +to `\fB^X^C\fP\&', and a widget \fB_foo_list\fP for listing, bound to `\fB^X^D\fP'\&. +.RE +.TP +\fB#autoload\fP [ \fIoptions\fP ] +Functions with the \fB#autoload\fP tag are marked for autoloading but +are not otherwise treated specially\&. Typically they are to be called +from within one of the completion functions\&. Any \fIoptions\fP supplied +will be passed to the \fBautoload\fP builtin; a typical use is \fB+X\fP to +force the function to be loaded immediately\&. Note that the \fB\-U\fP and +\fB\-z\fP flags are always added implicitly\&. +.PP +The \fB#\fP is part of the tag name and no white space is allowed after it\&. +The \fB#compdef\fP tags use the \fBcompdef\fP function described below; the +main difference is that the name of the function is supplied implicitly\&. +.PP +The special contexts for which completion functions can be defined are: +.PP +.PD 0 +.TP +.PD +\fB\-array\-value\-\fP +The right hand side of an array\-assignment +(`\fIname\fP\fB=(\fP\fI\&.\&.\&.\fP\fB)\fP\&') +.TP +\fB\-assign\-parameter\-\fP +The name of a parameter in an assignment, i\&.e\&. on the left hand side of +an `\fB=\fP\&' +.TP +\fB\-brace\-parameter\-\fP +The name of a parameter expansion within braces (`\fB${\fP\fI\&.\&.\&.\fP\fB}\fP\&') +.TP +\fB\-command\-\fP +A word in command position +.TP +\fB\-condition\-\fP +A word inside a condition (`\fB[[\fP\fI\&.\&.\&.\fP\fB]]\fP\&') +.TP +\fB\-default\-\fP +Any word for which no other completion is defined +.TP +\fB\-equal\-\fP +A word beginning with an equals sign +.TP +\fB\-first\-\fP +This is tried before any other completion function\&. The function called +may set the \fB_compskip\fP parameter to one of various values: +\fBall\fP: no further completion is attempted; a string +containing the substring \fBpatterns\fP: no pattern completion functions +will be called; a string containing \fBdefault\fP: the +function for the `\fB\-default\-\fP\&' context will not be called, but +functions defined for commands will be\&. +.TP +\fB\-math\-\fP +Inside mathematical contexts, such as +`\fB((\fP\fI\&.\&.\&.\fP\fB))\fP\&' +.TP +\fB\-parameter\-\fP +The name of a parameter expansion (`\fB$\fP\fI\&.\&.\&.\fP\&') +.TP +\fB\-redirect\-\fP +The word after a redirection operator\&. +.TP +\fB\-subscript\-\fP +The contents of a parameter subscript\&. +.TP +\fB\-tilde\-\fP +After an initial tilde (`\fB~\fP\&'), but before the first slash +in the word\&. +.TP +\fB\-value\-\fP +On the right hand side of an assignment\&. +.PP +Default implementations are supplied for each of these +contexts\&. In most cases the context \fB\-\fP\fIcontext\fP\fB\-\fP is +implemented by a corresponding function \fB_\fP\fIcontext\fP, for example +the context `\fB\-tilde\-\fP\&' and the function `\fB_tilde\fP')\&. +.PP +The contexts \fB\-redirect\-\fP and \fB\-value\-\fP allow extra context\-specific +information\&. (Internally, this is handled by the functions for each +context calling the function \fB_dispatch\fP\&.) The extra +information is added separated by commas\&. +.PP +For the \fB\-redirect\-\fP context, the extra information is in the form +`\fB\-redirect\-,\fP\fIop\fP\fB,\fP\fIcommand\fP\&', where \fIop\fP is the +redirection operator and \fIcommand\fP is the name of the command on +the line\&. If there is no command on the line yet, the \fIcommand\fP +field will be empty\&. +.PP +For the \fB\-value\-\fP context, the form is +`\fB\-value\-,\fP\fIname\fP\fB,\fP\fIcommand\fP\&', where \fIname\fP is the name of +the parameter on the left hand side of the assignment\&. +In the case of elements of an associative array, for +example `\fBassoc=(key <TAB>\fP\&', \fIname\fP is expanded to +`\fIname\fP\fB\-\fP\fIkey\fP\&'\&. In certain special contexts, such as +completing after `\fBmake CFLAGS=\fP\&', the \fIcommand\fP part gives the +name of the command, here \fBmake\fP; otherwise it is empty\&. +.PP +It is not necessary to define fully specific completions as the +functions provided will try to generate completions by progressively +replacing the elements with `\fB\-default\-\fP\&'\&. For example, when +completing after `\fBfoo=<TAB>\fP\&', \fB_value\fP will try the names +`\fB\-value\-,foo,\fP\&' (note the empty \fIcommand\fP part), +`\fB\-value\-,foo,\-default\-\fP\&' and`\fB\-value\-,\-default\-,\-default\-\fP', in +that order, until it finds a function to handle the context\&. +.PP +As an example: +.PP +.RS +.nf +\fBcompdef \&'_files \-g "*\&.log"' '\-redirect\-,2>,\-default\-'\fP +.fi +.RE +.PP +completes files matching `\fB*\&.log\fP\&' after `\fB2> <TAB>\fP' for any +command with no more specific handler defined\&. +.PP +Also: +.PP +.RS +.nf +\fBcompdef _foo \-value\-,\-default\-,\-default\-\fP +.fi +.RE +.PP +specifies that \fB_foo\fP provides completions for the values of +parameters for which no special function has been defined\&. This is +usually handled by the function \fB_value\fP itself\&. +.PP +The same lookup rules are used when looking up styles (as described +below); for example +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:\-redirect\-,2>,*:*' file\-patterns '*\&.log'\fP +.fi +.RE +.PP +is another way to make completion after `\fB2> <TAB>\fP\&' complete files +matching `\fB*\&.log\fP\&'\&. +.PP +.SS "Functions" +.PP +The following function is defined by \fBcompinit\fP and may be called +directly\&. +.PP +.PD 0 + +.TP +.PD 0 +\fBcompdef\fP [ \fB\-ane\fP ] \fIfunction name\fP \&.\&.\&. [ \fB\-\fP{\fBp\fP|\fBP\fP} \fIpattern\fP \&.\&.\&. [ \fB\-N\fP \fIname\fP \&.\&.\&.]] +.TP +.PD 0 +\fBcompdef \-d\fP \fIname\fP \&.\&.\&. +.TP +.PD 0 +\fBcompdef \-k\fP [ \fB\-an\fP ] \fIfunction style key\-sequence\fP [ \fIkey\-sequence\fP \&.\&.\&. ] +.TP +.PD +\fBcompdef \-K\fP [ \fB\-an\fP ] \fIfunction name style key\-seq\fP [ \fIname style seq\fP \&.\&.\&. ] +The first form defines the \fIfunction\fP to call for completion in the +given contexts as described for the \fB#compdef\fP tag above\&. +.RS +.PP +Alternatively, all the arguments may have the form +`\fIcmd\fP\fB=\fP\fIservice\fP\&'\&. Here \fIservice\fP should already have been +defined by `\fIcmd1\fP\fB=\fP\fIservice\fP\&' lines in \fB#compdef\fP files, as +described above\&. The argument for \fIcmd\fP will be completed in the +same way as \fIservice\fP\&. +.PP +The \fIfunction\fP argument may alternatively be a string containing +almost any shell code\&. If the string contains an equal sign, the above +will take precedence\&. The option \fB\-e\fP may be used to specify the first +argument is to be evaluated as shell code even if it contains an equal +sign\&. The string will be executed using the \fBeval\fP builtin command to +generate completions\&. This provides a way of avoiding having to define +a new completion function\&. For example, to complete files ending in +`\fB\&.h\fP\&' as arguments to the command \fBfoo\fP: +.PP +.RS +.nf +\fBcompdef \&'_files \-g "*\&.h"' foo\fP +.fi +.RE +.PP +The option \fB\-n\fP prevents any completions already defined for the +command or context from being overwritten\&. +.PP +The option \fB\-d\fP deletes any completion defined for the command or +contexts listed\&. +.PP +The \fIname\fPs may also contain \fB\-p\fP, \fB\-P\fP and \fB\-N\fP options as +described for the \fB#compdef\fP tag\&. The effect on the argument list is +identical, switching between definitions of patterns tried initially, +patterns tried finally, and normal commands and contexts\&. +.PP +The parameter \fB$_compskip\fP may be set by any function defined for a +pattern context\&. If it is set to a value containing the substring +`\fBpatterns\fP\&' none of the pattern\-functions will be called; if it is +set to a value containing the substring `\fBall\fP\&', no other function +will be called\&. Setting \fB$_compskip\fP in this manner is of particular +utility when using the \fB\-p\fP option, as otherwise the dispatcher will +move on to additional functions (likely the default one) after calling +the pattern\-context one, which can mangle the display of completion +possibilities if not handled properly\&. +.PP +The form with \fB\-k\fP defines a widget with the same name as the \fIfunction\fP +that will be called for each of the \fIkey\-sequence\fPs; this is like the +\fB#compdef \-k\fP tag\&. The function should generate the completions needed +and will otherwise behave like the builtin widget whose name is given as +the \fIstyle\fP argument\&. The widgets usable for this are: +\fBcomplete\-word\fP, \fBdelete\-char\-or\-list\fP, \fBexpand\-or\-complete\fP, +\fBexpand\-or\-complete\-prefix\fP, \fBlist\-choices\fP, \fBmenu\-complete\fP, +\fBmenu\-expand\-or\-complete\fP, and \fBreverse\-menu\-complete\fP, as well as +\fBmenu\-select\fP if the \fBzsh/complist\fP module is loaded\&. The option \fB\-n\fP +prevents the key being bound if it is already to bound to something other +than \fBundefined\-key\fP\&. +.PP +The form with \fB\-K\fP is similar and defines multiple widgets based on the +same \fIfunction\fP, each of which requires the set of three arguments +\fIname\fP, \fIstyle\fP and \fIkey\-seq\fPuence, where the latter two are as +for \fB\-k\fP and the first must be a unique widget name beginning with an +underscore\&. +.PP +Wherever applicable, the \fB\-a\fP option makes the \fIfunction\fP +autoloadable, equivalent to \fBautoload \-U \fP\fIfunction\fP\&. +.RE +.PP +The function \fBcompdef\fP can be used to associate existing completion +functions with new commands\&. For example, +.PP +.RS +.nf +\fBcompdef _pids foo\fP +.fi +.RE +.PP +uses the function \fB_pids\fP to complete process IDs for the command \fBfoo\fP\&. +.PP +Note also the \fB_gnu_generic\fP function described below, which can be +used to complete options for commands that understand the +`\fB\-\fP\fB\-help\fP\&' option\&. +.PP +.SH "COMPLETION SYSTEM CONFIGURATION" +.PP +This section gives a short overview of how the completion system works, +and then more detail on how users can configure how and when matches are +generated\&. +.PP +.SS "Overview" +.PP +When completion is attempted somewhere on the command line the +completion system begins building the context\&. The context represents +everything that the shell knows about the meaning of the command line +and the significance of the cursor position\&. This takes account of a +number of things including the command word (such as `\fBgrep\fP\&' or +`\fBzsh\fP\&') and options to which the current word may be an argument +(such as the `\fB\-o\fP\&' option to \fBzsh\fP which takes a shell option as an +argument)\&. +.PP +The context starts out very generic ("we are beginning a completion") +and becomes more specific as more is learned ("the current word is in a +position that is usually a command name" or "the current word might be a +variable name" and so on)\&. Therefore the context will vary during the +same call to the completion system\&. +.PP +This context information is condensed into a string consisting of multiple +fields separated by colons, referred to simply as `the context\&' in the +remainder of the documentation\&. Note that a user of the completion system +rarely needs to compose a context string, unless for example a new +function is being written to perform completion for a new command\&. What a +user may need to do is compose a \fIstyle\fP pattern, which is matched +against a context when needed to look up context\-sensitive options that +configure the completion system\&. +.PP +The next few paragraphs explain how a context is composed within the +completion function suite\&. Following that is discussion of how \fIstyles\fP +are defined\&. Styles determine such things as how the matches are +generated, similarly to shell options but with much more control\&. They +are defined with the \fBzstyle\fP builtin command (see \fIzshmodules\fP(1))\&. +.PP +The context string always consists of a fixed set of fields, separated +by colons and with a leading colon before the first\&. Fields which are +not yet known are left empty, but the surrounding colons appear anyway\&. +The fields are always in the order +\fB:completion:\fP\fIfunction\fP\fB:\fP\fIcompleter\fP\fB:\fP\fIcommand\fP\fB:\fP\fIargument\fP\fB:\fP\fItag\fP\&. These have the following meaning: +.PP +.PD 0 +.TP +.PD +\(bu +The literal string \fBcompletion\fP, saying that this style is used by +the completion system\&. This distinguishes the context from those used +by, for example, zle widgets and ZFTP functions\&. + +.TP +\(bu +The \fIfunction\fP, if completion is called from a named widget rather +than through the normal completion system\&. Typically this is blank, but +it is set by special widgets such as \fBpredict\-on\fP and the various +functions in the \fBWidget\fP directory of the distribution to the name of +that function, often in an abbreviated form\&. + +.TP +\(bu +The \fIcompleter\fP currently active, the name of the function without the +leading underscore and with other underscores converted to hyphens\&. A +`completer\&' is in overall control of how completion is to be performed; +`\fBcomplete\fP\&' is the simplest, but other completers exist to perform +related tasks such as correction, or to modify the behaviour of a later +completer\&. See +the section `Control Functions\&' below +for more information\&. + +.TP +\(bu +The \fIcommand\fP or a special \fB\-\fP\fIcontext\fP\fB\-\fP, just at it appears +following the \fB#compdef\fP tag or the \fBcompdef\fP function\&. Completion +functions for commands that have sub\-commands usually modify this field +to contain the name of the command followed by a minus sign and the +sub\-command\&. For example, the completion function for the \fBcvs\fP +command sets this field to \fBcvs\-add\fP when completing arguments to +the \fBadd\fP subcommand\&. + +.TP +\(bu +The \fIargument\fP; this indicates which command line or option argument +we are completing\&. For command arguments this generally takes the form +\fBargument\-\fP\fIn\fP, where \fIn\fP is the number of the argument, +and for arguments to options the form \fBoption\-\fP\fIopt\fP\fB\-\fP\fIn\fP +where \fIn\fP is the number of the argument to option \fIopt\fP\&. However, +this is only the case if the command line is parsed with standard +UNIX\-style options and arguments, so many completions do not set this\&. + +.TP +\(bu +The \fItag\fP\&. As described previously, tags are used to discriminate between +the types of matches a completion function can generate in a certain context\&. +Any completion function may use any tag name it likes, but a list of the +more common ones is given below\&. + +.PP +The context is gradually put together as the functions are executed, starting +with the main entry point, which adds \fB:completion:\fP and the \fIfunction\fP +element if necessary\&. The completer then adds the \fIcompleter\fP element\&. +The contextual completion adds the \fIcommand\fP and \fIargument\fP options\&. +Finally, the \fItag\fP is added when the types of completion are known\&. +For example, the context name +.PP +.RS +.nf +\fB\fB:completion::complete:dvips:option\-o\-1:files\fP\fP +.fi +.RE +.PP +says that normal completion was attempted as the first argument to the +option \fB\-o\fP of the command \fBdvips\fP: +.PP +.RS +.nf +\fB\fBdvips \-o \&.\&.\&.\fP\fP +.fi +.RE +.PP +and the completion function will generate filenames\&. +.PP +Usually completion will be tried for all possible tags in an order given +by the completion function\&. However, this can be altered by using the +\fBtag\-order\fP style\&. Completion is then restricted to the list of given +tags in the given order\&. +.PP +The \fB_complete_help\fP bindable command shows all the contexts and tags +available for completion at a particular point\&. This provides an easy +way of finding information for \fBtag\-order\fP and other styles\&. It is +described in +the section `Bindable Commands\&' below\&. +.PP +When looking up styles the completion system uses full context names, +including the tag\&. Looking up the value of a style therefore consists of +two things: the context, which is matched to the most specific (best +fitting) pattern, and the name of the style itself, which must be +matched exactly\&. The following examples demonstrate that patterns +may be loosely defined for styles that apply broadly, or as tightly +defined as desired for styles that apply in narrower circumstances\&. +.PP +For example, many completion functions can generate matches in a +simple and a verbose form and use the \fBverbose\fP style to decide +which form should be used\&. To make all such functions use the verbose form, +put +.PP +.RS +.nf +\fBzstyle \&':completion:*' verbose yes\fP +.fi +.RE +.PP +in a startup file (probably \fB\&.zshrc\fP)\&. +This gives the \fBverbose\fP style the value \fByes\fP in every +context inside the completion system, unless that context has a more +specific definition\&. It is best to avoid giving the pattern as `\fB*\fP\&' +in case the style has some meaning outside the completion system\&. +.PP +Many such general purpose styles can be configured simply by using the +\fBcompinstall\fP function\&. +.PP +A more specific example of the use of the \fBverbose\fP style is by the +completion for the \fBkill\fP builtin\&. If the style is set, the builtin +lists full job texts and process command lines; otherwise it shows the +bare job numbers and PIDs\&. To turn the style off for this use only: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:kill:*:*' verbose no\fP +.fi +.RE +.PP +For even more control, the style can use one of the tags `\fBjobs\fP\&' or +`\fBprocesses\fP\&'\&. To turn off verbose display only for jobs: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:kill:*:jobs' verbose no\fP +.fi +.RE +.PP +The \fB\-e\fP option to \fBzstyle\fP even allows completion function code to +appear as the argument to a style; this requires some understanding of +the internals of completion functions (see +see \fIzshcompwid\fP(1)))\&. For example, +.PP +.RS +.nf +\fB\fBzstyle \-e \&':completion:*' hosts 'reply=($myhosts)'\fP\fP +.fi +.RE +.PP +This forces the value of the \fBhosts\fP style to be read from the +variable \fBmyhosts\fP each time a host name is needed; this is useful +if the value of \fBmyhosts\fP can change dynamically\&. +For another useful example, see the example in the description of the +\fBfile\-list\fP style below\&. This form can be +slow and should be avoided for commonly examined styles such +as \fBmenu\fP and \fBlist\-rows\-first\fP\&. +.PP +Note that the order in which styles are \fIdefined\fP does not matter; the +style mechanism uses the most specific possible match for a particular +style to determine the set of values\&. Strings are +preferred over patterns (for example, `\fB:completion::complete:::foo\fP\&' is +more specific than `\fB:completion::complete:::*\&'\fP), and longer patterns are +preferred over the pattern `\fB*\fP\&'\&. See +\fIzmodules\fP(1) +for details\&. +.PP +Context patterns that use something other than a wildcard (\fB*\fP) to match the +middle parts of the context \-\- the \fIcompleter\fP, \fIcommand\fP, and +\fIargument\fP in +\fB:completion:\fP\fIfunction\fP\fB:\fP\fIcompleter\fP\fB:\fP\fIcommand\fP\fB:\fP\fIargument\fP\fB:\fP\fItag\fP +\-\- should include all six colons (\fB:\fP) explicitly\&. Without this, +a pattern such as \fB:completion:*:foo:*\fP could match \fBfoo\fP against a +component other than the intended one (for example, against \fIcompleter\fP when +a match against \fIcommand\fP was intended)\&. +.PP +Style names like those of tags are arbitrary and depend on the completion +function\&. However, the following two sections list some of the most +common tags and styles\&. +.PP +.SS "Standard Tags" +.PP +Some of the following are only used when looking up particular styles +and do not refer to a type of match\&. +.PP +.PD 0 +.TP +.PD +\fBaccounts\fP +used to look up the \fBusers\-hosts\fP style +.TP +\fBall\-expansions\fP +used by the \fB_expand\fP completer when adding the single string containing +all possible expansions +.TP +\fBall\-files\fP +for the names of all files (as distinct from a particular subset, see the +\fBglobbed\-files\fP tag)\&. +.TP +\fBarguments\fP +for arguments to a command +.TP +\fBarrays\fP +for names of array parameters +.TP +\fBassociation\-keys\fP +for keys of associative arrays; used when completing inside a +subscript to a parameter of this type +.TP +\fBbookmarks\fP +when completing bookmarks (e\&.g\&. for URLs and the \fBzftp\fP function suite) +.TP +\fBbuiltins\fP +for names of builtin commands +.TP +\fBcharacters\fP +for single characters in arguments of commands such as \fBstty\fP\&. Also used +when completing character classes after an opening bracket +.TP +\fBcolormapids\fP +for X colormap ids +.TP +\fBcolors\fP +for color names +.TP +\fBcommands\fP +for names of external commands\&. Also used by complex commands such as +\fBcvs\fP when completing names subcommands\&. +.TP +\fBcontexts\fP +for contexts in arguments to the \fBzstyle\fP builtin command +.TP +\fBcorrections\fP +used by the \fB_approximate\fP and \fB_correct\fP completers for possible +corrections +.TP +\fBcursors\fP +for cursor names used by X programs +.TP +\fBdefault\fP +used in some contexts to provide a way of supplying a default when more +specific tags are also valid\&. Note that this tag is +used when only the \fIfunction\fP field of the context name is set +.TP +\fBdescriptions\fP +used when looking up the value of the \fBformat\fP style to generate +descriptions for types of matches +.TP +\fBdevices\fP +for names of device special files +.TP +\fBdirectories\fP +for names of directories \-\- \fBlocal\-directories\fP is used instead +when completing arguments of \fBcd\fP and related builtin commands when +the \fBcdpath\fP array is set +.TP +\fBdirectory\-stack\fP +for entries in the directory stack +.TP +\fBdisplays\fP +for X display names +.TP +\fBdomains\fP +for network domains +.TP +\fBemail\-\fP\fIplugin\fP +for email addresses from the `\fB_email\-\fP\fIplugin\fP\&' backend of \fB_email_addresses\fP +.TP +\fBexpansions\fP +used by the \fB_expand\fP completer for individual words (as opposed to +the complete set of expansions) resulting from the expansion of a word +on the command line +.TP +\fBextensions\fP +for X server extensions +.TP +\fBfile\-descriptors\fP +for numbers of open file descriptors +.TP +\fBfiles\fP +the generic file\-matching tag used by functions completing filenames +.TP +\fBfonts\fP +for X font names +.TP +\fBfstypes\fP +for file system types (e\&.g\&. for the \fBmount\fP command) +.TP +\fBfunctions\fP +names of functions \-\- normally shell functions, although certain +commands may understand other kinds of function +.TP +\fBglobbed\-files\fP +for filenames when the name has been generated by pattern matching +.TP +\fBgroups\fP +for names of user groups +.TP +\fBhistory\-words\fP +for words from the history +.TP +\fBhosts\fP +for hostnames +.TP +\fBindexes\fP +for array indexes +.TP +\fBinterfaces\fP +for network interfaces +.TP +\fBjobs\fP +for jobs (as listed by the `\fBjobs\fP\&' builtin) +.TP +\fBkeymaps\fP +for names of zsh keymaps +.TP +\fBkeysyms\fP +for names of X keysyms +.TP +\fBlibraries\fP +for names of system libraries +.TP +\fBlimits\fP +for system limits +.TP +\fBlocal\-directories\fP +for names of directories that are subdirectories of the current working +directory when completing arguments of \fBcd\fP and related builtin +commands (compare \fBpath\-directories\fP) \-\- when the \fBcdpath\fP +array is unset, \fBdirectories\fP is used instead +.TP +\fBmailboxes\fP +for e\-mail folders +.TP +\fBmanuals\fP +for names of manual pages +.TP +\fBmaps\fP +for map names (e\&.g\&. NIS maps) +.TP +\fBmessages\fP +used to look up the \fBformat\fP style for messages +.TP +\fBmodifiers\fP +for names of X modifiers +.TP +\fBmodules\fP +for modules (e\&.g\&. \fBzsh\fP modules) +.TP +\fBmy\-accounts\fP +used to look up the \fBusers\-hosts\fP style +.TP +\fBnamed\-directories\fP +for named directories (you wouldn\&'t have guessed that, would you?) +.TP +\fBnames\fP +for all kinds of names +.TP +\fBnewsgroups\fP +for USENET groups +.TP +\fBnicknames\fP +for nicknames of NIS maps +.TP +\fBoptions\fP +for command options +.TP +\fBoriginal\fP +used by the \fB_approximate\fP, \fB_correct\fP and \fB_expand\fP completers when +offering the original string as a match +.TP +\fBother\-accounts\fP +used to look up the \fBusers\-hosts\fP style +.TP +\fBpackages\fP +for packages (e\&.g\&. \fBrpm\fP or installed \fBDebian\fP packages) +.TP +\fBparameters\fP +for names of parameters +.TP +\fBpath\-directories\fP +for names of directories found by searching the \fBcdpath\fP array when +completing arguments of \fBcd\fP and related builtin commands (compare +\fBlocal\-directories\fP) +.TP +\fBpaths\fP +used to look up the values of the \fBexpand\fP, \fBambiguous\fP and +\fBspecial\-dirs\fP styles +.TP +\fBpods\fP +for perl pods (documentation files) +.TP +\fBports\fP +for communication ports +.TP +\fBprefixes\fP +for prefixes (like those of a URL) +.TP +\fBprinters\fP +for print queue names +.TP +\fBprocesses\fP +for process identifiers +.TP +\fBprocesses\-names\fP +used to look up the \fBcommand\fP style when generating the names of +processes for \fBkillall\fP +.TP +\fBsequences\fP +for sequences (e\&.g\&. \fBmh\fP sequences) +.TP +\fBsessions\fP +for sessions in the \fBzftp\fP function suite +.TP +\fBsignals\fP +for signal names +.TP +\fBstrings\fP +for strings (e\&.g\&. the replacement strings for the \fBcd\fP builtin +command) +.TP +\fBstyles\fP +for styles used by the zstyle builtin command +.TP +\fBsuffixes\fP +for filename extensions +.TP +\fBtags\fP +for tags (e\&.g\&. \fBrpm\fP tags) +.TP +\fBtargets\fP +for makefile targets +.TP +\fBtime\-zones\fP +for time zones (e\&.g\&. when setting the \fBTZ\fP parameter) +.TP +\fBtypes\fP +for types of whatever (e\&.g\&. address types for the \fBxhost\fP command) +.TP +\fBurls\fP +used to look up the \fBurls\fP and \fBlocal\fP styles when completing URLs +.TP +\fBusers\fP +for usernames +.TP +\fBvalues\fP +for one of a set of values in certain lists +.TP +\fBvariant\fP +used by \fB_pick_variant\fP to look up the command to run when determining +what program is installed for a particular command name\&. +.TP +\fBvisuals\fP +for X visuals +.TP +\fBwarnings\fP +used to look up the \fBformat\fP style for warnings +.TP +\fBwidgets\fP +for zsh widget names +.TP +\fBwindows\fP +for IDs of X windows +.TP +\fBzsh\-options\fP +for shell options +.PP +.SS "Standard Styles" +.PP +Note that the values of several of these styles represent boolean +values\&. Any of the strings `\fBtrue\fP\&', `\fBon\fP', +`\fByes\fP\&', and `\fB1\fP' can be used for the value `true' and +any of the strings `\fBfalse\fP\&', `\fBoff\fP', `\fBno\fP', and `\fB0\fP' for +the value `false\&'\&. The behavior for any other value is undefined +except where explicitly mentioned\&. The default value may +be either `true\&' or `false' if the style is not set\&. +.PP +Some of these styles are tested first for every possible tag +corresponding to a type of match, and if no style was found, for the +\fBdefault\fP tag\&. The most notable styles of this type are \fBmenu\fP, +\fBlist\-colors\fP and styles controlling completion listing such as +\fBlist\-packed\fP and \fBlast\-prompt\fP\&. When tested for the \fBdefault\fP +tag, only the \fIfunction\fP field of the context will be set so that +a style using the \fBdefault\fP tag will normally be defined along the lines of: +.PP +.RS +.nf +\fBzstyle \&':completion:*:default' menu \&.\&.\&.\fP +.fi +.RE +.PP +.PD 0 +.TP +.PD +\fBaccept\-exact\fP +This is tested for the \fBdefault\fP tag in addition to the tags valid for +the current context\&. If it is set to `true\&' and any of the trial +matches is the same as the string on the command line, this match will +immediately be accepted (even if it would otherwise be considered +ambiguous)\&. +.RS +.PP +When completing pathnames (where the tag used is `\fBpaths\fP\&') +this style accepts any number of patterns as the value in addition to +the boolean values\&. Pathnames matching one of these +patterns will be accepted immediately even if the command line contains +some more partially typed pathname components and these match no file +under the directory accepted\&. +.PP +This style is also used by the \fB_expand\fP completer to decide if +words beginning with a tilde or parameter expansion should be +expanded\&. For example, if there are parameters +\fBfoo\fP and \fBfoobar\fP, the string `\fB$foo\fP\&' will only be expanded if +\fBaccept\-exact\fP is set to `true\&'; otherwise the completion system will +be allowed to complete \fB$foo\fP to \fB$foobar\fP\&. If the style is set to +`\fBcontinue\fP\&', \fB_expand\fP will add the expansion as a match and the completion +system will also be allowed to continue\&. +.RE +.TP +\fBaccept\-exact\-dirs\fP +This is used by filename completion\&. Unlike \fBaccept\-exact\fP it is +a boolean\&. By default, filename completion examines all components +of a path to see if there are completions of that component, even if +the component matches an existing directory\&. For example, when +completion after \fB/usr/bin/\fP, the function examines possible +completions to \fB/usr\fP\&. +.RS +.PP +When this style is `true\&', any prefix of a path that matches an existing +directory is accepted without any attempt to complete it further\&. +Hence, in the given example, the path \fB/usr/bin/\fP is accepted +immediately and completion tried in that directory\&. +.PP +This style is also useful when completing after directories that +magically appear when referenced, such as ZFS \fB\&.zfs\fP directories +or NetApp \fB\&.snapshot\fP directories\&. When the style is set the +shell does not check for the existence of the directory within the +parent directory\&. +.PP +If you wish to inhibit this behaviour entirely, set the \fBpath\-completion\fP +style (see below) to `false\&'\&. +.RE +.TP +\fBadd\-space\fP +This style is used by the \fB_expand\fP completer\&. If it is `true\&' (the +default), a space will be inserted after all words resulting from the +expansion, or a slash in the case of directory names\&. If the value +is `\fBfile\fP\&', the completer will only add a space +to names of existing files\&. Either a boolean `true\&' or the value +`\fBfile\fP\&' may be combined with `\fBsubst\fP', in which case the completer +will not add a space to words generated from the expansion of a +substitution of the form `\fB$(\fP\fI\&.\&.\&.\fP\fB)\fP\&' or `\fB${\fP\fI\&.\&.\&.\fP\fB}\fP'\&. +.RS +.PP +The \fB_prefix\fP completer uses this style as a simple boolean value +to decide if a space should be inserted before the suffix\&. +.RE +.TP +\fBambiguous\fP +This applies when completing non\-final components of filename paths, in +other words those with a trailing slash\&. If it is set, the cursor is +left after the first ambiguous component, even if menu completion is in +use\&. The style is always tested with the \fBpaths\fP tag\&. +.TP +\fBassign\-list\fP +When completing after an equals sign that is being treated as an +assignment, the completion system normally completes only one filename\&. +In some cases the value may be a list of filenames separated by colons, +as with \fBPATH\fP and similar parameters\&. This style can be set to a +list of patterns matching the names of such parameters\&. +.RS +.PP +The default is to complete lists when the word on the line already +contains a colon\&. +.RE +.TP +\fBauto\-description\fP +If set, this style\&'s value will be used as the description for options that +are not described by the completion functions, but that have exactly +one argument\&. The sequence `\fB%d\fP\&' in the value will be replaced by +the description for this argument\&. Depending on personal preferences, +it may be useful to set this style to something like `\fBspecify: %d\fP\&'\&. +Note that this may not work for some commands\&. +.TP +\fBavoid\-completer\fP +This is used by the \fB_all_matches\fP completer to decide if the string +consisting of all matches should be added to the list currently being +generated\&. Its value is a list of names of completers\&. If any of +these is the name of the completer that generated the matches in this +completion, the string will not be added\&. +.RS +.PP +The default value for this style is `\fB_expand _old_list _correct +_approximate\fP\&', i\&.e\&. it contains the completers for which a string +with all matches will almost never be wanted\&. +.RE +.TP +\fBcache\-path\fP +This style defines the path where any cache files containing dumped +completion data are stored\&. It defaults to `\fB$ZDOTDIR/\&.zcompcache\fP\&', or +`\fB$HOME/\&.zcompcache\fP\&' if \fB$ZDOTDIR\fP is not defined\&. The completion +cache will not be used unless the \fBuse\-cache\fP style is set\&. +.TP +\fBcache\-policy\fP +This style defines the function that will be used to determine whether +a cache needs rebuilding\&. See the section on the \fB_cache_invalid\fP +function below\&. +.TP +\fBcall\-command\fP +This style is used in the function for commands such as \fBmake\fP and +\fBant\fP where calling the command directly to generate matches suffers +problems such as being slow or, as in the case of \fBmake\fP can +potentially cause actions in the makefile to be executed\&. If it is set +to `true\&' the command is called to generate matches\&. The default value +of this style is `false\&'\&. +.TP +\fBcommand\fP +In many places, completion functions need to call external commands to +generate the list of completions\&. This style can be used to override the +command that is called in some such cases\&. The elements of the value are +joined with spaces to form a command line to execute\&. The value can also +start with a hyphen, in which case the usual command will be added to the +end; this is most useful for putting `\fBbuiltin\fP\&' or `\fBcommand\fP' in +front to make sure the appropriate version of a command is called, for +example to avoid calling a shell function with the same name as an external +command\&. +.RS +.PP +As an example, the completion function for process IDs uses this +style with the \fBprocesses\fP tag to generate the IDs to complete and +the list of processes to display (if the \fBverbose\fP style is `true\&')\&. +The list produced by the command should look like the output of the +\fBps\fP command\&. The first line is not displayed, but is searched for +the string `\fBPID\fP\&' (or `\fBpid\fP') to find the position of the +process IDs in the following lines\&. If the line does not contain +`\fBPID\fP\&', the first numbers in each of the other lines are taken as the +process IDs to complete\&. +.PP +Note that the completion function generally has to call the specified +command for each attempt to generate the completion list\&. Hence +care should be taken to specify only commands that take a short +time to run, and in particular to avoid any that may never terminate\&. +.RE +.TP +\fBcommand\-path\fP +This is a list of directories to search for commands to complete\&. The +default for this style is the value of the special parameter \fBpath\fP\&. +.TP +\fBcommands\fP +This is used by the function completing sub\-commands for the system +initialisation scripts (residing in \fB/etc/init\&.d\fP or somewhere not +too far away from that)\&. Its values give the default commands to +complete for those commands for which the completion function isn\&'t +able to find them out automatically\&. The default for this style are +the two strings `\fBstart\fP\&' and `\fBstop\fP'\&. +.TP +\fBcomplete\fP +This is used by the \fB_expand_alias\fP function when invoked as a +bindable command\&. If set to `true\&' and the word on the command +line is not the name of an alias, matching alias names will be +completed\&. +.TP +\fBcomplete\-options\fP +This is used by the completer for \fBcd\fP, \fBchdir\fP and \fBpushd\fP\&. +For these commands a \fB\-\fP is used to introduce a directory stack entry +and completion of these is far more common than completing options\&. +Hence unless the value of this style is `true\&' options will not be +completed, even after an initial \fB\-\fP\&. If it is `true\&', options will +be completed after an initial \fB\-\fP unless there is a preceding +\fB\-\fP\fB\-\fP on the command line\&. +.TP +\fBcompleter\fP +The strings given as the value of this style provide the names of the +completer functions to use\&. The available completer functions are +described in +the section `Control Functions\&' below\&. +.RS +.PP +Each string may be either the name of a completer function or a string +of the form `\fIfunction\fP\fB:\fP\fIname\fP\&'\&. In the first case the +\fIcompleter\fP field of the context will contain the name of the +completer without the leading underscore and with all other +underscores replaced by hyphens\&. In the second case the +\fIfunction\fP is the name of the completer to call, but the context +will contain the user\-defined \fIname\fP in the \fIcompleter\fP field of +the context\&. If the \fIname\fP starts with a hyphen, the string for the +context will be build from the name of the completer function as in +the first case with the \fIname\fP appended to it\&. For example: +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer _complete _complete:\-foo\fP +.fi +.RE +.PP +Here, completion will call the \fB_complete\fP completer twice, once +using `\fBcomplete\fP\&' and once using `\fBcomplete\-foo\fP' in the +\fIcompleter\fP field of the context\&. Normally, using the same +completer more than once only makes sense when used with the +`\fIfunctions\fP\fB:\fP\fIname\fP\&' form, because otherwise the context +name will be the same in all calls to the completer; possible +exceptions to this rule are the \fB_ignored\fP and \fB_prefix\fP +completers\&. +.PP +The default value for this style is `\fB_complete _ignored\fP\&': +only completion will be done, first using the \fBignored\-patterns\fP style +and the \fB$fignore\fP array and then without ignoring matches\&. +.RE +.TP +\fBcondition\fP +This style is used by the \fB_list\fP completer function to decide if +insertion of matches should be delayed unconditionally\&. The default is +`true\&'\&. +.TP +\fBdelimiters\fP +This style is used when adding a delimiter for use with history +modifiers or glob qualifiers that have delimited arguments\&. It is +an array of preferred delimiters to add\&. Non\-special characters are +preferred as the completion system may otherwise become confused\&. +The default list is \fB:\fP, \fB+\fP, \fB/\fP, \fB\-\fP, \fB%\fP\&. The list +may be empty to force a delimiter to be typed\&. +.TP +\fBdisabled\fP +If this is set to `true\&', the \fB_expand_alias\fP completer and bindable +command will try to expand disabled aliases, too\&. The default is +`false\&'\&. +.TP +\fBdomains\fP +A list of names of network domains for completion\&. +If this is not set, domain names will be taken from +the file \fB/etc/resolv\&.conf\fP\&. +.TP +\fBenviron\fP +The environ style is used when completing for `\fBsudo\fP\&'\&. It is set to an +array of `\fIVAR\fP\fB=\fP\fIvalue\fP\&' assignments to be exported into the +local environment before the completion for the target command is invoked\&. +.RS +.nf +\fBzstyle \&':completion:*:sudo::' environ \e + PATH="/sbin:/usr/sbin:$PATH" HOME="/root"\fP +.fi +.RE +.TP +\fBexpand\fP +This style is used when completing strings consisting of multiple +parts, such as path names\&. +.RS +.PP +If one of its values is the string `\fBprefix\fP\&', the partially typed +word from the line will be expanded as far as possible even if trailing +parts cannot be completed\&. +.PP +If one of its values is the string `\fBsuffix\fP\&', matching names for +components after the first ambiguous one will also be added\&. This means +that the resulting string is the longest unambiguous string possible\&. +However, menu completion can be used to cycle through all matches\&. +.RE +.TP +\fBextra\-verbose\fP +If set, the completion listing is more verbose at the cost of +a probable decrease in completion speed\&. Completion performance +will suffer if this style is set to `true\&'\&. +.TP +\fBfake\fP +This style may be set for any completion context\&. It +specifies additional strings that will always be completed in that +context\&. The form of each string is `\fIvalue\fP\fB:\fP\fIdescription\fP\&'; +the colon and description may be omitted, but any literal colons in +\fIvalue\fP must be quoted with a backslash\&. Any \fIdescription\fP +provided is shown alongside the value in completion listings\&. +.RS +.PP +It is important to use a sufficiently restrictive context when specifying +fake strings\&. Note that the styles \fBfake\-files\fP and \fBfake\-parameters\fP +provide additional features when completing files or parameters\&. +.RE +.TP +\fBfake\-always\fP +This works identically to the \fBfake\fP style except that +the \fBignored\-patterns\fP style is not applied to it\&. This makes it +possible to override a set of matches completely by setting the +ignored patterns to `\fB*\fP\&'\&. +.RS +.PP +The following shows a way of supplementing any tag with arbitrary data, but +having it behave for display purposes like a separate tag\&. In this example +we use the features of the \fBtag\-order\fP style to divide the +\fBnamed\-directories\fP tag into two when performing completion with +the standard completer \fBcomplete\fP for arguments of \fBcd\fP\&. The tag +\fBnamed\-directories\-normal\fP behaves as normal, but the tag +\fBnamed\-directories\-mine\fP contains a fixed set of directories\&. +This has the effect of adding the match group `\fBextra directories\fP\&' with +the given completions\&. +.PP +.RS +.nf +\fBzstyle \&':completion::complete:cd:*' tag\-order \e + \&'named\-directories:\-mine:extra\e directories + named\-directories:\-normal:named\e directories *\&' +zstyle \&':completion::complete:cd:*:named\-directories\-mine' \e + fake\-always mydir1 mydir2 +zstyle \&':completion::complete:cd:*:named\-directories\-mine' \e + ignored\-patterns \&'*'\fP +.fi +.RE +.RE +.TP +\fBfake\-files\fP +This style is used when completing files and looked up +without a tag\&. Its values are of the form +`\fIdir\fP\fB:\fP\fInames\&.\&.\&.\fP\&'\&. This will add the \fInames\fP (strings +separated by spaces) as +possible matches when completing in the directory \fIdir\fP, even if no +such files really exist\&. The dir may be a pattern; pattern characters +or colons in \fIdir\fP should be quoted with a backslash to be treated +literally\&. +.RS +.PP +This can be useful on systems that support special file systems whose +top\-level pathnames can not be listed or generated with glob patterns +(but see \fBaccept\-exact\-dirs\fP for a more general way of dealing +with this problem)\&. It can also be used for directories for which one +does not have read permission\&. +.PP +The pattern form can be used to add a certain `magic\&' entry +to all directories on a particular file system\&. +.RE +.TP +\fBfake\-parameters\fP +This is used by the completion function for parameter names\&. +Its values are names of parameters that might not yet be +set but should be completed nonetheless\&. Each name may also be +followed by a colon and a string specifying the type of the parameter +(like `\fBscalar\fP\&', `\fBarray\fP' or `\fBinteger\fP')\&. If the type is +given, the name will only be completed if parameters of that type are +required in the particular context\&. Names for which no type is +specified will always be completed\&. +.TP +\fBfile\-list\fP +This style controls whether files completed using the standard builtin +mechanism are to be listed with a long list similar to \fBls \-l\fP\&. +Note that this feature uses the shell module +\fBzsh/stat\fP for file information; this loads the builtin \fBstat\fP +which will replace any external \fBstat\fP executable\&. To avoid +this the following code can be included in an initialization file: +.RS +.PP +.RS +.nf +\fBzmodload \-i zsh/stat +disable stat\fP +.fi +.RE +.PP +The style may either be set to a `true\&' value (or `\fBall\fP'), or +one of the values `\fBinsert\fP\&' or `\fBlist\fP', indicating that files +are to be listed in long format in all circumstances, or when +attempting to insert a file name, or when listing file names +without attempting to insert one\&. +.PP +More generally, the value may be an array of any of the above values, +optionally followed by \fB=\fP\fInum\fP\&. If \fInum\fP is present it +gives the maximum number of matches for which long listing style +will be used\&. For example, +.PP +.RS +.nf +\fBzstyle \&':completion:*' file\-list list=20 insert=10\fP +.fi +.RE +.PP +specifies that long format will be used when listing up to 20 files +or inserting a file with up to 10 matches (assuming a listing +is to be shown at all, for example on an ambiguous completion), else short +format will be used\&. +.PP +.RS +.nf +\fBzstyle \-e \&':completion:*' file\-list \e + \&'(( ${+NUMERIC} )) && reply=(true)'\fP +.fi +.RE +.PP +specifies that long format will be used any time a numeric argument is +supplied, else short format\&. +.RE +.TP +\fBfile\-patterns\fP +This is used by the standard function for completing filenames, +\fB_files\fP\&. If the style is unset up to three tags are offered, +`\fBglobbed\-files\fP\&',`\fBdirectories\fP' and `\fBall\-files\fP', depending on +the types of files expected by the caller of \fB_files\fP\&. The first two +(`\fBglobbed\-files\fP\&' and `\fBdirectories\fP') are normally offered +together to make it easier to complete files in sub\-directories\&. +.RS +.PP +The \fBfile\-patterns\fP style provides alternatives to the default tags, +which are not used\&. Its value consists of elements of the form +`\fIpattern\fP\fB:\fP\fItag\fP\&'; each string may contain any number of +such specifications separated by spaces\&. +.PP +The \fIpattern\fP is a pattern that is to be used to generate filenames\&. +Any occurrence of the sequence `\fB%p\fP\&' is replaced by any +pattern(s) +passed by the function calling \fB_files\fP\&. Colons in the pattern must +be preceded by a backslash to make them distinguishable from the colon +before the \fItag\fP\&. If more than one pattern is needed, the patterns +can be given inside braces, separated by commas\&. +.PP +The \fItag\fPs of all strings in the value will be offered by \fB_files\fP +and used when looking up other styles\&. Any \fItag\fPs in the same +word will be offered at the same time and before later words\&. +If no `\fB:\fP\fItag\fP\&' is given the `\fBfiles\fP' tag will be used\&. +.PP +The \fItag\fP may also be followed by an optional second colon and a +description, which will be used for the `\fB%d\fP\&' in the value of +the \fBformat\fP style (if that is set) instead of the default +description supplied by the completion function\&. The inclusion +of a description also gives precedence to associated options such as +for completion grouping so it can be used where files should be +separated\&. +.PP +For example, to make the \fBrm\fP command first complete only names of +object files and then the names of all files if there is no matching +object file: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:rm:*:*' file\-patterns \e + \&'*\&.o:object\-files' '%p:all\-files'\fP +.fi +.RE +.PP +To alter the default behaviour of file completion \-\- offer files +matching a pattern and directories on the first attempt, then all files +\-\- to offer only matching files on the first attempt, then directories, +and finally all files: +.PP +.RS +.nf +\fBzstyle \&':completion:*' file\-patterns \e + \&'%p:globbed\-files' '*(\-/):directories' '*:all\-files'\fP +.fi +.RE +.PP +This works even where there is no special pattern: \fB_files\fP matches +all files using the pattern `\fB*\fP\&' at the first step and stops when it +sees this pattern\&. Note also it will never try a pattern more than once +for a single completion attempt\&. +.PP +To separate directories into a separate group from the files but still +complete them at the first attempt, a description needs to be given\&. +Note that directories need to be explicitly excluded from the +globbed\-files because `\fB*\fP\&' will match directories\&. For grouping, it +is also necessary to set the \fBgroup\-name\fP style\&. +.PP +.RS +.nf +\fBzstyle \&':completion:*' file\-patterns \e + \&'%p(^\-/):globbed\-files *(\-/):directories:location'\fP +.fi +.RE +.PP +During the execution of completion functions, the \fBEXTENDED_GLOB\fP +option is in effect, so the characters `\fB#\fP\&', `\fB~\fP' and `\fB^\fP' have +special meanings in the patterns\&. +.RE +.TP +\fBfile\-sort\fP +The standard filename completion function uses this style without a tag +to determine in which order the names should be listed; menu completion +will cycle through them in the same order\&. The possible +values are: `\fBsize\fP\&' to sort by the size of the file; +`\fBlinks\fP\&' to sort by the number of links to the file; +`\fBmodification\fP\&' (or `\fBtime\fP' or `\fBdate\fP') to sort by the last +modification time; `\fBaccess\fP\&' to sort by the last access time; and +`\fBinode\fP\&' (or `\fBchange\fP') to sort by the last inode change +time\&. If the style is set to any other value, or is unset, files will be +sorted alphabetically by name\&. If the value contains the string +`\fBreverse\fP\&', sorting is done in the opposite order\&. If the value +contains the string `\fBfollow\fP\&', timestamps are associated with the +targets of symbolic links; the default is to use the timestamps +of the links themselves\&. +.TP +\fBfile\-split\-chars\fP +A set of characters that will cause \fIall\fP file completions for +the given context to be split at the point where any of the characters +occurs\&. A typical use is to set the style to \fB:\fP; then everything +up to and including the last \fB:\fP in the string so far is ignored when +completing files\&. As this is quite heavy\-handed, it is usually +preferable to update completion functions for contexts where this +behaviour is useful\&. +.TP +\fBfilter\fP +The \fBldap\fP plugin of email address completion (see \fB_email_addresses\fP) uses +this style to specify +the attributes to match against when filtering entries\&. So for example, if +the style is set to `\fBsn\fP\&', matching is done against surnames\&. Standard +LDAP filtering is used so normal completion matching is bypassed\&. If this +style is not set, the LDAP plugin is skipped\&. You may also need to set the +\fBcommand\fP style to specify how to connect to your LDAP server\&. +.TP +\fBforce\-list\fP +This forces a list of completions to be shown at any point where listing is +done, even in cases where the list would usually be suppressed\&. +For example, normally the list is only shown if +there are at least two different matches\&. By setting this style to +`\fBalways\fP\&', the list will always be shown, even if there is only a +single match that will immediately be accepted\&. The style may also +be set to a number\&. In this case the list will be shown if there are +at least that many matches, even if they would all insert the same +string\&. +.RS +.PP +This style is tested for the default tag as well as for each tag valid +for the current completion\&. Hence the listing can be forced only for +certain types of match\&. +.RE +.TP +\fBformat\fP +If this is set for the \fBdescriptions\fP tag, its value is used as a +string to display above matches in completion lists\&. The sequence +`\fB%d\fP\&' in this string will be replaced with a short description of +what these matches are\&. This string may also contain the output +attribute sequences understood by \fBcompadd \-X\fP +(see +\fIzshcompwid\fP(1))\&. +.RS +.PP +The style is tested with each tag valid for the current completion +before it is tested for the \fBdescriptions\fP tag\&. Hence different format +strings can be defined for different types of match\&. +.PP +Note also that some completer functions define additional +`\fB%\fP\&'\-sequences\&. These are described for the completer functions that +make use of them\&. +.PP +Some completion functions display messages that may be customised by +setting this style for the \fBmessages\fP tag\&. Here, the `\fB%d\fP\&' is +replaced with a message given by the completion function\&. +.PP +Finally, the format string is looked up with the \fBwarnings\fP tag, +for use when no matches could be generated at all\&. In this case the +`\fB%d\fP\&' is replaced with the descriptions for the matches that were +expected separated by spaces\&. The sequence `\fB%D\fP\&' is replaced with +the same descriptions separated by newlines\&. +.PP +It is possible to use printf\-style field width specifiers with `\fB%d\fP\&' +and similar escape sequences\&. This is handled by the \fBzformat\fP +builtin command from the \fBzsh/zutil\fP module, see +\fIzshmodules\fP(1)\&. +.RE +.TP +\fBgain\-privileges\fP +If set to \fBtrue\fP, this style enables the use of commands like \fBsudo\fP +or \fBdoas\fP to gain extra privileges when retrieving information for +completion\&. This is only done when a command such as \fBsudo\fP appears on +the command\-line\&. To force the use of, e\&.g\&. \fBsudo\fP or to override any +prefix that might be added due to \fBgain\-privileges\fP, the \fBcommand\fP +style can be used with a value that begins with a hyphen\&. +.TP +\fBglob\fP +This is used by the \fB_expand\fP completer\&. If +it is set to `true\&' (the default), globbing will be attempted on the +words resulting from a previous substitution (see the \fBsubstitute\fP +style) or else the original string from the line\&. +.TP +\fBglobal\fP +If this is set to `true\&' (the default), the \fB_expand_alias\fP +completer and bindable command will try to expand global aliases\&. +.TP +\fBgroup\-name\fP +The completion system can group different types of matches, which appear +in separate lists\&. This style can be used to give the names of groups +for particular tags\&. For example, in command position the completion +system generates names of builtin and external commands, names of +aliases, shell functions and parameters and reserved words as possible +completions\&. To have the external commands and shell functions listed +separately: +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:\-command\-:*:commands' \e + group\-name commands +zstyle \&':completion:*:*:\-command\-:*:functions' \e + group\-name functions\fP +.fi +.RE +.PP +As a consequence, any match with the same tag will be displayed in the +same group\&. +.PP +If the name given is the empty string the name of the tag for +the matches will be used as the name of the group\&. So, to have all +different types of matches displayed separately, one can just set: +.PP +.RS +.nf +\fBzstyle \&':completion:*' group\-name ''\fP +.fi +.RE +.PP +All matches for which no group name is defined will be put in a group +named \fB\-default\-\fP\&. +.PP +To display the group name in the output, see the \fBformat\fP style (q\&.v\&.) +under the \fBdescriptions\fP tag\&. +.RE +.TP +\fBgroup\-order\fP +This style is additional to the \fBgroup\-name\fP style to specify the +order for display of the groups defined by that style (compare \fBtag\-order\fP, +which determines which completions appear at all)\&. The groups named +are shown in the given order; any other groups +are shown in the order defined by the completion function\&. +.RS +.PP +For example, to have names of builtin commands, shell functions and +external commands appear in that order when completing in command +position: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:\-command\-:*:*' group\-order \e + builtins functions commands\fP +.fi +.RE +.RE +.TP +\fBgroups\fP +A list of names of UNIX groups\&. If this is not set, +group names are taken from the YP database or the file `\fB/etc/group\fP\&'\&. +.TP +\fBhidden\fP +If this is set to `true\&', matches for the given context +will not be listed, although +any description for the matches set with the \fBformat\fP style will be +shown\&. If it is set to `\fBall\fP\&', not even the description will be +displayed\&. +.RS +.PP +Note that the matches will still be completed; they are just not shown +in the list\&. To avoid having matches considered as possible +completions at all, the \fBtag\-order\fP style can be modified as described +below\&. +.RE +.TP +\fBhosts\fP +A list of names of hosts that should be completed\&. If this is not set, +hostnames are taken from the file `\fB/etc/hosts\fP\&'\&. +.TP +\fBhosts\-ports\fP +This style is used by commands that need or accept hostnames and +network ports\&. The strings in the value should be of the form +`\fIhost\fP\fB:\fP\fIport\fP\&'\&. Valid ports are determined by the presence +of hostnames; multiple ports for the same host may appear\&. +.TP +\fBignore\-line\fP +This is tested for each tag valid for the current completion\&. If +it is set to `true\&', none of the words that are already on the line +will be considered as possible completions\&. If it is set to +`\fBcurrent\fP\&', the word the cursor is on will not be considered as a +possible completion\&. The value `\fBcurrent\-shown\fP\&' is similar but only +applies if the list of completions is currently shown on the screen\&. +Finally, if the style is set to `\fBother\fP\&', all words on the line except +for the current one will be excluded from the possible completions\&. +.RS +.PP +The values `\fBcurrent\fP\&' and `\fBcurrent\-shown\fP' are a bit like the +opposite of the \fBaccept\-exact\fP style: only strings with +missing characters will be completed\&. +.PP +Note that you almost certainly don\&'t want to set this to `true' or +`\fBother\fP\&' for a general +context such as `\fB:completion:*\fP\&'\&. This is because it would disallow +completion of, for example, options multiple times even if the command +in question accepts the option more than once\&. +.RE +.TP +\fBignore\-parents\fP +The style is tested without a tag by the function completing pathnames +in order to determine whether to ignore +the names of directories already mentioned in the current word, or the +name of the current working directory\&. The value must include one or both +of the following strings: +.RS +.PP +.PD 0 +.TP +.PD +\fBparent\fP +The name of any directory whose path is already contained in the word on +the line is ignored\&. For example, when completing after \fBfoo/\&.\&./\fP, the +directory \fBfoo\fP will not be considered a valid completion\&. +.TP +\fBpwd\fP +The name of the current working directory will not be completed; hence, +for example, completion after \fB\&.\&./\fP will not use the name of the current +directory\&. +.PP +In addition, the value may include one or both of: +.PP +.PD 0 +.TP +.PD +\fB\&.\&.\fP +Ignore the specified directories only when the word on the line contains +the substring `\fB\&.\&./\fP\&'\&. +.TP +\fBdirectory\fP +Ignore the specified directories only when names of directories are +completed, not when completing names of files\&. +.PP +Excluded values act in a similar fashion to values of the +\fBignored\-patterns\fP style, so they can be restored to consideration by +the \fB_ignored\fP completer\&. +.RE +.TP +\fBignored\-patterns\fP +A list of patterns; any trial completion matching one of the patterns +will be excluded from consideration\&. The +\fB_ignored\fP completer can appear in the list of completers to +restore the ignored matches\&. This is a more configurable +version of the shell parameter \fB$fignore\fP\&. +.RS +.PP +Note that the +\fBEXTENDED_GLOB\fP option is set during the execution of completion +functions, so the characters `\fB#\fP\&', `\fB~\fP' and `\fB^\fP' have special +meanings in the patterns\&. +.RE +.TP +\fBinsert\fP +This style is used by the \fB_all_matches\fP completer to decide whether to +insert the list of all matches unconditionally instead of adding the +list as another match\&. +.TP +\fBinsert\-ids\fP +When completing process IDs, for example as arguments to the \fBkill\fP and +\fBwait\fP builtins the name of a +command may be converted to the appropriate process ID\&. A problem +arises when the process name typed is not unique\&. By default (or if this +style is set explicitly to `\fBmenu\fP\&') the name will be converted +immediately to a set of possible IDs, and menu completion will be started +to cycle through them\&. +.RS +.PP +If the value of the style is `\fBsingle\fP\&', +the shell will wait until the user has typed enough to make the command +unique before converting the name to an ID; attempts at completion will +be unsuccessful until that point\&. If the value is any other +string, menu completion will be started when the string typed by the +user is longer than the common prefix to the corresponding IDs\&. +.RE +.TP +\fBinsert\-sections\fP +This style is used with tags of the form `\fBmanuals\&.\fP\fIX\fP\&' when +completing names of manual pages\&. If set and the \fIX\fP in the tag name matches +the section number of the page being completed, the section number is inserted +along with the page name\&. For example, given +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*:manuals\&.*' insert\-sections true\fP +.fi +.RE +.PP +\fBman ssh_<TAB>\fP may be completed to \fBman 5 ssh_config\fP\&. +.PP +The value may also be set to one of `\fBprepend\fP\&', or `\fBsuffix\fP'\&. +`\fBprepend\fP\&' behaves the same as `true' as in the above example, while +`\fBsuffix\fP\&' would complete \fBman ssh_<TAB>\fP as \fBman ssh_config\&.5\fP\&. +.PP +This is especially useful in conjunction with \fBseparate\-sections\fP, as +it ensures that the page requested of \fBman\fP corresponds to the one +displayed in the completion listing when there are multiple pages with the +same name (e\&.g\&., \fBprintf(1)\fP and \fBprintf(3)\fP)\&. +.PP +The default for this style is `false\&'\&. +.RE +.TP +\fBinsert\-tab\fP +If this is set to `true\&', the completion system will +insert a TAB character (assuming that was used to start completion) instead +of performing completion when there is no non\-blank character to the left +of the cursor\&. If it is set to `false\&', completion will be done even there\&. +.RS +.PP +The value may also contain the substrings `\fBpending\fP\&' or +`\fBpending=\fP\fIval\fP\&'\&. In this case, the typed character will be +inserted instead of starting completion when there is unprocessed input +pending\&. If a \fIval\fP is given, completion will not be done if there +are at least that many characters of unprocessed input\&. This is often +useful when pasting characters into a terminal\&. Note +however, that it relies on the \fB$PENDING\fP special parameter from the +\fBzsh/zle\fP module being set properly which is not guaranteed on all +platforms\&. +.PP +The default value of this style is `true\&' except for completion within +\fBvared\fP builtin command where it is `false\&'\&. +.RE +.TP +\fBinsert\-unambiguous\fP +This is used by the \fB_match\fP and \fB_approximate\fP completers\&. +These completers are often used with menu completion since the word typed +may bear little resemblance to the final completion\&. +However, if this style is `true\&', the completer will start menu +completion only if it could find no unambiguous initial string at +least as long as the original string typed by the user\&. +.RS +.PP +In the case of the \fB_approximate\fP completer, the completer +field in the context will already have been set to one of +\fBcorrect\-\fP\fInum\fP or \fBapproximate\-\fP\fInum\fP, where \fInum\fP is the +number of errors that were accepted\&. +.PP +In the case of the \fB_match\fP completer, the style may also be set to +the string `\fBpattern\fP\&'\&. Then the pattern on the line is left +unchanged if it does not match unambiguously\&. +.RE +.TP +\fBkeep\-prefix\fP +This style is used by the \fB_expand\fP completer\&. If it is `true\&', the +completer will try to keep a prefix containing a tilde or parameter +expansion\&. Hence, for example, the string `\fB~/f*\fP\&' would be expanded to +`\fB~/foo\fP\&' instead of `\fB/home/user/foo\fP'\&. If the style is set to +`\fBchanged\fP\&' (the default), the prefix will only be left unchanged if +there were other changes between the expanded words and the original +word from the command line\&. Any other value forces the prefix to be +expanded unconditionally\&. +.RS +.PP +The behaviour of \fB_expand\fP when this style is `true\&' is to cause \fB_expand\fP +to give up when a single expansion with the restored prefix is the same +as the original; hence any remaining completers may be called\&. +.RE +.TP +\fBknown\-hosts\-files\fP +This style should contain a list of files to search for host names and +(if the \fBuse\-ip\fP style is set) IP addresses in a format compatible with +ssh \fBknown_hosts\fP files\&. If it is not set, the files +\fB/etc/ssh/ssh_known_hosts\fP and \fB~/\&.ssh/known_hosts\fP are used\&. +.TP +\fBlast\-prompt\fP +This is a more flexible form of the \fBALWAYS_LAST_PROMPT\fP option\&. +If it is `true\&', the completion system will try to return the cursor to +the previous command line after displaying a completion list\&. It is +tested for all tags valid for the current completion, then the +\fBdefault\fP tag\&. The cursor will be moved back to the +previous line if this style is `true\&' for all types of match\&. Note +that unlike the \fBALWAYS_LAST_PROMPT\fP option this is independent of the +numeric argument\&. +.TP +\fBlist\fP +This style is used by the \fB_history_complete_word\fP bindable command\&. +If it is set to `true\&' it has no effect\&. If it is set to `false' +matches will not be listed\&. This overrides the setting of the options +controlling listing behaviour, in particular \fBAUTO_LIST\fP\&. The context +always starts with `\fB:completion:history\-words\fP\&'\&. +.TP +\fBlist\-colors\fP +If the \fBzsh/complist\fP module is loaded, this style can be used to set +color specifications\&. This mechanism replaces the use of the +\fBZLS_COLORS\fP and \fBZLS_COLOURS\fP parameters described in +the section `The zsh/complist Module\&' in \fIzshmodules\fP(1), but the syntax is the same\&. +.RS +.PP +If this style is set for the \fBdefault\fP tag, the strings in the value +are taken as specifications that are to be used everywhere\&. If it is +set for other tags, the specifications are used only for matches of +the type described by the tag\&. For this to work best, the \fBgroup\-name\fP +style must be set to an empty string\&. +.PP +In addition to setting styles for specific tags, it is also possible to +use group names specified explicitly by the \fBgroup\-name\fP tag together +with the `\fB(group)\fP\&' syntax allowed by the \fBZLS_COLORS\fP and +\fBZLS_COLOURS\fP parameters and simply using the \fBdefault\fP tag\&. +.PP +It is possible to use any color specifications already set up for the GNU +version of the \fBls\fP command: +.PP +.RS +.nf +\fBzstyle \&':completion:*:default' list\-colors \e + ${(s\&.:\&.)LS_COLORS}\fP +.fi +.RE +.PP +The default colors are the same as for the GNU \fBls\fP command and can be +obtained by setting the style to an empty string (i\&.e\&. \fB\&''\fP)\&. +.RE +.TP +\fBlist\-dirs\-first\fP +This is used by file completion and corresponds to a particular +setting of the \fBfile\-patterns\fP style\&. +If set, the default directories to be completed +are listed separately from and before completion for other files\&. +.TP +\fBlist\-grouped\fP +If this style is `true\&' (the default), the completion system will try to +make certain completion listings more compact by grouping matches\&. +For example, options for commands that have the same description (shown +when the \fBverbose\fP style is set to `true\&') will appear as a single +entry\&. However, menu selection can be used to cycle through all the +matches\&. +.TP +\fBlist\-packed\fP +This is tested for each tag valid in the current context as well as the +\fBdefault\fP tag\&. If it is set to `true\&', the corresponding matches +appear in listings as if the \fBLIST_PACKED\fP option were set\&. If it is +set to `false\&', they are listed normally\&. +.TP +\fBlist\-prompt\fP +If this style is set for the \fBdefault\fP tag, +completion lists that don\&'t fit on the screen can be scrolled (see +the description of the \fBzsh/complist\fP module in \fIzshmodules\fP(1))\&. The value, if not the empty string, will be displayed after every +screenful and the shell will prompt for a key press; if the style is +set to the empty string, +a default prompt will be used\&. +.RS +.PP +The value may contain the escape sequences: +`\fB%l\fP\&' or `\fB%L\fP', which will be replaced by the number of the last line +displayed and the total number of lines; `\fB%m\fP\&' or `\fB%M\fP', +the number of the last match shown and the total number of +matches; and `\fB%p\fP\&' and `\fB%P\fP', `\fBTop\fP' +when at the beginning of the list, `\fBBottom\fP\&' when at the end and the +position shown as a percentage of the total length otherwise\&. In each +case the form with the uppercase letter will be replaced by a string of fixed +width, padded to the right with spaces, while the lowercase form will +be replaced by a variable width string\&. As in other prompt strings, the +escape sequences `\fB%S\fP\&', `\fB%s\fP', `\fB%B\fP', `\fB%b\fP', `\fB%U\fP', +`\fB%u\fP\&' for entering and leaving the display modes +standout, bold and underline, and `\fB%F\fP\&', `\fB%f\fP', `\fB%K\fP', `\fB%k\fP' for +changing the foreground background colour, are also available, as is the form +`\fB%{\fP\&.\&.\&.\fB%}\fP\&' for enclosing escape sequences which display with zero +(or, with a numeric argument, some other) width\&. +.PP +After deleting this prompt the variable \fBLISTPROMPT\fP should be unset for +the removal to take effect\&. +.RE +.TP +\fBlist\-rows\-first\fP +This style is tested in the same way as the \fBlist\-packed\fP style and +determines whether matches are to be listed in a rows\-first fashion as +if the \fBLIST_ROWS_FIRST\fP option were set\&. +.TP +\fBlist\-separator\fP +The value of this style is used in completion listing to separate the +string to complete from a description when possible (e\&.g\&. when +completing options)\&. It defaults to `\fB\-\fP\fB\-\fP\&' (two hyphens)\&. +.TP +\fBlist\-suffixes\fP +This style is used by the function that completes filenames\&. If it is +`true\&', and completion is attempted on a string containing multiple partially +typed pathname components, all ambiguous components will be shown\&. +Otherwise, completion stops at the first ambiguous component\&. +.TP +\fBlocal\fP +This is for use with functions that complete URLs for which the +corresponding files are available directly from the file system\&. +Its value should consist of three strings: a +hostname, the path to the default web pages for the server, and the +directory name used by a user placing web pages within their home +area\&. +.RS +.PP +For example: +.PP +.RS +.nf +\fBzstyle \&':completion:*' local toast \e + /var/http/public/toast public_html\fP +.fi +.RE +.PP +Completion after `\fBhttp://toast/stuff/\fP\&' will look for files in the +directory \fB/var/http/public/toast/stuff\fP, while completion after +`\fBhttp://toast/~yousir/\fP\&' will look for files in the directory +\fB~yousir/public_html\fP\&. +.RE +.TP +\fBmail\-directory\fP +If set, zsh will assume that mailbox files can be found in +the directory specified\&. It defaults to `\fB~/Mail\fP\&'\&. +.TP +\fBmatch\-original\fP +This is used by the \fB_match\fP completer\&. If it is set to +\fBonly\fP, \fB_match\fP will try to generate matches without inserting a +`\fB*\fP\&' at the cursor position\&. If set to any other non\-empty value, +it will first try to generate matches without inserting the `\fB*\fP\&' +and if that yields no matches, it will try again with the `\fB*\fP\&' +inserted\&. If it is unset or set to the empty string, matching will +only be performed with the `\fB*\fP\&' inserted\&. +.TP +\fBmatcher\fP +This style is tested separately for each tag valid in the current +context\&. Its value is placed before any match specifications given by the +\fBmatcher\-list\fP style so can override them via the use of an \fBx:\fP +specification\&. The value should be in the form described in +the section `Completion Matching Control\&' in \fIzshcompwid\fP(1)\&. For examples of this, see the description of the \fBtag\-order\fP style\&. +.RS +.PP +For notes comparing the use of this and the \fBmatcher\-list\fP style, see +under the description of the \fBtag\-order\fP style\&. +.RE +.TP +\fBmatcher\-list\fP +This style can be set to a list of match specifications that are to +be applied everywhere\&. Match specifications are described in +the section `Completion Matching Control\&' in \fIzshcompwid\fP(1)\&. +The completion system will try them one after another for each completer +selected\&. For example, to try first simple completion and, if that +generates no matches, case\-insensitive completion: +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*' matcher\-list '' 'm:{a\-zA\-Z}={A\-Za\-z}'\fP +.fi +.RE +.PP +By default each specification replaces the previous one; however, if a +specification is prefixed with \fB+\fP, it is added to the existing list\&. +Hence it is possible to create increasingly general specifications +without repetition: +.PP +.RS +.nf +\fBzstyle \&':completion:*' matcher\-list \e + \&'' '+m:{a\-z}={A\-Z}' '+m:{A\-Z}={a\-z}'\fP +.fi +.RE +.PP +It is possible to create match specifications valid for particular +completers by using the third field of the context\&. This applies only +to completers that override the global matcher\-list, which as of this +writing includes only \fB_prefix\fP and \fB_ignored\fP\&. For example, to +use the completers \fB_complete\fP and \fB_prefix\fP but allow +case\-insensitive completion only with \fB_complete\fP: +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer _complete _prefix +zstyle \&':completion:*:complete:*:*:*' matcher\-list \e + \&'' 'm:{a\-zA\-Z}={A\-Za\-z}'\fP +.fi +.RE +.PP +User\-defined names, as explained for the \fBcompleter\fP style, are +available\&. This makes it possible to try the same completer more than +once with different match specifications each time\&. For example, to try +normal completion without a match specification, then normal completion +with case\-insensitive matching, then correction, and finally +partial\-word completion: +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer \e + _complete _correct _complete:foo +zstyle \&':completion:*:complete:*:*:*' matcher\-list \e + \&'' 'm:{a\-zA\-Z}={A\-Za\-z}' +zstyle \&':completion:*:foo:*:*:*' matcher\-list \e + \&'m:{a\-zA\-Z}={A\-Za\-z} r:|[\-_\&./]=* r:|=*'\fP +.fi +.RE +.PP +If the style is unset in any context no match specification is applied\&. +Note also that some completers such as \fB_correct\fP and \fB_approximate\fP +do not use the match specifications at all, though these completers will +only ever be called once even if the \fBmatcher\-list\fP contains more than +one element\&. +.PP +Where multiple specifications are useful, note that the \fIentire\fP +completion is done for each element of \fBmatcher\-list\fP, which can +quickly reduce the shell\&'s performance\&. As a rough rule of thumb, +one to three strings will give acceptable performance\&. On the other +hand, putting multiple space\-separated values into the same string does +not have an appreciable impact on performance\&. +.PP +If there is no current matcher or it is empty, and the option +\fBNO_CASE_GLOB\fP is in effect, the matching for files is performed +case\-insensitively in any case\&. However, any matcher must +explicitly specify case\-insensitive matching if that is required\&. +.PP +For notes comparing the use of this and the \fBmatcher\fP style, see +under the description of the \fBtag\-order\fP style\&. +.RE +.TP +\fBmax\-errors\fP +This is used by the \fB_approximate\fP and \fB_correct\fP completer functions +to determine the maximum number of errors to allow\&. The completer will try +to generate completions by first allowing one error, then two errors, and +so on, until either a match or matches were found or the maximum number of +errors given by this style has been reached\&. +.RS +.PP +If the value for this style contains the string `\fBnumeric\fP\&', the +completer function will take any numeric argument as the +maximum number of errors allowed\&. For example, with +.PP +.RS +.nf +\fBzstyle \&':completion:*:approximate:::' max\-errors 2 numeric\fP +.fi +.RE +.PP +two errors are allowed if no numeric argument is given, but with +a numeric argument of six (as in `\fBESC\-6 TAB\fP\&'), up to six +errors are accepted\&. Hence with a value of `\fB0 numeric\fP\&', no correcting +completion will be attempted unless a numeric argument is given\&. +.PP +If the value contains the string `\fBnot\-numeric\fP\&', the completer +will \fInot\fP try to generate corrected +completions when given a numeric argument, so in this case the number given +should be greater than zero\&. For example, `\fB2 not\-numeric\fP\&' specifies that +correcting completion with two errors will usually be performed, but if a +numeric argument is given, correcting completion will not be +performed\&. +.PP +The default value for this style is `\fB2 numeric\fP\&'\&. +.RE +.TP +\fBmax\-matches\-width\fP +This style is used to determine the trade off between the width of the +display used for matches and the width used for their descriptions when +the \fBverbose\fP style is in effect\&. The value gives the number of +display columns to reserve for the matches\&. The default is half the +width of the screen\&. +.RS +.PP +This has the most impact when several matches have the +same description and so will be grouped together\&. Increasing the style +will allow more matches to be grouped together; decreasing it will allow +more of the description to be visible\&. +.RE +.TP +\fBmenu\fP +If this is `true\&' in the context of any of the tags defined +for the current completion menu completion will be used\&. The value for +a specific tag will take precedence over that for the `\fBdefault\fP\&' tag\&. +.RS +.PP +If none of the values found in this way is `true\&' but at least +one is set to `\fBauto\fP\&', the shell behaves as if the \fBAUTO_MENU\fP +option is set\&. +.PP +If one of the values is explicitly set to `false\&', menu +completion will be explicitly turned off, overriding the +\fBMENU_COMPLETE\fP option and other settings\&. +.PP +In the form `\fByes=\fP\fInum\fP\&', where `\fByes\fP' may be any of the +`true\&' values (`\fByes\fP', `\fBtrue\fP', `\fBon\fP' and `\fB1\fP'), +menu completion will be turned on if there are at least \fInum\fP matches\&. +In the form `\fByes=long\fP\&', menu completion will be turned on +if the list does not fit on the screen\&. This does not activate menu +completion if the widget normally only lists completions, but menu +completion can be activated in that case with the value `\fByes=long\-list\fP\&' +(Typically, the value `\fBselect=long\-list\fP\&' described later is more +useful as it provides control over scrolling\&.) +.PP +Similarly, with any of the `false\&' values (as in `\fBno=10\fP'), menu +completion will \fInot\fP be used if there are \fInum\fP or more matches\&. +.PP +The value of this widget also controls menu selection, as implemented by +the \fBzsh/complist\fP module\&. The following values may appear either +alongside or instead of the values above\&. +.PP +If the value contains the string `\fBselect\fP\&', menu selection +will be started unconditionally\&. +.PP +In the form `\fBselect=\fP\fInum\fP\&', menu selection will only be started if +there are at least \fInum\fP matches\&. If the values for more than one +tag provide a number, the smallest number is taken\&. +.PP +Menu selection can be turned off explicitly by defining a value +containing the string`\fBno\-select\fP\&'\&. +.PP +It is also possible to start menu selection only if the list of +matches does not fit on the screen by using the value +`\fBselect=long\fP\&'\&. To start menu selection even if the current widget +only performs listing, use the value `\fBselect=long\-list\fP\&'\&. +.PP +To turn on menu completion or menu selection when there are a certain +number of matches \fIor\fP the list of matches does not fit on the +screen, both of `\fByes=\fP\&' and `\fBselect=\fP' may be given twice, once +with a number and once with `\fBlong\fP\&' or `\fBlong\-list\fP'\&. +.PP +Finally, it is possible to activate two special modes of menu selection\&. +The word `\fBinteractive\fP\&' in the value causes interactive mode +to be entered immediately when menu selection is started; see +the description of the \fBzsh/complist\fP module in \fIzshmodules\fP(1) +for a description of interactive mode\&. Including the string +`\fBsearch\fP\&' does the same for incremental search mode\&. To select backward +incremental search, include the string `\fBsearch\-backward\fP\&'\&. +.RE +.TP +\fBmuttrc\fP +If set, gives the location of the mutt configuration file\&. It defaults +to `\fB~/\&.muttrc\fP\&'\&. +.TP +\fBnumbers\fP +This is used with the \fBjobs\fP tag\&. If it is `true\&', the shell will +complete job numbers instead of the shortest unambiguous prefix +of the job command text\&. If the value is a number, job numbers will +only be used if that many words from the job descriptions are required to +resolve ambiguities\&. For example, if the value is `\fB1\fP\&', strings will +only be used if all jobs differ in the first word on their command lines\&. +.TP +\fBold\-list\fP +This is used by the \fB_oldlist\fP completer\&. If it is set to `\fBalways\fP\&', +then standard widgets which perform listing will retain the current list of +matches, however they were generated; this can be turned off explicitly +with the value `\fBnever\fP\&', giving the behaviour without the \fB_oldlist\fP +completer\&. If the style is unset, or any other value, then the existing +list of completions is displayed if it is not already; otherwise, the +standard completion list is generated; this is the default behaviour of +\fB_oldlist\fP\&. However, if there is an old list and this style contains +the name of the completer function that generated the list, then the +old list will be used even if it was generated by a widget which does +not do listing\&. +.RS +.PP +For example, suppose you type \fB^Xc\fP to use the \fB_correct_word\fP +widget, which generates a list of corrections for the word under the +cursor\&. Usually, typing \fB^D\fP would generate a standard list of +completions for the word on the command line, and show that\&. With +\fB_oldlist\fP, it will instead show the list of corrections already +generated\&. +.PP +As another example consider the \fB_match\fP completer: with the +\fBinsert\-unambiguous\fP style set to `true\&' it inserts only a common prefix +string, if there is any\&. However, this may remove parts of the original +pattern, so that further completion could produce more matches than on the +first attempt\&. By using the \fB_oldlist\fP completer and setting this style +to \fB_match\fP, the list of matches generated on the first attempt will be +used again\&. +.RE +.TP +\fBold\-matches\fP +This is used by the \fB_all_matches\fP completer to decide if an old +list of matches should be used if one exists\&. This is selected by one of +the `true\&' values or by the string `\fBonly\fP'\&. If +the value is `\fBonly\fP\&', \fB_all_matches\fP will only use an old list +and won\&'t have any effect on the list of matches currently being +generated\&. +.RS +.PP +If this style is set it is generally unwise to call the \fB_all_matches\fP +completer unconditionally\&. One possible use is for either this style or +the \fBcompleter\fP style to be defined with the \fB\-e\fP option to +\fBzstyle\fP to make the style conditional\&. +.RE +.TP +\fBold\-menu\fP +This is used by the \fB_oldlist\fP completer\&. It controls how menu +completion behaves when a completion has already been inserted and the +user types a standard completion key such as \fBTAB\fP\&. The default +behaviour of \fB_oldlist\fP is that menu completion always continues +with the existing list of completions\&. If this style is set to +`false\&', however, a new completion is started if the old list was +generated by a different completion command; this is the behaviour without +the \fB_oldlist\fP completer\&. +.RS +.PP +For example, suppose you type \fB^Xc\fP to generate a list of corrections, +and menu completion is started in one of the usual ways\&. Usually, or with +this style set to `false\&', typing \fBTAB\fP at this point would start +trying to complete the line as it now appears\&. With \fB_oldlist\fP, it +instead continues to cycle through the list of corrections\&. +.RE +.TP +\fBoriginal\fP +This is used by the \fB_approximate\fP and \fB_correct\fP +completers to decide if the original string should be added as +a possible completion\&. Normally, this is done only if there are +at least two possible corrections, but if this style is set to `true\&', it +is always added\&. Note that the style will be examined with the +completer field in the context name set to \fBcorrect\-\fP\fInum\fP or +\fBapproximate\-\fP\fInum\fP, where \fInum\fP is the number of errors that +were accepted\&. +.TP +\fBpackageset\fP +This style is used when completing arguments of the Debian `\fBdpkg\fP\&' +program\&. It contains an override for the default package set +for a given context\&. For example, +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*:complete:dpkg:option\-\-status\-1:*' \e + packageset avail\fP +.fi +.RE +.PP +causes available packages, rather than only installed packages, +to be completed for `\fBdpkg \-\fP\fB\-status\fP\&'\&. +.RE +.TP +\fBpath\fP +The function that completes color names uses this style with the +\fBcolors\fP tag\&. The value should be the pathname of a file +containing color names in the format of an X11 \fBrgb\&.txt\fP file\&. If +the style is not set but this file is found in one of various standard +locations it will be used as the default\&. +.TP +\fBpath\-completion\fP +This is used by filename completion\&. By default, filename completion +examines all components of a path to see if there are completions of +that component\&. For example, \fB/u/b/z\fP can be completed to +\fB/usr/bin/zsh\fP\&. Explicitly setting this style to `false\&' inhibits this +behaviour for path components up to the \fB/\fP before the cursor; this +overrides the setting of \fBaccept\-exact\-dirs\fP\&. +.RS +.PP +Even with the style set to `false\&', it is still possible to complete +multiple paths by setting the option \fBCOMPLETE_IN_WORD\fP and moving the +cursor back to the first component in the path to be completed\&. For +example, \fB/u/b/z\fP can be completed to \fB/usr/bin/zsh\fP if the cursor is +after the \fB/u\fP\&. +.RE +.TP +\fBpine\-directory\fP +If set, specifies the directory containing PINE mailbox files\&. There +is no default, since recursively searching this directory is inconvenient +for anyone who doesn\&'t use PINE\&. +.TP +\fBports\fP +A list of Internet service names (network ports) to complete\&. If this is +not set, service names are taken from the file `\fB/etc/services\fP\&'\&. +.TP +\fBprefix\-hidden\fP +This is used for certain completions which share a common prefix, for +example command options beginning with dashes\&. If it is `true\&', the +prefix will not be shown in the list of matches\&. +.RS +.PP +The default value for this style is `false\&'\&. +.RE +.TP +\fBprefix\-needed\fP +This style is also relevant for matches with a common prefix\&. If it is +set to `true\&' this common prefix must be typed by the user to generate +the matches\&. +.RS +.PP +The style is applicable to the \fBoptions\fP, \fBsignals\fP, \fBjobs\fP, +\fBfunctions\fP, and \fBparameters\fP completion tags\&. +.PP +For command options, this means that the initial `\fB\-\fP\&', `\fB+\fP', or +`\fB\-\fP\fB\-\fP\&' must be typed explicitly before option names will be +completed\&. +.PP +For signals, an initial `\fB\-\fP\&' is required before signal names will +be completed\&. +.PP +For jobs, an initial `\fB%\fP\&' is required before job names will be +completed\&. +.PP +For function and parameter names, an initial `\fB_\fP\&' or `\fB\&.\fP' is +required before function or parameter names starting with those +characters will be completed\&. +.PP +The default value for this style is `false\&' for \fBfunction\fP and +\fBparameter\fP completions, and `true\&' otherwise\&. +.RE +.TP +\fBpreserve\-prefix\fP +This style is used when completing path names\&. Its value should be a +pattern matching an initial prefix of the word to complete that should +be left unchanged under all circumstances\&. For example, on some Unices +an initial `\fB//\fP\&' (double slash) has a special meaning; setting +this style to the string `\fB//\fP\&' will preserve it\&. As another example, +setting this style to `\fB?:/\fP\&' under Cygwin would allow completion +after `\fBa:/\&.\&.\&.\fP\&' and so on\&. +.TP +\fBrange\fP +This is used by the \fB_history\fP completer and the +\fB_history_complete_word\fP bindable command to decide which words +should be completed\&. +.RS +.PP +If it is a single number, only the last \fIN\fP words from the history +will be completed\&. +.PP +If it is a range of the form `\fImax\fP\fB:\fP\fIslice\fP\&', +the last \fIslice\fP words will be completed; then if that +yields no matches, the \fIslice\fP words before those will be tried and +so on\&. This process stops either when at least one match has been +found, or \fImax\fP words have been tried\&. +.PP +The default is to complete all words from the history at once\&. +.RE +.TP +\fBrecursive\-files\fP +If this style is set, its value is an array of patterns to be +tested against `\fB$PWD/\fP\&': note the trailing slash, which allows +directories in the pattern to be delimited unambiguously by including +slashes on both sides\&. If an ordinary file completion fails +and the word on the command line does not yet have a directory part to its +name, the style is retrieved using the same tag as for the completion +just attempted, then the elements tested against \fB$PWD/\fP in turn\&. +If one matches, then the shell reattempts completion by prepending the word +on the command line with each directory in the expansion of \fB**/*(/)\fP +in turn\&. Typically the elements of the style will be set to restrict +the number of directories beneath the current one to a manageable +number, for example `\fB*/\&.git/*\fP\&'\&. +.RS +.PP +For example, +.PP +.RS +.nf +\fBzstyle \&':completion:*' recursive\-files '*/zsh/*'\fP +.fi +.RE +.PP +If the current directory is \fB/home/pws/zsh/Src\fP, then +\fBzle_tr<TAB>\fP can be completed to \fBZle/zle_tricky\&.c\fP\&. +.RE +.TP +\fBregular\fP +This style is used by the \fB_expand_alias\fP completer and bindable +command\&. If set to `true\&' (the default), regular aliases will be +expanded but only in command position\&. If it is set to `false\&', +regular aliases will never be expanded\&. If it is set to `\fBalways\fP\&', +regular aliases will be expanded even if not in command position\&. +.TP +\fBrehash\fP +If this is set when completing external commands, the internal +list (hash) of commands will be updated for each search by issuing +the \fBrehash\fP command\&. There is a speed penalty for this which +is only likely to be noticeable when directories in the path have +slow file access\&. +.TP +\fBremote\-access\fP +If set to `false\&', certain commands will be prevented from making +Internet connections to retrieve remote information\&. This includes the +completion for the \fBCVS\fP command\&. +.RS +.PP +It is not always possible to know if connections are in fact to a remote +site, so some may be prevented unnecessarily\&. +.RE +.TP +\fBremove\-all\-dups\fP +The \fB_history_complete_word\fP bindable command and the \fB_history\fP +completer use this to decide if all duplicate matches should be +removed, rather than just consecutive duplicates\&. +.TP +\fBselect\-prompt\fP +If this is set for the \fBdefault\fP tag, its +value will be displayed during menu selection (see the \fBmenu\fP style +above) when the completion list does not fit on the screen as a +whole\&. The same escapes as for the \fBlist\-prompt\fP style are +understood, except that the numbers refer to the match or line the mark is +on\&. A default prompt is used when the value is the empty string\&. +.TP +\fBselect\-scroll\fP +This style is tested for the \fBdefault\fP tag and determines how a +completion list is scrolled during a menu selection (see the \fBmenu\fP +style above) when the completion list does not fit on the screen as a +whole\&. If the value is `\fB0\fP\&' (zero), the list is scrolled by +half\-screenfuls; if it is a positive integer, the list is scrolled by the +given number of lines; if it is a negative number, the list is scrolled by a +screenful minus the absolute value of the given number of lines\&. +The default is to scroll by single lines\&. +.TP +\fBseparate\-sections\fP +This style is used with the \fBmanuals\fP tag when completing names of +manual pages\&. If it is `true\&', entries for different sections are +added separately using tag names of the form `\fBmanuals\&.\fP\fIX\fP\&', +where \fIX\fP is the section number\&. When the \fBgroup\-name\fP style is +also in effect, pages from different sections will appear separately\&. +This style is also used similarly with the \fBwords\fP style when +completing words for the dict command\&. It allows words from different +dictionary databases to be added separately\&. See also \fBinsert\-sections\fP\&. +.RS +.PP +The default for this style is `false\&'\&. +.RE +.TP +\fBshow\-ambiguity\fP +If the \fBzsh/complist\fP module is loaded, this style can be used to +highlight the first ambiguous character in completion lists\&. The +value is either a color indication such as those supported by the +\fBlist\-colors\fP style or, with a value of `true\&', a default of +underlining is selected\&. The highlighting is only applied if the +completion display strings correspond to the actual matches\&. +.TP +\fBshow\-completer\fP +Tested whenever a new completer is tried\&. If it is `true\&', the completion +system outputs a progress message in the listing area showing what +completer is being tried\&. The message will be overwritten by any output +when completions are found and is removed after completion is finished\&. +.TP +\fBsingle\-ignored\fP +This is used by the \fB_ignored\fP completer when there is only one match\&. +If its value is `\fBshow\fP\&', the single match will be +displayed but not inserted\&. If the value is `\fBmenu\fP\&', then the single +match and the original string are both added as matches and menu completion +is started, making it easy to select either of them\&. +.TP +\fBsort\fP +This allows the standard ordering of matches to be overridden\&. +.RS +.PP +If its value is `\fBtrue\fP\&' or `\fBfalse\fP', sorting is enabled or disabled\&. +Additionally the values associated with the `\fB\-o\fP\&' option to \fBcompadd\fP can +also be listed: \fBmatch\fP, \fBnosort\fP, \fBnumeric\fP, \fBreverse\fP\&. If it is not +set for the context, the standard behaviour of the calling widget is used\&. +.PP +The style is tested first against the full context including the tag, and +if that fails to produce a value against the context without the tag\&. +.PP +In many cases where a calling widget explicitly selects a particular ordering +in lieu of the default, a value of `\fBtrue\fP\&' is not honoured\&. An example of +where this is not the case is for command history where the default of sorting +matches chronologically may be overridden by setting the style to `true\&'\&. +.PP +In the \fB_expand\fP completer, if it is set to +`true\&', the expansions generated will always be sorted\&. If it is set +to `\fBmenu\fP\&', then the expansions are only sorted when they are offered +as single strings but not in the string containing all possible +expansions\&. +.RE +.TP +\fBspecial\-dirs\fP +Normally, the completion code will not produce the directory names +`\fB\&.\fP\&' and `\fB\&.\&.\fP' as possible completions\&. If this style is set to +`true\&', it will add both `\fB\&.\fP' and `\fB\&.\&.\fP' as possible completions; +if it is set to `\fB\&.\&.\fP\&', only `\fB\&.\&.\fP' will be added\&. +.RS +.PP +The following example sets \fBspecial\-dirs\fP to `\fB\&.\&.\fP\&' when the +current prefix is empty, is a single `\fB\&.\fP\&', or consists only of a path +beginning with `\fB\&.\&./\fP\&'\&. Otherwise the value is `false'\&. +.PP +.RS +.nf +\fBzstyle \-e \&':completion:*' special\-dirs \e + \&'[[ $PREFIX = (\&.\&./)#(|\&.|\&.\&.) ]] && reply=(\&.\&.)'\fP +.fi +.RE +.RE +.TP +\fBsqueeze\-slashes\fP +If set to `true\&', sequences of slashes in filename paths (for example in +`\fBfoo//bar\fP\&') will be treated as a single slash\&. This is the usual +behaviour of UNIX paths\&. However, by default the file completion +function behaves as if there were a `\fB*\fP\&' between the slashes\&. +.TP +\fBstop\fP +If set to `true\&', the \fB_history_complete_word\fP bindable +command will stop once when reaching the beginning or end of the +history\&. Invoking \fB_history_complete_word\fP will then wrap around to +the opposite end of the history\&. If this style is set to `false\&' (the +default), \fB_history_complete_word\fP will loop immediately as in a +menu completion\&. +.TP +\fBstrip\-comments\fP +If set to `true\&', this style causes non\-essential comment text to be +removed from completion matches\&. Currently it is only used when +completing e\-mail addresses where it removes any display name from the +addresses, cutting them down to plain \fIuser@host\fP form\&. +.TP +\fBsubst\-globs\-only\fP +This is used by the \fB_expand\fP completer\&. If it is set to `true\&', +the expansion will only be used if it resulted from globbing; hence, +if expansions resulted from the use of the \fBsubstitute\fP style +described below, but these were not further changed by globbing, the +expansions will be rejected\&. +.RS +.PP +The default for this style is `false\&'\&. +.RE +.TP +\fBsubstitute\fP +This boolean style controls whether the \fB_expand\fP completer will +first try to expand all substitutions in the string (such as +`\fB$(\fP\fI\&.\&.\&.\fP\fB)\fP\&' and `\fB${\fP\fI\&.\&.\&.\fP\fB}\fP')\&. +.RS +.PP +The default is `true\&'\&. +.RE +.TP +\fBsuffix\fP +This is used by the \fB_expand\fP completer if the word starts with a +tilde or contains a parameter expansion\&. If it is set to `true\&', the +word will only be expanded if it doesn\&'t have a suffix, i\&.e\&. if it is +something like `\fB~foo\fP\&' or `\fB$foo\fP' rather than `\fB~foo/\fP' or +`\fB$foo/bar\fP\&', unless that suffix itself contains characters eligible +for expansion\&. The default for this style is `true\&'\&. +.TP +\fBtag\-order\fP +This provides a mechanism for sorting how the tags available in a +particular context will be used\&. +.RS +.PP +The values for the style are sets of space\-separated lists of tags\&. +The tags in each value will be tried at the same time; if no match is +found, the next value is used\&. (See the \fBfile\-patterns\fP style for +an exception to this behavior\&.) +.PP +For example: +.PP +.RS +.nf +\fBzstyle \&':completion:*:complete:\-command\-:*:*' tag\-order \e + \&'commands functions'\fP +.fi +.RE +.PP +specifies that completion in command position first offers +external commands and shell functions\&. Remaining tags will be tried if +no completions are found\&. +.PP +In addition to tag names, each string in the value may take one of the +following forms: +.PP +.PD 0 +.TP +.PD +\fB\-\fP +If any value consists of only a hyphen, +then \fIonly\fP the tags specified in the other values are +generated\&. Normally all tags not explicitly selected are tried last +if the specified tags fail to generate any matches\&. This means +that a single value consisting only of a single hyphen +turns off completion\&. +.TP +\fB!\fP \fItags\fP\&.\&.\&. +A string starting with an exclamation mark +specifies names of tags that are \fInot\fP to be used\&. The effect is +the same as if all other possible tags for the context had been +listed\&. +.TP +\fItag\fP\fB:\fP\fIlabel\fP \&.\&.\&. +Here, \fItag\fP is one of the standard tags and \fIlabel\fP is an +arbitrary name\&. Matches are generated as normal but the name \fIlabel\fP +is used in contexts instead of \fItag\fP\&. This is not useful in words +starting with \fB!\fP\&. +.RS +.PP +If the \fIlabel\fP starts with a hyphen, the \fItag\fP is prepended to the +\fIlabel\fP to form the name used for lookup\&. This can be +used to make the completion system try a certain tag more than once, +supplying different style settings for each attempt; see below for an +example\&. +.RE +.TP +\fItag\fP\fB:\fP\fIlabel\fP\fB:\fP\fIdescription\fP +As before, but \fBdescription\fP will replace the `\fB%d\fP\&' in +the value of the \fBformat\fP style instead of the default description +supplied by the completion function\&. Spaces in the description must +be quoted with a backslash\&. A `\fB%d\fP\&' appearing +in \fIdescription\fP is replaced with the description given by the +completion function\&. +.PP +In any of the forms above the tag may be a pattern or several +patterns in the form `\fB{\fP\fIpat1\fP\fB,\fP\fIpat2\&.\&.\&.\fP\fB}\fP\&'\&. In this +case all matching tags will be used except +for any given explicitly in the same string\&. +.PP +One use of these features is to try +one tag more than once, setting other styles differently on +each attempt, but still to use all the other tags without having to +repeat them all\&. For example, to make completion of function names in +command position ignore all the completion functions starting with an +underscore the first time completion is tried: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:\-command\-:*:*' tag\-order \e + \&'functions:\-non\-comp *' functions +zstyle \&':completion:*:functions\-non\-comp' \e + ignored\-patterns \&'_*'\fP +.fi +.RE +.PP +On the first attempt, all tags will be offered but the \fBfunctions\fP tag +will be replaced by \fBfunctions\-non\-comp\fP\&. The \fBignored\-patterns\fP style +is set for this tag to exclude functions starting with an underscore\&. +If there are no matches, the second value of the +\fBtag\-order\fP style is used which completes functions using the default +tag, this time presumably including all function names\&. +.PP +The matches for one tag can be split into different groups\&. For example: +.PP +.RS +.nf +\fBzstyle \&':completion:*' tag\-order \e + \&'options:\-long:long\e options + options:\-short:short\e options + options:\-single\-letter:single\e letter\e options\&' +zstyle \&':completion:*:options\-long' \e + ignored\-patterns \&'[\-+](|\-|[^\-]*)' +zstyle \&':completion:*:options\-short' \e + ignored\-patterns \&'\-\-*' '[\-+]?' +zstyle \&':completion:*:options\-single\-letter' \e + ignored\-patterns \&'???*'\fP +.fi +.RE +.PP +With the \fBgroup\-names\fP style set, options beginning with +`\fB\-\fP\fB\-\fP\&', options beginning with a single `\fB\-\fP' or `\fB+\fP' but +containing multiple characters, and single\-letter options will be +displayed in separate groups with different descriptions\&. +.PP +Another use of patterns is to +try multiple match specifications one after another\&. The +\fBmatcher\-list\fP style offers something similar, but it is tested very +early in the completion system and hence can\&'t be set for single +commands nor for more specific contexts\&. Here is how to +try normal completion without any match specification and, if that +generates no matches, try again with case\-insensitive matching, restricting +the effect to arguments of the command \fBfoo\fP: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:foo:*:*' tag\-order '*' '*:\-case' +zstyle \&':completion:*\-case' matcher 'm:{a\-z}={A\-Z}'\fP +.fi +.RE +.PP +First, all the tags offered when completing after \fBfoo\fP are tried using +the normal tag name\&. If that generates no matches, the second value of +\fBtag\-order\fP is used, which tries all tags again except that this time +each has \fB\-case\fP appended to its name for lookup of styles\&. Hence this +time the value for the \fBmatcher\fP style from the second call to \fBzstyle\fP +in the example is used to make completion case\-insensitive\&. +.PP +It is possible to use the \fB\-e\fP option of the \fBzstyle\fP builtin +command to specify conditions for the use of particular tags\&. For +example: +.PP +.RS +.nf +\fBzstyle \-e \&'*:\-command\-:*' tag\-order ' + if [[ \-n $PREFIX$SUFFIX ]]; then + reply=( ) + else + reply=( \- ) + fi\&'\fP +.fi +.RE +.PP +Completion in command position will be attempted only if the string +typed so far is not empty\&. This is tested using the \fBPREFIX\fP +special parameter; see +zshcompwid +for a description of parameters which are special inside completion widgets\&. +Setting \fBreply\fP to an empty array provides the default +behaviour of trying all tags at once; setting it to an +array containing only a hyphen disables the use of all tags and hence of +all completions\&. +.PP +If no \fBtag\-order\fP style has been defined for a context, the strings +`\fB(|*\-)argument\-* (|*\-)option\-* values\fP\&' and `\fBoptions\fP' plus all +tags offered by the completion function will be used to provide a +sensible default behavior that causes arguments (whether normal command +arguments or arguments of options) to be completed before option names for +most commands\&. +.RE +.TP +\fBurls\fP +This is used together with the \fBurls\fP tag by +functions completing URLs\&. +.RS +.PP +If the value consists of more than one string, or if the only string +does not name a file or directory, the strings are used as the URLs to +complete\&. +.PP +If the value contains only one string which is the name of a normal +file the URLs are taken from that file (where the URLs may be +separated by white space or newlines)\&. +.PP +Finally, if the only string in the value names a directory, the +directory hierarchy rooted at this directory gives the completions\&. The +top level directory should be the file access method, such as +`\fBhttp\fP\&', `\fBftp\fP', `\fBbookmark\fP' and so on\&. In many cases the next +level of directories will be a filename\&. The directory hierarchy can +descend as deep as necessary\&. +.PP +For example, +.PP +.RS +.nf +\fBzstyle \&':completion:*' urls ~/\&.urls +mkdir \-p ~/\&.urls/ftp/ftp\&.zsh\&.org/pub +\fP +.fi +.RE +.PP +allows completion of all the components of the URL +\fBftp://ftp\&.zsh\&.org/pub\fP after suitable commands such as +`\fBnetscape\fP\&' or `\fBlynx\fP'\&. Note, however, that access methods and +files are completed separately, so if the \fBhosts\fP style is set hosts +can be completed without reference to the \fBurls\fP style\&. +.PP +See the description in the function \fB_urls\fP itself +for more information (e\&.g\&. `\fBmore $^fpath/_urls(N)\fP\&')\&. +.RE +.TP +\fBuse\-cache\fP +If this is set, the completion caching layer is activated for any completions +which use it (via the \fB_store_cache\fP, \fB_retrieve_cache\fP, and +\fB_cache_invalid\fP functions)\&. The directory containing the cache +files can be changed with the \fBcache\-path\fP style\&. +.TP +\fBuse\-compctl\fP +If this style is set to a string \fInot\fP equal to \fBfalse\fP, \fB0\fP, +\fBno\fP, and \fBoff\fP, the completion system may use any completion +specifications defined with the \fBcompctl\fP builtin command\&. If the +style is unset, this is done only if the \fBzsh/compctl\fP module +is loaded\&. The string may also contain the substring `\fBfirst\fP\&' to +use completions defined with `\fBcompctl \-T\fP\&', and the substring +`\fBdefault\fP\&' to use the completion defined with `\fBcompctl \-D\fP'\&. +.RS +.PP +Note that this is only intended to smooth the transition from +\fBcompctl\fP to the new completion system and may disappear in the +future\&. +.PP +Note also that the definitions from \fBcompctl\fP will only be used if +there is no specific completion function for the command in question\&. For +example, if there is a function \fB_foo\fP to complete arguments to the +command \fBfoo\fP, \fBcompctl\fP will never be invoked for \fBfoo\fP\&. +However, the \fBcompctl\fP version will be tried if \fBfoo\fP only uses +default completion\&. +.RE +.TP +\fBuse\-ip\fP +By default, the function \fB_hosts\fP that completes host names strips +IP addresses from entries read from host databases such as NIS and +ssh files\&. If this style is `true\&', the corresponding IP addresses +can be completed as well\&. This style is not use in any context +where the \fBhosts\fP style is set; note also it must be set before +the cache of host names is generated (typically the first completion +attempt)\&. +.TP +\fBusers\fP +This may be set to a list of usernames to be completed\&. +If it is not set all usernames will be completed\&. +Note that if it is set only that list of users will be completed; +this is because on some systems querying all users can take +a prohibitive amount of time\&. +.TP +\fBusers\-hosts\fP +The values of this style should be of the form +`\fIuser\fP\fB@\fP\fIhost\fP\&' or `\fIuser\fP\fB:\fP\fIhost\fP'\&. It is used for +commands that need pairs of +user\- and hostnames\&. These commands will complete usernames from this +style (only), and will restrict subsequent hostname completion to hosts +paired with that user in one of the values of the style\&. +.RS +.PP +It is possible to group values for sets of commands which allow a remote +login, such as \fBrlogin\fP and \fBssh\fP, by using the \fBmy\-accounts\fP tag\&. +Similarly, values for sets of commands which usually refer to the +accounts of other people, such as \fBtalk\fP and \fBfinger\fP, can be +grouped by using the \fBother\-accounts\fP tag\&. More ambivalent commands +may use the \fBaccounts\fP tag\&. +.RE +.TP +\fBusers\-hosts\-ports\fP +Like \fBusers\-hosts\fP but used for commands like \fBtelnet\fP and +containing strings of the form `\fIuser\fP\fB@\fP\fIhost\fP\fB:\fP\fIport\fP\&'\&. +.TP +\fBverbose\fP +If set, as it is by default, the completion listing is more verbose\&. +In particular many commands show descriptions for options if this +style is `true\&'\&. +.TP +\fBword\fP +This is used by the \fB_list\fP completer, which prevents the insertion of +completions until a second completion attempt when the line has not +changed\&. The normal way of finding out if the line has changed is to +compare its entire contents between the two occasions\&. If this style is +`true\&', the comparison is instead performed only on the current word\&. +Hence if completion is performed on another word with the same contents, +completion will not be delayed\&. +.PP +.SH "CONTROL FUNCTIONS" +.PP +The initialization script \fBcompinit\fP redefines all the widgets +which perform completion to call the supplied widget function +\fB_main_complete\fP\&. This function acts as a wrapper calling the +so\-called `completer\&' functions that generate matches\&. If +\fB_main_complete\fP is called with arguments, these are taken as the +names of completer functions to be called in the order given\&. If no +arguments are given, the set of functions to try is taken from the +\fBcompleter\fP style\&. For example, to use normal completion and +correction if that doesn\&'t generate any matches: +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer _complete _correct\fP +.fi +.RE +.PP +after calling \fBcompinit\fP\&. The default value for this style is +`\fB_complete _ignored\fP\&', i\&.e\&. normally only ordinary completion is tried, +first with the effect of the \fBignored\-patterns\fP style and then without +it\&. The \fB_main_complete\fP function uses the return status of the completer +functions to decide if other completers should be called\&. If the return +status is zero, no other completers are tried and the \fB_main_complete\fP +function returns\&. +.PP +If the first argument to \fB_main_complete\fP is a single hyphen, the +arguments will not be taken as names of completers\&. Instead, the +second argument gives a name to use in the \fIcompleter\fP field of the +context and the other arguments give a command name and arguments to +call to generate the matches\&. +.PP +The following completer functions are contained in the distribution, +although users may write their own\&. Note that in contexts the leading +underscore is stripped, for example basic completion is performed in the +context `\fB:completion::complete:\fP\fI\&.\&.\&.\fP\&'\&. +.PP +.PD 0 +.TP +.PD +\fB_all_matches\fP +This completer can be used to add a string consisting of all other +matches\&. As it influences later completers it must appear as the first +completer in the list\&. The list of all matches is affected by the +\fBavoid\-completer\fP and \fBold\-matches\fP styles described above\&. +.RS +.PP +It may be useful to use the \fB_generic\fP function described below +to bind \fB_all_matches\fP to its own keystroke, for example: +.PP +.RS +.nf +\fBzle \-C all\-matches complete\-word _generic +bindkey \&'^Xa' all\-matches +zstyle \&':completion:all\-matches:*' old\-matches only +zstyle \&':completion:all\-matches::::' completer _all_matches\fP +.fi +.RE +.PP +Note that this does not generate completions by itself: first use +any of the standard ways of generating a list of completions, +then use \fB^Xa\fP to show all matches\&. It is possible instead to +add a standard completer to the list and request that the +list of all matches should be directly inserted: +.PP +.RS +.nf +\fBzstyle \&':completion:all\-matches::::' completer \e + _all_matches _complete +zstyle \&':completion:all\-matches:*' insert true\fP +.fi +.RE +.PP +In this case the \fBold\-matches\fP style should not be set\&. +.RE +.TP +\fB_approximate\fP +This is similar to the basic \fB_complete\fP completer but allows the +completions to undergo corrections\&. The maximum number of errors can be +specified by the \fBmax\-errors\fP style; see the description of +approximate matching in +\fIzshexpn\fP(1) +for how errors are counted\&. Normally this completer will only be tried +after the normal \fB_complete\fP completer: +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer _complete _approximate\fP +.fi +.RE +.PP +This will give correcting completion if and only if +normal completion yields no possible completions\&. When +corrected completions are found, the completer will normally start +menu completion allowing you to cycle through these strings\&. +.PP +This completer uses the tags \fBcorrections\fP and \fBoriginal\fP when +generating the possible corrections and the original string\&. The +\fBformat\fP style for the former may contain the additional sequences +`\fB%e\fP\&' and `\fB%o\fP' which will be replaced by the number of errors +accepted to generate the corrections and the original string, +respectively\&. +.PP +The completer progressively increases the number of errors allowed up to +the limit by the \fBmax\-errors\fP style, hence if a completion is found +with one error, no completions with two errors will be shown, and so on\&. +It modifies the completer name in the context to indicate the number of +errors being tried: on the first try the completer field contains +`\fBapproximate\-1\fP\&', on the second try `\fBapproximate\-2\fP', and so on\&. +.PP +When \fB_approximate\fP is called from another function, the number of +errors to accept may be passed with the \fB\-a\fP option\&. The argument +is in the same format as the \fBmax\-errors\fP style, all in one string\&. +.PP +Note that this completer (and the \fB_correct\fP completer mentioned +below) can be quite expensive to call, especially when a large number +of errors are allowed\&. One way to avoid this is to set up the +\fBcompleter\fP style using the \fB\-e\fP option to zstyle so that some +completers are only used when completion is attempted a second time on +the same string, e\&.g\&.: +.PP +.RS +.nf +\fBzstyle \-e \&':completion:*' completer ' + if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then + _last_try="$HISTNO$BUFFER$CURSOR" + reply=(_complete _match _prefix) + else + reply=(_ignored _correct _approximate) + fi\&'\fP +.fi +.RE +.PP +This uses the \fBHISTNO\fP parameter and the \fBBUFFER\fP and \fBCURSOR\fP +special parameters that are available inside zle and completion +widgets to find out if the command line hasn\&'t changed since the last +time completion was tried\&. Only then are the \fB_ignored\fP, +\fB_correct\fP and \fB_approximate\fP completers called\&. +.RE +.TP +\fB_canonical_paths\fP [ \fB\-A\fP \fIvar\fP ] [ \fB\-N\fP ] [ \fB\-MJV12nfX\fP ] \fItag\fP \fIdescr\fP [ \fIpaths\fP \&.\&.\&. ] +This completion function completes all paths given to it, and also tries to +offer completions which point to the same file as one of the paths given +(relative path when an absolute path is given, and vice versa; when \fB\&.\&.\fP\&'s +are present in the word to be completed; and some paths got from symlinks)\&. +.RS +.PP +\fB\-A\fP, if specified, takes the paths from the array variable specified\&. Paths can +also be specified on the command line as shown above\&. \fB\-N\fP, if specified, +prevents canonicalizing the paths given before using them for completion, in +case they are already so\&. The options \fB\-M\fP, \fB\-J\fP, \fB\-V\fP, \fB\-1\fP, \fB\-2\fP, +\fB\-n\fP, \fB\-F\fP, \fB\-X\fP are passed to \fBcompadd\fP\&. +.PP +See \fB_description\fP for a description of \fItag\fP and \fIdescr\fP\&. +.RE +.TP +\fB_cmdambivalent\fP +Completes the remaining positional arguments as an external command\&. +The external command and its arguments are completed as separate arguments +(in a manner appropriate for completing \fB/usr/bin/env\fP) +if there are two or more remaining positional arguments on the command line, +and as a quoted command string (in the manner of \fBsystem(\&.\&.\&.)\fP) otherwise\&. +See also \fB_cmdstring\fP and \fB_precommand\fP\&. +.RS +.PP +This function takes no arguments\&. +.RE +.TP +\fB_cmdstring\fP +Completes an external command as a single argument, as for +\fBsystem(\&.\&.\&.)\fP\&. +.TP +\fB_complete\fP +This completer generates all possible completions in a context\-sensitive +manner, i\&.e\&. using the settings defined with the \fBcompdef\fP function +explained above and the current settings of all special parameters\&. +This gives the normal completion behaviour\&. +.RS +.PP +To complete arguments of commands, \fB_complete\fP uses the utility function +\fB_normal\fP, which is in turn responsible for finding the particular +function; it is described below\&. Various contexts of the form +\fB\-\fP\fIcontext\fP\fB\-\fP are handled specifically\&. These are all +mentioned above as possible arguments to the \fB#compdef\fP tag\&. +.PP +Before trying to find a function for a specific context, \fB_complete\fP +checks if the parameter `\fBcompcontext\fP\&' is set\&. Setting +`\fBcompcontext\fP\&' allows the usual completion dispatching to be +overridden which is useful in places such as a function that uses +\fBvared\fP for input\&. If it is set to an array, the elements are taken +to be the possible matches which will be completed using the tag +`\fBvalues\fP\&' and the description `\fBvalue\fP'\&. If it is set to an +associative array, the keys are used as the possible completions and +the values (if non\-empty) are used as descriptions for the matches\&. If +`\fBcompcontext\fP\&' is set to a string containing colons, it should be of +the form `\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP\&'\&. In this case the +\fItag\fP and \fIdescr\fP give the tag and description to use and the +\fIaction\fP indicates what should be completed in one of the forms +accepted by the \fB_arguments\fP utility function described below\&. +.PP +Finally, if `\fBcompcontext\fP\&' is set to a string without colons, the +value is taken as the name of the context to use and the function +defined for that context will be called\&. For this purpose, there is a +special context named \fB\-command\-line\-\fP that completes whole command +lines (commands and their arguments)\&. This is not used by the completion +system itself but is nonetheless handled when explicitly called\&. +.RE +.TP +\fB_correct\fP +Generate corrections, but not completions, for the current word; this is +similar to \fB_approximate\fP but will not allow any number of extra +characters at the cursor as that completer does\&. The effect is +similar to spell\-checking\&. It is based on \fB_approximate\fP, but the +completer field in the context name is \fBcorrect\fP\&. +.RS +.PP +For example, with: +.PP +.RS +.nf +\fBzstyle \&':completion:::::' completer \e + _complete _correct _approximate +zstyle \&':completion:*:correct:::' max\-errors 2 not\-numeric +zstyle \&':completion:*:approximate:::' max\-errors 3 numeric\fP +.fi +.RE +.PP +correction will accept up to two errors\&. If a numeric argument is +given, correction will not be performed, but correcting completion +will be, and will accept as many errors as given by the numeric +argument\&. Without a numeric argument, first correction and then +correcting completion will be tried, with the first one accepting two +errors and the second one accepting three errors\&. +.PP +When \fB_correct\fP is called as a function, the number of errors to accept +may be given following the \fB\-a\fP option\&. The argument is in the same +form a values to the \fBaccept\fP style, all in one string\&. +.PP +This completer function is intended to be used without the +\fB_approximate\fP completer or, as in the example, just before +it\&. Using it after the \fB_approximate\fP completer is useless since +\fB_approximate\fP will at least generate the corrected strings +generated by the \fB_correct\fP completer \-\- and probably more\&. +.RE +.TP +\fB_expand\fP +This completer function does not really perform completion, but instead +checks if the word on the command line is eligible for expansion and, +if it is, gives detailed control over how this expansion is done\&. For +this to happen, the completion system needs to be invoked with +\fBcomplete\-word\fP, not \fBexpand\-or\-complete\fP (the default binding for +\fBTAB\fP), as otherwise the string will be expanded by the shell\&'s +internal mechanism before the completion system is started\&. +Note also this completer should be called before the \fB_complete\fP +completer function\&. +.RS +.PP +The tags used when generating expansions are \fBall\-expansions\fP for the +string containing all possible expansions, \fBexpansions\fP when adding +the possible expansions as single matches and \fBoriginal\fP when adding +the original string from the line\&. The order in which these strings are +generated, if at all, can be controlled by the \fBgroup\-order\fP and +\fBtag\-order\fP styles, as usual\&. +.PP +The format string for \fBall\-expansions\fP and for \fBexpansions\fP may +contain the sequence `\fB%o\fP\&' which will be replaced by the original +string from the line\&. +.PP +The kind of expansion to be tried is controlled by the \fBsubstitute\fP, +\fBglob\fP and \fBsubst\-globs\-only\fP styles\&. +.PP +It is also possible to call \fB_expand\fP as a function, in which case the +different modes may be selected with options: \fB\-s\fP for +\fBsubstitute\fP, \fB\-g\fP for \fBglob\fP and \fB\-o\fP for \fBsubst\-globs\-only\fP\&. +.RE +.TP +\fB_expand_alias\fP +If the word the cursor is on is an alias, it is expanded and no other +completers are called\&. The types of aliases which are to be expanded can +be controlled with the styles \fBregular\fP, \fBglobal\fP and \fBdisabled\fP\&. +.RS +.PP +This function is also a bindable command, see +the section `Bindable Commands\&' below\&. +.RE +.TP +\fB_extensions\fP +If the cursor follows the string `\fB*\&.\fP\&', filename extensions are +completed\&. The extensions are taken from files in current directory or a +directory specified at the beginning of the current word\&. For exact matches, +completion continues to allow other completers such as \fB_expand\fP to +expand the pattern\&. The standard \fBadd\-space\fP and \fBprefix\-hidden\fP +styles are observed\&. +.TP +\fB_external_pwds\fP +Completes current directories of other zsh processes belonging to the +current user\&. +.RS +.PP +This is intended to be used via \fB_generic\fP, bound to a custom key +combination\&. Note that pattern matching is enabled so matching is +performed similar to how it works with the \fB_match\fP completer\&. +.RE +.TP +\fB_history\fP +Complete words from the shell\&'s command history\&. This completer +can be controlled by the \fBremove\-all\-dups\fP, and \fBsort\fP styles as for the +\fB_history_complete_word\fP bindable command, see +the section `Bindable Commands\&' below +and +the section `Completion System Configuration\&' above\&. +.TP +\fB_ignored\fP +The \fBignored\-patterns\fP style can be set to a list of patterns which are +compared against possible completions; matching ones are removed\&. +With this completer those matches can be reinstated, as +if no \fBignored\-patterns\fP style were set\&. The completer actually +generates its own list of matches; which completers are invoked +is determined in the same way as for the \fB_prefix\fP completer\&. +The \fBsingle\-ignored\fP style is also available as described above\&. +.TP +\fB_list\fP +This completer allows the insertion of matches to be delayed until +completion is attempted a second time without the word on the line +being changed\&. On the first attempt, only the list of matches will be +shown\&. It is affected by the styles \fBcondition\fP and \fBword\fP, see +the section `Completion System Configuration\&' above\&. +.TP +\fB_match\fP +This completer is intended to be used after the \fB_complete\fP +completer\&. It behaves similarly but the string on the command line may +be a pattern to match against trial completions\&. This gives the effect +of the \fBGLOB_COMPLETE\fP option\&. +.RS +.PP +Normally completion will be performed by taking the pattern from the line, +inserting a `\fB*\fP\&' at the cursor position and comparing the resulting +pattern with the possible completions generated\&. This can be modified +with the \fBmatch\-original\fP style described above\&. +.PP +The generated matches will be offered in a menu completion unless the +\fBinsert\-unambiguous\fP style is set to `true\&'; see the description above +for other options for this style\&. +.PP +Note that matcher specifications defined globally or used by the +completion functions (the styles \fBmatcher\-list\fP and \fBmatcher\fP) will +not be used\&. +.RE +.TP +\fB_menu\fP +This completer was written as simple example function to show how menu +completion can be enabled in shell code\&. However, it has the notable +effect of disabling menu selection which can be useful with +\fB_generic\fP based widgets\&. It should be used as the first completer in +the list\&. Note that this is independent of the setting of the +\fBMENU_COMPLETE\fP option and does not work with the other menu +completion widgets such as \fBreverse\-menu\-complete\fP, or +\fBaccept\-and\-menu\-complete\fP\&. +.TP +\fB_oldlist\fP +This completer controls how the standard completion widgets behave +when there is an existing list of completions which may have been +generated by a special completion (i\&.e\&. a separately\-bound completion +command)\&. It allows the ordinary completion keys to continue to use the +list of completions thus generated, instead of producing a new list of +ordinary contextual completions\&. +It should appear in the list of completers before any of +the widgets which generate matches\&. It uses two styles: \fBold\-list\fP and +\fBold\-menu\fP, see +the section `Completion System Configuration\&' above\&. +.TP +\fB_precommand\fP +Complete an external command in word\-separated arguments, as for +\fBexec\fP and \fB/usr/bin/env\fP\&. +.TP +\fB_prefix\fP +This completer can be used to try completion with the suffix (everything +after the cursor) ignored\&. In other words, the suffix will not be +considered to be part of the word to complete\&. The effect is similar +to the \fBexpand\-or\-complete\-prefix\fP command\&. +.RS +.PP +The \fBcompleter\fP style is used to decide which other completers are to +be called to generate matches\&. If this style is unset, the list of +completers set for the current context is used \-\- except, of course, the +\fB_prefix\fP completer itself\&. Furthermore, if this completer appears +more than once in the list of completers only those completers not +already tried by the last invocation of \fB_prefix\fP will be called\&. +.PP +For example, consider this global \fBcompleter\fP style: +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer \e + _complete _prefix _correct _prefix:foo\fP +.fi +.RE +.PP +Here, the \fB_prefix\fP completer tries normal completion but ignoring the +suffix\&. If that doesn\&'t generate any matches, and neither does +the call to the \fB_correct\fP completer after it, \fB_prefix\fP will +be called a second time and, now only trying correction with the +suffix ignored\&. On the second invocation the completer part of the +context appears as `\fBfoo\fP\&'\&. +.PP +To use \fB_prefix\fP as the last resort and try only normal completion +when it is invoked: +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer _complete \&.\&.\&. _prefix +zstyle \&':completion::prefix:*' completer _complete\fP +.fi +.RE +.PP +The \fBadd\-space\fP style is also respected\&. If it is set to `true\&' then +\fB_prefix\fP will insert a space between the matches generated (if any) +and the suffix\&. +.PP +Note that this completer is only useful if the +\fBCOMPLETE_IN_WORD\fP option is set; otherwise, the cursor will +be moved to the end of the current word before the completion code is +called and hence there will be no suffix\&. +.RE +.TP +\fB_user_expand\fP +This completer behaves similarly to the \fB_expand\fP completer but +instead performs expansions defined by users\&. The styles \fBadd\-space\fP and +\fBsort\fP styles specific to the \fB_expand\fP completer are usable with +\fB_user_expand\fP in addition to other styles handled more generally by +the completion system\&. The tag \fBall\-expansions\fP is also available\&. +.RS +.PP +The expansion depends on the array style \fBuser\-expand\fP being defined +for the current context; remember that the context for completers is less +specific than that for contextual completion as the full context has not +yet been determined\&. Elements of the array may have one of the following +forms: +.PP +.PD 0 +.TP +\fB$\fP\fIhash\fP + +\fIhash\fP is the name of an associative array\&. Note this is not a full +parameter expression, merely a \fB$\fP, suitably quoted to prevent immediate +expansion, followed by the name of an associative array\&. If the trial +expansion word matches a key in \fIhash\fP, the resulting expansion is the +corresponding value\&. +.PP +.TP +\fI_func\fP + +\fI_func\fP is the name of a shell function whose name must begin with +\fB_\fP but is not otherwise special to the completion system\&. The function +is called with the trial word as an argument\&. If the word is to be +expanded, the function should set the array \fBreply\fP to a list of +expansions\&. Optionally, it can set \fBREPLY\fP to a word that will +be used as a description for the set of expansions\&. +The return status of the function is irrelevant\&. +.PP +.PD +.RE +.PP +.SH "BINDABLE COMMANDS" +.PP +In addition to the context\-dependent completions provided, which are +expected to work in an intuitively obvious way, there are a few widgets +implementing special behaviour which can be bound separately to keys\&. The +following is a list of these and their default bindings\&. +.PP +.PD 0 +.TP +.PD +\fB_bash_completions\fP +This function is used by two widgets, \fB_bash_complete\-word\fP and +\fB_bash_list\-choices\fP\&. It exists to provide compatibility with +completion bindings in bash\&. The last character of the binding determines +what is completed: `\fB!\fP\&', command names; `\fB$\fP', environment variables; +`\fB@\fP\&', host names; `\fB/\fP', file names; `\fB~\fP' user names\&. In bash, the +binding preceded by `\fB\ee\fP\&' gives completion, and preceded by `\fB^X\fP' +lists options\&. As some of these bindings clash with standard zsh +bindings, only `\fB\ee~\fP\&' and `\fB^X~\fP' are bound by default\&. To add the +rest, the following should be added to \fB\&.zshrc\fP after \fBcompinit\fP has +been run: +.RS +.PP +.RS +.nf +\fBfor key in \&'!' '$' '@' '/' '~'; do + bindkey "\ee$key" _bash_complete\-word + bindkey "^X$key" _bash_list\-choices +done\fP +.fi +.RE +.PP +This includes the bindings for `\fB~\fP\&' in case they were already bound to +something else; the completion code does not override user bindings\&. +.RE +.TP +\fB_correct_filename\fP (\fB^XC\fP) +Correct the filename path at the cursor position\&. Allows up to six errors +in the name\&. Can also be called with an argument to correct +a filename path, independently of zle; the correction is printed on +standard output\&. +.TP +\fB_correct_word\fP (\fB^Xc\fP) +Performs correction of the current argument using the usual contextual +completions as possible choices\&. This stores the string +`\fBcorrect\-word\fP\&' in the \fIfunction\fP field of the context name and +then calls the \fB_correct\fP completer\&. +.TP +\fB_expand_alias\fP (\fB^Xa\fP) +This function can be used as a completer and as a bindable command\&. +It expands the word the cursor is on if it is an alias\&. The types of +alias expanded can be controlled with the styles \fBregular\fP, \fBglobal\fP +and \fBdisabled\fP\&. +.RS +.PP +When used as a bindable command there is one additional feature that +can be selected by setting the \fBcomplete\fP style to `true\&'\&. In this +case, if the word is not the name of an alias, \fB_expand_alias\fP tries +to complete the word to a full alias name without expanding it\&. It +leaves the cursor directly after the completed word so that invoking +\fB_expand_alias\fP once more will expand the now\-complete alias name\&. +.RE +.TP +\fB_expand_word\fP (\fB^Xe\fP) +Performs expansion on the current word: equivalent to the standard +\fBexpand\-word\fP command, but using the \fB_expand\fP completer\&. Before +calling it, the \fIfunction\fP field of the context is set to +`\fBexpand\-word\fP\&'\&. +.TP +\fB_generic\fP +This function is not defined as a widget and not bound by +default\&. However, it can be used to define a widget and will then +store the name of the widget in the \fIfunction\fP field of the context +and call the completion system\&. This allows custom completion widgets +with their own set of style settings to be defined easily\&. For example, +to define a widget that performs normal completion and starts +menu selection: +.RS +.PP +.RS +.nf +\fBzle \-C foo complete\-word _generic +bindkey \&'\&.\&.\&.' foo +zstyle \&':completion:foo:*' menu yes select=1\fP +.fi +.RE +.PP +Note in particular that the \fBcompleter\fP style may be set for the context +in order to change the set of functions used to generate possible matches\&. +If \fB_generic\fP is called with arguments, those are passed through to +\fB_main_complete\fP as the list of completers in place of those defined by +the \fBcompleter\fP style\&. +.RE +.TP +\fB_history_complete_word\fP (\fB\ee/\fP) +Complete words from the shell\&'s command history\&. This uses the +\fBlist\fP, \fBremove\-all\-dups\fP, \fBsort\fP, and \fBstop\fP styles\&. +.TP +\fB_most_recent_file\fP (\fB^Xm\fP) +Complete the name of the most recently modified file matching the pattern +on the command line (which may be blank)\&. If given a numeric argument +\fIN\fP, complete the \fIN\fPth most recently modified file\&. Note the +completion, if any, is always unique\&. +.TP +\fB_next_tags\fP (\fB^Xn\fP) +This command alters the set of matches used to that for the next tag, or +set of tags, either as given by the \fBtag\-order\fP style or as set by +default; these matches would otherwise not be available\&. +Successive invocations of the command cycle through all possible sets of +tags\&. +.TP +\fB_read_comp\fP (\fB^X^R\fP) +Prompt the user for a string, and use that to perform completion on the +current word\&. There are two possibilities for the string\&. First, it can +be a set of words beginning `\fB_\fP\&', for example `\fB_files \-/\fP', in which +case the function with any arguments will be called to generate the +completions\&. Unambiguous parts of the function name will be completed +automatically (normal completion is not available at this point) until a +space is typed\&. +.RS +.PP +Second, any other string will be passed as a set of arguments to +\fBcompadd\fP and should hence be an expression specifying what should +be completed\&. +.PP +A very restricted set of editing commands is available when reading the +string: `\fBDEL\fP\&' and `\fB^H\fP' delete the last character; `\fB^U\fP' deletes +the line, and `\fB^C\fP\&' and `\fB^G\fP' abort the function, while `\fBRET\fP' +accepts the completion\&. Note the string is used verbatim as a command +line, so arguments must be quoted in accordance with standard shell rules\&. +.PP +Once a string has been read, the next call to \fB_read_comp\fP will use the +existing string instead of reading a new one\&. To force a new string to be +read, call \fB_read_comp\fP with a numeric argument\&. +.RE +.TP +\fB_complete_debug\fP (\fB^X?\fP) +This widget performs ordinary completion, but captures in a temporary file +a trace of the shell commands executed by the completion system\&. Each +completion attempt gets its own file\&. A command to view each of these +files is pushed onto the editor buffer stack\&. +.TP +\fB_complete_help\fP (\fB^Xh\fP) +This widget displays information about the context names, +the tags, and the completion functions used +when completing at the current cursor position\&. If given a numeric +argument other than \fB1\fP (as in `\fBESC\-2 ^Xh\fP\&'), then the styles +used and the contexts for which they are used will be shown, too\&. +.RS +.PP +Note that the information about styles may be incomplete; it depends on the +information available from the completion functions called, which in turn +is determined by the user\&'s own styles and other settings\&. +.RE +.TP +\fB_complete_help_generic\fP +Unlike other commands listed here, this must be created as a normal ZLE +widget rather than a completion widget (i\&.e\&. with \fBzle \-N\fP)\&. It +is used for generating help with a widget bound to the \fB_generic\fP +widget that is described above\&. +.RS +.PP +If this widget is created using the name of the function, as it is by +default, then when executed it will read a key sequence\&. This is expected +to be bound to a call to a completion function that uses the \fB_generic\fP +widget\&. That widget will be executed, and information provided in +the same format that the \fB_complete_help\fP widget displays for +contextual completion\&. +.PP +If the widget\&'s name contains \fBdebug\fP, for example if it is created +as `\fBzle \-N _complete_debug_generic _complete_help_generic\fP\&', it +will read and execute the keystring for a generic widget as before, +but then generate debugging information as done by \fB_complete_debug\fP +for contextual completion\&. +.PP +If the widget\&'s name contains \fBnoread\fP, it will not read a keystring +but instead arrange that the next use of a generic widget run in +the same shell will have the effect as described above\&. +.PP +The widget works by setting the shell parameter +\fBZSH_TRACE_GENERIC_WIDGET\fP which is read by \fB_generic\fP\&. Unsetting +the parameter cancels any pending effect of the \fBnoread\fP form\&. +.PP +For example, after executing the following: +.PP +.RS +.nf +\fBzle \-N _complete_debug_generic _complete_help_generic +bindkey \&'^x:' _complete_debug_generic\fP +.fi +.RE +.PP +typing `\fBC\-x :\fP\&' followed by the key sequence for a generic widget +will cause trace output for that widget to be saved to a file\&. +.RE +.TP +\fB_complete_tag\fP (\fB^Xt\fP) +This widget completes symbol tags created by the \fBetags\fP or \fBctags\fP +programmes (note there is no connection with the completion system\&'s tags) +stored in a file \fBTAGS\fP, in the format used by \fBetags\fP, or \fBtags\fP, in the +format created by \fBctags\fP\&. It will look back up the path hierarchy for +the first occurrence of either file; if both exist, the file \fBTAGS\fP is +preferred\&. You can specify the full path to a \fBTAGS\fP or \fBtags\fP file by +setting the parameter \fB$TAGSFILE\fP or \fB$tagsfile\fP respectively\&. +The corresponding completion tags used are \fBetags\fP and \fBvtags\fP, after +emacs and vi respectively\&. +.PP +.SH "UTILITY FUNCTIONS" +.PP +Descriptions follow for utility functions that may be +useful when writing completion functions\&. If functions are installed in +subdirectories, most of these reside in the +\fBBase\fP subdirectory\&. Like the example +functions for commands in the distribution, the utility functions +generating matches all follow the convention of returning status zero if they +generated completions and non\-zero if no matching completions could be +added\&. +.PP +.PD 0 +.TP +.PD +\fB_absolute_command_paths\fP +This function completes external commands as absolute paths (unlike +\fB_command_names \-e\fP which completes their basenames)\&. It takes no +arguments\&. +.TP +\fB_all_labels\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP [ \fIcommand\fP \fIarg\fP \&.\&.\&. ] +This is a convenient interface to the \fB_next_label\fP function below, +implementing the loop shown in the \fB_next_label\fP example\&. The +\fIcommand\fP and its arguments are called to generate the matches\&. The +options stored in the parameter \fIname\fP will automatically be inserted +into the \fIarg\fPs passed to the \fIcommand\fP\&. Normally, they are put +directly after the \fIcommand\fP, but if one of the \fIarg\fPs is a single +hyphen, they are inserted directly before that\&. If the hyphen is the last +argument, it will be removed from the argument list before the +\fIcommand\fP is called\&. This allows \fB_all_labels\fP to be used in almost all +cases where the matches can be generated by a single call to the +\fBcompadd\fP builtin command or by a call to one of the utility functions\&. +.RS +.PP +For example: +.PP +.RS +.nf +\fBlocal expl +\&.\&.\&. +if _requested foo; then + \&.\&.\&. + _all_labels foo expl \&'\&.\&.\&.' compadd \&.\&.\&. \- $matches +fi\fP +.fi +.RE +.PP +Will complete the strings from the \fBmatches\fP parameter, using +\fBcompadd\fP with additional options which will take precedence over +those generated by \fB_all_labels\fP\&. +.RE +.TP +\fB_alternative\fP [ \fB\-O\fP \fIname\fP ] [ \fB\-C\fP \fIname\fP ] \fIspec\fP \&.\&.\&. +This function is useful in simple cases where multiple tags are available\&. +Essentially it implements a loop like the one described for the \fB_tags\fP +function below\&. +.RS +.PP +The tags to use and the action to perform if a tag is requested are +described using the \fIspec\fPs which are of the form: +`\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP\&'\&. The \fItag\fPs are offered using +\fB_tags\fP and if the tag is requested, the \fIaction\fP is executed with the +given description \fIdescr\fP\&. The \fIaction\fPs are those accepted +by the \fB_arguments\fP function (described below), with the following +exceptions: +.PD 0 +.TP +.PD +\(bu +The `\fB\->\fP\fIstate\fP\&' and `\fB=\fP\fI\&.\&.\&.\fP' forms are not supported\&. + +.TP +\(bu +The `\fB((a\e:bar b\e:baz\fP\fB))\fP\&' form does not need +the colon to be escaped, since the \fIspec\fPs have no colon\-separated fields +after the \fIaction\fP\&. + +.PP +For example, the \fIaction\fP may be a simple function call: +.PP +.RS +.nf +\fB_alternative \e + \&'users:user:_users' \e + \&'hosts:host:_hosts'\fP +.fi +.RE +.PP +offers usernames and hostnames as possible matches, +generated by the \fB_users\fP and \fB_hosts\fP functions respectively\&. +.PP +Like \fB_arguments\fP, this function uses \fB_all_labels\fP to execute +the actions, which will loop over all sets of tags\&. Special handling is +only required if there is an additional valid tag, for example inside a +function called from \fB_alternative\fP\&. +.PP +The option `\fB\-O\fP \fIname\fP\&' is used in the same way as by the +\fB_arguments\fP function\&. In other words, the elements of the \fIname\fP +array will be passed to \fBcompadd\fP when executing an action\&. +.PP +Like \fB_tags\fP this function supports the \fB\-C\fP option to give a +different name for the argument context field\&. +.RE + +.TP +.PD 0 +\fB_arguments \fP[ \fB\-nswWCRS\fP ] [ \fB\-A\fP \fIpat\fP ] [ \fB\-O\fP \fIname\fP ] [ \fB\-M\fP \fImatchspec\fP ] +.TP +.PD 0 +\fB \fP[ \fB:\fP ] \fIspec\fP \&.\&.\&. +.TP +.PD 0 +\fB_arguments \fP[ \fIopt\fP \&.\&.\&. ] \fB\-\fP\fB\-\fP [ \fB\-l\fP ] [ \fB\-i\fP \fIpats\fP ] [ \fB\-s\fP \fIpair\fP ] +.TP +.PD +\fB \fP[ \fIhelpspec\fP \&.\&.\&.] +This function can be used to give a complete specification for completion +for a command whose arguments follow standard UNIX option and argument +conventions\&. +.RS +.PP +\fIOptions Overview\fP +.PP +Options to \fB_arguments\fP itself must be in separate words, i\&.e\&. \fB\-s \-w\fP, +not \fB\-sw\fP\&. The options are followed by \fIspec\fPs that describe options and +arguments of the analyzed command\&. To avoid ambiguity, all +options to \fB_arguments\fP itself may be separated from the \fIspec\fP forms +by a single colon\&. +.PP +The `\fB\-\fP\fB\-\fP\&' +form is used to intuit \fIspec\fP forms from the help output of the command +being analyzed, and is described in detail below\&. The \fIopts\fP for the +`\fB\-\fP\fB\-\fP\&' form are otherwise the same options as the first form\&. Note +that `\fB\-s\fP\&' following `\fB\-\fP\fB\-\fP' has a distinct meaning from `\fB\-s\fP' +preceding `\fB\-\fP\fB\-\fP\&', and both may appear\&. +.PP +The option switches \fB\-s\fP, \fB\-S\fP, \fB\-A\fP, \fB\-w\fP, and \fB\-W\fP affect how +\fB_arguments\fP parses the analyzed command line\&'s options\&. These switches are +useful for commands with standard argument parsing\&. +.PP +The options of \fB_arguments\fP have the following meanings: +.PP +.PD 0 +.TP +.PD +\fB\-n\fP +With this option, \fB_arguments\fP sets the parameter \fBNORMARG\fP +to the position of the first normal argument in the \fB$words\fP array, +i\&.e\&. the position after the end of the options\&. If that argument +has not been reached, \fBNORMARG\fP is set to \fB\-1\fP\&. The caller +should declare `\fBinteger NORMARG\fP\&' if the \fB\-n\fP option is passed; +otherwise the parameter is not used\&. +.TP +\fB\-s\fP +Enable \fIoption stacking\fP for single\-letter options, whereby multiple +single\-letter options may be combined into a single word\&. For example, +the two options `\fB\-x\fP\&' and `\fB\-y\fP' may be combined into +a single word `\fB\-xy\fP\&'\&. By default, every word corresponds to a single +option name (`\fB\-xy\fP\&' is a single option named `\fBxy\fP')\&. +.RS +.PP +Options beginning with a single hyphen or plus sign are eligible for stacking; +words beginning with two hyphens are not\&. +.PP +Note that \fB\-s\fP after \fB\-\fP\fB\-\fP has a different meaning, which is documented +in the segment entitled `Deriving \fIspec\fP forms from the help output\&'\&. +.RE +.TP +\fB\-w\fP +In combination with \fB\-s\fP, allow option stacking +even if one or more of the options take +arguments\&. For example, if \fB\-x\fP takes an argument, with no +\fB\-s\fP, `\fB\-xy\fP\&' is considered as a single (unhandled) option; with +\fB\-s\fP, \fB\-xy\fP is an option with the argument `\fBy\fP\&'; with both \fB\-s\fP +and \fB\-w\fP, \fB\-xy\fP is the option \fB\-x\fP and the option \fB\-y\fP with +arguments to \fB\-x\fP (and to \fB\-y\fP, if it takes arguments) still to come +in subsequent words\&. +.TP +\fB\-W\fP +This option takes \fB\-w\fP a stage further: it is possible to +complete single\-letter options even after an argument that occurs in the +same word\&. However, it depends on the action performed whether options +will really be completed at this point\&. For more control, use a +utility function like \fB_guard\fP as part of the action\&. +.TP +\fB\-C\fP +Modify the \fBcurcontext\fP parameter for an action of the form `\fB\->\fP\fIstate\fP\&'\&. +This is discussed in detail below\&. +.TP +\fB\-R\fP +Return status 300 instead of zero when a \fB$state\fP is to +be handled, in the `\fB\->\fP\fIstring\fP\&' syntax\&. +.TP +\fB\-S\fP +Do not complete options after a `\fB\-\fP\fB\-\fP\&' appearing on the line, +and ignore the `\fB\-\fP\fB\-\fP\&'\&. For example, with \fB\-S\fP, in the line +.RS +.PP +.RS +.nf +\fBfoobar \-x \-\- \-y\fP +.fi +.RE +.PP +the `\fB\-x\fP\&' is considered an option, the `\fB\-y\fP' is considered an +argument, and the `\fB\-\fP\fB\-\fP\&' is considered to be neither\&. +.RE +.TP +\fB\-A\fP \fIpat\fP +Do not complete options after the first non\-option +argument on the line\&. \fIpat\fP is a pattern matching +all strings which are not to be taken as arguments\&. For example, to make +\fB_arguments\fP stop completing options after the first normal argument, but +ignoring all strings starting with a hyphen even if they are not described +by one of the \fIoptspec\fPs, the form is `\fB\-A "\-*"\fP\&'\&. +.TP +\fB\-O\fP \fIname\fP +Pass the elements of the array \fIname\fP as arguments to functions called to +execute \fIaction\fPs\&. +This is discussed in detail below\&. +.TP +\fB\-M\fP \fImatchspec\fP +Use the match specification \fImatchspec\fP for completing option names and values\&. +The default \fImatchspec\fP allows partial word completion after `\fB_\fP\&' and +`\fB\-\fP\&', such as completing `\fB\-f\-b\fP' to `\fB\-foo\-bar\fP'\&. The default +\fImatchspec\fP is: +.RS +.nf +\fB\fBr:|[_\-]=* r:|=*\fP\fP +.fi +.RE +.TP +\fB\-0\fP +When populating values of the `\fBopt_args\fP\&' associative array, don't +backslash\-escape colons and backslashes and use NUL rather than colon for +joining multiple values\&. This option is described in more detail below, under +the heading \fI\fIspec\fPs: actions\fP\&. +.PP +\fI\fIspec\fPs: overview\fP +.PP +Each of the following forms is a \fIspec\fP describing individual sets of +options or arguments on the command line being analyzed\&. +.PP +.PD 0 +.TP +.PD 0 +\fIn\fP\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD +\fIn\fP\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP +This describes the \fIn\fP\&'th normal argument\&. The \fImessage\fP will be +printed above the matches generated and the \fIaction\fP indicates what can +be completed in this position (see below)\&. If there are two colons +before the \fImessage\fP the argument is optional\&. If the +\fImessage\fP contains only white space, nothing will be printed above +the matches unless the action adds an explanation string itself\&. +.TP +.PD 0 +\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD +\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP +Similar, but describes the \fInext\fP argument, whatever number that +happens to be\&. If all arguments are specified in this form in the +correct order the numbers are unnecessary\&. +.TP +.PD 0 +\fB*:\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD 0 +\fB*::\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD +\fB*:::\fP\fImessage\fP\fB:\fP\fIaction\fP +This describes how arguments (usually non\-option arguments, those not +beginning with \fB\-\fP or \fB+\fP) are to be completed when neither +of the first two forms was provided\&. Any number of arguments can +be completed in this fashion\&. +.RS +.PP +With two colons before the \fImessage\fP, the \fBwords\fP special array and +the \fBCURRENT\fP special parameter are modified to refer only to the +normal arguments when the \fIaction\fP is executed or evaluated\&. With +three colons before the \fImessage\fP they are modified to refer only to +the normal arguments covered by this description\&. +.RE +.TP +.PD 0 +\fIoptspec\fP +.TP +.PD +\fIoptspec\fP\fB:\fP\fI\&.\&.\&.\fP +This describes an option\&. The colon indicates handling for one or more +arguments to the option; if it is not present, the option is assumed to +take no arguments\&. +.RS +.PP +The following forms are available for the initial \fIoptspec\fP, whether +or not the option has arguments\&. +.PP +.PD 0 +.TP +.PD +\fB*\fP\fIoptspec\fP +Here \fIoptspec\fP is one of the remaining forms below\&. This indicates +the following \fIoptspec\fP may be repeated\&. Otherwise if the +corresponding option is already present on the command line to the left +of the cursor it will not be offered again\&. +.TP +.PD 0 +\fB\-\fP\fIoptname\fP +.TP +.PD +\fB+\fP\fIoptname\fP +In the simplest form the \fIoptspec\fP is just the option name beginning +with a minus or a plus sign, such as `\fB\-foo\fP\&'\&. The first argument for +the option (if any) must follow as a \fIseparate\fP word directly after the +option\&. +.RS +.PP +Either of `\fB\-+\fP\fIoptname\fP\&' and `\fB+\-\fP\fIoptname\fP' can be used to +specify that \fB\-\fP\fIoptname\fP and \fB+\fP\fIoptname\fP are both valid\&. +.PP +In all the remaining forms, the leading `\fB\-\fP\&' may be replaced by or +paired with `\fB+\fP\&' in this way\&. +.RE +.TP +\fB\-\fP\fIoptname\fP\fB\-\fP +The first argument of the option must come directly after the option name +\fIin the same word\fP\&. For example, `\fB\-foo\-:\fP\fI\&.\&.\&.\fP\&' specifies that +the completed option and argument will look like `\fB\-foo\fP\fIarg\fP\&'\&. +.TP +\fB\-\fP\fIoptname\fP\fB+\fP +The first argument may appear immediately after \fIoptname\fP in the same +word, or may appear as a separate word after the option\&. For example, +`\fB\-foo+:\fP\fI\&.\&.\&.\fP\&' specifies that the completed option and argument +will look like either `\fB\-foo\fP\fIarg\fP\&' or `\fB\-foo\fP \fIarg\fP'\&. +.TP +\fB\-\fP\fIoptname\fP\fB=\fP +The argument may appear as the next word, or in same word as the option +name provided that it is separated from it by an equals sign, for +example `\fB\-foo=\fP\fIarg\fP\&' or `\fB\-foo\fP \fIarg\fP'\&. +.TP +\fB\-\fP\fIoptname\fP\fB=\-\fP +The argument to the option must appear after an equals sign in the same +word, and may not be given in the next argument\&. +.TP +\fIoptspec\fP\fB[\fP\fIexplanation\fP\fB]\fP +An explanation string may be appended to any of the preceding forms of +\fIoptspec\fP by enclosing it in brackets, as in `\fB\-q[query operation]\fP\&'\&. +.RS +.PP +The \fBverbose\fP style is used to decide whether the explanation strings +are displayed with the option in a completion listing\&. +.PP +If no bracketed explanation string is given but the \fBauto\-description\fP +style is set and only one argument is described for this \fIoptspec\fP, the +value of the style is displayed, with any appearance of the sequence +`\fB%d\fP\&' in it replaced by the \fImessage\fP of the first \fIoptarg\fP +that follows the \fIoptspec\fP; see below\&. +.RE +.PP +It is possible for options with a literal `\fB+\fP\&' or `\fB=\fP' to +appear, but that character must be quoted, for example `\fB\-\e+\fP\&'\&. +.PP +Each \fIoptarg\fP following an \fIoptspec\fP must take one of the +following forms: +.PP +.PD 0 +.TP +.PD 0 +\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD +\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP +An argument to the option; \fImessage\fP and \fIaction\fP are treated as +for ordinary arguments\&. In the first form, the argument is mandatory, +and in the second form it is optional\&. +.RS +.PP +This group may be repeated for options which take multiple arguments\&. +In other words, +\fB:\fP\fImessage1\fP\fB:\fP\fIaction1\fP\fB:\fP\fImessage2\fP\fB:\fP\fIaction2\fP +specifies that the option takes two arguments\&. +.RE +.TP +.PD 0 +\fB:*\fP\fIpattern\fP\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD 0 +\fB:*\fP\fIpattern\fP\fB::\fP\fImessage\fP\fB:\fP\fIaction\fP +.TP +.PD +\fB:*\fP\fIpattern\fP\fB:::\fP\fImessage\fP\fB:\fP\fIaction\fP +This describes multiple arguments\&. Only the last \fIoptarg\fP for +an option taking multiple arguments may be +given in this form\&. If the \fIpattern\fP is empty (i\&.e\&. \fB:*:\fP), all +the remaining words on the line are to be completed as described by the +\fIaction\fP; otherwise, all the words up to and including a word matching +the \fIpattern\fP are to be completed using the \fIaction\fP\&. +.RS +.PP +Multiple colons are treated as for the `\fB*:\fP\fI\&.\&.\&.\fP\&' forms for +ordinary arguments: when the \fImessage\fP is preceded by two colons, +the \fBwords\fP special array and the \fBCURRENT\fP special parameter are +modified during the execution or evaluation of the \fIaction\fP to refer +only to the words after the option\&. When preceded by three colons, they +are modified to refer only to the words covered by this description\&. +.RE +.RE +.PP +Any literal colon in an \fIoptname\fP, \fImessage\fP, or \fIaction\fP +must be preceded by a backslash, `\fB\e:\fP\&'\&. +.PP +Each of the forms above may be preceded by a list in parentheses +of option names and argument numbers\&. If the given option is on +the command line, the options and arguments indicated in parentheses +will not be offered\&. For example, +`\fB(\-two \-three 1)\-one:\fP\fI\&.\&.\&.\fP\&' completes the option `\fB\-one\fP'; if this +appears on the command line, the options \fB\-two\fP and \fB\-three\fP and the +first ordinary argument will not be completed after it\&. +`\fB(\-foo):\fP\fI\&.\&.\&.\fP\&' specifies an ordinary argument completion; +\fB\-foo\fP will not be completed if that argument is already present\&. +.PP +Other items may appear in the list of excluded options to indicate +various other items that should not be applied when the current +specification is matched: a single star (\fB*\fP) for the rest arguments +(i\&.e\&. a specification of the form `\fB*:\fP\fI\&.\&.\&.\fP\&'); a colon (\fB:\fP) +for all normal (non\-option\-) arguments; and a hyphen (\fB\-\fP) for all +options\&. For example, if `\fB(*)\fP\&' appears before an option and the +option appears on the command line, the list of remaining arguments +(those shown in the above table beginning with `\fB*:\fP\&') will not be +completed\&. +.PP +To aid in reuse of specifications, it is possible to precede any of the +forms above with `\fB!\fP\&'; then the form will no longer be completed, +although if the option or argument appears on the command line they will +be skipped as normal\&. The main use for this is when the arguments are +given by an array, and \fB_arguments\fP is called repeatedly for more +specific contexts: on the first call `\fB_arguments $global_options\fP\&' is +used, and on subsequent calls `\fB_arguments !$^global_options\fP\&'\&. +.PP +\fI\fIspec\fPs: actions\fP + +.PP +In each of the forms above the \fIaction\fP determines how +completions should be generated\&. Except for the `\fB\->\fP\fIstring\fP\&' +form below, the \fIaction\fP will be executed by calling the +\fB_all_labels\fP function to process all tag labels\&. No special handling +of tags is needed unless a function call introduces a new one\&. +.PP +The functions called to execute \fIaction\fPs will be called with the +elements of the array named by the `\fB\-O\fP \fIname\fP\&' option as arguments\&. +This can be used, for example, to pass the same set of options for the +\fBcompadd\fP builtin to all \fIaction\fPs\&. +.PP +The forms for \fIaction\fP are as follows\&. +.PP +.PD 0 +.TP +.PD +\fB \fP(single unquoted space) +This is useful where an argument is required but it is not possible or +desirable to generate matches for it\&. The +\fImessage\fP will be displayed but no completions listed\&. Note +that even in this case the colon at the end of the \fImessage\fP is +needed; it may only be omitted when neither a \fImessage\fP +nor an \fIaction\fP is given\&. +.TP +\fB(\fP\fIitem1\fP \fIitem2\fP \fI\&.\&.\&.\fP\fB)\fP +One of a list of possible matches, for example: +.RS +.PP +.RS +.nf +\fB\fB:foo:(foo bar baz\fP\fB)\fP\fP +.fi +.RE +.RE +.TP +\fB((\fIitem1\fP\e:\fIdesc1\fP \fI\&.\&.\&.\fP))\fP +Similar to the above, but with descriptions for each possible match\&. +Note the backslash before the colon\&. For example, +.RS +.PP +.RS +.nf +\fB\fB:foo:((a\e:bar b\e:baz\fP\fB))\fP\fP +.fi +.RE +.PP +The matches will be listed together with their descriptions if the +\fBdescription\fP style is set with the \fBvalues\fP tag in the context\&. +.RE +.TP +\fB\->\fP\fIstring\fP +In this form, \fB_arguments\fP processes the arguments and options and then +returns control to the calling function with parameters set to indicate the +state of processing; the calling function then makes its own arrangements +for generating completions\&. For example, functions that implement a state +machine can use this type of action\&. +.RS +.PP +Where \fB_arguments\fP encounters \fIaction\fP in the `\fB\->\fP\fIstring\fP\&' +format, it will strip all leading and trailing whitespace from \fIstring\fP +and set the array \fBstate\fP to the set of all \fIstring\fPs for which an +action is to be performed\&. The elements of the array \fBstate_descr\fP are +assigned the corresponding \fImessage\fP field from each \fIoptarg\fP +containing such an \fIaction\fP\&. +.PP +By default and in common with all other well behaved completion +functions, _arguments returns status zero if it was able to add matches and +non\-zero otherwise\&. However, if the \fB\-R\fP option is given, +\fB_arguments\fP will instead return a status of 300 to indicate that +\fB$state\fP is to be handled\&. +.PP +In addition to \fB$state\fP and \fB$state_descr\fP, \fB_arguments\fP also +sets the global +parameters `\fBcontext\fP\&', `\fBline\fP' and `\fBopt_args\fP' as described +below, and does not reset any changes made to the special parameters +such as \fBPREFIX\fP and \fBwords\fP\&. This gives the calling function the +choice of resetting these parameters or propagating changes in them\&. +.PP +A function calling \fB_arguments\fP with at least +one action containing a `\fB\->\fP\fIstring\fP\&' must therefore declare +appropriate local parameters: +.PP +.RS +.nf +\fBlocal context state state_descr line +typeset \-A opt_args\fP +.fi +.RE +.PP +to prevent \fB_arguments\fP from altering the global environment\&. +.RE +.TP +\fB{\fP\fIeval\-string\fP\fB}\fP +A string in braces is evaluated as shell code to generate matches\&. If the +\fIeval\-string\fP itself does not begin with an opening parenthesis or +brace it is split into separate words before execution\&. +.TP +\fB= \fP\fIaction\fP +If the \fIaction\fP starts with `\fB= \fP\&' (an equals sign followed by a +space), \fB_arguments\fP will insert the contents of the \fIargument\fP +field of the current context as the new first element in the \fBwords\fP +special array and increment the value of the \fBCURRENT\fP special +parameter\&. This has the effect of inserting a dummy word onto the +completion command line while not changing the point at which completion is +taking place\&. +.RS +.PP +This is most useful with one of the specifiers that restrict the words on +the command line on which the \fIaction\fP is to operate (the two\- and +three\-colon forms above)\&. One particular use is when an \fIaction\fP itself +causes \fB_arguments\fP on a restricted range; it is necessary to use this +trick to insert an appropriate command name into the range for the second +call to \fB_arguments\fP to be able to parse the line\&. +.RE +.TP +.PD 0 +\fI\fB \fPword\&.\&.\&.\fP +.TP +.PD +\fIword\&.\&.\&.\fP +This covers all forms other than those above\&. If the \fIaction\fP +starts with a space, the remaining list of words will be invoked unchanged\&. +.RS +.PP +Otherwise it will be invoked with some extra strings placed after the +first word; these are to be passed down as options to the \fBcompadd\fP +builtin\&. They ensure that the state specified by \fB_arguments\fP, in +particular the descriptions of options and arguments, is correctly passed +to the completion command\&. These additional arguments +are taken from the array parameter `\fBexpl\fP\&'; this will be set up +before executing the \fIaction\fP and hence may be referred to inside it, +typically in an expansion of the form `\fB$expl[@]\fP\&' which preserves empty +elements of the array\&. +.RE +.PP +During the performance of the action the array `\fBline\fP\&' will be set to +the normal arguments from the command line, i\&.e\&. the words from the +command line after the command name excluding all options and their +arguments\&. Options are stored in the associative array +`\fBopt_args\fP\&' with option names as keys and their arguments as +the values\&. By default, all colons and backslashes in the value are escaped +with backslashes, and if an option has multiple arguments (for example, when +using an \fIoptspec\fP of the form `\fB*\fP\fIoptspec\fP\&'), they are joined with +(unescaped) colons\&. However, if the \fB\-0\fP option was passed, no backslash +escaping is performed, and multiple values are joined with NUL bytes\&. For +example, after `\fBzsh \-o foo:foo \-o bar:bar \-o <TAB>\fP\&', the contents of +`\fBopt_args\fP\&' would be +.PP +.RS +.nf +\fBtypeset \-A opt_args=( [\-o]=\&'foo\e:foo:bar\e:bar:' )\fP +.fi +.RE +.PP +by default, and +.PP +.RS +.nf +\fBtypeset \-A opt_args=( [\-o]=$\&'foo:foo\ex00bar:bar\ex00' )\fP +.fi +.RE +.PP +if \fB_arguments\fP had been called with the \fB\-0\fP option\&. +.PP +The parameter `\fBcontext\fP\&' is set when returning to the calling function +to perform an action of the form `\fB\->\fP\fIstring\fP\&'\&. It is set to an +array of elements corresponding to the elements of \fB$state\fP\&. Each +element is a suitable name for the argument field of the context: either a +string of the form `\fBoption\fP\fI\-opt\fP\fB\-\fP\fIn\fP\&' for the \fIn\fP'th +argument of the option \fI\-opt\fP, or a string of the form +`\fBargument\-\fP\fIn\fP\&' for the \fIn\fP'th argument\&. For `rest' arguments, +that is those in the list at the end not handled by position, \fIn\fP is the +string `\fBrest\fP\&'\&. For example, when completing the argument of the \fB\-o\fP +option, the name is `\fBoption\-o\-1\fP\&', while for the second normal +(non\-option\-) argument it is `\fBargument\-2\fP\&'\&. +.PP +Furthermore, during the evaluation of the \fIaction\fP the context name in +the \fBcurcontext\fP parameter is altered to append the same string that is +stored in the \fBcontext\fP parameter\&. +.PP +The option \fB\-C\fP tells \fB_arguments\fP to modify the \fBcurcontext\fP +parameter for an action of the form `\fB\->\fP\fIstate\fP\&'\&. This is the +standard parameter used to keep track of the current context\&. Here it +(and not the \fBcontext\fP array) should be made local to the calling +function to avoid passing back the modified value and should be +initialised to the current value at the start of the function: +.PP +.RS +.nf +\fBlocal curcontext="$curcontext"\fP +.fi +.RE +.PP +This is useful where it is not possible for multiple states to be valid +together\&. +.PP +\fIGrouping Options\fP +.PP +Options can be grouped to simplify exclusion lists\&. A group is +introduced with `\fB+\fP\&' followed by a name for the group in the +subsequent word\&. Whole groups can then be referenced in an exclusion +list or a group name can be used to disambiguate between two forms of +the same option\&. For example: +.PP +.RS +.nf +\fB_arguments \e + \&'(group2\-\-x)\-a' \e + + group1 \e + \-m \e + \&'(group2)\-n' \e + + group2 \e + \-x \-y\fP +.fi +.RE +.PP +If the name of a group is specified in the form +`\fB(\fP\fIname\fP\fB)\fP\&' then only one value from that group +will ever be completed; more formally, all specifications are mutually +exclusive to all other specifications in that group\&. This is useful for +defining options that are aliases for each other\&. For example: +.PP +.RS +.nf +\fB_arguments \e + \-a \-b \e + + \&'(operation)' \e + {\-c,\-\-compress}\&'[compress]' \e + {\-d,\-\-decompress}\&'[decompress]' \e + {\-l,\-\-list}\&'[list]'\fP +.fi +.RE +.PP +If an option in a group appears on the command line, it is stored in the +associative array `\fBopt_args\fP\&' with '\fIgroup\fP\fB\-\fP\fIoption\fP' +as a key\&. In the example above, a key `\fBoperation\-\-c\fP\&' is used if the option +`\fB\-c\fP\&' is present on the command line\&. +.PP +\fISpecifying Multiple Sets of Arguments\fP +.PP +It is possible to specify multiple sets of options and arguments with +the sets separated by single hyphens\&. This differs from groups in that +sets are considered to be mutually exclusive of each other\&. +.PP +Specifications before the first set and from any group are common to +all sets\&. For example: +.PP +.RS +.nf +\fB_arguments \e + \-a \e + \- set1 \e + \-c \e + \- set2 \e + \-d \e + \&':arg:(x2 y2)'\fP +.fi +.RE +.PP +This defines two sets\&. When the command line contains the option +`\fB\-c\fP\&', the `\fB\-d\fP' option and the argument will not be considered +possible completions\&. When it contains `\fB\-d\fP\&' or an argument, the +option `\fB\-c\fP\&' will not be considered\&. However, after `\fB\-a\fP' +both sets will still be considered valid\&. +.PP +As for groups, the name of a set may appear in exclusion lists, either +alone or preceding a normal option or argument specification\&. +.PP +The completion code has to parse the command line separately for each +set\&. This can be slow so sets should only be used when necessary\&. +A useful alternative is often an option specification with rest\-arguments +(as in `\fB\-foo:*:\&.\&.\&.\fP\&'); here the option \fB\-foo\fP swallows up all +remaining arguments as described by the \fIoptarg\fP definitions\&. +.PP +\fIDeriving \fIspec\fP forms from the help output\fP +.PP +The option `\fB\-\fP\fB\-\fP\&' allows \fB_arguments\fP to work out the names of long +options that support the `\fB\-\fP\fB\-help\fP\&' option which is standard in many +GNU commands\&. The command word is called with the argument +`\fB\-\fP\fB\-help\fP\&' and the output examined for option names\&. Clearly, it can +be dangerous to pass this to commands which may not support this option as +the behaviour of the command is unspecified\&. +.PP +In addition to options, `\fB_arguments \-\fP\fB\-\fP\&' will try to deduce the +types of arguments available for options when the form +`\fB\-\fP\fB\-\fP\fIopt\fP\fB=\fP\fIval\fP\&' is valid\&. It is also possible to provide +hints by examining the help text of the command and adding \fIhelpspec\fP of +the form `\fIpattern\fP\fB:\fP\fImessage\fP\fB:\fP\fIaction\fP\&'; note that other +\fB_arguments\fP \fIspec\fP forms are not used\&. The \fIpattern\fP is matched +against the help text for an option, and if it matches the \fImessage\fP and +\fIaction\fP are used as for other argument specifiers\&. The special case +of `\fB*:\fP\&' means both \fImessage\fP and \fIaction\fP are empty, which has +the effect of causing options having no description in the help output to +be ordered in listings ahead of options that have a description\&. +.PP +For example: +.PP +.RS +.nf +\fB_arguments \-\- \&'*\e*:toggle:(yes no)' \e + \&'*=FILE*:file:_files' \e + \&'*=DIR*:directory:_files \-/' \e + \&'*=PATH*:directory:_files \-/'\fP +.fi +.RE +.PP +Here, `\fByes\fP\&' and `\fBno\fP' will be completed as the argument of +options whose description ends in a star; file names will be completed for +options that contain the substring `\fB=FILE\fP\&' in the description; and +directories will be completed for options whose description contains +`\fB=DIR\fP\&' or `\fB=PATH\fP'\&. The last three are in fact the default and so +need not be given explicitly, although it is possible to override the use +of these patterns\&. A typical help text which uses this feature is: +.PP +.RS +.nf +\fB \-C, \-\-directory=DIR change to directory DIR\fP +.fi +.RE +.PP +so that the above specifications will cause directories to be completed +after `\fB\-\fP\fB\-directory\fP\&', though not after `\fB\-C\fP'\&. +.PP +Note also that \fB_arguments\fP tries to find out automatically if the +argument for an option is optional\&. This can be specified explicitly by +doubling the colon before the \fImessage\fP\&. +.PP +If the \fIpattern\fP ends in `\fB(\-)\fP\&', this will be removed from the +pattern and the \fIaction\fP will be used only directly after the +`\fB=\fP\&', not in the next word\&. This is the behaviour of a normal +specification defined with the form `\fB=\-\fP\&'\&. +.PP +By default, the command (with the option `\fB\-\-help\fP\&') is run after +resetting all the locale categories (except for \fBLC_CTYPE\fP) to `\fBC\fP\&'\&. +If the localized help output is known to work, the option `\fB\-l\fP\&' can +be specified after the `\fB_arguments \-\fP\fB\-\fP\&' so that the command is +run in the current locale\&. +.PP +The `\fB_arguments \-\fP\fB\-\fP\&' can be followed by the option `\fB\-i\fP +\fIpatterns\fP\&' to give patterns for options which are not to be +completed\&. The patterns can be given as the name of an array parameter +or as a literal list in parentheses\&. For example, +.PP +.RS +.nf +\fB_arguments \-\- \-i \e + "(\-\-(en|dis)able\-FEATURE*)"\fP +.fi +.RE +.PP +will cause completion to ignore the options +`\fB\-\fP\fB\-enable\-FEATURE\fP\&' and `\fB\-\fP\fB\-disable\-FEATURE\fP' (this example is +useful with GNU \fBconfigure\fP)\&. +.PP +The `\fB_arguments \-\fP\fB\-\fP\&' form can also be followed by the option `\fB\-s\fP +\fIpair\fP\&' to describe option aliases\&. The \fIpair\fP consists of a list +of alternating patterns and corresponding replacements, enclosed in parens +and quoted so that it forms a single argument word in the \fB_arguments\fP +call\&. +.PP +For example, some \fBconfigure\fP\-script help output describes options only +as `\fB\-\fP\fB\-enable\-foo\fP\&', but the script also accepts the negated form +`\fB\-\fP\fB\-disable\-foo\fP\&'\&. To allow completion of the second form: +.PP +.RS +.nf +\fB_arguments \-\- \-s "((#s)\-\-enable\- \-\-disable\-)"\fP +.fi +.RE +.PP +\fIMiscellaneous notes\fP +.PP +Finally, note that \fB_arguments\fP generally expects to be the primary +function handling any completion for which it is used\&. It may have side +effects which change the treatment of any matches added by other functions +called after it\&. To combine \fB_arguments\fP with other functions, those +functions should be called either before \fB_arguments\fP, as an \fIaction\fP +within a \fIspec\fP, or in handlers for `\fB\->\fP\fIstate\fP\&' actions\&. +.PP +Here is a more general example of the use of \fB_arguments\fP: +.PP +.RS +.nf +\fB_arguments \&'\-l+:left border:' \e + \&'\-format:paper size:(letter A4)' \e + \&'*\-copy:output file:_files::resolution:(300 600)' \e + \&':postscript file:_files \-g \e*\&.\e(ps\e|eps\e)' \e + \&'*:page number:'\fP +.fi +.RE +.PP +This describes three options: `\fB\-l\fP\&', `\fB\-format\fP', and +`\fB\-copy\fP\&'\&. The first takes one argument described as `\fIleft +border\fP\&' for which no completion will be offered because of the empty +action\&. Its argument may come directly after the `\fB\-l\fP\&' or it may be +given as the next word on the line\&. +.PP +The `\fB\-format\fP\&' option takes one +argument in the next word, described as `\fIpaper size\fP\&' for which +only the strings `\fBletter\fP\&' and `\fBA4\fP' will be completed\&. +.PP +The `\fB\-copy\fP\&' option may appear more than once on the command line and +takes two arguments\&. The first is mandatory and will be completed as a +filename\&. The second is optional (because of the second colon before +the description `\fIresolution\fP\&') and will be completed from the strings +`\fB300\fP\&' and `\fB600\fP'\&. +.PP +The last two descriptions say what should be completed as +arguments\&. The first describes the first argument as a +`\fIpostscript file\fP\&' and makes files ending in `\fBps\fP' or `\fBeps\fP' +be completed\&. The last description gives all other arguments the +description `\fIpage number\fP\&' but does not offer completions\&. +.RE +.TP +\fB_cache_invalid\fP \fIcache_identifier\fP +This function returns status zero if the completions cache corresponding to +the given cache identifier needs rebuilding\&. It determines this by +looking up the \fBcache\-policy\fP style for the current context\&. +This should provide a function name which is run with the full path to the +relevant cache file as the only argument\&. +.RS +.PP +Example: +.PP +.RS +.nf +\fB_example_caching_policy () { + # rebuild if cache is more than a week old + local \-a oldp + oldp=( "$1"(Nm+7) ) + (( $#oldp )) +}\fP +.fi +.RE +.RE +.TP +\fB_call_function\fP \fIreturn\fP \fIname\fP [ \fIarg\fP \&.\&.\&. ] +If a function \fIname\fP exists, it is called with the arguments +\fIarg\fPs\&. The \fIreturn\fP argument gives the name of a parameter in which +the return status from the function \fIname\fP should be stored; if \fIreturn\fP +is empty or a single hyphen it is ignored\&. +.RS +.PP +The return status of \fB_call_function\fP itself is zero if the function +\fIname\fP exists and was called and non\-zero otherwise\&. +.RE +.TP +\fB_call_program\fP [ \fB\-l\fP ] [ \fB\-p\fP ] \fItag\fP \fIstring\fP \&.\&.\&. +This function provides a mechanism for the user to override the use of an +external command\&. It looks up the \fBcommand\fP style with the supplied +\fItag\fP\&. If the style is set, its value is used as the command to +execute\&. The \fIstring\fPs from the call to \fB_call_program\fP, or from the +style if set, are concatenated with spaces between them and the resulting +string is evaluated\&. The return status is the return status of the command +called\&. +.RS +.PP +By default, the command is run in an environment where all the locale +categories (except for \fBLC_CTYPE\fP) are reset to `\fBC\fP\&' by calling the +utility function \fB_comp_locale\fP (see below)\&. If the option `\fB\-l\fP\&' is +given, the command is run with the current locale\&. +.PP +If the option `\fB\-p\fP\&' is supplied it indicates that the command +output is influenced by the permissions it is run with\&. If the +\fBgain\-privileges\fP style is set to true, \fB_call_program\fP will make +use of commands such as \fBsudo\fP, if present on the command\-line, to +match the permissions to whatever the final command is likely to run +under\&. When looking up the \fBgain\-privileges\fP and \fBcommand\fP styles, +the command component of the zstyle context will end with a slash +(`\fB/\fP\&') followed by the command that would be used to gain privileges\&. +.RE +.TP +\fB_combination\fP [ \fB\-s\fP \fIpattern\fP ] \fItag\fP \fIstyle\fP \fIspec\fP \&.\&.\&. \fIfield\fP \fIopts\fP \&.\&.\&. +This function is used to complete combinations of values, for example +pairs of hostnames and usernames\&. The \fIstyle\fP argument gives the style +which defines the pairs; it is looked up in a context with the \fItag\fP +specified\&. +.RS +.PP +The style name consists of field names separated by hyphens, for example +`\fBusers\-hosts\-ports\fP\&'\&. For each field for a value is already known, a +\fIspec\fP of the form `\fIfield\fP\fB=\fP\fIpattern\fP\&' is given\&. For example, +if the command line so far specifies a user `\fBpws\fP\&', the argument +`\fBusers=pws\fP\&' should appear\&. +.PP +The next argument with no equals sign is taken as the name of the field +for which completions should be generated (presumably not one of the +\fIfield\fPs for which the value is known)\&. +.PP +The matches generated will be taken from the value of the style\&. These +should contain the possible values for the combinations in the appropriate +order (users, hosts, ports in the example above)\&. +The values for the different fields are separated by colons\&. This +can be altered with the option \fB\-s\fP to \fB_combination\fP which specifies a +pattern\&. Typically this is a character class, as for example +`\fB\-s "[:@]"\fP\&' in the case of the \fBusers\-hosts\fP style\&. Each +`\fIfield\fP\fB=\fP\fIpattern\fP\&' specification restricts the +completions which apply to elements of the style with appropriately +matching fields\&. +.PP +If no style with the given name is defined for the given tag, +or if none of the strings in style\&'s value match, but a +function name of the required field preceded by an +underscore is defined, that function will be called to generate the +matches\&. For example, if there is no `\fBusers\-hosts\-ports\fP\&' or no +matching hostname when a host is required, the function `\fB_hosts\fP\&' will +automatically be called\&. +.PP +If the same name is used for more than one field, in both the +`\fIfield\fP\fB=\fP\fIpattern\fP\&' and the argument that gives the name of the +field to be completed, the number of the field (starting with one) may +be given after the fieldname, separated from it by a colon\&. +.PP +All arguments after the required field name are passed to +\fBcompadd\fP when generating matches from the style value, or to +the functions for the fields if they are called\&. +.RE +.TP +\fB_command_names\fP [ \fB\-e\fP | \fB\-\fP ] +This function completes words that are valid at command position: names of +aliases, builtins, hashed commands, functions, and so on\&. With the \fB\-e\fP +flag, only hashed commands are completed\&. The \fB\-\fP flag is ignored\&. +.TP +\fB_comp_locale\fP +This function resets all the locale categories other than \fBLC_CTYPE\fP to +`\fBC\fP\&' so that the output from external commands can be easily analyzed by +the completion system\&. \fBLC_CTYPE\fP retains the current value (taking +\fBLC_ALL\fP and \fBLANG\fP into account), ensuring that non\-ASCII characters +in file names are still handled properly\&. +.RS +.PP +This function should normally be run only in a subshell, because the new +locale is exported to the environment\&. Typical usage would be +`\fB$(_comp_locale; \fP\fIcommand\fP \&.\&.\&.\fB)\fP\&'\&. +.RE +.TP +\fB_completers\fP [ \fB\-p\fP ] +This function completes names of completers\&. +.RS +.PP +.PD 0 +.TP +.PD +\fB\-p\fP +Include the leading underscore (`\fB_\fP\&') in the matches\&. +.RE +.TP +\fB_default\fP +This function corresponds to the \fB\-default\-\fP special context which is +applied where no completion is defined\&. It is useful to call it under +certain error conditions such as completion after an unrecognised +subcommand\&. This applies the concept of graceful degradation to the +completion system, allowing it to fallback on basic completion of +commonly useful things like filenames\&. + +.TP +.PD 0 +\fB_describe \fP[\fB\-12JVx\fP] [ \fB\-oO\fP | \fB\-t\fP \fItag\fP ] \fIdescr\fP \fIname1\fP [ \fIname2\fP ] [ \fIopt\fP \&.\&.\&. ] +.TP +.PD +\fB \fP[ \fB\-\fP\fB\-\fP \fIname1\fP [ \fIname2\fP ] [ \fIopt\fP \&.\&.\&. ] \&.\&.\&. ] +This function associates completions with descriptions\&. +Multiple groups separated by \fB\-\fP\fB\-\fP can be supplied, potentially with +different completion options \fIopt\fPs\&. +.RS +.PP +The \fIdescr\fP is taken as a string to display above the matches if the +\fBformat\fP style for the \fBdescriptions\fP tag is set\&. This is followed by +one or two names of arrays followed by options to pass to \fBcompadd\fP\&. The +array \fIname1\fP contains the possible completions with their descriptions in +the form `\fIcompletion\fP\fB:\fP\fIdescription\fP\&'\&. Any literal colons in +\fIcompletion\fP must be quoted with a backslash\&. If a \fIname2\fP is +given, it should have the same number of elements as \fIname1\fP; in this +case the corresponding elements are added as possible completions instead +of the \fIcompletion\fP strings from \fIname1\fP\&. The completion list +will retain the descriptions from \fIname1\fP\&. Finally, a set of +completion options can appear\&. +.PP +If the option `\fB\-o\fP\&' appears before the first argument, the matches added +will be treated as names of command options (N\&.B\&. not shell options), +typically following a `\fB\-\fP\&', `\fB\-\fP\fB\-\fP' or `\fB+\fP' on the command +line\&. In this case \fB_describe\fP uses the \fBprefix\-hidden\fP, +\fBprefix\-needed\fP and \fBverbose\fP styles to find out if the strings should +be added as completions and if the descriptions should be shown\&. Without +the `\fB\-o\fP\&' option, only the \fBverbose\fP style is used to decide how +descriptions are shown\&. If `\fB\-O\fP\&' is used instead of `\fB\-o\fP', command +options are completed as above but \fB_describe\fP will not handle the +\fBprefix\-needed\fP style\&. +.PP +With the \fB\-t\fP option a \fItag\fP can be specified\&. The default is +`\fBvalues\fP\&' or, if the \fB\-o\fP option is given, `\fBoptions\fP'\&. +.PP +The options \fB\-1\fP, \fB\-2\fP, \fB\-J\fP, \fB\-V\fP, \fB\-x\fP are passed to +\fB_next_label\fP\&. +.PP +If selected by the \fBlist\-grouped\fP style, strings with the same +description will appear together in the list\&. +.PP +\fB_describe\fP uses the \fB_all_labels\fP function to generate the matches, so +it does not need to appear inside a loop over tag labels\&. +.RE +.TP +\fB_description\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP [ \fIspec\fP \&.\&.\&. ] +This function is not to be confused with the previous one; it is used as +a helper function for creating options to \fBcompadd\fP\&. It is buried +inside many of the higher level completion functions and so often does +not need to be called directly\&. +.RS +.PP +The styles listed below are tested in the current context using the +given \fItag\fP\&. The resulting options for \fBcompadd\fP are put into the +array named \fIname\fP (this is traditionally `\fBexpl\fP\&', but this +convention is not enforced)\&. The description for the corresponding set +of matches is passed to the function in \fIdescr\fP\&. +.PP +The styles tested are: \fBformat\fP, \fBhidden\fP, \fBmatcher\fP, +\fBignore\-line\fP, \fBignored\-patterns\fP, \fBgroup\-name\fP and \fBsort\fP\&. +The \fBformat\fP style is first tested for the given \fItag\fP and then for +the \fBdescriptions\fP tag if no value was found, while the remainder are +only tested for the tag given as the first argument\&. The function also +calls \fB_setup\fP which tests some more styles\&. +.PP +The string returned by the \fBformat\fP style (if any) will be modified so +that the sequence `\fB%d\fP\&' is replaced by the \fIdescr\fP given as the third +argument without any leading or trailing white space\&. If, after +removing the white space, the \fIdescr\fP is the empty string, the format +style will not be used and the options put into the \fIname\fP array will +not contain an explanation string to be displayed above the matches\&. +.PP +If \fB_description\fP is called with more than three arguments, +the additional \fIspec\fPs should be of the form `\fIchar\fP\fB:\fP\fIstr\fP\&'\&. +These supply escape sequence replacements for the \fBformat\fP style: +every appearance of `\fB%\fP\fIchar\fP\&' will be replaced by \fIstring\fP\&. +If no additional \fIspec\fPs are given but the description in \fIdescr\fP +conforms to a common form then further escape sequences are set for +elements of that description\&. These elements correspond to a default +value (`\fB%o\fP\&'), the units (`\fB%m\fP') range of acceptable values +(`\fB%r\fP\&') and the remaining initial part of the description (`\fB%h\fP')\&. +The form the description takes consists of specifying the units and +range in parentheses and the default value in square brackets, for +example: +.PP +.RS +.nf +\fB_description times expl \&'timeout (seconds) (0\-60) [20]'\fP +.fi +.RE +.PP +It is possible to use \fBzformat\fP conditional expressions when styling +these elements\&. So, for example, to add `\fBdefault:\fP\&' as a tag but only +when there is a default value to show, the \fBformat\fP style might +include `\fB%(o\&.default: %o\&.)\fP\&'\&. +.PP +If the \fB\-x\fP option is given, the description will be passed to +\fBcompadd\fP using the \fB\-x\fP option instead of the default \fB\-X\fP\&. This +means that the description will be displayed even if there are no +corresponding matches\&. +.PP +The options placed in the array \fIname\fP take account of the +\fBgroup\-name\fP style, so matches are placed in a separate group where +necessary\&. The group normally has its elements sorted (by passing the +option \fB\-J\fP to \fBcompadd\fP), but if an option starting with `\fB\-V\fP\&', +`\fB\-J\fP\&', `\fB\-1\fP', or `\fB\-2\fP' is passed to \fB_description\fP, that +option will be included in the array\&. Hence it is possible for the +completion group to be unsorted by giving the option `\fB\-V\fP\&', +`\fB\-1V\fP\&', or `\fB\-2V\fP'\&. +.PP +In most cases, the function will be used like this: +.PP +.RS +.nf +\fBlocal expl +_description files expl file +compadd "$expl[@]" \- "$files[@]"\fP +.fi +.RE +.PP +Note the use of the parameter \fBexpl\fP, the hyphen, and the list of +matches\&. Almost all calls to \fBcompadd\fP within the completion system use +a similar format; this ensures that user\-specified styles are correctly +passed down to the builtins which implement the internals of completion\&. +.RE +.TP +\fB_dir_list\fP [ \fB\-s\fP \fIsep\fP ] [ \fB\-S\fP ] +Complete a list of directory names separated by colons +(the same format as \fB$PATH\fP)\&. +.RS +.PP +.PD 0 +.TP +.PD +\fB\-s\fP \fIsep\fP +Use \fIsep\fP as separator between items\&. +\fIsep\fP defaults to a colon (`\fB:\fP\&')\&. +.TP +\fB\-S\fP +Add \fIsep\fP instead of slash (`\fB/\fP\&') as an autoremoveable suffix\&. +.RE +.TP +\fB_dispatch\fP \fIcontext string\fP \&.\&.\&. +This sets the current context to \fIcontext\fP and looks for completion +functions to handle this context by hunting through the list of command +names or special contexts (as described above for \fBcompdef\fP) +given as \fIstring\fPs\&. The first completion function to be defined +for one of the contexts in the list is used to generate matches\&. +Typically, the last \fIstring\fP is \fB\-default\-\fP to cause the function +for default completion to be used as a fallback\&. +.RS +.PP +The function sets the parameter +\fB$service\fP to the \fIstring\fP being tried, and sets +the \fIcontext/command\fP field (the fourth) of the \fB$curcontext\fP +parameter to the \fIcontext\fP given as the first argument\&. +.RE +.TP +\fB_email_addresses\fP [ \fB\-c\fP ] [ \fB\-n\fP \fIplugin\fP ] +Complete email addresses\&. Addresses are provided by plugins\&. +.RS +.PP +.PD 0 +.TP +.PD +\fB\-c\fP +Complete bare \fBlocalhost@domain\&.tld\fP addresses, without a name part or +a comment\&. +Without this option, RFC822 `\fIFirstname Lastname\fP \fB<\fP\fIaddress\fP\fB>\fP\&' +strings are completed\&. +.TP +\fB\-n\fP \fIplugin\fP +Complete aliases from \fIplugin\fP\&. +.PP +The following plugins are available by default: +\fB_email\-ldap\fP (see the \fBfilter\fP style), +\fB_email\-local\fP (completes \fIuser\fP\fB@\fP\fIhostname\fP Unix addresses), +\fB_email\-mail\fP (completes aliases from \fB~/\&.mailrc\fP), +\fB_email\-mush\fP, +\fB_email\-mutt\fP, +and +\fB_email\-pine\fP\&. +.PP +Addresses from the \fB_email\-\fP\fIfoo\fP plugin are added under the +tag `\fBemail\-\fP\fIfoo\fP\&'\&. +.PP +\fIWriting plugins\fP +.PP +Plugins are written as separate functions with names starting with `\fB_email\-\fP\&'\&. +They are invoked with the \fB\-c\fP option and \fBcompadd\fP options\&. +They should either do their own completion or +set the \fB$reply\fP array to a list of `\fIalias\fP\fB:\fP\fIaddress\fP\&' elements and return \fB300\fP\&. +New plugins will be picked up and run automatically\&. +.RE +.TP +\fB_files\fP +The function \fB_files\fP is a wrapper around \fB_path_files\fP\&. It supports +all of the same functionality, with some enhancements \-\- notably, it +respects the \fBlist\-dirs\-first\fP style, and it allows users to override +the behaviour of the \fB\-g\fP and \fB\-/\fP options with the \fBfile\-patterns\fP +style\&. \fB_files\fP should therefore be preferred over \fB_path_files\fP in +most cases\&. +.RS +.PP +This function accepts the full set of options allowed by +\fB_path_files\fP, described below\&. +.RE +.TP +\fB_gnu_generic\fP +This function is a simple wrapper around the \fB_arguments\fP function +described above\&. It can be used to determine automatically the long +options understood by commands that produce a list when passed the +option `\fB\-\fP\fB\-help\fP\&'\&. It is intended to be used as a top\-level +completion function in its own right\&. For example, to enable option +completion for the commands \fBfoo\fP and \fBbar\fP, use +.RS +.PP +.RS +.nf +\fBcompdef _gnu_generic foo bar\fP +.fi +.RE +.PP +after the call to \fBcompinit\fP\&. +.PP +The completion system as supplied is conservative in its use of this +function, since it is important to be sure the command understands the +option `\fB\-\fP\fB\-help\fP\&'\&. +.RE +.TP +\fB_guard\fP [ \fIoptions\fP ] \fIpattern descr\fP +This function displays \fIdescr\fP if \fIpattern\fP matches the string to +be completed\&. It is intended to be used in the \fIaction\fP for the +specifications passed to \fB_arguments\fP and similar functions\&. +.RS +.PP +The return status is zero if the message was displayed and the word to +complete is not empty, and non\-zero otherwise\&. +.PP +The \fIpattern\fP may be preceded by any of the options understood by +\fBcompadd\fP that are passed down from \fB_description\fP, namely \fB\-M\fP, +\fB\-J\fP, \fB\-V\fP, \fB\-1\fP, \fB\-2\fP, \fB\-n\fP, \fB\-F\fP and \fB\-X\fP\&. All of these +options will be ignored\&. This fits in conveniently with the +argument\-passing conventions of actions for \fB_arguments\fP\&. +.PP +As an example, consider a command taking the options \fB\-n\fP and +\fB\-none\fP, where \fB\-n\fP must be followed by a numeric value in the +same word\&. By using: +.PP +.RS +.nf +\fB_arguments \&'\-n\-: :_guard "[0\-9]#" "numeric value"' '\-none'\fP +.fi +.RE +.PP +\fB_arguments\fP can be made to both display the message `\fBnumeric +value\fP\&' and complete options after `\fB\-n<TAB>\fP'\&. If the `\fB\-n\fP' is +already followed by one or more digits (the pattern passed to +\fB_guard\fP) only the message will be displayed; if the `\fB\-n\fP\&' is +followed by another character, only options are completed\&. +.RE +.TP +.PD 0 +\fB_message\fP [ \fB\-r12\fP ] [ \fB\-VJ\fP \fIgroup\fP ] \fIdescr\fP +.TP +.PD +\fB_message \-e\fP [ \fItag\fP ] \fIdescr\fP +The \fIdescr\fP is used in the same way as the third +argument to the \fB_description\fP function, except that the resulting +string will always be shown whether or not matches were +generated\&. This is useful for displaying a help message in places where +no completions can be generated\&. +.RS +.PP +The \fBformat\fP style is examined with the \fBmessages\fP tag to find a +message; the usual tag, \fBdescriptions\fP, is used only if the style is +not set with the former\&. +.PP +If the \fB\-r\fP option is given, no style is used; the \fIdescr\fP is +taken literally as the string to display\&. This is most useful +when the \fIdescr\fP comes from a pre\-processed argument list +which already contains an expanded description\&. Note that this +option does not disable the `\fB%\fP\&'\-sequence parsing done by +\fBcompadd\fP\&. +.PP +The \fB\-12VJ\fP options and the \fIgroup\fP are passed to \fBcompadd\fP and +hence determine the group the message string is added to\&. +.PP +The second \fB\-e\fP form gives a description for completions with the tag +\fItag\fP to be shown even if there are no matches for that tag\&. This form +is called by \fB_arguments\fP in the event that there is no action for an +option specification\&. The tag can be omitted and if so the tag is taken +from the parameter \fB$curtag\fP; this is maintained by the completion +system and so is usually correct\&. Note that if there are no matches at +the time this function is called, \fBcompstate[insert]\fP is cleared, so +additional matches generated later are not inserted on the command line\&. +.RE +.TP +\fB_multi_parts\fP [ \fB\-i\fP ] \fIsep\fP \fIarray\fP +The argument \fIsep\fP is a separator character\&. +The \fIarray\fP may be either the +name of an array parameter or a literal array in the form +`\fB(foo bar\fP\fB)\fP\&', a parenthesised list of words separated +by whitespace\&. The possible completions are the +strings from the array\&. However, each chunk delimited by \fIsep\fP will be +completed separately\&. For example, the \fB_tar\fP function uses +`\fB_multi_parts\fP \fB/\fP \fIpatharray\fP\&' to complete partial file paths +from the given array of complete file paths\&. +.RS +.PP +The \fB\-i\fP option causes \fB_multi_parts\fP to insert a unique match even +if that requires multiple separators to be inserted\&. This is not usually +the expected behaviour with filenames, but certain other types of +completion, for example those with a fixed set of possibilities, may be +more suited to this form\&. +.PP +Like other utility functions, this function accepts the `\fB\-V\fP\&', +`\fB\-J\fP\&', `\fB\-1\fP', `\fB\-2\fP', `\fB\-n\fP', `\fB\-f\fP', `\fB\-X\fP', `\fB\-M\fP', +`\fB\-P\fP\&', `\fB\-S\fP', `\fB\-r\fP', `\fB\-R\fP', and `\fB\-q\fP' options and passes +them to the \fBcompadd\fP builtin\&. +.RE +.TP +\fB_next_label\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP [ \fIoption\fP \&.\&.\&. ] +This function is used to implement the loop over different tag +labels for a particular tag as described above for the \fBtag\-order\fP +style\&. On each call it checks to see if there are any more tag labels; if +there is it returns status zero, otherwise non\-zero\&. +As this function requires a current tag to be set, it must always follow +a call to \fB_tags\fP or \fB_requested\fP\&. +.RS +.PP +The \fB\-x12VJ\fP options and the first three arguments are passed to the +\fB_description\fP function\&. Where appropriate the \fItag\fP will be +replaced by a tag label in this call\&. Any description given in +the \fBtag\-order\fP style is preferred to the \fIdescr\fP passed to +\fB_next_label\fP\&. +.PP +The \fIoption\fPs given after the \fIdescr\fP +are set in the parameter given by \fIname\fP, and hence are to be passed +to \fBcompadd\fP or whatever function is called to add the matches\&. +.PP +Here is a typical use of this function for the tag \fBfoo\fP\&. The call to +\fB_requested\fP determines if tag \fBfoo\fP is required at all; the loop +over \fB_next_label\fP handles any labels defined for the tag in the +\fBtag\-order\fP style\&. +.PP +.RS +.nf +\fBlocal expl ret=1 +\&.\&.\&. +if _requested foo; then + \&.\&.\&. + while _next_label foo expl \&'\&.\&.\&.'; do + compadd "$expl[@]" \&.\&.\&. && ret=0 + done + \&.\&.\&. +fi +return ret\fP +.fi +.RE +.RE +.TP +\fB_normal\fP [ \fB\-P\fP | \fB\-p\fP \fIprecommand\fP ] +This is the standard function called to handle completion outside +any special \fB\-\fP\fIcontext\fP\fB\-\fP\&. It is called both to complete the command +word and also the arguments for a command\&. In the second case, +\fB_normal\fP looks for a special completion for that command, and if +there is none it uses the completion for the \fB\-default\-\fP context\&. +.RS +.PP +A second use is to reexamine the command line specified by the \fB$words\fP +array and the \fB$CURRENT\fP parameter after those have been modified\&. +For example, the function \fB_precommand\fP, which +completes after precommand specifiers such as \fBnohup\fP, removes the +first word from the \fBwords\fP array, decrements the \fBCURRENT\fP parameter, +then calls `\fB_normal \-p $service\fP\&'\&. The effect is that +`\fBnohup\fP \fIcmd \&.\&.\&.\fP\&' is treated in the same way as `\fIcmd \&.\&.\&.\fP'\&. +.PP +.PD 0 +.TP +.PD +\fB\-P\fP +Reset the list of precommands\&. This option should be used if completing +a command line which allows internal commands (e\&.g\&. builtins and +functions) regardless of prior precommands (e\&.g\&. `\fBzsh \-c\fP\&')\&. +.TP +\fB\-p\fP \fIprecommand\fP +Append \fIprecommand\fP to the list of precommands\&. This option should be +used in nearly all cases in which \fB\-P\fP is not applicable\&. +.PP +If the command name matches one of the patterns given by one of the +options \fB\-p\fP or \fB\-P\fP to \fBcompdef\fP, the corresponding completion +function is called and then the parameter \fB_compskip\fP is +checked\&. If it is set completion is terminated at that point even if +no matches have been found\&. This is the same effect as in the +\fB\-first\-\fP context\&. +.RE +.TP +\fB_numbers\fP [ \fIoption\fP \&.\&.\&. ] [ \fIdescription\fP ] [ \fIsuffix\fP \&.\&.\&. ] +This can be used where a number is followed by a suffix to indicate the units\&. +The unit suffixes are completed and can also be included in the description +used when completion is invoked for the preceding number\&. +.RS +.PP +In addition to common \fBcompadd\fP options, \fB_numbers\fP accepts the following +options: +.PP +.PD 0 +.TP +.PD +\fB\-t\fP \fItag\fP +Specify a tag to use instead of the default of \fBnumbers\fP\&. +.TP +\fB\-u\fP \fIunits\fP +Indicate the default units for the number, e\&.g\&. \fBbytes\fP\&. +.TP +\fB\-l\fP \fImin\fP +Specify the lowest possible value for the number\&. +.TP +\fB\-m\fP \fImax\fP +Specify the highest possible value for the number\&. +.TP +\fB\-d\fP \fIdefault\fP +Specify the default value\&. +.TP +\fB\-N\fP +Allow negative numbers\&. This is implied if the range includes a negative\&. +.TP +\fB\-f\fP +Allow decimal numbers\&. +.PP +Where a particular suffix represents the default units for a number, it +should be prefixed with a colon\&. Additionally, suffixes can be followed +by a colon and a description\&. So for example, the following allows the +age of something to be specified, either in seconds or with an optional +suffix with a longer unit of time: +.PP +.RS +.nf +\fB_numbers \-u seconds age :s:seconds m:minutes h:hours d:days\fP +.fi +.RE +.PP +It is typically helpful for units to be presented in order of magnitude +when completed\&. To facilitate this, the order in which they are given +is preserved\&. +.PP +When the \fBformat\fP style is looked up with the \fBdescriptions\fP tag or +the tag specified with \fB\-t\fP, the list of suffixes is available as a +`\fB%x\fP\&' escape sequence\&. This is in addition to the usual sequences +documented under the \fBformat\fP style\&. The form this list takes can also +be configured\&. To this end, the \fBformat\fP style is first looked up with +the tag \fBunit\-suffixes\fP\&. The retrieved format is applied to each +suffix in turn and the results are then concatenated to form the +completed list\&. For the \fBunit\-suffixes\fP format, `\fB%x\fP\&' expands to +the individual suffix and `\fB%X\fP\&' to its description\&. \fB%d\fP' indicates +a default suffix and can be used in a condition\&. The index and reverse +index are set in `\fB%i\fP\&' and `\fB%r\fP' respectively and are useful for +text included only with the first and last suffixes in the list\&. So for +example, the following joins the suffixes together as a comma\-separated +list: +.PP +.RS +.nf +\fBzstyle \&':completion:*:unit\-suffixes' format '%x%(r::,)'\fP +.fi +.RE +.RE +.PP +.TP +\fB_options\fP +This can be used to complete the names of shell options\&. It provides a +matcher specification that ignores a leading `\fBno\fP\&', ignores +underscores and allows upper\-case letters to +match their lower\-case counterparts (for example, `\fBglob\fP\&', +`\fBnoglob\fP\&', `\fBNO_GLOB\fP' are all completed)\&. Any arguments +are propagated to the \fBcompadd\fP builtin\&. +.TP +\fB_options_set\fP and \fB_options_unset\fP +These functions complete only set or unset options, with the same +matching specification used in the \fB_options\fP function\&. +.RS +.PP +Note that you need to uncomment a few lines in the \fB_main_complete\fP +function for these functions to work properly\&. The lines in question +are used to store the option settings in effect before the completion +widget locally sets the options it needs\&. Hence these functions are not +generally used by the completion system\&. +.RE +.TP +\fB_parameters\fP +This is used to complete the names of shell parameters\&. +.RS +.PP +The option `\fB\-g\fP \fIpattern\fP\&' limits the completion to parameters +whose type matches the \fIpattern\fP\&. The type of a parameter is that +shown by `\fBprint ${(t)\fP\fIparam\fP\fB}\fP\&', hence judicious use of +`\fB*\fP\&' in \fIpattern\fP is probably necessary\&. +.PP +All other arguments are passed to the \fBcompadd\fP builtin\&. +.RE +.TP +\fB_path_files\fP +This function is used throughout the completion system +to complete filenames\&. It allows completion of partial paths\&. For +example, the string `\fB/u/i/s/sig\fP\&' may be completed to +`\fB/usr/include/sys/signal\&.h\fP\&'\&. +.RS +.PP +The options accepted by both \fB_path_files\fP and \fB_files\fP are: +.PP +.PD 0 +.TP +.PD +\fB\-f\fP +Complete all filenames\&. This is the default\&. +.TP +\fB\-/\fP +Specifies that only directories should be completed\&. +.TP +\fB\-g\fP \fIpattern\fP +Specifies that only files matching the \fIpattern\fP should be completed\&. +.TP +\fB\-W\fP \fIpaths\fP +Specifies path prefixes that are to be prepended to the string from the +command line to generate the filenames but that should not be inserted +as completions nor shown in completion listings\&. Here, \fIpaths\fP may be +the name of an array parameter, a literal list of paths enclosed in +parentheses or an absolute pathname\&. +.TP +\fB\-F\fP \fIignored\-files\fP +This behaves as for the corresponding option to the \fBcompadd\fP builtin\&. +It gives direct control over which +filenames should be ignored\&. If the option is not present, the +\fBignored\-patterns\fP style is used\&. +.PP +Both \fB_path_files\fP and \fB_files\fP also accept the following options +which are passed to \fBcompadd\fP: `\fB\-J\fP\&', `\fB\-V\fP', +`\fB\-1\fP\&', `\fB\-2\fP', `\fB\-n\fP', `\fB\-X\fP', `\fB\-M\fP', `\fB\-P\fP', `\fB\-S\fP', +`\fB\-q\fP\&', `\fB\-r\fP', and `\fB\-R\fP'\&. +.PP +Finally, the \fB_path_files\fP function uses the styles \fBexpand\fP, +\fBambiguous\fP, \fBspecial\-dirs\fP, \fBlist\-suffixes\fP and \fBfile\-sort\fP +described above\&. +.RE + +.TP +.PD 0 +\fB_pick_variant \fP[ \fB\-b\fP \fIbuiltin\-label\fP ] [ \fB\-c\fP \fIcommand\fP ] [ \fB\-r\fP \fIname\fP ] +.TP +.PD +\fB \fP\fIlabel\fP\fB=\fP\fIpattern\fP \&.\&.\&. \fIlabel\fP [ \fIarg\fP \&.\&.\&. ] +This function is used to resolve situations where a single command name +requires more than one type of handling, either because it +has more than one variant or because there is a name clash between two +different commands\&. +.RS +.PP +The command to run is taken from the first element of the array +\fBwords\fP unless this is overridden by the option \fB\-c\fP\&. This command +is run and its output is compared with a series of patterns\&. Arguments +to be passed to the command can be specified at the end after all the +other arguments\&. The patterns to try in order are given by the arguments +\fIlabel\fP\fB=\fP\fIpattern\fP; if the output of `\fIcommand\fP \fIarg\fP +\&.\&.\&.\&' contains \fIpattern\fP, then \fIlabel\fP is selected as the label +for the command variant\&. If none of the patterns match, the final +command label is selected and status 1 is returned\&. +.PP +If the `\fB\-b\fP \fIbuiltin\-label\fP\&' is given, the command is tested to +see if it is provided as a shell builtin, possibly autoloaded; if so, +the label \fIbuiltin\-label\fP is selected as the label for the variant\&. +.PP +If the `\fB\-r\fP \fIname\fP\&' is given, the \fIlabel\fP picked is stored in +the parameter named \fIname\fP\&. +.PP +The results are also cached in the \fB_cmd_variant\fP associative array +indexed by the name of the command run\&. +.RE +.TP +\fB_regex_arguments\fP \fIname\fP \fIspec\fP \&.\&.\&. +This function generates a completion function \fIname\fP which matches +the specifications \fIspec\fPs, a set of regular expressions as +described below\&. After running \fB_regex_arguments\fP, the function +\fIname\fP should be called as a normal completion function\&. +The pattern to be matched is given by the contents of +the \fBwords\fP array up to the current cursor position joined together +with null characters; no quotation is applied\&. +.RS +.PP +The arguments are grouped as sets of alternatives separated by `\fB|\fP\&', +which are tried one after the other until one matches\&. Each alternative +consists of a one or more specifications which are tried left to right, +with each pattern matched being stripped in turn from the command line +being tested, until all of the group succeeds or until one fails; in the +latter case, the next alternative is tried\&. This structure can be +repeated to arbitrary depth by using parentheses; matching proceeds from +inside to outside\&. +.PP +A special procedure is applied if no test succeeds but the remaining +command line string contains no null character (implying the remaining +word is the one for which completions are to be generated)\&. The +completion target is restricted to the remaining word and any +\fIaction\fPs for the corresponding patterns are executed\&. In this case, +nothing is stripped from the command line string\&. The order of +evaluation of the \fIaction\fPs can be determined by the \fBtag\-order\fP +style; the various formats supported by \fB_alternative\fP can be used +in \fIaction\fP\&. The \fIdescr\fP is used for setting up the array +parameter \fBexpl\fP\&. +.PP +Specification arguments take one of following forms, in which +metacharacters such as `\fB(\fP\&', `\fB)\fP', `\fB#\fP' and `\fB|\fP' +should be quoted\&. +.PP +.PD 0 +.TP +.PD +\fB/\fP\fIpattern\fP\fB/\fP [\fB%\fP\fIlookahead\fP\fB%\fP] [\fB\-\fP\fIguard\fP] [\fB:\fP\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP] +This is a single primitive component\&. +The function tests whether the combined pattern +`\fB(#b)((#B)\fP\fIpattern\fP\fB)\fP\fIlookahead\fP\fB*\fP\&' matches +the command line string\&. If so, `\fIguard\fP\&' is evaluated and +its return status is examined to determine if the test has succeeded\&. +The \fIpattern\fP string `\fB[]\fP\&' is guaranteed never to match\&. +The \fIlookahead\fP is not stripped from the command line before the next +pattern is examined\&. +.RS +.PP +The argument starting with \fB:\fP is used in the same manner as an argument to +\fB_alternative\fP\&. +.PP +A component is used as follows: \fIpattern\fP is tested to +see if the component already exists on the command line\&. If +it does, any following specifications are examined to find something to +complete\&. If a component is reached but no such pattern exists yet on the +command line, the string containing the \fIaction\fP is used to generate +matches to insert at that point\&. +.RE +.TP +\fB/\fP\fIpattern\fP\fB/+\fP [\fB%\fP\fIlookahead\fP\fB%\fP] [\fB\-\fP\fIguard\fP] [\fB:\fP\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP] +This is similar to `\fB/\fP\fIpattern\fP\fB/\fP \&.\&.\&.\&' but the left part of the +command line string (i\&.e\&. the part already matched by previous patterns) +is also considered part of the completion target\&. +.TP +\fB/\fP\fIpattern\fP\fB/\-\fP [\fB%\fP\fIlookahead\fP\fB%\fP] [\fB\-\fP\fIguard\fP] [\fB:\fP\fItag\fP\fB:\fP\fIdescr\fP\fB:\fP\fIaction\fP] +This is similar to `\fB/\fP\fIpattern\fP\fB/\fP \&.\&.\&.\&' but the \fIaction\fPs of the +current and previously matched patterns are ignored even if the +following `\fIpattern\fP\&' matches the empty string\&. +.TP +\fB(\fP \fIspec\fP \fB)\fP +Parentheses may be used to groups \fIspec\fPs; note each parenthesis +is a single argument to \fB_regex_arguments\fP\&. +.TP +\fIspec\fP \fB#\fP +This allows any number of repetitions of \fIspec\fP\&. +.TP +\fIspec\fP \fIspec\fP +The two \fIspec\fPs are to be matched one after the other as described +above\&. +.TP +\fIspec\fP \fB|\fP \fIspec\fP +Either of the two \fIspec\fPs can be matched\&. +.PP +The function \fB_regex_words\fP can be used as a helper function to +generate matches for a set of alternative words possibly with +their own arguments as a command line argument\&. +.PP +Examples: +.PP +.RS +.nf +\fB_regex_arguments _tst /$\&'[^\e0]#\e0'/ \e + /$\&'[^\e0]#\e0'/ :'compadd aaa'\fP +.fi +.RE +.PP +This generates a function \fB_tst\fP that completes \fBaaa\fP as its only +argument\&. The \fItag\fP and \fIdescription\fP for the action have been +omitted for brevity (this works but is not recommended in normal use)\&. +The first component matches the command word, which is arbitrary; the +second matches any argument\&. As the argument is also arbitrary, any +following component would not depend on \fBaaa\fP being present\&. +.PP +.RS +.nf +\fB_regex_arguments _tst /$\&'[^\e0]#\e0'/ \e + /$\&'aaa\e0'/ :'compadd aaa'\fP +.fi +.RE +.PP +This is a more typical use; it is similar, but any following patterns +would only match if \fBaaa\fP was present as the first argument\&. +.PP +.RS +.nf +\fB_regex_arguments _tst /$\&'[^\e0]#\e0'/ \e( \e + /$\&'aaa\e0'/ :'compadd aaa' \e + /$\&'bbb\e0'/ :'compadd bbb' \e) \e#\fP +.fi +.RE +.PP +In this example, an indefinite number of command arguments may be +completed\&. Odd arguments are completed as \fBaaa\fP and even arguments +as \fBbbb\fP\&. Completion fails unless the set of \fBaaa\fP and \fBbbb\fP +arguments before the current one is matched correctly\&. +.PP +.RS +.nf +\fB_regex_arguments _tst /$\&'[^\e0]#\e0'/ \e + \e( /$\&'aaa\e0'/ :'compadd aaa' \e| \e + /$\&'bbb\e0'/ :'compadd bbb' \e) \e#\fP +.fi +.RE +.PP +This is similar, but either \fBaaa\fP or \fBbbb\fP may be completed for +any argument\&. In this case \fB_regex_words\fP could be used to generate +a suitable expression for the arguments\&. +.PP +.RE +.TP +\fB_regex_words\fP \fItag\fP \fIdescription\fP \fIspec\fP \&.\&.\&. +This function can be used to generate arguments for the +\fB_regex_arguments\fP command which may be inserted at any point where +a set of rules is expected\&. The \fItag\fP and \fIdescription\fP give a +standard tag and description pertaining to the current context\&. Each +\fIspec\fP contains two or three arguments separated by a colon: note +that there is no leading colon in this case\&. +.RS +.PP +Each \fIspec\fP gives one of a set of words that may be completed at +this point, together with arguments\&. It is thus roughly equivalent to +the \fB_arguments\fP function when used in normal (non\-regex) completion\&. +.PP +The part of the \fIspec\fP before the first colon is the word to be +completed\&. This may contain a \fB*\fP; the entire word, before and after +the \fB*\fP is completed, but only the text before the \fB*\fP is required +for the context to be matched, so that further arguments may be +completed after the abbreviated form\&. +.PP +The second part of \fIspec\fP is a description for the word being +completed\&. +.PP +The optional third part of the \fIspec\fP describes how words following +the one being completed are themselves to be completed\&. It will be +evaluated in order to avoid problems with quoting\&. This means that +typically it contains a reference to an array containing previously +generated regex arguments\&. +.PP +The option \fB\-t\fP \fIterm\fP specifies a terminator for the word +instead of the usual space\&. This is handled as an auto\-removable suffix +in the manner of the option \fB\-s\fP \fIsep\fP to \fB_values\fP\&. +.PP +The result of the processing by \fB_regex_words\fP is placed in the array +\fBreply\fP, which should be made local to the calling function\&. +If the set of words and arguments may be matched repeatedly, a \fB#\fP +should be appended to the generated array at that point\&. +.PP +For example: +.PP +.RS +.nf +\fBlocal \-a reply +_regex_words mydb\-commands \&'mydb commands' \e + \&'add:add an entry to mydb:$mydb_add_cmds' \e + \&'show:show entries in mydb' +_regex_arguments _mydb "$reply[@]" +_mydb "$@"\fP +.fi +.RE +.PP +This shows a completion function for a command \fBmydb\fP which takes +two command arguments, \fBadd\fP and \fBshow\fP\&. \fBshow\fP takes no arguments, +while the arguments for \fBadd\fP have already been prepared in an +array \fBmydb_add_cmds\fP, quite possibly by a previous call to +\fB_regex_words\fP\&. +.RE +.TP +\fB_requested\fP [ \fB\-x\fP ] [ \fB\-12VJ\fP ] \fItag\fP [ \fIname\fP \fIdescr\fP [ \fIcommand\fP [ \fIarg\fP \&.\&.\&. ] ] +This function is called to decide whether a tag already registered by a +call to \fB_tags\fP (see below) has been requested by the user and hence +completion should be performed for it\&. It returns status zero if the +tag is requested and non\-zero otherwise\&. The function is typically used +as part of a loop over different tags as follows: +.RS +.PP +.RS +.nf +\fB_tags foo bar baz +while _tags; do + if _requested foo; then + \&.\&.\&. # perform completion for foo + fi + \&.\&.\&. # test the tags bar and baz in the same way + \&.\&.\&. # exit loop if matches were generated +done\fP +.fi +.RE +.PP +Note that the test for whether matches were generated is not performed +until the end of the \fB_tags\fP loop\&. This is so that the user can set +the \fBtag\-order\fP style to specify a set of tags to be completed at the +same time\&. +.PP +If \fIname\fP and \fIdescr\fP are given, \fB_requested\fP calls the +\fB_description\fP function with these arguments together with the options +passed to \fB_requested\fP\&. +.PP +If \fIcommand\fP is given, the \fB_all_labels\fP function will be called +immediately with the same arguments\&. In simple cases this makes it +possible to perform the test for the tag and the matching in one go\&. +For example: +.PP +.RS +.nf +\fBlocal expl ret=1 +_tags foo bar baz +while _tags; do + _requested foo expl \&'description' \e + compadd foobar foobaz && ret=0 + \&.\&.\&. + (( ret )) || break +done\fP +.fi +.RE +.PP +If the \fIcommand\fP is not \fBcompadd\fP, it must nevertheless be prepared +to handle the same options\&. +.RE +.TP +\fB_retrieve_cache\fP \fIcache_identifier\fP +This function retrieves completion information from the file given by +\fIcache_identifier\fP, stored in a directory specified by the +\fBcache\-path\fP style which defaults to \fB~/\&.zcompcache\fP\&. The return status +is zero if retrieval was successful\&. It will only attempt retrieval +if the \fBuse\-cache\fP style is set, so you can call this function +without worrying about whether the user wanted to use the caching +layer\&. +.RS +.PP +See \fB_store_cache\fP below for more details\&. +.RE +.TP +\fB_sep_parts\fP +This function is passed alternating arrays and separators as arguments\&. +The arrays specify completions for parts of strings to be separated by the +separators\&. The arrays may be the names of array parameters or +a quoted list of words in parentheses\&. For example, with the array +`\fBhosts=(ftp news)\fP\&' the call `\fB_sep_parts '(foo bar)' @ hosts\fP' will +complete the string `\fBf\fP\&' to `\fBfoo\fP' and the string `\fBb@n\fP' to +`\fBbar@news\fP\&'\&. +.RS +.PP +This function accepts the \fBcompadd\fP options `\fB\-V\fP\&', `\fB\-J\fP', +`\fB\-1\fP\&', `\fB\-2\fP', `\fB\-n\fP', `\fB\-X\fP', `\fB\-M\fP', `\fB\-P\fP', `\fB\-S\fP', +`\fB\-r\fP\&', `\fB\-R\fP', and `\fB\-q\fP' and passes them on to the \fBcompadd\fP +builtin used to add the matches\&. +.RE +.TP +\fB_sequence\fP [ \fB\-s\fP \fIsep\fP ] [ \fB\-n\fP \fImax\fP ] [ \fB\-d\fP ] \fIfunction\fP [ \fB\-\fP ] \&.\&.\&. +This function is a wrapper to other functions for completing items in a +separated list\&. The same function is used to complete each item in the +list\&. The separator is specified with the \fB\-s\fP option\&. If \fB\-s\fP is +omitted it will use `\fB,\fP\&'\&. Duplicate values are not matched unless +\fB\-d\fP is specified\&. If there is a fixed or maximum number of items in +the list, this can be specified with the \fB\-n\fP option\&. +.RS +.PP +Common \fBcompadd\fP options are passed on to the function\&. It is possible +to use \fBcompadd\fP directly with \fB_sequence\fP, though \fB_values\fP may +be more appropriate in this situation\&. +.RE +.TP +\fB_setup\fP \fItag\fP [ \fIgroup\fP ] +This function sets up the special +parameters used by the completion system appropriately for the \fItag\fP +given as the first argument\&. It uses the styles \fBlist\-colors\fP, +\fBlist\-packed\fP, \fBlist\-rows\-first\fP, \fBlast\-prompt\fP, \fBaccept\-exact\fP, +\fBmenu\fP and \fBforce\-list\fP\&. +.RS +.PP +The optional \fIgroup\fP supplies the name of the group in which the +matches will be placed\&. If it is not given, the \fItag\fP is used as +the group name\&. +.PP +This function is called automatically from \fB_description\fP +and hence is not normally called explicitly\&. +.RE +.TP +\fB_store_cache\fP \fIcache_identifier\fP \fIparam\fP \&.\&.\&. +This function, together with \fB_retrieve_cache\fP and +\fB_cache_invalid\fP, implements a caching layer which can be used +in any completion function\&. Data obtained by +costly operations are stored in parameters; +this function then dumps the values of those parameters to a file\&. The +data can then be retrieved quickly from that file via \fB_retrieve_cache\fP, +even in different instances of the shell\&. +.RS +.PP +The \fIcache_identifier\fP specifies the file which the data should be +dumped to\&. The file is stored in a directory specified by the +\fBcache\-path\fP style which defaults to \fB~/\&.zcompcache\fP\&. The remaining +\fIparam\fPs arguments are the parameters to dump to the file\&. +.PP +The return status is zero if storage was successful\&. The function will +only attempt storage if the \fBuse\-cache\fP style is set, so you can +call this function without worrying about whether the user wanted to +use the caching layer\&. +.PP +The completion function may avoid calling \fB_retrieve_cache\fP when it +already has the completion data available as parameters\&. +However, in that case it should +call \fB_cache_invalid\fP to check whether the data in the parameters and +in the cache are still valid\&. +.PP +See the _perl_modules completion function for a simple example of +the usage of the caching layer\&. +.RE +.TP +\fB_tags\fP [ [ \fB\-C\fP \fIname\fP ] \fItag\fP \&.\&.\&. ] +If called with arguments, these are taken to be the names of tags +valid for completions in the current context\&. These tags are stored +internally and sorted by using the \fBtag\-order\fP style\&. +.RS +.PP +Next, \fB_tags\fP is called repeatedly without arguments from the same +completion function\&. This successively selects the first, second, +etc\&. set of tags requested by the user\&. The return status is zero if at +least one of the tags is requested and non\-zero otherwise\&. To test if a +particular tag is to be tried, the \fB_requested\fP function should be +called (see above)\&. +.PP +If `\fB\-C\fP \fIname\fP\&' is given, \fIname\fP is temporarily stored in the +\fIargument\fP field (the fifth) of the context in the \fBcurcontext\fP parameter +during the call to \fB_tags\fP; the field is restored on exit\&. This +allows \fB_tags\fP to use a more +specific context without having to change and reset the +\fBcurcontext\fP parameter (which has the same effect)\&. +.RE +.TP +\fB_tilde_files\fP +Like \fB_files\fP, but resolve leading tildes according to the rules of +filename expansion, so the suggested completions don\&'t start with +a `\fB~\fP\&' even if the filename on the command\-line does\&. +.TP +\fB_values\fP [ \fB\-O\fP \fIname\fP ] [ \fB\-s\fP \fIsep\fP ] [ \fB\-S\fP \fIsep\fP ] [ \fB\-wC\fP ] \fIdesc\fP \fIspec\fP \&.\&.\&. +This is used to complete arbitrary keywords (values) and their arguments, +or lists of such combinations\&. +.RS +.PP +If the first argument is the option `\fB\-O\fP \fIname\fP\&', it will be used +in the same way as by the \fB_arguments\fP function\&. In other words, the +elements of the \fIname\fP array will be passed to \fBcompadd\fP +when executing an action\&. +.PP +If the first argument (or the first argument after `\fB\-O\fP \fIname\fP\&') +is `\fB\-s\fP\&', the next argument is used as the character that separates +multiple values\&. This character is automatically added after each value +in an auto\-removable fashion (see below); all values completed by +`\fB_values \-s\fP\&' appear in the same word on the command line, unlike +completion using \fB_arguments\fP\&. If this option is not present, only a +single value will be completed per word\&. +.PP +Normally, \fB_values\fP will only use the current word to determine +which values are already present on the command line and hence are not +to be completed again\&. If the \fB\-w\fP option is given, other arguments +are examined as well\&. +.PP +The first non\-option argument, \fIdesc\fP, is used as a string to print as a +description before listing the values\&. +.PP +All other arguments describe the possible values and their +arguments in the same format used for the description of options by +the \fB_arguments\fP function (see above)\&. The only differences are that +no minus or plus sign is required at the beginning, +values can have only one argument, and the forms of action +beginning with an equal sign are not supported\&. +.PP +The character separating a value from its argument can be set using the +option \fB\-S\fP (like \fB\-s\fP, followed by the character to use as the +separator in the next argument)\&. By default the equals +sign will be used as the separator between values and arguments\&. +.PP +Example: +.PP +.RS +.nf +\fB_values \-s , \&'description' \e + \&'*foo[bar]' \e + \&'(two)*one[number]:first count:' \e + \&'two[another number]::second count:(1 2 3)'\fP +.fi +.RE +.PP +This describes three possible values: `\fBfoo\fP\&', `\fBone\fP', and +`\fBtwo\fP\&'\&. The first is described as `\fBbar\fP', takes no argument +and may appear more than once\&. The second is described as +`\fBnumber\fP\&', may appear more than once, and takes one mandatory +argument described as `\fBfirst count\fP\&'; no action is +specified, so it will not be completed\&. The +`\fB(two)\fP\&' at the beginning says that if the value `\fBone\fP' is on +the line, the value `\fBtwo\fP\&' will no longer be considered a possible +completion\&. Finally, the last value (`\fBtwo\fP\&') is described +as `\fBanother number\fP\&' and takes an optional argument described as +`\fBsecond count\fP\&' for which the completions (to appear after an +`\fB=\fP\&') are `\fB1\fP', `\fB2\fP', and `\fB3\fP'\&. The \fB_values\fP function +will complete lists of these values separated by commas\&. +.PP +Like \fB_arguments\fP, this function temporarily adds another context name +component to the arguments element (the fifth) of the current context +while executing the \fIaction\fP\&. Here this name is just the name of the +value for which the argument is completed\&. +.PP +The style \fBverbose\fP is used to decide if the descriptions for the +values (but not those for the arguments) should be printed\&. +.PP +The associative array \fBval_args\fP is used to report values and their +arguments; this works similarly to the \fBopt_args\fP associative array +used by \fB_arguments\fP\&. Hence the function calling \fB_values\fP should +declare the local parameters \fBstate\fP, \fBstate_descr\fP, \fBline\fP, +\fBcontext\fP and \fBval_args\fP: +.PP +.RS +.nf +\fBlocal context state state_descr line +typeset \-A val_args\fP +.fi +.RE +.PP +when using an action of the form `\fB\->\fP\fIstring\fP\&'\&. With this +function the \fBcontext\fP parameter will be set to the name of the +value whose argument is to be completed\&. Note that for \fB_values\fP, +the \fBstate\fP and \fBstate_descr\fP are scalars rather than arrays\&. +Only a single matching state is returned\&. +.PP +Note also that \fB_values\fP normally adds the character used as the +separator between values as an auto\-removable suffix (similar to a +`\fB/\fP\&' after a directory)\&. However, this is not possible for a +`\fB\->\fP\fIstring\fP\&' action as the matches for the argument are +generated by the calling function\&. To get the usual behaviour, +the calling function can add the separator \fIx\fP as a suffix by +passing the options `\fB\-qS\fP \fIx\fP\&' either directly or indirectly to +\fBcompadd\fP\&. +.PP +The option \fB\-C\fP is treated in the same way as it is by \fB_arguments\fP\&. +In that case the parameter \fBcurcontext\fP should be made local instead +of \fBcontext\fP (as described above)\&. +.RE +.TP +\fB_wanted\fP [ \fB\-x\fP ] [ \fB\-C\fP \fIname\fP ] [ \fB\-12VJ\fP ] \fItag\fP \fIname\fP \fIdescr\fP \fIcommand\fP [ \fIarg\fP \&.\&.\&.] +In many contexts, completion can only generate one particular set of +matches, usually corresponding to a single tag\&. However, it is +still necessary to decide whether the user requires matches of this type\&. +This function is useful in such a case\&. +.RS +.PP +The arguments to \fB_wanted\fP are the same as those to \fB_requested\fP, +i\&.e\&. arguments to be passed to \fB_description\fP\&. However, in this case +the \fIcommand\fP is not optional; all the processing of tags, including +the loop over both tags and tag labels and the generation of matches, +is carried out automatically by \fB_wanted\fP\&. +.PP +Hence to offer only one tag and immediately add the corresponding +matches with the given description: +.PP +.RS +.nf +\fBlocal expl +_wanted tag expl \&'description' \e + compadd \-\- \fImatch1\fP \fImatch2\fP\&.\&.\&.\fP +.fi +.RE +.PP +See also the use of \fB_wanted\fP in the example function in +the subsection `Dynamic named directories\&' in \fIzshexpn\fP(1)\&. +.PP +Note that, as for \fB_requested\fP, the \fIcommand\fP must be able to +accept options to be passed down to \fBcompadd\fP\&. +.PP +Like \fB_tags\fP this function supports the \fB\-C\fP option to give a +different name for the argument context field\&. The \fB\-x\fP option has +the same meaning as for \fB_description\fP\&. +.RE +.TP +\fB_widgets\fP [ \fB\-g\fP \fIpattern\fP ] +This function completes names of zle widgets (see +the section `Widgets\&' in \fIzshzle\fP(1))\&. The \fIpattern\fP, if present, is matched against values of the \fB$widgets\fP +special parameter, documented in +the section `The zsh/zleparameter Module\&' in \fIzshmodules\fP(1)\&. +.PP +.SH "COMPLETION SYSTEM VARIABLES" +.PP +There are some standard variables, initialised by the \fB_main_complete\fP +function and then used from other functions\&. +.PP +The standard variables are: +.PP +.PD 0 +.TP +.PD +\fB_comp_caller_options\fP +The completion system uses \fBsetopt\fP to set a number of options\&. This +allows functions to be written without concern for compatibility with +every possible combination of user options\&. However, sometimes completion +needs to know what the user\&'s option preferences are\&. These are saved +in the \fB_comp_caller_options\fP associative array\&. Option names, spelled +in lowercase without underscores, are mapped to one or other of the +strings `\fBon\fP\&' and `\fBoff\fP'\&. +.TP +\fB_comp_priv_prefix\fP +Completion functions such as \fB_sudo\fP can set the \fB_comp_priv_prefix\fP +array to a command prefix that may then be used by \fB_call_program\fP to +match the privileges when calling programs to generate matches\&. +.PP +Two more features are offered by the \fB_main_complete\fP function\&. The +arrays \fBcompprefuncs\fP and \fBcomppostfuncs\fP may contain +names of functions that are to be called immediately before or after +completion has been tried\&. A function will only be called once unless +it explicitly reinserts itself into the array\&. +.PP +.SH "COMPLETION DIRECTORIES" +.PP +In the source distribution, the files are contained in various +subdirectories of the \fBCompletion\fP directory\&. They may have been +installed in the same structure, or into one single function directory\&. +The following is a description of the files found in the original directory +structure\&. If you wish to alter an installed file, you will need to copy +it to some directory which appears earlier in your \fBfpath\fP than the +standard directory where it appears\&. +.PP +.PD 0 +.TP +.PD +\fBBase\fP +The core functions and special completion widgets automatically bound +to keys\&. You will certainly need most of these, though will +probably not need to alter them\&. Many of these are documented above\&. +.TP +\fBZsh\fP +Functions for completing arguments of shell builtin commands and +utility functions for this\&. Some of these are also used by functions from +the \fBUnix\fP directory\&. +.TP +\fBUnix\fP +Functions for completing arguments of external commands and suites of +commands\&. They may need modifying for your system, although in many cases +some attempt is made to decide which version of a command is present\&. For +example, completion for the \fBmount\fP command tries to determine the system +it is running on, while completion for many other utilities try to decide +whether the GNU version of the command is in use, and hence whether the +\fB\-\fP\fB\-help\fP option is supported\&. +.TP +\fBX\fP, \fBAIX\fP, \fBBSD\fP, \&.\&.\&. +Completion and utility function for commands available only on some systems\&. +These are not arranged hierarchically, so, for example, both the +\fBLinux\fP and \fBDebian\fP directories, as well as the \fBX\fP directory, +may be useful on your system\&. diff --git a/Doc/zshcompwid.1 b/Doc/zshcompwid.1 new file mode 100644 index 000000000..22c1d086d --- /dev/null +++ b/Doc/zshcompwid.1 @@ -0,0 +1,1306 @@ +.TH "ZSHCOMPWID" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshcompwid \- zsh completion widgets +.\" Yodl file: Zsh/compwid.yo +.SH "DESCRIPTION" +The shell\&'s programmable completion mechanism can be manipulated in two +ways; here the low\-level features supporting the newer, function\-based +mechanism are defined\&. A complete set of shell functions based on these +features is described in +\fIzshcompsys\fP(1), +and users with no interest in adding to that system (or, potentially, +writing their own \-\- see dictionary entry for `hubris\&') should skip +the current section\&. The older system based on the \fBcompctl\fP builtin +command is described in +\fIzshcompctl\fP(1)\&. +.PP +Completion widgets are defined by the \fB\-C\fP option to the \fBzle\fP +builtin command provided by the \fBzsh/zle\fP module (see +\fIzshzle\fP(1))\&. For example, +.PP +.RS +.nf +\fBzle \-C complete expand\-or\-complete completer\fP +.fi +.RE +.PP +defines a widget named `\fBcomplete\fP\&'\&. The second argument is the name +of any of the builtin widgets that handle completions: +\fBcomplete\-word\fP, \fBexpand\-or\-complete\fP, +\fBexpand\-or\-complete\-prefix\fP, \fBmenu\-complete\fP, +\fBmenu\-expand\-or\-complete\fP, \fBreverse\-menu\-complete\fP, +\fBlist\-choices\fP, or \fBdelete\-char\-or\-list\fP\&. Note that this will still +work even if the widget in question has been re\-bound\&. +.PP +When this newly defined widget is bound to a key +using the \fBbindkey\fP builtin command defined in the \fBzsh/zle\fP module +(see \fIzshzle\fP(1)), typing that key will call the shell function `\fBcompleter\fP\&'\&. This +function is responsible for generating completion matches using the +builtins described below\&. As with other ZLE widgets, the function is +called with its standard input closed\&. +.PP +Once the function returns, the completion code takes over control again +and treats the matches in the same manner as the specified builtin +widget, in this case \fBexpand\-or\-complete\fP\&. +.PP +.PP +.SH "COMPLETION SPECIAL PARAMETERS" +.PP +The parameters \fBZLE_REMOVE_SUFFIX_CHARS\fP and \fBZLE_SPACE_SUFFIX_CHARS\fP +are used by the completion mechanism, but are not special\&. See +\fIParameters Used By The Shell\fP in \fIzshparam\fP(1)\&. +.PP +Inside completion widgets, and any functions called from them, some +parameters have special meaning; outside these functions they are not +special to the shell in any way\&. These parameters are used to pass +information between the completion code and the completion widget\&. Some of +the builtin commands and the condition codes use or change the current +values of these parameters\&. Any existing values will be hidden during +execution of completion widgets; except for \fBcompstate\fP, the parameters +are reset on each function exit (including nested function calls from +within the completion widget) to the values they had when the function was +entered\&. +.PP +.PD 0 +.TP +.PD +\fBCURRENT\fP +This is the number of the current word, i\&.e\&. the word the cursor is +currently on in the \fBwords\fP array\&. Note that this value is only +correct if the \fBksharrays\fP option is not set\&. +.TP +\fBIPREFIX\fP +Initially this will be set to the empty string\&. This parameter functions +like \fBPREFIX\fP; it contains a string which precedes the one in \fBPREFIX\fP +and is not considered part of the list of matches\&. Typically, a string is +transferred from the beginning of \fBPREFIX\fP to the end of \fBIPREFIX\fP, for +example: +.RS +.PP +.RS +.nf +\fBIPREFIX=${PREFIX%%\e=*}= +PREFIX=${PREFIX#*=}\fP +.fi +.RE +.PP +causes the part of the prefix up to and including the first equal sign not +to be treated as part of a matched string\&. This can be done automatically +by the \fBcompset\fP builtin, see below\&. +.RE +.TP +\fBISUFFIX\fP +As \fBIPREFIX\fP, but for a suffix that should not be considered part +of the matches; note that the \fBISUFFIX\fP string follows the \fBSUFFIX\fP +string\&. +.TP +\fBPREFIX\fP +Initially this will be set to the part of the current word from the +beginning of the word up to the position of the cursor; it may be altered +to give a common prefix for all matches\&. +.TP +\fBQIPREFIX\fP +This parameter is read\-only and contains the quoted string up to the +word being completed\&. E\&.g\&. when completing `\fB"foo\fP\&', this parameter +contains the double quote\&. If the \fB\-q\fP option of \fBcompset\fP is used +(see below), and the original string was `\fB"foo bar\fP\&' with the +cursor on the `\fBbar\fP\&', this parameter contains `\fB"foo \fP'\&. +.TP +\fBQISUFFIX\fP +Like \fBQIPREFIX\fP, but containing the suffix\&. +.TP +\fBSUFFIX\fP +Initially this will be set to the part of the current word from the +cursor position to the end; it may be altered to give a common suffix for +all matches\&. It is most useful when the option \fBCOMPLETE_IN_WORD\fP is +set, as otherwise the whole word on the command line is treated as a +prefix\&. +.TP +\fBcompstate\fP +This is an associative array with various keys and values that the +completion code uses to exchange information with the completion widget\&. +The keys are: +.RS +.PP +.PD 0 +.TP +.PD +\fBall_quotes\fP +The \fB\-q\fP option of the \fBcompset\fP builtin command (see below) +allows a quoted string to be broken into separate words; if the cursor is +on one of those words, that word will be completed, possibly invoking +`\fBcompset \-q\fP\&' recursively\&. With this key it is possible to test the +types of quoted strings which are currently broken into parts in this +fashion\&. Its value contains one character for each quoting level\&. The +characters are a single quote or a double quote for strings quoted with +these characters, a dollars sign for strings quoted with +\fB$\&'\fP\fI\&.\&.\&.\fP\fB'\fP and a backslash for strings not starting with a +quote character\&. The first character in the value always corresponds to the +innermost quoting level\&. +.TP +\fBcontext\fP +This will be set by the completion code to the overall context +in which completion is attempted\&. Possible values are: +.RS +.PP +.PD 0 +.TP +.PD +\fBarray_value\fP +when completing inside the value of an array parameter assignment; in +this case the \fBwords\fP array contains the words inside the parentheses\&. +.TP +\fBbrace_parameter\fP +when completing the name of a parameter in a parameter expansion beginning +with \fB${\fP\&. This context will also be set when completing parameter +flags following \fB${(\fP; the full command line argument is presented +and the handler must test the value to be completed to ascertain that +this is the case\&. +.TP +\fBassign_parameter\fP +when completing the name of a parameter in a parameter assignment\&. +.TP +\fBcommand\fP +when completing for a normal command (either in command position or for +an argument of the command)\&. +.TP +\fBcondition\fP +when completing inside a `\fB[[\fP\&.\&.\&.\fB]]\fP\&' conditional expression; in +this case the \fBwords\fP array contains only the words inside the +conditional expression\&. +.TP +\fBmath\fP +when completing in a mathematical environment such as a +`\fB((\fP\&.\&.\&.\fB))\fP\&' construct\&. +.TP +\fBparameter\fP +when completing the name of a parameter in a parameter expansion beginning +with \fB$\fP but not \fB${\fP\&. +.TP +\fBredirect\fP +when completing after a redirection operator\&. +.TP +\fBsubscript\fP +when completing inside a parameter subscript\&. +.TP +\fBvalue\fP +when completing the value of a parameter assignment\&. +.RE +.TP +\fBexact\fP +Controls the behaviour when the \fBREC_EXACT\fP option is set\&. It will be +set to \fBaccept\fP if an exact match would be accepted, and will be unset +otherwise\&. +.RS +.PP +If it was set when at least one match equal to the string on the line +was generated, the match is accepted\&. +.RE +.TP +\fBexact_string\fP +The string of an exact match if one was found, otherwise unset\&. +.TP +\fBignored\fP +The number of completions that were ignored because they matched one of the +patterns given with the \fB\-F\fP option to the \fBcompadd\fP builtin +command\&. +.TP +\fBinsert\fP +This controls the manner in which a match is inserted into the command +line\&. On entry to the widget function, if it is unset the command line is +not to be changed; if set to \fBunambiguous\fP, any prefix common to all +matches is to be inserted; if set to \fBautomenu\-unambiguous\fP, the +common prefix is to be inserted and the next invocation of the +completion code may start menu completion (due to the \fBAUTO_MENU\fP +option being set); if set to \fBmenu\fP or \fBautomenu\fP menu completion +will be started for the matches currently generated (in the +latter case this will happen because the \fBAUTO_MENU\fP is set)\&. The +value may also contain the string `\fBtab\fP\&' when the completion code +would normally not really do completion, but only insert the TAB +character\&. +.RS +.PP +On exit it may be set to any of the values above (where setting it to +the empty string is the same as unsetting it), or to a number, in which +case the match whose number is given will be inserted into the command line\&. +Negative numbers count backward from the last match (with `\fB\-1\fP\&' +selecting the last match) and out\-of\-range values are wrapped +around, so that a value of zero selects the last match and a value +one more than the maximum selects the first\&. Unless the value of this +key ends in a space, the match is inserted as in a menu completion, +i\&.e\&. without automatically appending a space\&. +.PP +Both \fBmenu\fP and \fBautomenu\fP may also specify the number of the +match to insert, given after a colon\&. For example, `\fBmenu:2\fP\&' says +to start menu completion, beginning with the second match\&. +.PP +Note that a value containing the substring `\fBtab\fP\&' makes the +matches generated be ignored and only the TAB be inserted\&. +.PP +Finally, it may also be set to \fBall\fP, which makes all matches +generated be inserted into the line\&. +.RE +.TP +\fBinsert_positions\fP +When the completion system inserts an unambiguous string into the +line, there may be multiple places where characters are missing or +where the character inserted differs from at least one match\&. The +value of this key contains a colon separated list of all these +positions, as indexes into the command line\&. +.TP +\fBlast_prompt\fP +If this is set to a non\-empty string for every match added, the +completion code will move the cursor back to the previous prompt after +the list of completions has been displayed\&. Initially this is set or +unset according to the \fBALWAYS_LAST_PROMPT\fP option\&. +.TP +\fBlist\fP +This controls whether or how the list of matches will be displayed\&. If it +is unset or empty they will never be listed; if its value begins with +\fBlist\fP, they will always be listed; if it begins with \fBautolist\fP +or \fBambiguous\fP, they will be listed when the \fBAUTO_LIST\fP or +\fBLIST_AMBIGUOUS\fP options respectively would normally cause them to +be\&. +.RS +.PP +If the substring \fBforce\fP appears in the value, this makes the +list be shown even if there is only one match\&. Normally, the list +would be shown only if there are at least two matches\&. +.PP +The value contains the substring \fBpacked\fP if the \fBLIST_PACKED\fP +option is set\&. If this substring is given for all matches added to a +group, this group will show the \fBLIST_PACKED\fP behavior\&. The same is +done for the \fBLIST_ROWS_FIRST\fP option with the substring \fBrows\fP\&. +.PP +Finally, if the value contains the string \fBexplanations\fP, only the +explanation strings, if any, will be listed and if it contains +\fBmessages\fP, only the messages (added with the \fB\-x\fP option of +\fBcompadd\fP) will be listed\&. If it contains both \fBexplanations\fP and +\fBmessages\fP both kinds of explanation strings will be listed\&. It +will be set appropriately on entry to a completion widget and may be +changed there\&. +.RE +.TP +\fBlist_lines\fP +This gives the number of lines that are needed to display the full +list of completions\&. Note that to calculate the total number of lines +to display you need to add the number of lines needed for the command +line to this value, this is available as the value of the \fBBUFFERLINES\fP +special parameter\&. +.TP +\fBlist_max\fP +Initially this is set to the value of the \fBLISTMAX\fP parameter\&. +It may be set to any other value; when the widget exits this value +will be used in the same way as the value of \fBLISTMAX\fP\&. +.TP +\fBnmatches\fP +The number of matches added by the completion code so far\&. +.TP +\fBold_insert\fP +On entry to the widget this will be set to the number of the match of +an old list of completions that is currently inserted into the command +line\&. If no match has been inserted, this is unset\&. +.RS +.PP +As with \fBold_list\fP, the value of this key will only be used if it is the +string \fBkeep\fP\&. If it was set to this value by the widget and there was an +old match inserted into the command line, this match will be kept and if +the value of the \fBinsert\fP key specifies that another match should be +inserted, this will be inserted after the old one\&. +.RE +.TP +\fBold_list\fP +This is set to \fByes\fP if there is still a valid list of completions +from a previous completion at the time the widget is invoked\&. This will +usually be the case if and only if the previous editing operation was a +completion widget or one of the builtin completion functions\&. If there is a +valid list and it is also currently shown on the screen, the value of this +key is \fBshown\fP\&. +.RS +.PP +After the widget has exited the value of this key is only used if it +was set to \fBkeep\fP\&. In this case the completion code will continue +to use this old list\&. If the widget generated new matches, they will +not be used\&. +.RE +.TP +\fBparameter\fP +The name of the parameter when completing in a subscript or in the +value of a parameter assignment\&. +.TP +\fBpattern_insert\fP +Normally this is set to \fBmenu\fP, which specifies that menu completion will +be used whenever a set of matches was generated using \fBpattern_match\fP +(see below)\&. If +it is set to any other non\-empty string by the user and menu completion is +not selected by other option settings, the code will instead insert any +common prefix for the generated matches as with normal completion\&. +.TP +\fBpattern_match\fP +Locally controls the behaviour given by the \fBGLOB_COMPLETE\fP option\&. +Initially it is set to `\fB*\fP\&' if and only if the option is set\&. +The completion widget may set it to this value, to an empty string +(which has the same effect as unsetting it), or to any +other non\-empty string\&. If it is non\-empty, unquoted metacharacters on the +command line will be treated as patterns; if it is `\fB*\fP\&', then +additionally a wildcard `\fB*\fP\&' is assumed at the cursor position; if +it is empty or unset, metacharacters will be treated literally\&. +.RS +.PP +Note that the match specifications given to the \fBcompadd\fP builtin +command are not used if this is set to a non\-empty string\&. +.RE +.TP +\fBquote\fP +When completing inside quotes, this contains the quotation character +(i\&.e\&. either a single quote, a double quote, or a backtick)\&. Otherwise it +is unset\&. +.TP +\fBquoting\fP +When completing inside single quotes, this is set to the string +\fBsingle\fP; inside double quotes, the string +\fBdouble\fP; inside backticks, the string \fBbacktick\fP\&. +Otherwise it is unset\&. +.TP +\fBredirect\fP +The redirection operator when completing in a redirection position, +i\&.e\&. one of \fB<\fP, \fB>\fP, etc\&. +.TP +\fBrestore\fP +This is set to \fBauto\fP before a function is entered, which forces the +special parameters mentioned above (\fBwords\fP, \fBCURRENT\fP, \fBPREFIX\fP, +\fBIPREFIX\fP, \fBSUFFIX\fP, and \fBISUFFIX\fP) to be restored to their +previous values when the function exits\&. If a function unsets it or +sets it to any other string, they will not be restored\&. +.TP +\fBto_end\fP +Specifies the occasions on which the cursor is moved to the end of a string +when a match is inserted\&. On entry to a widget function, it may be +\fBsingle\fP if this will happen when a single unambiguous match was inserted +or \fBmatch\fP if it will happen any time a match is inserted (for example, +by menu completion; this is likely to be the effect of the \fBALWAYS_TO_END\fP +option)\&. +.RS +.PP +On exit, it may be set to \fBsingle\fP as above\&. It may also be set to +\fBalways\fP, or to the empty string or unset; in those cases the cursor will +be moved to the end of the string always or never respectively\&. Any +other string is treated as \fBmatch\fP\&. +.RE +.TP +\fBunambiguous\fP +This key is read\-only and will always be set to the common (unambiguous) +prefix the completion code has generated for all matches added so far\&. +.TP +\fBunambiguous_cursor\fP +This gives the position the cursor would be placed at if the +common prefix in the \fBunambiguous\fP key were inserted, relative to +the value of that key\&. The cursor would be placed before the character +whose index is given by this key\&. +.TP +\fBunambiguous_positions\fP +This contains all positions where characters in the unambiguous string +are missing or where the character inserted differs from at least one +of the matches\&. The positions are given as indexes into the string +given by the value of the \fBunambiguous\fP key\&. +.TP +\fBvared\fP +If completion is called while editing a line using the \fBvared\fP +builtin, the value of this key is set to the name of the parameter +given as an argument to \fBvared\fP\&. This key is only set while a \fBvared\fP +command is active\&. +.RE +.TP +\fBwords\fP +This array contains the words present on the command line currently being +edited\&. +.PP +.SH "COMPLETION BUILTIN COMMANDS" +.PD 0 + +.TP +.PD 0 +\fBcompadd \fP[ \fB\-akqQfenUl12C\fP ] [ \fB\-F\fP \fIarray\fP ] +.TP +.PD 0 +\fB \fP[\fB\-P\fP \fIprefix\fP ] [ \fB\-S\fP \fIsuffix\fP ] +.TP +.PD 0 +\fB \fP[\fB\-p\fP \fIhidden\-prefix\fP ] [ \fB\-s\fP \fIhidden\-suffix\fP ] +.TP +.PD 0 +\fB \fP[\fB\-i\fP \fIignored\-prefix\fP ] [ \fB\-I\fP \fIignored\-suffix\fP ] +.TP +.PD 0 +\fB \fP[\fB\-W\fP \fIfile\-prefix\fP ] [ \fB\-d\fP \fIarray\fP ] +.TP +.PD 0 +\fB \fP[\fB\-J\fP \fIgroup\-name\fP ] [ \fB\-X\fP \fIexplanation\fP ] [ \fB\-x\fP \fImessage\fP ] +.TP +.PD 0 +\fB \fP[\fB\-V\fP \fIgroup\-name\fP ] [ \fB\-o\fP [ \fIorder\fP ] ] +.TP +.PD 0 +\fB \fP[\fB\-r\fP \fIremove\-chars\fP ] [ \fB\-R\fP \fIremove\-func\fP ] +.TP +.PD 0 +\fB \fP[\fB\-D\fP \fIarray\fP ] [ \fB\-O\fP \fIarray\fP ] [ \fB\-A\fP \fIarray\fP ] +.TP +.PD 0 +\fB \fP[\fB\-E\fP \fInumber\fP ] +.TP +.PD +\fB \fP[\fB\-M\fP \fImatch\-spec\fP ] [ \fB\-\fP\fB\-\fP ] [ \fIcompletions\fP \&.\&.\&. ] +.RS +.PP +This builtin command can be used to add matches directly and control +all the information the completion code stores with each possible +completion\&. The return status is zero if at least one match was added and +non\-zero if no matches were added\&. +.PP +The completion code breaks each match into seven fields in the order: +.PP +.RS +.nf +\fI<ipre><apre><hpre><body><hsuf><asuf><isuf>\fP +.fi +.RE +.PP +The first field +is an ignored prefix taken from the command line, the contents of the +\fBIPREFIX\fP parameter plus the string given with the \fB\-i\fP +option\&. With the \fB\-U\fP option, only the string from the \fB\-i\fP +option is used\&. The field \fI<apre>\fP is an optional prefix string +given with the \fB\-P\fP option\&. The \fI<hpre>\fP field is a string +that is considered part of the match but that should not be shown when +listing completions, given with the \fB\-p\fP option; for example, +functions that do filename generation might specify +a common path prefix this way\&. \fI<body>\fP is the part of the match that +should appear in the list of matches shown to the user\&. +The suffixes \fI<hsuf>\fP, +\fI<asuf>\fP and \fI<isuf>\fP correspond to the prefixes \fI<hpre>\fP, +\fI<apre>\fP and \fI<ipre>\fP and are given by the options \fB\-s\fP, \fB\-S\fP and +\fB\-I\fP, respectively\&. +.PP +The supported flags are: +.PP +.PD 0 +.TP +.PD +\fB\-P\fP \fIprefix\fP +This gives a string to be inserted before each match\&. The +string given is not considered as part of the match and any shell +metacharacters in it will not be quoted when the string is inserted\&. +.TP +\fB\-S\fP \fIsuffix\fP +Like \fB\-P\fP, but gives a string to be inserted after each match\&. +.TP +\fB\-p\fP \fIhidden\-prefix\fP +This gives a string that should be inserted before each +match but that should not appear in the list of matches\&. Unless the +\fB\-U\fP option is given, this string must be matched as part of the string +on the command line\&. +.TP +\fB\-s\fP \fIhidden\-suffix\fP +Like `\fB\-p\fP\&', but gives a string to insert after each match\&. +.TP +\fB\-i\fP \fIignored\-prefix\fP +This gives a string to insert just before any +string given with the `\fB\-P\fP\&' option\&. Without `\fB\-P\fP' the string is +inserted before the string given with `\fB\-p\fP\&' or directly before each +match\&. +.TP +\fB\-I\fP \fIignored\-suffix\fP +Like \fB\-i\fP, but gives an ignored suffix\&. +.TP +\fB\-a\fP +With this flag the \fIcompletions\fP are taken as names of arrays and the +actual completions are their values\&. If only some elements of the +arrays are needed, the \fIcompletions\fP may also contain subscripts, as in +`\fBfoo[2,\-1]\fP\&'\&. +.TP +\fB\-k\fP +With this flag the \fIcompletions\fP are taken as names of associative arrays +and the actual completions are their keys\&. As for \fB\-a\fP, the +\fIwords\fP may also contain subscripts, as in `\fBfoo[(R)*bar*]\fP\&'\&. +.TP +\fB\-d\fP \fIarray\fP +This adds per\-completion display strings\&. The \fIarray\fP should contain one +element per \fIcompletion\fP given\&. The completion code will then display the +first element instead of the first \fIcompletion\fP, and so on\&. The +\fIarray\fP may be given as the name of an array parameter or directly +as a space\-separated list of words in parentheses\&. +.RS +.PP +If there are fewer display strings than \fIcompletions\fP, the leftover +\fIcompletions\fP will be displayed unchanged and if there are more display +strings than \fIcompletions\fP, the leftover display strings will be silently +ignored\&. +.RE +.TP +\fB\-l\fP +This option only has an effect if used together with the \fB\-d\fP +option\&. If it is given, the display strings are listed one per line, +not arrayed in columns\&. +.TP +\fB\-o\fP [ \fIorder\fP ] +This controls the order in which matches are sorted\&. \fIorder\fP is a +comma\-separated list comprising the following possible values\&. These values +can be abbreviated to their initial two or three characters\&. Note that the +order forms part of the group name space so matches with different orderings +will not be in the same group\&. +.RS +.PP +.PD 0 +.TP +.PD +\fBmatch\fP +If given, the order of the output is determined by the match strings; +otherwise it is determined by the display strings (i\&.e\&. the strings given +by the \fB\-d\fP option)\&. This is the default if `\fB\-o\fP\&' is specified but +the \fIorder\fP argument is omitted\&. +.TP +\fBnosort\fP +This specifies that the \fIcompletions\fP +are pre\-sorted and their order should be +preserved\&. This value only makes sense alone and cannot be combined with any +others\&. +.TP +\fBnumeric\fP +If the matches include numbers, sort them numerically rather than +lexicographically\&. +.TP +\fBreverse\fP +Arrange the matches backwards by reversing the sort ordering\&. +.RE +.TP +\fB\-J\fP \fIgroup\-name\fP +Gives the name of the group that the matches should be stored in\&. +.TP +\fB\-V\fP \fIgroup\-name\fP +Like \fB\-J\fP but naming an unsorted group\&. This option is identical to +the combination of \fB\-J\fP and \fB\-o nosort\fP\&. +.TP +\fB\-1\fP +If given together with the \fB\-V\fP option, makes +only consecutive duplicates in the group be removed\&. If combined with +the \fB\-J\fP option, this has no visible effect\&. Note that groups +with and without this flag are in different name spaces\&. +.TP +\fB\-2\fP +If given together with the \fB\-J\fP or \fB\-V\fP option, makes all +duplicates be kept\&. Again, groups with and without this flag are in +different name spaces\&. +.TP +\fB\-X\fP \fIexplanation\fP +The \fIexplanation\fP string will be printed with the list of matches, +above the group currently selected\&. +.RS +.PP +Within the \fIexplanation\fP, the following sequences may be used to +specify output attributes +as described in the section EXPANSION OF PROMPT SEQUENCES in +\fIzshmisc\fP(1): +`\fB%B\fP\&', `\fB%S\fP', `\fB%U\fP', `\fB%F\fP', `\fB%K\fP' and their lower case +counterparts, as well as `\fB%{\fP\&.\&.\&.\fB%}\fP\&'\&. `\fB%F\fP', `\fB%K\fP' and +`\fB%{\fP\&.\&.\&.\fB%}\fP\&' take arguments in the same form as prompt +expansion\&. (Note that the sequence `\fB%G\fP\&' is not available; an +argument to `\fB%{\fP\&' should be used instead\&.) The sequence `\fB%%\fP' +produces a literal `\fB%\fP\&'\&. +.PP +These sequences are most often employed by users when customising the +\fBformat\fP style +(see +\fIzshcompsys\fP(1)), +but they must also be taken into account when writing completion +functions, as passing descriptions with unescaped `\fB%\fP\&' characters +to utility functions such as \fB_arguments\fP and \fB_message\fP may +produce unexpected results\&. If arbitrary text is to be passed in a +description, it can be escaped using e\&.g\&. \fB${my_str//\e%/%%}\fP\&. +.RE +.TP +\fB\-x\fP \fImessage\fP +Like \fB\-X\fP, but the \fImessage\fP will be printed even if there are no +matches in the group\&. +.TP +\fB\-q\fP +The suffix given with \fB\-S\fP will be automatically removed if +the next character typed is a blank or does not insert anything, or if +the suffix consists of only one character and the next character typed +is the same character\&. +.TP +\fB\-r\fP \fIremove\-chars\fP +This is a more versatile form of the \fB\-q\fP option\&. +The suffix given with \fB\-S\fP or the slash automatically added after +completing directories will be automatically removed if +the next character typed inserts one of the characters given in the +\fIremove\-chars\fP\&. This string is parsed as a characters class and +understands the backslash sequences used by the \fBprint\fP command\&. For +example, `\fB\-r "a\-z\et"\fP\&' removes the suffix if the next character typed +inserts a lower case character or a TAB, and `\fB\-r "^0\-9"\fP\&' removes the +suffix if the next character typed inserts anything but a digit\&. One extra +backslash sequence is understood in this string: `\fB\e\-\fP\&' stands for +all characters that insert nothing\&. Thus `\fB\-S "=" \-q\fP\&' is the same +as `\fB\-S "=" \-r "= \et\en\e\-"\fP\&'\&. +.RS +.PP +This option may also be used without the \fB\-S\fP option; then any +automatically added space will be removed when one of the characters in the +list is typed\&. +.RE +.TP +\fB\-R\fP \fIremove\-func\fP +This is another form of the \fB\-r\fP option\&. When a match +has been accepted and a suffix has been inserted, the function +\fIremove\-func\fP will be called after the next character typed\&. It is +passed the length of the suffix as an argument and can use the special +parameters available in ordinary (non\-completion) zle widgets (see +\fIzshzle\fP(1)) to analyse and modify the command line\&. +.TP +\fB\-f\fP +If this flag is given, all of the matches built from the \fIcompletions\fP are +marked as being the names of files\&. They are not required to be actual +filenames, but if they are, and the option \fBLIST_TYPES\fP is set, the +characters describing the types of the files in the completion lists will +be shown\&. This also forces a slash to be added when the name of a +directory is completed\&. +.TP +\fB\-e\fP +This flag can be used to tell the completion code that the matches +added are parameter names for a parameter expansion\&. This will make +the \fBAUTO_PARAM_SLASH\fP and \fBAUTO_PARAM_KEYS\fP options be used for +the matches\&. +.TP +\fB\-W\fP \fIfile\-prefix\fP +This string is a pathname that will be prepended to each match together +with any prefix specified by the \fB\-p\fP option to form a complete filename +for testing\&. Hence it is only useful if combined with the \fB\-f\fP flag, as +the tests will not otherwise be performed\&. +.TP +\fB\-F\fP \fIarray\fP +Specifies an array containing patterns\&. \fIcompletions\fP that match one of +these patterns are ignored, that is, not considered to be matches\&. +.RS +.PP +The \fIarray\fP may be the name of an array parameter or a list of +literal patterns enclosed in parentheses and quoted, as in `\fB\-F "(*?\&.o +*?\&.h)"\fP\&'\&. If the name of an array is given, the elements of the array are +taken as the patterns\&. +.RE +.TP +\fB\-Q\fP +This flag instructs the completion +code not to quote any metacharacters in the matches when inserting them +into the command line\&. +.TP +\fB\-M\fP \fImatch\-spec\fP +This gives local match specifications as described below in +the section `Completion Matching Control\&'\&. This option may be given more than once\&. +In this case all \fImatch\-spec\fPs given are concatenated with spaces +between them to form the specification string to use\&. +Note that they will only be used if the \fB\-U\fP option is not given\&. +.TP +\fB\-n\fP +Specifies that matching \fIcompletions\fP are to be added to the set of +matches, but are not to be listed to the user\&. +.TP +\fB\-U\fP +If this flag is given, all \fIcompletions\fP are added +to the set of matches and no matching +will be done by the completion code\&. Normally this is used in +functions that do the matching themselves\&. +.TP +\fB\-O\fP \fIarray\fP +If this option is given, the \fIcompletions\fP are \fInot\fP added to the set of +matches\&. Instead, matching is done as usual and all of the +\fIcompletions\fP that match +will be stored in the array parameter whose name is given as \fIarray\fP\&. +.TP +\fB\-A\fP \fIarray\fP +As the \fB\-O\fP option, except that instead of those of the \fIcompletions\fP +which +match being stored in \fIarray\fP, the strings generated internally by the +completion code are stored\&. For example, +with a match specification of `\fB\-M "L:|no="\fP\&', a current word of `\fBnof\fP' +and \fIcompletions\fP of `\fBfoo\fP\&', this +option stores the string `\fBnofoo\fP\&' in the array, whereas the \fB\-O\fP +option stores the `\fBfoo\fP\&' originally given\&. +.TP +\fB\-D\fP \fIarray\fP +As with \fB\-O\fP, the \fIcompletions\fP are not added to the set of matches\&. +Instead, whenever the \fIn\fPth \fIcompletion\fP does not +match, the \fIn\fPth element of the \fIarray\fP is removed\&. Elements +for which the corresponding \fIcompletion\fP matches are retained\&. +This option can be used more than once to remove elements from multiple +arrays\&. +.TP +\fB\-C\fP +This option adds a special match which expands to all other matches +when inserted into the line, even those that are added after this +option is used\&. Together with the \fB\-d\fP option it is possible to +specify a string that should be displayed in the list for this special +match\&. If no string is given, it will be shown as a string containing +the strings that would be inserted for the other matches, truncated to +the width of the screen\&. +.TP +\fB\-E\fP \fInumber\fP +This option adds \fInumber\fP empty matches after matching \fIcompletions\fP have +been added\&. An empty match takes up space in completion listings but +will never be inserted in the line and can\&'t be selected with menu +completion or menu selection\&. This makes empty matches only useful to +format completion lists and to make explanatory string be shown in +completion lists (since empty matches can be given display strings +with the \fB\-d\fP option)\&. And because all but one empty string would +otherwise be removed, this option implies the \fB\-V\fP and \fB\-2\fP +options (even if an explicit \fB\-J\fP option is given)\&. This can be +important to note as it affects the name space into which matches are +added\&. +.TP +.PD 0 +\fB\-\fP +.TP +.PD +\fB\-\fP\fB\-\fP +This flag ends the list of flags and options\&. All arguments after it +will be taken as the \fIcompletions\fP even if they begin with +hyphens\&. +.PP +Except for the \fB\-M\fP flag, if any of these flags is given more than +once, the first one (and its argument) will be used\&. +.RE +.TP +.PD 0 +\fBcompset \-p\fP \fInumber\fP +.TP +.PD 0 +\fBcompset \-P\fP [ \fInumber\fP ] \fIpattern\fP +.TP +.PD 0 +\fBcompset \-s\fP \fInumber\fP +.TP +.PD 0 +\fBcompset \-S\fP [ \fInumber\fP ] \fIpattern\fP +.TP +.PD 0 +\fBcompset \-n\fP \fIbegin\fP [ \fIend\fP ] +.TP +.PD 0 +\fBcompset \-N\fP \fIbeg\-pat\fP [ \fIend\-pat\fP ] +.TP +.PD +\fBcompset \-q\fP +This command simplifies modification of the special parameters, +while its return status allows tests on them to be carried out\&. +.RS +.PP +The options are: +.PP +.PD 0 +.TP +.PD +\fB\-p\fP \fInumber\fP +If the value of the \fBPREFIX\fP parameter is at least \fInumber\fP +characters long, the first \fInumber\fP characters are removed from it and +appended to the contents of the \fBIPREFIX\fP parameter\&. +.TP +\fB\-P\fP [ \fInumber\fP ] \fIpattern\fP +If the value of the \fBPREFIX\fP parameter begins with anything that +matches the \fIpattern\fP, the matched portion is removed from +\fBPREFIX\fP and appended to \fBIPREFIX\fP\&. +.RS +.PP +Without the optional \fInumber\fP, the longest match is taken, but +if \fInumber\fP is given, anything up to the \fInumber\fPth match is +moved\&. If the \fInumber\fP is negative, the \fInumber\fPth longest +match is moved\&. For example, if \fBPREFIX\fP contains the string +`\fBa=b=c\fP\&', then \fBcompset \-P '*\e='\fP will move the string `\fBa=b=\fP' +into the \fBIPREFIX\fP parameter, but \fBcompset \-P 1 \&'*\e='\fP will move only +the string `\fBa=\fP\&'\&. +.RE +.TP +\fB\-s\fP \fInumber\fP +As \fB\-p\fP, but transfer the last \fInumber\fP characters from the +value of \fBSUFFIX\fP to the front of the value of \fBISUFFIX\fP\&. +.TP +\fB\-S\fP [ \fInumber\fP ] \fIpattern\fP +As \fB\-P\fP, but match the last portion of \fBSUFFIX\fP and transfer the +matched portion to the front of the value of \fBISUFFIX\fP\&. +.TP +\fB\-n\fP \fIbegin\fP [ \fIend\fP ] +If the current word position as specified by the parameter \fBCURRENT\fP +is greater than or equal to \fIbegin\fP, anything up to the +\fIbegin\fPth word is removed from the \fBwords\fP array and the value +of the parameter \fBCURRENT\fP is decremented by \fIbegin\fP\&. +.RS +.PP +If the optional \fIend\fP is given, the modification is done only if +the current word position is also less than or equal to \fIend\fP\&. In +this case, the words from position \fIend\fP onwards are also removed from +the \fBwords\fP array\&. +.PP +Both \fIbegin\fP and \fIend\fP may be negative to count backwards +from the last element of the \fBwords\fP array\&. +.RE +.TP +\fB\-N\fP \fIbeg\-pat\fP [ \fIend\-pat\fP ] +If one of the elements of the \fBwords\fP array before the one at the +index given by the value of the parameter \fBCURRENT\fP matches the +pattern \fIbeg\-pat\fP, all elements up to and including the matching one are +removed from the \fBwords\fP array and the value of \fBCURRENT\fP is changed to +point to the same word in the changed array\&. +.RS +.PP +If the optional pattern \fIend\-pat\fP is also given, and there is an +element in the \fBwords\fP array matching this pattern, the parameters +are modified only if the index of this word is higher than the one +given by the \fBCURRENT\fP parameter (so that the matching word has +to be after the cursor)\&. In this case, the words starting with the one +matching \fBend\-pat\fP are also removed from the \fBwords\fP +array\&. If \fBwords\fP contains no word matching \fIend\-pat\fP, the +testing and modification is performed as if it were not given\&. +.RE +.TP +\fB\-q\fP +The word +currently being completed is split on spaces into separate words, +respecting the usual shell quoting conventions\&. The +resulting words are stored in the \fBwords\fP array, and \fBCURRENT\fP, +\fBPREFIX\fP, \fBSUFFIX\fP, \fBQIPREFIX\fP, and \fBQISUFFIX\fP are modified to +reflect the word part that is completed\&. +.PP +In all the above cases the return status is zero if the test succeeded +and the parameters were modified and non\-zero otherwise\&. This allows +one to use this builtin in tests such as: +.PP +.RS +.nf +\fBif compset \-P \&'*\e='; then \&.\&.\&.\fP +.fi +.RE +.PP +This forces anything up to and including the last equal sign to be +ignored by the completion code\&. +.RE +.TP +\fBcompcall\fP [ \fB\-TD\fP ] +This allows the use of completions defined with the \fBcompctl\fP builtin +from within completion widgets\&. The list of matches will be generated as +if one of the non\-widget completion functions (\fBcomplete\-word\fP, etc\&.) +had been called, except that only \fBcompctl\fPs given for specific commands +are used\&. To force the code to try completions defined with the \fB\-T\fP +option of \fBcompctl\fP and/or the default completion (whether defined by +\fBcompctl \-D\fP or the builtin default) in the appropriate places, the +\fB\-T\fP and/or \fB\-D\fP flags can be passed to \fBcompcall\fP\&. +.RS +.PP +The return status can be used to test if a matching \fBcompctl\fP +definition was found\&. It is non\-zero if a \fBcompctl\fP was found and +zero otherwise\&. +.PP +Note that this builtin is defined by the \fBzsh/compctl\fP module\&. +.RE +.PP +.SH "COMPLETION CONDITION CODES" +.PP +The following additional condition codes for use within the \fB[[\fP \fI\&.\&.\&.\fP \fB]]\fP +construct are available in completion widgets\&. These work on the special +parameters\&. All of these tests can also be performed by the \fBcompset\fP +builtin, but in the case of the condition codes the contents of the special +parameters are not modified\&. +.PP +.PD 0 +.TP +.PD +\fB\-prefix\fP [ \fInumber\fP ] \fIpattern\fP +true if the test for the \fB\-P\fP option of \fBcompset\fP would succeed\&. +.TP +\fB\-suffix\fP [ \fInumber\fP ] \fIpattern\fP +true if the test for the \fB\-S\fP option of \fBcompset\fP would succeed\&. +.TP +\fB\-after\fP \fIbeg\-pat\fP +true if the test of the \fB\-N\fP option with only the \fIbeg\-pat\fP given +would succeed\&. +.TP +\fB\-between\fP \fIbeg\-pat end\-pat\fP +true if the test for the \fB\-N\fP option with both patterns would succeed\&. +.PP +.SH "COMPLETION MATCHING CONTROL" +.PP +When the user invokes completion, the current \fIword\fP on the command line +(that is, the word the cursor is currently on) is used to generate a \fImatch +pattern\fP\&. Only those \fIcompletions\fP that match the pattern are offered to the +user as \fImatches\fP\&. +.PP +The default match pattern is generated from the current word by either +.PP +.PD 0 +.TP +.PD +\(bu +appending a `\fB*\fP\&' (matching any number of characters in a completion) +\fIor,\fP +.TP +\(bu +if the shell option \fBCOMPLETE_IN_WORD\fP is set, inserting a `\fB*\fP\&' at the +cursor position\&. +.PP +This narrow pattern can be broadened selectively by passing a \fImatch +specification\fP to the \fBcompadd\fP builtin command through its \fB\-M\fP option +(see +`Completion Builtin Commands\&' above)\&. A match specification consists of one or more \fImatchers\fP separated by +whitespace\&. Matchers in a match specification are applied one at a time, from +left to right\&. Once all matchers have been applied, completions are compared +to the final match pattern and non\-matching ones are discarded\&. +.PP +.PD 0 +.TP +.PD +\(bu +Note that the \fB\-M\fP option is ignored if the current word contains a glob +pattern and the shell option \fBGLOB_COMPLETE\fP is set or if the +\fBpattern_match\fP key of the special associative array \fBcompstate\fP is set to +a non\-empty value (see +`Completion Special Parameters\&' above)\&. +.TP +\(bu +Users of the completion system (see \fIzshcompsys\fP(1)) should generally not use the \fB\-M\fP option directly, but rather use the +\fBmatcher\-list\fP and \fBmatcher\fP styles (see the subsection \fIStandard Styles\fP +in +the documentation for COMPLETION SYSTEM CONFIGURATION in \fIzshcompsys\fP(1))\&. +.PP +Each matcher consists of +.PP +.PD 0 +.TP +.PD +\(bu +a case\-sensitive letter +.TP +\(bu +a `\fB:\fP\&', +.TP +\(bu +one or more patterns separated by pipes (`\fB|\fP\&'), +.TP +\(bu +an equals sign (`\fB=\fP\&'), and +.TP +\(bu +another pattern\&. +.PP +The patterns before the `\fB=\fP\&' are used to match substrings of the current +word\&. For each matched substring, the corresponding part of the match pattern +is broadened with the pattern after the `\fB=\fP\&', by means of a logical \fBOR\fP\&. +.PP +Each pattern in a matcher cosists of either +.PP +.PD 0 +.TP +.PD +\(bu +the empty string or +.TP +\(bu +a sequence of +.RS +.PP +.PD 0 +.TP +.PD +\(bu +literal characters (which may be quoted with a `\fB\e\fP\&'), +.TP +\(bu +question marks (`\fB?\fP\&'), +.TP +\(bu +bracket expressions (`\fB[\&.\&.\&.]\fP\&'; see the subsection \fIGlob Operators\fP in +the documentation for GLOB OPERATORS in \fIzshexpn\fP(1)), and/or +.TP +\(bu +brace expressions (see below)\&. + +.RE +.PP +Other shell patterns are not allowed\&. +.PP +A brace expression, like a bracket expression, consists of a list of +.PP +.PD 0 +.TP +.PD +\(bu +literal characters, +.TP +\(bu +ranges (`\fB0\-9\fP\&'), and/or +.TP +\(bu +character classes (`\fB[:\fP\fIname\fP\fB:]\fP\&')\&. +.PP +However, they differ from each other as follows: +.PP +.PD 0 +.TP +.PD +\(bu +A brace expression is delimited by a pair of braces (`\fB{\&.\&.\&.}\fP\&')\&. +.TP +\(bu +Brace expressions do not support negations\&. That is, an initial +`\fB!\fP\&' or `\fB^\fP' has no special meaning and will be interpreted as a literal +character\&. +.TP +\(bu +When a character in the current word matches the \fIn\fPth pattern in a brace +expression, the corresponding part of the match pattern is broadened only with +the \fIn\fPth pattern of the brace expression on the other side of the `\fB=\fP\&', +if there is one; if there is no brace expression on the other side, then this +pattern is the empty string\&. However, if either brace expression has more +elements than the other, then the excess entries are simply ignored\&. When +comparing indexes, each literal character or character class counts as one +element, but each range is instead expanded to the full list of literal +characters it represents\&. Additionally, if on \fIboth\fP sides of the +`\fB=\fP\&', the \fIn\fPth pattern is `\fB[:upper:]\fP' or `\fB[:lower:]\fP', then these +are expanded as ranges, too\&. +.PP +Note that, although the matching system does not yet handle multibyte +characters, this is likely to be a future extension\&. Hence, using +`\fB[:upper:]\fP\&' and `\fB[:lower:]\fP' is recommended over +`\fBA\-Z\fP\&' and `\fBa\-z\fP'\&. +.PP +Below are the different forms of matchers supported\&. Each \fIuppercase\fP form +behaves exactly like its lowercase counterpart, but adds an additional step +\fIafter\fP the match pattern has filtered out non\-matching completions: Each of +a match\&'s substrings that was matched by a subpattern from an uppercase matcher +is replaced with the corresponding substring of the current word\&. However, +patterns from \fIlowercase\fP matchers have higher weight: If a substring of the +current word was matched by patterns from both a lowercase and an uppercase +matcher, then the lowercase matcher\&'s pattern wins and the corresponding part +of the match is not modified\&. +.PP +Unless indicated otherwise, each example listed assumes \fBCOMPLETE_IN_WORD\fP to +be unset (as it is by default)\&. +.PP +.PD 0 +.TP +.PD 0 +\fBm:\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD +\fBM:\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.RS +.PP +For each substring of the current word that matches \fIword\-pat\fP, broaden the +corresponding part of the match pattern to additionally match \fImatch\-pat\fP\&. +.PP +.PD 0 +.TP +.PD +Examples: +.RS +.PP +\fBm:{[:lower:]}={[:upper:]}\fP lets any lower case character in the current word +be completed to itself or its uppercase counterpart\&. So, the completions +`\fBfoo\fP\&', `\fBFOO\fP' and `\fBFoo\fP' will are be considered matches for the word +`\fBfo\fP\&'\&. +.PP +\fBM:_=\fP inserts every underscore from the current word into each match, in the +same relative position, determined by matching the substrings around it\&. So, +given a completion `\fBfoo\fP\&', the word `\fBf_o\fP' will be completed to the match +`\fBf_oo\fP\&', even though the latter was not present as a completion\&. +.RE +.RE +.TP +.PD 0 +\fBb:\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBB:\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBe:\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD +\fBE:\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.RS +.PP +For each consecutive substring at the \fBb:\fPeginning or \fBe:\fPnd of the current +word that matches \fIword\-pat\fP, broaden the corresponding part of the match +pattern to additionally match \fImatch\-pat\fP\&. +.PP +.PD 0 +.TP +.PD +Examples: +.RS +.PP +`\fBb:\-=+\fP\&' lets any number of minuses at the start of the current word be +completed to a minus or a plus\&. +.PP +`\fBB:0=\fP\&' adds all zeroes at the beginning of the current word to the +beginning of each match\&. +.RE +.RE +.TP +.PD 0 +\fBl:\fP\fB|\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBL:\fP\fB|\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBR:\fP\fIword\-pat\fP\fB|\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD +\fBr:\fP\fIword\-pat\fP\fB|\fP\fB=\fP\fImatch\-pat\fP +.RS +.PP +If there is a substring at the \fBl:\fPeft or \fBr:\fPight edge of the current word +that matches \fIword\-pat\fP, then broaden the corresponding part of the match +pattern to additionally match \fImatch\-pat\fP\&. +.PP +For each \fBl:\fP, \fBL:\fP, \fBr:\fP and \fBR:\fP matcher (including the ones below), +the pattern \fImatch\-pat\fP may also be a `\fB*\fP\&'\&. This matches any number of +characters in a completion\&. +.PP +.PD 0 +.TP +.PD +Examples: +.RS +.PP +`\fBr:|=*\fP\&' appends a `\fB*\fP' to the match pattern, even when +\fBCOMPLETE_IN_WORD\fP is set and the cursor is not at the end of the current +word\&. +.PP +If the current word starts with a minus, then `\fBL:|\-=\fP\&' will prepend it to +each match\&. +.RE +.RE +.TP +.PD 0 +\fBl:\fP\fIanchor\fP\fB|\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBL:\fP\fIanchor\fP\fB|\fP\fIword\-pat\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBr:\fP\fIword\-pat\fP\fB|\fP\fIanchor\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD +\fBR:\fP\fIword\-pat\fP\fB|\fP\fIanchor\fP\fB=\fP\fImatch\-pat\fP +.RS +.PP +For each substring of the current word that matches \fIword\-pat\fP and has on +its \fBl:\fPeft or \fBr:\fPight another substring matching \fIanchor\fP, broaden the +corresponding part of the match pattern to additionally match \fImatch\-pat\fP\&. +.PP +Note that these matchers (and the ones below) modify only what is matched by +\fIword\-pat\fP; they do not change the matching behavior of what is matched by +\fIanchor\fP (or \fIcoanchor\fP; see the matchers below)\&. Thus, unless its +corresponding part of the match pattern has been modified, the anchor in the +current word has to match literally in each completion, just like any other +substring of the current word\&. +.PP +If a matcher includes at least one anchor (which includes the matchers with two +anchors, below), then \fImatch\-pat\fP may also be `\fB*\fP\&' or `\fB**\fP'\&. `\fB*\fP' +can match any part of a completion that does not contain any substrings +matching \fIanchor\fP, whereas a `\fB**\fP\&' can match any part of a completion, +period\&. (Note that this is different from the behavior of `\fB*\fP\&' in the +anchorless forms of `\fBl:\fP\&' and `\fBr:\fP' and and also different from `\fB*\fP' +and `\fB**\fP\&' in glob expressions\&.) +.PP +.PD 0 +.TP +.PD +Examples: +.RS +.PP +`\fBr:|\&.=*\fP\&' makes the completion `\fBcomp\&.sources\&.unix\fP' a match for the word +`\fB\&.\&.u\fP\&' \-\- but \fInot\fP for the word `\fB\&.u\fP'\&. +.PP +Given a completion `\fB\-\fP\fB\-foo\fP\&', the matcher `\fBL:\-\-|no\-=\fP' will complete +the word `\fB\-\fP\fB\-no\-\fP\&' to the match `\fB\-\fP\fB\-no\-foo\fP'\&. +.RE +.RE +.TP +.PD 0 +\fBl:\fP\fIanchor\fP\fB||\fP\fIcoanchor\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBL:\fP\fIanchor\fP\fB||\fP\fIcoanchor\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD 0 +\fBr:\fP\fIcoanchor\fP\fB||\fP\fIanchor\fP\fB=\fP\fImatch\-pat\fP +.TP +.PD +\fBR:\fP\fIcoanchor\fP\fB||\fP\fIanchor\fP\fB=\fP\fImatch\-pat\fP +.RS +.PP +For any two consecutive substrings of the current word that match \fIanchor\fP +and \fIcoanchor\fP, in the order given, insert the pattern \fImatch\-pat\fP +between their corresponding parts in the match pattern\&. +.PP +Note that, unlike \fIanchor\fP, the pattern \fIcoanchor\fP does not change what +`\fB*\fP\&' can match\&. +.PP +.PD 0 +.TP +.PD +Examples: +.RS +.PP +`\fBr:?||[[:upper:]]=*\fP\&' will complete the current word `\fBfB\fP' to +`\fBfooBar\fP\&', but it will not complete it to `\fBfooHooBar\fP' (because `\fB*\fP' +here cannot match anything that includes a match for `\fB[[:upper:]]\fP), nor +will it complete `\fBB\fP\&' to `\fBfooBar\fP' (because there is no character in the +current word to match \fIcoanchor\fP)\&. +.PP +Given the current word `\fBpass\&.n\fP\&' and a completion `\fBpass\&.byname\fP', the +matcher `\fBL:\&.||[[:alpha:]]=by\fP\&' will produce the match `\fBpass\&.name\fP'\&. +.RE +.RE +.TP +\fBx:\fP +.RS +.PP +Ignore this matcher and all matchers to its right\&. +.PP +This matcher is used to mark the end of a match specification\&. In a single +standalone list of matchers, this has no use, but where match specifications +are concatenated, as is often the case when using the +completion system (see \fIzshcompsys\fP(1)), it can allow one match specification to override another\&. +.RE +.PP +.SH "COMPLETION WIDGET EXAMPLE" +.PP +The first step is to define the widget: +.PP +.RS +.nf +\fBzle \-C complete complete\-word complete\-files\fP +.fi +.RE +.PP +Then the widget can be bound to a key using the \fBbindkey\fP builtin +command: +.PP +.RS +.nf +\fBbindkey \&'^X\et' complete\fP +.fi +.RE +.PP +After that the shell function \fBcomplete\-files\fP will be invoked +after typing control\-X and TAB\&. The function should then generate the +matches, e\&.g\&.: +.PP +.RS +.nf +\fBcomplete\-files () { compadd \- * }\fP +.fi +.RE +.PP +This function will complete files in the current directory matching the +current word\&. diff --git a/Doc/zshcontrib.1 b/Doc/zshcontrib.1 new file mode 100644 index 000000000..573822d46 --- /dev/null +++ b/Doc/zshcontrib.1 @@ -0,0 +1,5558 @@ +.TH "ZSHCONTRIB" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshcontrib \- user contributions to zsh +.\" Yodl file: Zsh/contrib.yo +.SH "DESCRIPTION" +.PP +The Zsh source distribution includes a number of items contributed by the +user community\&. These are not inherently a part of the shell, and some +may not be available in every zsh installation\&. The most significant of +these are documented here\&. For documentation on other contributed items +such as shell functions, look for comments in the function source files\&. +.PP +.PP +.SH "UTILITIES" +.PP +.SS "Accessing On\-Line Help" +.PP +The key sequence \fBESC h\fP is normally bound by ZLE to execute the +\fBrun\-help\fP widget (see +\fIzshzle\fP(1))\&. This invokes the \fBrun\-help\fP command with the command word from the +current input line as its argument\&. By default, \fBrun\-help\fP is an alias +for the \fBman\fP command, so this often fails when the command word is a +shell builtin or a user\-defined function\&. By redefining the \fBrun\-help\fP +alias, one can improve the on\-line help provided by the shell\&. +.PP +The \fBhelpfiles\fP utility, found in the \fBUtil\fP directory of the +distribution, is a Perl program that can be used to process the zsh manual +to produce a separate help file for each shell builtin and for many other +shell features as well\&. The autoloadable \fBrun\-help\fP function, found in +\fBFunctions/Misc\fP, searches for these helpfiles and performs several +other tests to produce the most complete help possible for the command\&. +.PP +Help files are installed by default to a subdirectory of \fB/usr/share/zsh\fP +or \fB/usr/local/share/zsh\fP\&. +.PP +To create your own help files with \fBhelpfiles\fP, choose or create a +directory where the individual command help files will reside\&. For +example, you might choose \fB~/zsh_help\fP\&. If you unpacked the zsh +distribution in your home directory, you would use the commands: +.PP +.RS +.nf +\fBmkdir ~/zsh_help +perl ~/zsh\-5\&.8\&.1\&.3\-test/Util/helpfiles ~/zsh_help\fP +.fi +.RE +.PP +The \fBHELPDIR\fP parameter tells \fBrun\-help\fP where to look for the help +files\&. When unset, it uses the default installation path\&. +To use your own set of help files, set this to the appropriate path +in one of your startup files: +.PP +.RS +.nf +\fBHELPDIR=~/zsh_help\fP +.fi +.RE +.PP +To use the \fBrun\-help\fP function, you need to add lines something +like the following to your \fB\&.zshrc\fP or equivalent startup file: +.PP +.RS +.nf +\fBunalias run\-help +autoload run\-help\fP +.fi +.RE +.PP +Note that in order for `\fBautoload run\-help\fP\&' to work, the \fBrun\-help\fP +file must be in one of the directories named in your \fBfpath\fP array (see +\fIzshparam\fP(1))\&. This should already be the case if you have a standard zsh +installation; if it is not, copy \fBFunctions/Misc/run\-help\fP to an +appropriate directory\&. +.PP +.SS "Recompiling Functions" +.PP +If you frequently edit your zsh functions, or periodically update your zsh +installation to track the latest developments, you may find that function +digests compiled with the \fBzcompile\fP builtin are frequently out of date +with respect to the function source files\&. This is not usually a problem, +because zsh always looks for the newest file when loading a function, but +it may cause slower shell startup and function loading\&. Also, if a digest +file is explicitly used as an element of \fBfpath\fP, zsh won\&'t check whether +any of its source files has changed\&. +.PP +The \fBzrecompile\fP autoloadable function, found in \fBFunctions/Misc\fP, can +be used to keep function digests up to date\&. +.PP +.PD 0 +.TP +.PD 0 +\fBzrecompile\fP [ \fB\-qt\fP ] [ \fIname\fP \&.\&.\&. ] +.TP +.PD +\fBzrecompile\fP [ \fB\-qt\fP ] \fB\-p\fP \fIarg\fP \&.\&.\&. [ \fB\-\fP\fB\-\fP \fIarg\fP \&.\&.\&. ] +This tries to find \fB*\&.zwc\fP files and automatically re\-compile them if at +least one of the original files is newer than the compiled file\&. This +works only if the names stored in the compiled files are full paths or are +relative to the directory that contains the \fB\&.zwc\fP file\&. +.RS +.PP +In the first form, each \fIname\fP is the name of a compiled file or a +directory containing \fB*\&.zwc\fP files that should be checked\&. If no +arguments are given, the directories and \fB*\&.zwc\fP files in \fBfpath\fP are +used\&. +.PP +When \fB\-t\fP is given, no compilation is performed, but a return status of +zero (true) is set if there are files that need to be re\-compiled and +non\-zero (false) otherwise\&. The \fB\-q\fP option quiets the chatty output +that describes what \fBzrecompile\fP is doing\&. +.PP +Without the \fB\-t\fP option, the return status is zero if all files that +needed re\-compilation could be compiled and non\-zero if compilation for at +least one of the files failed\&. +.PP +If the \fB\-p\fP option is given, the \fIarg\fPs are interpreted as one +or more sets of arguments for \fBzcompile\fP, separated by `\fB\-\fP\fB\-\fP\&'\&. +For example: +.PP +.RS +.nf +\fBzrecompile \-p \e + \-R ~/\&.zshrc \-\- \e + \-M ~/\&.zcompdump \-\- \e + ~/zsh/comp\&.zwc ~/zsh/Completion/*/_*\fP +.fi +.RE +.PP +This compiles \fB~/\&.zshrc\fP into \fB~/\&.zshrc\&.zwc\fP if that doesn\&'t exist or +if it is older than \fB~/\&.zshrc\fP\&. The compiled file will be marked for +reading instead of mapping\&. The same is done for \fB~/\&.zcompdump\fP and +\fB~/\&.zcompdump\&.zwc\fP, but this compiled file is marked for mapping\&. The +last line re\-creates the file \fB~/zsh/comp\&.zwc\fP if any of the files +matching the given pattern is newer than it\&. +.PP +Without the \fB\-p\fP option, \fBzrecompile\fP does not create function digests +that do not already exist, nor does it add new functions to the digest\&. +.RE +.PP +The following shell loop is an example of a method for creating function +digests for all functions in your \fBfpath\fP, assuming that you have write +permission to the directories: +.PP +.RS +.nf +\fBfor ((i=1; i <= $#fpath; ++i)); do + dir=$fpath[i] + zwc=${dir:t}\&.zwc + if [[ $dir == (\&.|\&.\&.) || $dir == (\&.|\&.\&.)/* ]]; then + continue + fi + files=($dir/*(N\-\&.)) + if [[ \-w $dir:h && \-n $files ]]; then + files=(${${(M)files%/*/*}#/}) + if ( cd $dir:h && + zrecompile \-p \-U \-z $zwc $files ); then + fpath[i]=$fpath[i]\&.zwc + fi + fi +done\fP +.fi +.RE +.PP +The \fB\-U\fP and \fB\-z\fP options are appropriate for functions in the default +zsh installation \fBfpath\fP; you may need to use different options for your +personal function directories\&. +.PP +Once the digests have been created and your \fBfpath\fP modified to refer to +them, you can keep them up to date by running \fBzrecompile\fP with no +arguments\&. +.PP +.SS "Keyboard Definition" +.PP +The large number of possible combinations of keyboards, workstations, +terminals, emulators, and window systems makes it impossible for zsh to +have built\-in key bindings for every situation\&. The \fBzkbd\fP utility, +found in \fBFunctions/Misc\fP, can help you quickly create key bindings for your +configuration\&. +.PP +Run \fBzkbd\fP either as an autoloaded function, or as a shell script: +.PP +.RS +.nf +\fBzsh \-f ~/zsh\-5\&.8\&.1\&.3\-test/Functions/Misc/zkbd\fP +.fi +.RE +.PP +When you run \fBzkbd\fP, it first asks you to enter your terminal type; if +the default it offers is correct, just press return\&. It then asks you to +press a number of different keys to determine characteristics of your +keyboard and terminal; \fBzkbd\fP warns you if it finds anything out of the +ordinary, such as a Delete key that sends neither \fB^H\fP nor \fB^?\fP\&. +.PP +The keystrokes read by \fBzkbd\fP are recorded as a definition for an +associative array named \fBkey\fP, written to a file in the subdirectory +\fB\&.zkbd\fP within either your \fBHOME\fP or \fBZDOTDIR\fP directory\&. The name +of the file is composed from the \fBTERM\fP, \fBVENDOR\fP and \fBOSTYPE\fP +parameters, joined by hyphens\&. +.PP +You may read this file into your \fB\&.zshrc\fP or another startup file with +the `\fBsource\fP\&' or `\fB\&.\fP' commands, then reference the \fBkey\fP parameter +in bindkey commands, like this: +.PP +.RS +.nf +\fBsource ${ZDOTDIR:\-$HOME}/\&.zkbd/$TERM\-$VENDOR\-$OSTYPE +[[ \-n ${key[Left]} ]] && bindkey "${key[Left]}" backward\-char +[[ \-n ${key[Right]} ]] && bindkey "${key[Right]}" forward\-char +# etc\&.\fP +.fi +.RE +.PP +Note that in order for `\fBautoload zkbd\fP\&' to work, the \fBzkdb\fP file must +be in one of the directories named in your \fBfpath\fP array (see +\fIzshparam\fP(1))\&. This should already be the case if you have a standard zsh +installation; if it is not, copy \fBFunctions/Misc/zkbd\fP to an +appropriate directory\&. +.PP +.SS "Dumping Shell State" +.PP +Occasionally you may encounter what appears to be a bug in the shell, +particularly if you are using a beta version of zsh or a development +release\&. Usually it is sufficient to send a description of the +problem to one of the zsh mailing lists (see +\fIzsh\fP(1)), but sometimes one of the zsh developers will need to recreate your +environment in order to track the problem down\&. +.PP +The script named \fBreporter\fP, found in the \fBUtil\fP directory of the +distribution, is provided for this purpose\&. (It is also possible to +\fBautoload reporter\fP, but \fBreporter\fP is not installed in \fBfpath\fP +by default\&.) This script outputs a detailed dump of the shell state, +in the form of another script that can be read with `\fBzsh \-f\fP\&' to +recreate that state\&. +.PP +To use \fBreporter\fP, read the script into your shell with the `\fB\&.\fP\&' +command and redirect the output into a file: +.PP +.RS +.nf +\fB\&. ~/zsh\-5\&.8\&.1\&.3\-test/Util/reporter > zsh\&.report\fP +.fi +.RE +.PP +You should check the \fBzsh\&.report\fP file for any sensitive information +such as passwords and delete them by hand before sending the script to the +developers\&. Also, as the output can be voluminous, it\&'s best to wait for +the developers to ask for this information before sending it\&. +.PP +You can also use \fBreporter\fP to dump only a subset of the shell state\&. +This is sometimes useful for creating startup files for the first time\&. +Most of the output from reporter is far more detailed than usually is +necessary for a startup file, but the \fBaliases\fP, \fBoptions\fP, and +\fBzstyles\fP states may be useful because they include only changes from +the defaults\&. The \fBbindings\fP state may be useful if you have created +any of your own keymaps, because \fBreporter\fP arranges to dump the keymap +creation commands as well as the bindings for every keymap\&. +.PP +As is usual with automated tools, if you create a startup file with +\fBreporter\fP, you should edit the results to remove unnecessary commands\&. +Note that if you\&'re using the new completion system, you should \fInot\fP +dump the \fBfunctions\fP state to your startup files with \fBreporter\fP; use +the \fBcompdump\fP function instead (see +\fIzshcompsys\fP(1))\&. +.PP +.PD 0 +.TP +.PD +\fBreporter\fP [ \fIstate\fP \&.\&.\&. ] +Print to standard output the indicated subset of the current shell state\&. +The \fIstate\fP arguments may be one or more of: +.RS +.PP +.PD 0 +.TP +\fBall\fP +Output everything listed below\&. +.TP +\fBaliases\fP +Output alias definitions\&. +.TP +\fBbindings\fP +Output ZLE key maps and bindings\&. +.TP +\fBcompletion\fP +Output old\-style \fBcompctl\fP commands\&. +New completion is covered by \fBfunctions\fP and \fBzstyles\fP\&. +.TP +\fBfunctions\fP +Output autoloads and function definitions\&. +.TP +\fBlimits\fP +Output \fBlimit\fP commands\&. +.TP +\fBoptions\fP +Output \fBsetopt\fP commands\&. +.TP +\fBstyles\fP +Same as \fBzstyles\fP\&. +.TP +\fBvariables\fP +Output shell parameter assignments, plus \fBexport\fP +commands for any environment variables\&. +.TP +\fBzstyles\fP +Output \fBzstyle\fP commands\&. +.PD +.PP +If the \fIstate\fP is omitted, \fBall\fP is assumed\&. +.RE +.PP +With the exception of `\fBall\fP\&', every \fIstate\fP can be abbreviated by +any prefix, even a single letter; thus \fBa\fP is the same as \fBaliases\fP, +\fBz\fP is the same as \fBzstyles\fP, etc\&. +.PP +.SS "Manipulating Hook Functions" +.PP +.PD 0 +.TP +.PD +\fBadd\-zsh\-hook\fP [ \fB\-L\fP | \fB\-dD\fP ] [ \fB\-Uzk\fP ] \fIhook\fP \fIfunction\fP +Several functions are special to the shell, as described in the section +SPECIAL FUNCTIONS, see \fIzshmisc\fP(1), +in that they are automatically called at specific points during shell execution\&. +Each has an associated array consisting of names of functions to be +called at the same point; these are so\-called `hook functions\&'\&. +The shell function \fBadd\-zsh\-hook\fP provides a simple way of adding or +removing functions from the array\&. +.RS +.PP +\fIhook\fP is one of \fBchpwd\fP, \fBperiodic\fP, \fBprecmd\fP, \fBpreexec\fP, +\fBzshaddhistory\fP, \fBzshexit\fP, or \fBzsh_directory_name\fP, +the special functions in question\&. Note that \fBzsh_directory_name\fP +is called in a different way from the other functions, but may +still be manipulated as a hook\&. +.PP +\fIfunction\fP is name of an ordinary shell function\&. If no options +are given this will be added to the array of functions to be executed +in the given context\&. +Functions are invoked in the order they were added\&. +.PP +If the option \fB\-L\fP is given, the current values for the hook arrays +are listed with \fBtypeset\fP\&. +.PP +If the option \fB\-d\fP is given, the \fIfunction\fP is removed from +the array of functions to be executed\&. +.PP +If the option \fB\-D\fP is given, the \fIfunction\fP is treated as a pattern +and any matching names of functions are removed from the array of +functions to be executed\&. +.PP +The options \fB\-U\fP, \fB\-z\fP and \fB\-k\fP are passed as arguments to +\fBautoload\fP for \fIfunction\fP\&. For functions contributed with zsh, the +options \fB\-Uz\fP are appropriate\&. +.RE +.TP +\fBadd\-zle\-hook\-widget\fP [ \fB\-L\fP | \fB\-dD\fP ] [ \fB\-Uzk\fP ] \fIhook\fP \fIwidgetname\fP +Several widget names are special to the line editor, as described in the section +Special Widgets, see \fIzshzle\fP(1), +in that they are automatically called at specific points during editing\&. +Unlike function hooks, these do not use a predefined array of other names +to call at the same point; the shell function \fBadd\-zle\-hook\-widget\fP +maintains a similar array and arranges for the special widget to invoke +those additional widgets\&. +.RS +.PP +\fIhook\fP is one of \fBisearch\-exit\fP, \fBisearch\-update\fP, +\fBline\-pre\-redraw\fP, \fBline\-init\fP, \fBline\-finish\fP, \fBhistory\-line\-set\fP, +or \fBkeymap\-select\fP, corresponding to each of the special widgets +\fBzle\-isearch\-exit\fP, etc\&. The special widget names are also accepted +as the \fIhook\fP argument\&. +.PP +\fIwidgetname\fP is the name of a ZLE widget\&. If no options are given this +is added to the array of widgets to be invoked in the given hook context\&. +Widgets are invoked in the order they were added, with +.RS +.nf +\fB\fBzle \fP\fIwidgetname\fP\fB \-Nw \-f "nolast" \-\- "$@"\fP\fP +.fi +.RE +.PP +Note that this means that the `\fBWIDGET\fP\&' special parameter tracks the +\fIwidgetname\fP when the widget function is called, rather than tracking +the name of the corresponding special hook widget\&. +.PP +If the option \fB\-d\fP is given, the \fIwidgetname\fP is removed from +the array of widgets to be executed\&. +.PP +If the option \fB\-D\fP is given, the \fIwidgetname\fP is treated as a pattern +and any matching names of widgets are removed from the array\&. +.PP +If \fIwidgetname\fP does not name an existing widget when added to the +array, it is assumed that a shell function also named \fIwidgetname\fP is +meant to provide the implementation of the widget\&. This name is therefore +marked for autoloading, and the options \fB\-U\fP, \fB\-z\fP and \fB\-k\fP are +passed as arguments to \fBautoload\fP as with \fBadd\-zsh\-hook\fP\&. The +widget is also created with `\fBzle \-N \fP\fIwidgetname\fP\&' to cause the +corresponding function to be loaded the first time the hook is called\&. +.PP +The arrays of \fIwidgetname\fP are currently maintained in \fBzstyle\fP +contexts, one for each \fIhook\fP context, with a style of `\fBwidgets\fP\&'\&. +If the \fB\-L\fP option is given, this set of styles is listed with +`\fBzstyle \-L\fP\&'\&. This implementation may change, and the special widgets +that refer to the styles are created only if \fBadd\-zle\-hook\-widget\fP is +called to add at least one widget, so if this function is used for any +hooks, then all hooks should be managed only via this function\&. +.RE +.PP +.SH "REMEMBERING RECENT DIRECTORIES" +.PP +The function \fBcdr\fP allows you to change the working directory to a +previous working directory from a list maintained automatically\&. It is +similar in concept to the directory stack controlled by the \fBpushd\fP, +\fBpopd\fP and \fBdirs\fP builtins, but is more configurable, and as it stores +all entries in files it is maintained across sessions and (by default) +between terminal emulators in the current session\&. Duplicates are +automatically removed, so that the list reflects the single most recent +use of each directory\&. +.PP +Note that the \fBpushd\fP directory stack is not actually modified or used +by \fBcdr\fP unless you configure it to do so as described in the +configuration section below\&. +.PP +.SS "Installation" +.PP +The system works by means of a hook function that is called every time the +directory changes\&. To install the system, autoload the required functions +and use the \fBadd\-zsh\-hook\fP function described above: +.PP +.RS +.nf +\fBautoload \-Uz chpwd_recent_dirs cdr add\-zsh\-hook +add\-zsh\-hook chpwd chpwd_recent_dirs\fP +.fi +.RE +.PP +Now every time you change directly interactively, no matter which +command you use, the directory to which you change will be remembered +in most\-recent\-first order\&. +.PP +.SS "Use" +.PP +All direct user interaction is via the \fBcdr\fP function\&. +.PP +The argument to cdr is a number \fIN\fP corresponding to the \fIN\fPth most +recently changed\-to directory\&. 1 is the immediately preceding directory; +the current directory is remembered but is not offered as a destination\&. +Note that if you have multiple windows open 1 may refer to a directory +changed to in another window; you can avoid this by having per\-terminal +files for storing directory as described for the +\fBrecent\-dirs\-file\fP style below\&. +.PP +If you set the \fBrecent\-dirs\-default\fP style described below \fBcdr\fP +will behave the same as \fBcd\fP if given a non\-numeric argument, or more +than one argument\&. The recent directory list is updated just the same +however you change directory\&. +.PP +If the argument is omitted, 1 is assumed\&. This is similar to \fBpushd\fP\&'s +behaviour of swapping the two most recent directories on the stack\&. +.PP +Completion for the argument to \fBcdr\fP is available if compinit has been +run; menu selection is recommended, using: +.PP +.RS +.nf +\fBzstyle \&':completion:*:*:cdr:*:*' menu selection\fP +.fi +.RE +.PP +to allow you to cycle through recent directories; the order is preserved, +so the first choice is the most recent directory before the current one\&. +The verbose style is also recommended to ensure the directory is shown; this +style is on by default so no action is required unless you have changed it\&. +.PP +.SS "Options" +.PP +The behaviour of \fBcdr\fP may be modified by the following options\&. +.PP +.PD 0 +.TP +.PD +\fB\-l\fP +lists the numbers and the corresponding directories in +abbreviated form (i\&.e\&. with \fB~\fP substitution reapplied), one per line\&. +The directories here are not quoted (this would only be an issue if a +directory name contained a newline)\&. This is used by the completion +system\&. +.TP +\fB\-r\fP +sets the variable \fBreply\fP to the current set of directories\&. Nothing +is printed and the directory is not changed\&. +.TP +\fB\-e\fP +allows you to edit the list of directories, one per line\&. The +list can be edited to any extent you like; no sanity checking is +performed\&. Completion is available\&. No quoting is necessary (except for +newlines, where I have in any case no sympathy); directories are in +unabbreviated form and contain an absolute path, i\&.e\&. they start with \fB/\fP\&. +Usually the first entry should be left as the current directory\&. +.TP +\fB\-p \&'\fP\fIpattern\fP\fB'\fP +Prunes any items in the directory list that match the given extended glob +pattern; the pattern needs to be quoted from immediate expansion on the +command line\&. The pattern is matched against each completely expanded +file name in the list; the full string must match, so wildcards at the +end (e\&.g\&. \fB\&'*removeme*'\fP) are needed to remove entries with a given +substring\&. +.RS +.PP +If output is to a terminal, then the function will print the new list +after pruning and prompt for confirmation by the user\&. This output and +confirmation step can be skipped by using \fB\-P\fP instead of \fB\-p\fP\&. +.RE +.PP +.SS "Configuration" +.PP +Configuration is by means of the styles mechanism that should be familiar +from completion; if not, see the description of the \fBzstyle\fP command in +see \fIzshmodules\fP(1)\&. The context for setting styles +should be \fB\&':chpwd:*'\fP in case the meaning of the context is extended in +future, for example: +.PP +.RS +.nf +\fBzstyle \&':chpwd:*' recent\-dirs\-max 0\fP +.fi +.RE +.PP +sets the value of the \fBrecent\-dirs\-max\fP style to 0\&. In practice the +style name is specific enough that a context of \&'*' should be fine\&. +.PP +An exception is \fBrecent\-dirs\-insert\fP, which is used exclusively by the +completion system and so has the usual completion system context +(\fB\&':completion:*'\fP if nothing more specific is needed), though again +\fB\&'*'\fP should be fine in practice\&. +.PP +.PD 0 +.TP +.PD +\fBrecent\-dirs\-default\fP +If true, and the command is expecting a recent directory index, and +either there is more than one argument or the argument is not an +integer, then fall through to "cd"\&. This allows the lazy to use only +one command for directory changing\&. Completion recognises this, too; +see recent\-dirs\-insert for how to control completion when this option +is in use\&. +.TP +\fBrecent\-dirs\-file\fP +The file where the list of directories is saved\&. The default +is \fB${ZDOTDIR:\-$HOME}/\&.chpwd\-recent\-dirs\fP, i\&.e\&. this is in your +home directory unless you have set the variable \fBZDOTDIR\fP to point +somewhere else\&. Directory names are saved in \fB$\&'\fP\fI\&.\&.\&.\fP\fB'\fP quoted +form, so each line in the file can be supplied directly to the shell as an +argument\&. +.RS +.PP +The value of this style may be an array\&. In this case, the first +file in the list will always be used for saving directories while any +other files are left untouched\&. When reading the recent directory +list, if there are fewer than the maximum number of entries in the +first file, the contents of later files in the array will be appended +with duplicates removed from the list shown\&. The contents of the two +files are not sorted together, i\&.e\&. all the entries in the first file +are shown first\&. The special value \fB+\fP can appear in the list to +indicate the default file should be read at that point\&. This allows +effects like the following: +.PP +.RS +.nf +\fBzstyle \&':chpwd:*' recent\-dirs\-file \e +~/\&.chpwd\-recent\-dirs\-${TTY##*/} +\fP +.fi +.RE +.PP +Recent directories are read from a file numbered according to +the terminal\&. If there are insufficient entries the list +is supplemented from the default file\&. +.PP +It is possible to use \fBzstyle \-e\fP to make the directory configurable +at run time: +.PP +.RS +.nf +\fBzstyle \-e \&':chpwd:*' recent\-dirs\-file pick\-recent\-dirs\-file +pick\-recent\-dirs\-file() { + if [[ $PWD = ~/text/writing(|/*) ]]; then + reply=(~/\&.chpwd\-recent\-dirs\-writing) + else + reply=(+) + fi +}\fP +.fi +.RE +.PP +In this example, if the current directory is \fB~/text/writing\fP or a +directory under it, then use a special file for saving recent +directories, else use the default\&. +.RE +.TP +\fBrecent\-dirs\-insert\fP +Used by completion\&. If \fBrecent\-dirs\-default\fP is true, then setting +this to \fBtrue\fP causes the actual directory, rather than its index, to +be inserted on the command line; this has the same effect as using +the corresponding index, but makes the history clearer and the line +easier to edit\&. With this setting, if part of an argument was +already typed, normal directory completion rather than recent +directory completion is done; this is because recent directory +completion is expected to be done by cycling through entries menu +fashion\&. +.RS +.PP +If the value of the style is \fBalways\fP, then only recent directories will +be completed; in that case, use the \fBcd\fP command when you want to +complete other directories\&. +.PP +If the value is \fBfallback\fP, recent directories will be tried first, then +normal directory completion is performed if recent directory completion +failed to find a match\&. +.PP +Finally, if the value is \fBboth\fP then both sets of completions are +presented; the usual tag mechanism can be used to distinguish results, with +recent directories tagged as \fBrecent\-dirs\fP\&. Note that the recent +directories inserted are abbreviated with directory names where appropriate\&. +.RE +.TP +\fBrecent\-dirs\-max\fP +The maximum number of directories to save to the file\&. If +this is zero or negative there is no maximum\&. The default is 20\&. +Note this includes the current directory, which isn\&'t offered, +so the highest number of directories you will be offered +is one less than the maximum\&. +.TP +\fBrecent\-dirs\-prune\fP +This style is an array determining what directories should (or should +not) be added to the recent list\&. Elements of the array can include: +.RS +.PP +.PD 0 +.TP +.PD +\fBparent\fP +Prune parents (more accurately, ancestors) from the recent list\&. +If present, changing directly down by any number of directories +causes the current directory to be overwritten\&. For example, +changing from ~pws to ~pws/some/other/dir causes ~pws not to be +left on the recent directory stack\&. This only applies to direct +changes to descendant directories; earlier directories on the +list are not pruned\&. For example, changing from ~pws/yet/another +to ~pws/some/other/dir does not cause ~pws to be pruned\&. +.TP +\fBpattern:\fP\fIpattern\fP +Gives a zsh pattern for directories that should not be +added to the recent list (if not already there)\&. This element +can be repeated to add different patterns\&. For example, +\fB\&'pattern:/tmp(|/*)'\fP stops \fB/tmp\fP or its descendants +from being added\&. The \fBEXTENDED_GLOB\fP option is always turned on +for these patterns\&. +.RE +.TP +\fBrecent\-dirs\-pushd\fP +If set to true, \fBcdr\fP will use \fBpushd\fP instead of \fBcd\fP to change the +directory, so the directory is saved on the directory stack\&. As the +directory stack is completely separate from the list of files saved +by the mechanism used in this file there is no obvious reason to do +this\&. +.PP +.SS "Use with dynamic directory naming" +.PP +It is possible to refer to recent directories using the dynamic directory +name syntax by using the supplied function \fBzsh_directory_name_cdr\fP +a hook: +.PP +.RS +.nf +\fBautoload \-Uz add\-zsh\-hook +add\-zsh\-hook \-Uz zsh_directory_name zsh_directory_name_cdr\fP +.fi +.RE +.PP +When this is done, \fB~[1]\fP will refer to the most recent +directory other than $PWD, and so on\&. Completion after \fB~[\fP\fI\&.\&.\&.\fP +also works\&. +.PP +.SS "Details of directory handling" +.PP +This section is for the curious or confused; most users will not +need to know this information\&. +.PP +Recent directories are saved to a file immediately and hence are +preserved across sessions\&. Note currently no file locking is applied: +the list is updated immediately on interactive commands and nowhere else +(unlike history), and it is assumed you are only going to change +directory in one window at once\&. This is not safe on shared accounts, +but in any case the system has limited utility when someone else is +changing to a different set of directories behind your back\&. +.PP +To make this a little safer, only directory changes instituted from the +command line, either directly or indirectly through shell function calls +(but not through subshells, evals, traps, completion functions and the +like) are saved\&. Shell functions should use \fBcd \-q\fP or \fBpushd \-q\fP to +avoid side effects if the change to the directory is to be invisible at the +command line\&. See the contents of the function \fBchpwd_recent_dirs\fP for +more details\&. +.PP +.SH "ABBREVIATED DYNAMIC REFERENCES TO DIRECTORIES" +.PP +The dynamic directory naming system is described in the subsection +\fIDynamic named directories\fP of +the section \fIFilename Expansion\fP in \fIzshexpn\fP(1)\&. In this, a reference to +\fB~[\fP\fI\&.\&.\&.\fP\fB]\fP is expanded by a function found by the hooks +mechanism\&. +.PP +The contributed function \fBzsh_directory_name_generic\fP provides a +system allowing the user to refer to directories with only a limited +amount of new code\&. It supports all three of the standard interfaces +for directory naming: converting from a name to a directory, converting +in the reverse direction to find a short name, and completion of names\&. +.PP +The main feature of this function is a path\-like syntax, +combining abbreviations at multiple levels separated by ":"\&. +As an example, ~[g:p:s] might specify: +.PD 0 +.TP +.PD +\fBg\fP +The top level directory for your git area\&. This first component +has to match, or the function will return indicating another +directory name hook function should be tried\&. +.TP +\fBp\fP +The name of a project within your git area\&. +.TP +\fBs\fP +The source area within that project\&. +This allows you to collapse references to long hierarchies to a very +compact form, particularly if the hierarchies are similar across different +areas of the disk\&. +.PP +Name components may be completed: if a description is shown at the top +of the list of completions, it includes the path to which previous +components expand, while the description for an individual completion +shows the path segment it would add\&. No additional configuration is +needed for this as the completion system is aware of the dynamic +directory name mechanism\&. +.PP +.SS "Usage" +.PP +To use the function, first define a wrapper function for your specific +case\&. We\&'ll assume it's to be autoloaded\&. This can have any name but +we\&'ll refer to it as zdn_mywrapper\&. This wrapper function will define +various variables and then call this function with the same arguments +that the wrapper function gets\&. This configuration is described below\&. +.PP +Then arrange for the wrapper to be run as a zsh_directory_name hook: +.PP +.RS +.nf +\fBautoload \-Uz add\-zsh\-hook zsh_directory_name_generic zdn_mywrapper +add\-zsh\-hook \-U zsh_directory_name zdn_mywrapper\fP +.fi +.RE +.PP +.SS "Configuration" +.PP +The wrapper function should define a local associative array zdn_top\&. +Alternatively, this can be set with a style called \fBmapping\fP\&. The +context for the style is \fB:zdn:\fP\fIwrapper\-name\fP where +\fIwrapper\-name\fP is the function calling zsh_directory_name_generic; +for example: +.PP +.RS +.nf +\fBzstyle :zdn:zdn_mywrapper: mapping zdn_mywrapper_top\fP +.fi +.RE +.PP +The keys in this associative array correspond to the first component of +the name\&. The values are matching directories\&. They may have an +optional suffix with a slash followed by a colon and the name of a +variable in the same format to give the next component\&. (The slash +before the colon is to disambiguate the case where a colon is needed in +the path for a drive\&. There is otherwise no syntax for escaping this, +so path components whose names start with a colon are not supported\&.) A +special component \fB:default:\fP specifies a variable in the form +\fB/:\fP\fIvar\fP (the path section is ignored and so is usually empty) +that will be used for the next component if no variable is given for the +path\&. Variables referred to within \fBzdn_top\fP have the same format as +\fBzdn_top\fP itself, but contain relative paths\&. +.PP +For example, +.PP +.RS +.nf +\fBlocal \-A zdn_top=( + g ~/git + ga ~/alternate/git + gs /scratch/$USER/git/:second2 + :default: /:second1 +)\fP +.fi +.RE +.PP +This specifies the behaviour of a directory referred to as \fB~[g:\&.\&.\&.]\fP +or \fB~[ga:\&.\&.\&.]\fP or \fB~[gs:\&.\&.\&.]\fP\&. Later path components are optional; +in that case \fB~[g]\fP expands to \fB~/git\fP, and so on\&. \fBgs\fP expands +to \fB/scratch/$USER/git\fP and uses the associative array \fBsecond2\fP to +match the second component; \fBg\fP and \fBga\fP use the associative array +\fBsecond1\fP to match the second component\&. +.PP +When expanding a name to a directory, if the first component is not \fBg\fP or +\fBga\fP or \fBgs\fP, it is not an error; the function simply returns 1 so that a +later hook function can be tried\&. However, matching the first component +commits the function, so if a later component does not match, an error +is printed (though this still does not stop later hooks from being +executed)\&. +.PP +For components after the first, a relative path is expected, but note that +multiple levels may still appear\&. Here is an example of \fBsecond1\fP: +.PP +.RS +.nf +\fBlocal \-A second1=( + p myproject + s somproject + os otherproject/subproject/:third +)\fP +.fi +.RE +.PP +The path as found from \fBzdn_top\fP is extended with the matching +directory, so \fB~[g:p]\fP becomes \fB~/git/myproject\fP\&. The slash between +is added automatically (it\&'s not possible to have a later component +modify the name of a directory already matched)\&. Only \fBos\fP specifies +a variable for a third component, and there\&'s no \fB:default:\fP, so it's +an error to use a name like \fB~[g:p:x]\fP or \fB~[ga:s:y]\fP because +there\&'s nowhere to look up the \fBx\fP or \fBy\fP\&. +.PP +The associative arrays need to be visible within this function; the +generic function therefore uses internal variable names beginning +\fB_zdn_\fP in order to avoid clashes\&. Note that the variable \fBreply\fP +needs to be passed back to the shell, so should not be local in the +calling function\&. +.PP +The function does not test whether directories assembled by component +actually exist; this allows the system to work across automounted +file systems\&. The error from the command trying to use a non\-existent +directory should be sufficient to indicate the problem\&. +.PP +.SS "Complete example" +.PP +Here is a full fictitious but usable autoloadable definition of the +example function defined by the code above\&. So \fB~[gs:p:s]\fP expands +to \fB/scratch/$USER/git/myscratchproject/top/srcdir\fP (with \fB$USER\fP +also expanded)\&. +.PP +.RS +.nf +\fBlocal \-A zdn_top=( + g ~/git + ga ~/alternate/git + gs /scratch/$USER/git/:second2 + :default: /:second1 +) + +local \-A second1=( + p myproject + s somproject + os otherproject/subproject/:third +) + +local \-A second2=( + p myscratchproject + s somescratchproject +) + +local \-A third=( + s top/srcdir + d top/documentation +) + +# autoload not needed if you did this at initialisation\&.\&.\&. +autoload \-Uz zsh_directory_name_generic +zsh_directory_name_generic "$@\fP +.fi +.RE +.PP +It is also possible to use global associative arrays, suitably named, +and set the style for the context of your wrapper function to +refer to this\&. Then your set up code would contain the following: +.PP +.RS +.nf +\fBtypeset \-A zdn_mywrapper_top=(\&.\&.\&.) +# \&.\&.\&. and so on for other associative arrays \&.\&.\&. +zstyle \&':zdn:zdn_mywrapper:' mapping zdn_mywrapper_top +autoload \-Uz add\-zsh\-hook zsh_directory_name_generic zdn_mywrapper +add\-zsh\-hook \-U zsh_directory_name zdn_mywrapper\fP +.fi +.RE +.PP +and the function \fBzdn_mywrapper\fP would contain only the following: +.PP +.RS +.nf +\fBzsh_directory_name_generic "$@"\fP +.fi +.RE +.PP +.SH "GATHERING INFORMATION FROM VERSION CONTROL SYSTEMS" +.PP +In a lot of cases, it is nice to automatically retrieve information from +version control systems (VCSs), such as subversion, CVS or git, to be able +to provide it to the user; possibly in the user\&'s prompt\&. So that you can +instantly tell which branch you are currently on, for example\&. +.PP +In order to do that, you may use the \fBvcs_info\fP function\&. +.PP +The following VCSs are supported, showing the abbreviated name by which +they are referred to within the system: +.PD 0 +.TP +Bazaar (\fBbzr\fP) +\fBhttps://bazaar\&.canonical\&.com/\fP +.TP +Codeville (\fBcdv\fP) +\fBhttp://freecode\&.com/projects/codeville/\fP +.TP +Concurrent Versioning System (\fBcvs\fP) +\fBhttps://www\&.nongnu\&.org/cvs/\fP +.TP +Darcs (\fBdarcs\fP) +\fBhttp://darcs\&.net/\fP +.TP +Fossil (\fBfossil\fP) +\fBhttps://fossil\-scm\&.org/\fP +.TP +Git (\fBgit\fP) +\fBhttps://git\-scm\&.com/\fP +.TP +GNU arch (\fBtla\fP) +\fBhttps://www\&.gnu\&.org/software/gnu\-arch/\fP +.TP +Mercurial (\fBhg\fP) +\fBhttps://www\&.mercurial\-scm\&.org/\fP +.TP +Monotone (\fBmtn\fP) +\fBhttps://monotone\&.ca/\fP +.TP +Perforce (\fBp4\fP) +\fBhttps://www\&.perforce\&.com/\fP +.TP +Subversion (\fBsvn\fP) +\fBhttps://subversion\&.apache\&.org/\fP +.TP +SVK (\fBsvk\fP) +\fBhttps://svk\&.bestpractical\&.com/\fP +.PD +.PP +There is also support for the patch management system \fBquilt\fP +(\fBhttps://savannah\&.nongnu\&.org/projects/quilt\fP)\&. See +\fBQuilt Support\fP +below for details\&. +.PP +To load \fBvcs_info\fP: +.PP +.RS +.nf +\fBautoload \-Uz vcs_info\fP +.fi +.RE +.PP +It can be used in any existing prompt, because it does not require any +specific \fB$psvar\fP entries to be available\&. +.PP +.PP +.SS "Quickstart" +.PP +To get this feature working quickly (including colors), you can do the +following (assuming, you loaded \fBvcs_info\fP properly \- see above): +.PP +.RS +.nf +\fBzstyle \&':vcs_info:*' actionformats \e + \&'%F{5}(%f%s%F{5})%F{3}\-%F{5}[%F{2}%b%F{3}|%F{1}%a%F{5}]%f ' +zstyle \&':vcs_info:*' formats \e + \&'%F{5}(%f%s%F{5})%F{3}\-%F{5}[%F{2}%b%F{5}]%f ' +zstyle \&':vcs_info:(sv[nk]|bzr):*' branchformat '%b%F{1}:%F{3}%r' +precmd () { vcs_info } +PS1=\&'%F{5}[%F{2}%n%F{5}] %F{3}%3~ ${vcs_info_msg_0_}%f%# '\fP +.fi +.RE +.PP +Obviously, the last two lines are there for demonstration\&. You need to +call \fBvcs_info\fP from your \fBprecmd\fP function\&. Once that is done you need +a \fIsingle quoted\fP \fB\&'${vcs_info_msg_0_}'\fP in your prompt\&. +.PP +To be able to use \fB\&'${vcs_info_msg_0_}'\fP directly in your prompt like +this, you will need to have the \fBPROMPT_SUBST\fP option enabled\&. +.PP +Now call the \fBvcs_info_printsys\fP utility from the command line: +.PP +.RS +.nf +\fB% vcs_info_printsys +## list of supported version control backends: +## disabled systems are prefixed by a hash sign (#) +bzr +cdv +cvs +darcs +fossil +git +hg +mtn +p4 +svk +svn +tla +## flavours (cannot be used in the enable or disable styles; they +## are enabled and disabled with their master [git\-svn \-> git]) +## they *can* be used in contexts: \&':vcs_info:git\-svn:*'\&. +git\-p4 +git\-svn +hg\-git +hg\-hgsubversion +hg\-hgsvn\fP +.fi +.RE +.PP +You may not want all of these because there is no point in running the +code to detect systems you do not use\&. So there is a way to disable +some backends altogether: +.PP +.RS +.nf +\fBzstyle \&':vcs_info:*' disable bzr cdv darcs mtn svk tla\fP +.fi +.RE +.PP +You may also pick a few from that list and enable only those: +.PP +.RS +.nf +\fBzstyle \&':vcs_info:*' enable git cvs svn\fP +.fi +.RE +.PP +If you rerun \fBvcs_info_printsys\fP after one of these commands, you will +see the backends listed in the \fBdisable\fP style (or backends not in the +\fBenable\fP style \- if you used that) marked as disabled by a hash sign\&. +That means the detection of these systems is skipped \fIcompletely\fP\&. No +wasted time there\&. +.PP +.SS "Configuration" +.PP +The \fBvcs_info\fP feature can be configured via \fBzstyle\fP\&. +.PP +First, the context in which we are working: +.RS +.nf +\fB:vcs_info:\fIvcs\-string\fP:\fIuser\-context\fP:\fIrepo\-root\-name\fP\fP +.fi +.RE +.PP +.PD 0 +.TP +.PD +\fIvcs\-string\fP +is one of: \fBgit\fP, \fBgit\-svn\fP, \fBgit\-p4\fP, \fBhg\fP, \fBhg\-git\fP, +\fBhg\-hgsubversion\fP, \fBhg\-hgsvn\fP, \fBdarcs\fP, \fBbzr\fP, \fBcdv\fP, \fBmtn\fP, +\fBsvn\fP, \fBcvs\fP, \fBsvk\fP, \fBtla\fP, \fBp4\fP or \fBfossil\fP\&. +This is followed by `\fB\&.quilt\-\fP\fIquilt\-mode\fP\&' in Quilt mode +(see \fBQuilt Support\fP for details) +and by `\fB+\fP\fIhook\-name\fP\&' while hooks are active +(see \fBHooks in vcs_info\fP for details)\&. +.RS +.PP + +Currently, hooks in quilt mode don\&'t add the `\fB\&.quilt\-\fP\fIquilt\-mode\fP' information\&. +This may change in the future\&. +.RE +.TP +\fIuser\-context\fP +is a freely configurable string, assignable by +the user as the first argument to \fBvcs_info\fP (see its description +below)\&. +.TP +\fIrepo\-root\-name\fP +is the name of a repository in which you want a +style to match\&. So, if you want a setting specific to \fB/usr/src/zsh\fP, +with that being a CVS checkout, you can set \fIrepo\-root\-name\fP to +\fBzsh\fP to make it so\&. +.PP +There are three special values for \fIvcs\-string\fP: The first is named +\fB\-init\-\fP, that is in effect as long as there was no decision what VCS +backend to use\&. The second is \fB\-preinit\-\fP; it is used \fIbefore\fP +\fBvcs_info\fP is run, when initializing the data exporting variables\&. The +third special value is \fBformats\fP and is used by the \fBvcs_info_lastmsg\fP +for looking up its styles\&. +.PP +The initial value of \fIrepo\-root\-name\fP is \fB\-all\-\fP and it is replaced +with the actual name, as soon as it is known\&. Only use this part of the +context for defining the \fBformats\fP, \fBactionformats\fP or +\fBbranchformat\fP styles, as it is guaranteed that \fIrepo\-root\-name\fP is +set up correctly for these only\&. For all other styles, just use \fB\&'*'\fP +instead\&. +.PP +There are two pre\-defined values for \fIuser\-context\fP: +.PD 0 +.TP +\fBdefault\fP +the one used if none is specified +.TP +\fBcommand\fP +used by vcs_info_lastmsg to lookup its styles +.PD +.PP +You can of course use \fB\&':vcs_info:*'\fP to match all VCSs in all +user\-contexts at once\&. +.PP +This is a description of all styles that are looked up\&. +.PP +.PD 0 +.TP +.PD +\fBformats\fP +A list of formats, used when actionformats is not used +(which is most of the time)\&. +.TP +\fBactionformats\fP +A list of formats, used if there is a special +action going on in your current repository; like an interactive rebase or +a merge conflict\&. +.TP +\fBbranchformat\fP +Some backends replace \fB%b\fP in the formats and +actionformats styles above, not only by a branch name but also by a +revision number\&. This style lets you modify how that string should look\&. +.TP +\fBnvcsformats\fP +These "formats" are set when we didn\&'t detect a version control system +for the current directory or \fBvcs_info\fP was disabled\&. This is useful if +you want \fBvcs_info\fP to completely take over the generation of your +prompt\&. You would do something like \fBPS1=\&'${vcs_info_msg_0_}'\fP to +accomplish that\&. +.TP +\fBhgrevformat\fP +\fBhg\fP uses both a hash and a revision number to reference a specific +changeset in a repository\&. With this style you can format the revision +string (see \fBbranchformat\fP) to include either or both\&. It\&'s only +useful when \fBget\-revision\fP is true\&. Note, the full 40\-character revision id +is not available (except when using the \fBuse\-simple\fP option) because +executing hg more than once per prompt is too slow; you may customize this +behavior using hooks\&. +.TP +\fBmax\-exports\fP +Defines the maximum number of +\fBvcs_info_msg_*_\fP variables \fBvcs_info\fP will set\&. +.TP +\fBenable\fP +A list of backends you want to use\&. Checked in the \fB\-init\-\fP context\&. If +this list contains an item called \fBNONE\fP no backend is used at all and +\fBvcs_info\fP will do nothing\&. If this list contains \fBALL\fP, \fBvcs_info\fP +will use all known backends\&. Only with \fBALL\fP in \fBenable\fP will the +\fBdisable\fP style have any effect\&. \fBALL\fP and \fBNONE\fP are case insensitive\&. +.TP +\fBdisable\fP +A list of VCSs you don\&'t want \fBvcs_info\fP to test for +repositories (checked in the \fB\-init\-\fP context, too)\&. Only used if +\fBenable\fP contains \fBALL\fP\&. +.TP +\fBdisable\-patterns\fP +A list of patterns that are checked against \fB$PWD\fP\&. If a pattern +matches, \fBvcs_info\fP will be disabled\&. This style is checked in the +\fB:vcs_info:\-init\-:*:\-all\-\fP context\&. +.RS +.PP +Say, \fB~/\&.zsh\fP is a directory under version control, in which you do +not want \fBvcs_info\fP to be active, do: +.RS +.nf +\fBzstyle \&':vcs_info:*' disable\-patterns "${(b)HOME}/\&.zsh(|/*)"\fP +.fi +.RE +.RE +.TP +\fBuse\-quilt\fP +If enabled, the \fBquilt\fP support code is active in `addon\&' mode\&. +See \fBQuilt Support\fP for details\&. +.TP +\fBquilt\-standalone\fP +If enabled, `standalone\&' mode detection is attempted if no VCS is active +in a given directory\&. See \fBQuilt Support\fP for details\&. +.TP +\fBquilt\-patch\-dir\fP +Overwrite the value of the \fB$QUILT_PATCHES\fP environment variable\&. See +\fBQuilt Support\fP for details\&. +.TP +\fBquiltcommand\fP +When \fBquilt\fP itself is called in quilt support, the value of this style +is used as the command name\&. +.TP +\fBcheck\-for\-changes\fP +If enabled, this style causes the \fB%c\fP and \fB%u\fP format escapes to show +when the working directory has uncommitted changes\&. The strings displayed by +these escapes can be controlled via the \fBstagedstr\fP and \fBunstagedstr\fP +styles\&. The only backends that currently support this option are \fBgit\fP, +\fBhg\fP, and \fBbzr\fP (the latter two only support unstaged)\&. +.RS +.PP +For this style to be evaluated with the \fBhg\fP backend, the \fBget\-revision\fP +style needs to be set and the \fBuse\-simple\fP style needs to be unset\&. The +latter is the default; the former is not\&. +.PP +With the \fBbzr\fP backend, \fIlightweight checkouts\fP only honor this style if +the \fBuse\-server\fP style is set\&. +.PP +Note, the actions taken if this style is enabled are potentially expensive +(read: they may be slow, depending on how big the current repository is)\&. +Therefore, it is disabled by default\&. +.RE +.TP +\fBcheck\-for\-staged\-changes\fP +This style is like \fBcheck\-for\-changes\fP, but it never checks the worktree +files, only the metadata in the \fB\&.${vcs}\fP dir\&. Therefore, +this style initializes only the \fB%c\fP escape (with \fBstagedstr\fP) but +not the \fB%u\fP escape\&. This style is faster than \fBcheck\-for\-changes\fP\&. +.RS +.PP +In the \fBgit\fP backend, this style checks for changes in the index\&. +Other backends do not currently implement this style\&. +.PP +This style is disabled by default\&. +.RE +.TP +\fBstagedstr\fP +This string will be used in the \fB%c\fP escape if there are staged changes in +the repository\&. +.TP +\fBunstagedstr\fP +This string will be used in the \fB%u\fP escape if there are unstaged changes +in the repository\&. +.TP +\fBcommand\fP +This style causes \fBvcs_info\fP to use the supplied string as the command +to use as the VCS\&'s binary\&. Note, that setting this in '\fB:vcs_info:*\fP' is +not a good idea\&. +.RS +.PP +If the value of this style is empty (which is the default), the used binary +name is the name of the backend in use (e\&.g\&. \fBsvn\fP is used in an \fBsvn\fP +repository)\&. +.PP +The \fBrepo\-root\-name\fP part in the context is always the default \fB\-all\-\fP +when this style is looked up\&. +.PP +For example, this style can be used to use binaries from non\-default +installation directories\&. Assume, \fBgit\fP is installed in /usr/bin but +your sysadmin installed a newer version in /usr/local/bin\&. Instead of +changing the order of your \fB$PATH\fP parameter, you can do this: +.RS +.nf +\fBzstyle \&':vcs_info:git:*:\-all\-' command /usr/local/bin/git\fP +.fi +.RE +.RE +.TP +\fBuse\-server\fP +This is used by the Perforce backend (\fBp4\fP) to decide if it should +contact the Perforce server to find out if a directory is managed +by Perforce\&. This is the only reliable way of doing this, but runs +the risk of a delay if the server name cannot be found\&. If the +server (more specifically, the \fIhost\fP\fB:\fP\fIport\fP pair describing the +server) cannot be contacted, its name is put into the associative array +\fBvcs_info_p4_dead_servers\fP and is not contacted again during the session +until it is removed by hand\&. If you do not set this style, the \fBp4\fP +backend is only usable if you have set the environment variable +\fBP4CONFIG\fP to a file name and have corresponding files in the root +directories of each Perforce client\&. See comments in the function +\fBVCS_INFO_detect_p4\fP for more detail\&. +.RS +.PP +The Bazaar backend (\fBbzr\fP) uses this to permit contacting the server +about lightweight checkouts, see the \fBcheck\-for\-changes\fP style\&. +.RE +.TP +\fBuse\-simple\fP +If there are two different ways of gathering +information, you can select the simpler one by setting this style to true; +the default is to use the not\-that\-simple code, which is potentially a lot +slower but might be more accurate in all possible cases\&. This style is +used by the \fBbzr\fP, \fBhg\fP, and \fBgit\fP backends\&. In the case of \fBhg\fP it will invoke +the external hexdump program to parse the binary dirstate cache file; this +method will not return the local revision number\&. +.TP +\fBget\-revision\fP +If set to true, vcs_info goes the extra mile to figure out the revision of +a repository\&'s work tree (currently for the \fBgit\fP and \fBhg\fP backends, +where this kind of information is not always vital)\&. For \fBgit\fP, the +hash value of the currently checked out commit is available via the \fB%i\fP +expansion\&. With \fBhg\fP, the local revision number and the corresponding +global hash are available via \fB%i\fP\&. +.TP +\fBget\-mq\fP +If set to true, the \fBhg\fP backend will look for a Mercurial Queue (\fBmq\fP) +patch directory\&. Information will be available via the `\fB%m\fP\&' replacement\&. +.TP +\fBget\-bookmarks\fP +If set to true, the \fBhg\fP backend will try to get a list of current +bookmarks\&. They will be available via the `\fB%m\fP\&' replacement\&. +.RS +.PP +The default is to generate a comma\-separated list of all bookmark names +that refer to the currently checked out revision\&. If a bookmark is active, +its name is suffixed an asterisk and placed first in the list\&. +.RE +.TP +\fBuse\-prompt\-escapes\fP +Determines if we assume that the assembled +string from \fBvcs_info\fP includes prompt escapes\&. (Used by +\fBvcs_info_lastmsg\fP\&.) +.TP +\fBdebug\fP +Enable debugging output to track possible problems\&. Currently this style +is only used by \fBvcs_info\fP\&'s hooks system\&. +.TP +\fBhooks\fP +A list style that defines hook\-function names\&. See \fBHooks in vcs_info\fP +below for details\&. +.TP +.PD 0 +\fBpatch\-format\fP +.TP +.PD +\fBnopatch\-format\fP +This pair of styles format the patch information used by the \fB%m\fP expando in +formats and actionformats for the \fBgit\fP and \fBhg\fP backends\&. The value is +subject to certain \fB%\fP\-expansions described below\&. +The expanded value is made available in the global \fBbackend_misc\fP array as +\fB${backend_misc[patches]}\fP (also if a \fBset\-patch\-format\fP hook is used)\&. +.TP +\fBget\-unapplied\fP +This boolean style controls whether a backend should attempt to gather a list +of unapplied patches (for example with Mercurial Queue patches)\&. +.RS +.PP +Used by the \fBquilt\fP, \fBhg\fP, and \fBgit\fP backends\&. +.RE +.PP +The default values for these styles in all contexts are: +.PP +.PD 0 +.TP +\fBformats\fP +" (%s)\-[%b]%u%c\-" +.TP +\fBactionformats\fP +" (%s)\-[%b|%a]%u%c\-" +.TP +\fBbranchformat\fP +"%b:%r" (for bzr, svn, svk and hg) +.TP +\fBnvcsformats\fP +"" +.TP +\fBhgrevformat\fP +"%r:%h" +.TP +\fBmax\-exports\fP +2 +.TP +\fBenable\fP +ALL +.TP +\fBdisable\fP +(empty list) +.TP +\fBdisable\-patterns\fP +(empty list) +.TP +\fBcheck\-for\-changes\fP +false +.TP +\fBcheck\-for\-staged\-changes\fP +false +.TP +\fBstagedstr\fP +(string: "S") +.TP +\fBunstagedstr\fP +(string: "U") +.TP +\fBcommand\fP +(empty string) +.TP +\fBuse\-server\fP +false +.TP +\fBuse\-simple\fP +false +.TP +\fBget\-revision\fP +false +.TP +\fBget\-mq\fP +true +.TP +\fBget\-bookmarks\fP +false +.TP +\fBuse\-prompt\-escapes\fP +true +.TP +\fBdebug\fP +false +.TP +\fBhooks\fP +(empty list) +.TP +\fBuse\-quilt\fP +false +.TP +\fBquilt\-standalone\fP +false +.TP +\fBquilt\-patch\-dir\fP +empty \- use \fB$QUILT_PATCHES\fP +.TP +\fBquiltcommand\fP +quilt +.TP +\fBpatch\-format\fP +\fIbackend dependent\fP +.TP +\fBnopatch\-format\fP +\fIbackend dependent\fP +.TP +\fBget\-unapplied\fP +false +.PD +.PP +In normal \fBformats\fP and \fBactionformats\fP the following replacements are +done: +.PP +.PD 0 +.TP +\fB%s\fP +The VCS in use (git, hg, svn, etc\&.)\&. +.TP +\fB%b\fP +Information about the current branch\&. +.TP +\fB%a\fP +An identifier that describes the action\&. Only makes sense in +\fBactionformats\fP\&. +.TP +\fB%i\fP +The current revision number or identifier\&. For \fBhg\fP +the \fBhgrevformat\fP style may be used to customize the output\&. +.TP +\fB%c\fP +The string from the \fBstagedstr\fP style if there are staged +changes in the repository\&. +.TP +\fB%u\fP +The string from the \fBunstagedstr\fP style if there are +unstaged changes in the repository\&. +.TP +\fB%R\fP +The base directory of the repository\&. +.TP +\fB%r\fP +The repository name\&. If \fB%R\fP is \fB/foo/bar/repoXY\fP, \fB%r\fP +is \fBrepoXY\fP\&. +.TP +\fB%S\fP +A subdirectory within a repository\&. If \fB$PWD\fP is +\fB/foo/bar/repoXY/beer/tasty\fP, \fB%S\fP is \fBbeer/tasty\fP\&. +.PD +.PD 0 +.TP +.PD +\fB%m\fP +A "misc" replacement\&. It is at the discretion of the backend to +decide what this replacement expands to\&. +.RS +.PP +The \fBhg\fP and \fBgit\fP backends use this expando to display patch information\&. +\fBhg\fP sources patch information from the \fBmq\fP extensions; \fBgit\fP from in\-progress +\fBrebase\fP and \fBcherry\-pick\fP operations and from the \fBstgit\fP extension\&. The \fBpatch\-format\fP +and \fBnopatch\-format\fP styles control the generated string\&. The former is used +when at least one patch from the patch queue has been applied, and the latter +otherwise\&. +.PP +The \fBhg\fP backend displays bookmark information in this expando (in addition +to \fBmq\fP information)\&. See the \fBget\-mq\fP and \fBget\-bookmarks\fP styles\&. Both +of these styles may be enabled at the same time\&. If both are enabled, both +resulting strings will be shown separated by a semicolon (that cannot currently +be customized)\&. +.PP +The \fBquilt\fP `standalone\&' backend sets this expando to the same value as the +\fB%Q\fP expando\&. +.RE +.TP +\fB%Q\fP +Quilt series information\&. +When quilt is used (either in `addon\&' mode or as a `standalone' backend), +this expando is set to the quilt series\&' \fBpatch\-format\fP string\&. +The \fBset\-patch\-format\fP hook and \fBnopatch\-format\fP style are honoured\&. +.RS +.PP +See \fBQuilt Support\fP below for details\&. +.RE +.PP +In \fBbranchformat\fP these replacements are done: +.PP +.PD 0 +.TP +\fB%b\fP +The branch name\&. For \fBhg\fP, the branch name can include a +topic name\&. +.TP +\fB%r\fP +The current revision number or the \fBhgrevformat\fP style for +\fBhg\fP\&. +.PD +.PP +In \fBhgrevformat\fP these replacements are done: +.PP +.PD 0 +.TP +\fB%r\fP +The current local revision number\&. +.TP +\fB%h\fP +The current global revision identifier\&. +.PD +.PP +In \fBpatch\-format\fP and \fBnopatch\-format\fP these replacements are done: +.PP +.PD 0 +.TP +\fB%p\fP +The name of the top\-most applied patch; may be overridden by the \fBapplied\-string\fP hook\&. +.TP +\fB%u\fP +The number of unapplied patches; may be overridden by the \fBunapplied\-string\fP hook\&. +.TP +\fB%n\fP +The number of applied patches\&. +.TP +\fB%c\fP +The number of unapplied patches\&. +.TP +\fB%a\fP +The number of all patches (\fB%a = %n + %c\fP)\&. +.TP +\fB%g\fP +The names of active \fBmq\fP guards (\fBhg\fP backend)\&. +.TP +\fB%G\fP +The number of active \fBmq\fP guards (\fBhg\fP backend)\&. +.PD +.PP +Not all VCS backends have to support all replacements\&. For \fBnvcsformats\fP +no replacements are performed at all, it is just a string\&. +.PP +.SS "Oddities" +.PP +If you want to use the \fB%b\fP (bold off) prompt expansion in \fBformats\fP, +which expands \fB%b\fP itself, use \fB%%b\fP\&. That will cause the \fBvcs_info\fP +expansion to replace \fB%%b\fP with \fB%b\fP, so that zsh\&'s prompt expansion +mechanism can handle it\&. Similarly, to hand down \fB%b\fP from +\fBbranchformat\fP, use \fB%%%%b\fP\&. Sorry for this inconvenience, but it +cannot be easily avoided\&. Luckily we do not clash with a lot of prompt +expansions and this only needs to be done for those\&. +.PP +When one of the \fBgen\-applied\-string\fP, \fBgen\-unapplied\-string\fP, and +\fBset\-patch\-format\fP hooks is defined, +applying \fB%\fP\-escaping (`\fBfoo=${foo//\&'%'/%%}\fP') to the interpolated values +for use in the prompt is the responsibility of those hooks (jointly); +when neither of those hooks is defined, \fBvcs_info\fP handles escaping by itself\&. +We regret this coupling, but it was required for backwards compatibility\&. +.PP +.SS "Quilt Support" +.PP +\fBQuilt\fP is not a version control system, therefore this is not implemented +as a backend\&. It can help keeping track of a series of patches\&. People use it +to keep a set of changes they want to use on top of software packages (which +is tightly integrated into the package build process \- the Debian project +does this for a large number of packages)\&. Quilt can also help individual +developers keep track of their own patches on top of real version control +systems\&. +.PP +The \fBvcs_info\fP integration tries to support both ways of using quilt by +having two slightly different modes of operation: `addon\&' mode and +`standalone\&' mode)\&. +.PP +Quilt integration is off by default; to enable it, set the \fBuse\-quilt\fP style, +and add \fB%Q\fP to your \fBformats\fP or \fBactionformats\fP style: +.RS +.nf +\fBzstyle \&':vcs_info:*' use\-quilt true\fP +.fi +.RE +.PP +Styles looked up from the Quilt support code include `\fB\&.quilt\-\fP\fIquilt\-mode\fP\&' +in the \fIvcs\-string\fP part of the context, where \fIquilt\-mode\fP is either +\fBaddon\fP or \fBstandalone\fP\&. +Example: \fB:vcs_info:git\&.quilt\-addon:default:\fP\fIrepo\-root\-name\fP\&. +.PP +For `addon\&' mode to become active \fBvcs_info\fP must have already detected a +real version control system controlling the directory\&. If that is the case, +a directory that holds quilt\&'s patches needs to be found\&. That directory is +configurable via the `\fBQUILT_PATCHES\fP\&' environment variable\&. If that +variable exists its value is used, otherwise the value `\fBpatches\fP\&' is +assumed\&. The value from \fB$QUILT_PATCHES\fP can be overwritten using the +`\fBquilt\-patch\-dir\fP\&' style\&. (Note: you can use \fBvcs_info\fP to keep the value +of \fB$QUILT_PATCHES\fP correct all the time via the \fBpost\-quilt\fP hook)\&. +.PP +When the directory in question is found, quilt is assumed to be active\&. To +gather more information, \fBvcs_info\fP looks for a directory called `\&.pc\&'; +Quilt uses that directory to track its current state\&. If this directory does +not exist we know that quilt has not done anything to the working directory +(read: no patches have been applied yet)\&. +.PP +If patches are applied, \fBvcs_info\fP will try to find out which\&. If you want +to know which patches of a series are not yet applied, you need to activate +the \fBget\-unapplied\fP style in the appropriate context\&. +.PP +\fBvcs_info\fP allows for very detailed control over how the gathered +information is presented (see +the \fBConfiguration\fP and \fBHooks in vcs_info\fP sections), +all of which are documented below\&. Note there are a number of +other patch tracking systems that work on top of a certain version control +system (like \fBstgit\fP for \fBgit\fP, or \fBmq\fP for \fBhg\fP); the configuration +for systems like that are generally configured the same way as the \fBquilt\fP +support\&. +.PP +If the \fBquilt\fP support is working in `addon\&' mode, the produced string is +available as a simple format replacement (\fB%Q\fP to be precise), which can +be used in \fBformats\fP and \fBactionformats\fP; see below for details)\&. +.PP +If, on the other hand, the support code is working in `standalone\&' mode, +\fBvcs_info\fP will pretend as if \fBquilt\fP were an actual version control +system\&. That means that the version control system identifier (which +otherwise would be something like `svn\&' or `cvs') will be set to +`\fB\-quilt\-\fP\&'\&. This has implications on the used style context where this +identifier is the second element\&. \fBvcs_info\fP will have filled in a proper +value for the "repository\&'s" root directory and the string containing the +information about quilt\&'s state will be available as the `misc' replacement +(and \fB%Q\fP for compatibility with `addon\&' mode)\&. +.PP +What is left to discuss is how `standalone\&' mode is detected\&. The detection +itself is a series of searches for directories\&. You can have this detection +enabled all the time in every directory that is not otherwise under version +control\&. If you know there is only a limited set of trees where you would +like \fBvcs_info\fP to try and look for Quilt in `standalone\&' mode to minimise +the amount of searching on every call to \fBvcs_info\fP, there are a number of +ways to do that: +.PP +Essentially, `standalone\&' mode detection is controlled by a style called +`\fBquilt\-standalone\fP\&'\&. It is a string style and its value can have different +effects\&. The simplest values are: `\fBalways\fP\&' to run detection every time +\fBvcs_info\fP is run, and `\fBnever\fP\&' to turn the detection off entirely\&. +.PP +If the value of \fBquilt\-standalone\fP is something else, it is interpreted +differently\&. If the value is the name of a scalar variable the value of that +variable is checked and that value is used in the same `always\&'/`never' way +as described above\&. +.PP +If the value of \fBquilt\-standalone\fP is an array, the elements of that array +are used as directory names under which you want the detection to be active\&. +.PP +If \fBquilt\-standalone\fP is an associative array, the keys are taken as +directory names under which you want the detection to be active, but only if +the corresponding value is the string `\fBtrue\fP\&'\&. +.PP +Last, but not least, if the value of \fBquilt\-standalone\fP is the name of a +function, the function is called without arguments and the return value +decides whether detection should be active\&. A `0\&' return value is true; a +non\-zero return value is interpreted as false\&. +.PP +Note, if there is both a function and a variable by the name of +\fBquilt\-standalone\fP, the function will take precedence\&. +.PP +.SS "Function Descriptions (Public API)" +.PP +.PD 0 +.TP +.PD +\fBvcs_info\fP [\fIuser\-context\fP] +The main function, that runs all backends and assembles all data into +\fB${vcs_info_msg_*_}\fP\&. This is the function you want to call from +\fBprecmd\fP if you want to include up\-to\-date information in your prompt (see +\fBVariable Description\fP +below)\&. If an argument is given, that string will be +used instead of \fBdefault\fP in the \fIuser\-context\fP field of the style +context\&. +.TP +\fBvcs_info_hookadd\fP +Statically registers a number of functions to a given hook\&. The hook needs +to be given as the first argument; what follows is a list of hook\-function +names to register to the hook\&. The `\fB+vi\-\fP\&' prefix needs to be left out +here\&. See \fBHooks in vcs_info\fP +below for details\&. +.TP +\fBvcs_info_hookdel\fP +Remove hook\-functions from a given hook\&. The hook needs to be given as the +first non\-option argument; what follows is a list of hook\-function +names to un\-register from the hook\&. If `\fB\-a\fP\&' is used as the first +argument, \fBall\fP occurrences of the functions are unregistered\&. Otherwise +only the last occurrence is removed (if a function was registered to a hook +more than once)\&. The `\fB+vi\-\fP\&' prefix needs to be left out here\&. +See \fBHooks in vcs_info\fP +below for details\&. +.TP +\fBvcs_info_lastmsg\fP +Outputs the current values of \fB${vcs_info_msg_*_}\fP\&. +Takes into account the value of the \fBuse\-prompt\-escapes\fP style in +\fB\&':vcs_info:formats:command:\-all\-'\fP\&. It also only prints \fBmax\-exports\fP +values\&. +.TP +\fBvcs_info_printsys\fP [\fIuser\-context\fP] +Prints a list of all +supported version control systems\&. Useful to find out possible contexts +(and which of them are enabled) or values for the \fBdisable\fP style\&. +.TP +\fBvcs_info_setsys\fP +Initializes \fBvcs_info\fP\&'s internal list of +available backends\&. With this function, you can add support for new VCSs +without restarting the shell\&. +.PP +All functions named \fBVCS_INFO_*\fP are for internal use only\&. +.PP +.SS "Variable Description" +.PP +.PD 0 +.TP +.PD +\fB${vcs_info_msg_\fP\fIN\fP\fB_}\fP (Note the trailing underscore) +Where \fIN\fP is an integer, e\&.g\&., \fBvcs_info_msg_0_\fP\&. These variables +are the storage for the informational message the last \fBvcs_info\fP call +has assembled\&. These are strongly connected to the \fBformats\fP, +\fBactionformats\fP and \fBnvcsformats\fP styles described above\&. Those styles +are lists\&. The first member of that list gets expanded into +\fB${vcs_info_msg_0_}\fP, the second into \fB${vcs_info_msg_1_}\fP +and the Nth into \fB${vcs_info_msg_N\-1_}\fP\&. (See the \fBmax\-exports\fP +style above\&.) +.PP +All variables named \fBVCS_INFO_*\fP are for internal use only\&. +.PP +.SS "Hooks in vcs_info" +.PP +Hooks are places in \fBvcs_info\fP where you can run your own code\&. That +code can communicate with the code that called it and through that, +change the system\&'s behaviour\&. +.PP +For configuration, hooks change the style context: +.RS +.nf +\fB:vcs_info:\fIvcs\-string\fP+\fIhook\-name\fP:\fIuser\-context\fP:\fIrepo\-root\-name\fP\fP +.fi +.RE +.PP +To register functions to a hook, you need to list them in the \fBhooks\fP +style in the appropriate context\&. +.PP +Example: +.RS +.nf +\fBzstyle \&':vcs_info:*+foo:*' hooks bar baz\fP +.fi +.RE +.PP +This registers functions to the hook `foo\&' for all backends\&. In order to +avoid namespace problems, all registered function names are prepended by +a `\fB+vi\-\fP\&', so the actual functions called for the `foo' hook are +`\fB+vi\-bar\fP\&' and `\fB+vi\-baz\fP'\&. +.PP +If you would like to register a function to a hook regardless of the +current context, you may use the \fBvcs_info_hookadd\fP function\&. To remove +a function that was added like that, the \fBvcs_info_hookdel\fP function +can be used\&. +.PP +If something seems weird, you can enable the `debug\&' boolean style in +the proper context and the hook\-calling code will print what it tried +to execute and whether the function in question existed\&. +.PP +When you register more than one function to a hook, all functions are +executed one after another until one function returns non\-zero or until +all functions have been called\&. Context\-sensitive hook functions are +executed \fBbefore\fP statically registered ones (the ones added by +\fBvcs_info_hookadd\fP)\&. +.PP +You may pass data between functions via an associative array, \fBuser_data\fP\&. +For example: +.RS +.nf +\fB ++vi\-git\-myfirsthook(){ + user_data[myval]=$myval +} ++vi\-git\-mysecondhook(){ + # do something with ${user_data[myval]} +}\fP +.fi +.RE +.PP +There are a number of variables that are special in hook contexts: +.PP +.PD 0 +.TP +.PD +\fBret\fP +The return value that the hooks system will return to the caller\&. The +default is an integer `zero\&'\&. If and how a changed \fBret\fP value changes +the execution of the caller depends on the specific hook\&. See the hook +documentation below for details\&. +.TP +\fBhook_com\fP +An associated array which is used for bidirectional communication from +the caller to hook functions\&. The used keys depend on the specific hook\&. +.TP +\fBcontext\fP +The active context of the hook\&. Functions that wish to change this +variable should make it local scope first\&. +.TP +\fBvcs\fP +The current VCS after it was detected\&. The same values as in the +enable/disable style are used\&. Available in all hooks except \fBstart\-up\fP\&. +.PP +Finally, the full list of currently available hooks: +.PP +.PD 0 +.TP +.PD +\fBstart\-up\fP +Called after starting \fBvcs_info\fP but before the VCS in this directory is +determined\&. It can be used to deactivate \fBvcs_info\fP temporarily if +necessary\&. When \fBret\fP is set to \fB1\fP, \fBvcs_info\fP aborts and does +nothing; when set to \fB2\fP, \fBvcs_info\fP sets up everything as if no +version control were active and exits\&. +.TP +\fBpre\-get\-data\fP +Same as \fBstart\-up\fP but after the VCS was detected\&. +.TP +\fBgen\-hg\-bookmark\-string\fP +Called in the Mercurial backend when a bookmark string is generated; the +\fBget\-revision\fP and \fBget\-bookmarks\fP styles must be true\&. +.RS +.PP +This hook gets the names of the Mercurial bookmarks that +\fBvcs_info\fP collected from `hg\&'\&. +.PP +If a bookmark is active, the key \fB${hook_com[hg\-active\-bookmark]}\fP is +set to its name\&. The key is otherwise unset\&. +.PP +When setting \fBret\fP to non\-zero, the string in +\fB${hook_com[hg\-bookmark\-string]}\fP will be used in the \fB%m\fP escape in +\fBformats\fP and \fBactionformats\fP and will be available in the global +\fBbackend_misc\fP array as \fB${backend_misc[bookmarks]}\fP\&. +.RE +.TP +\fBgen\-applied\-string\fP +Called in the \fBgit\fP (with \fBstgit\fP or during rebase or merge), and \fBhg\fP +(with \fBmq\fP) backends and in \fBquilt\fP support when the \fBapplied\-string\fP +is generated; the \fBuse\-quilt\fP zstyle must be true for \fBquilt\fP (the \fBmq\fP +and \fBstgit\fP backends are active by default)\&. +.RS +.PP +The arguments to this hook describe applied patches +in the opposite order, which means that the first argument is the +top\-most patch and so forth\&. +.PP +When the patches\&' log messages can be extracted, those are embedded +within each argument after a space, so each argument is of the form +`\fIpatch\-name\fP \fIfirst line of the log message\fP\&', where \fIpatch\-name\fP +contains no whitespace\&. The \fBmq\fP backend passes arguments of +the form `\fIpatch name\fP\&', with possible embedded spaces, but without +extracting the patch\&'s log message\&. +.PP +When setting \fBret\fP to non\-zero, the string in +\fB${hook_com[applied\-string]}\fP will be +available as \fB%p\fP in the \fBpatch\-format\fP and \fBnopatch\-format\fP styles\&. +This hook is, in concert with \fBset\-patch\-format\fP, responsible for +\fB%\fP\-escaping that value for use in the prompt\&. +(See the \fBOddities\fP section\&.) +.PP +The \fBquilt\fP backend passes to this hook the inputs +\fB${hook_com[quilt\-patches\-dir]}\fP and, if it has been +determined, \fB${hook_com[quilt\-pc\-dir]}\fP\&. +.RE +.TP +\fBgen\-unapplied\-string\fP +Called in the \fBgit\fP (with \fBstgit\fP or during rebase), and \fBhg\fP (with +\fBmq\fP) backend and in \fBquilt\fP support when the \fBunapplied\-string\fP is +generated; the \fBget\-unapplied\fP style must be true\&. +.RS +.PP +This hook gets the names of all unapplied patches which \fBvcs_info\fP +in order, which means that the first argument is +the patch next\-in\-line to be applied and so forth\&. +.PP +The format of each argument is as for \fBgen\-applied\-string\fP, above\&. +.PP +When setting \fBret\fP to non\-zero, the string in +\fB${hook_com[unapplied\-string]}\fP will be available as \fB%u\fP in the +\fBpatch\-format\fP and \fBnopatch\-format\fP styles\&. +This hook is, in concert with \fBset\-patch\-format\fP, responsible for +\fB%\fP\-escaping that value for use in the prompt\&. +(See the \fBOddities\fP section\&.) +.PP +The \fBquilt\fP backend passes to this hook the inputs +\fB${hook_com[quilt\-patches\-dir]}\fP and, if it has been +determined, \fB${hook_com[quilt\-pc\-dir]}\fP\&. +.RE +.TP +\fBgen\-mqguards\-string\fP +Called in the \fBhg\fP backend when \fBguards\-string\fP is generated; the +\fBget\-mq\fP style must be true (default)\&. +.RS +.PP +This hook gets the names of any active \fBmq\fP guards\&. +.PP +When setting \fBret\fP to non\-zero, the string in +\fB${hook_com[guards\-string]}\fP will be used in the \fB%g\fP escape in the +\fBpatch\-format\fP and \fBnopatch\-format\fP styles\&. +.RE +.TP +\fBno\-vcs\fP +This hooks is called when no version control system was detected\&. +.RS +.PP +The `\fBhook_com\fP\&' parameter is not used\&. +.RE +.TP +\fBpost\-backend\fP +Called as soon as the backend has finished collecting information\&. +.RS +.PP +The `\fBhook_com\fP\&' keys available are as for the \fBset\-message\fP hook\&. +.RE +.TP +\fBpost\-quilt\fP +Called after the \fBquilt\fP support is done\&. The following information +is passed as arguments to the hook: 1\&. the quilt\-support mode (`addon\&' or +`standalone\&'); 2\&. the directory that contains the patch series; 3\&. the +directory that holds quilt\&'s status information (the `\&.pc' directory) or +the string \fB"\-nopc\-"\fP if that directory wasn\&'t found\&. +.RS +.PP +The `hook_com\&' parameter is not used\&. +.RE +.TP +\fBset\-branch\-format\fP +Called before `\fBbranchformat\fP\&' is set\&. The only argument to the +hook is the format that is configured at this point\&. +.RS +.PP +The `\fBhook_com\fP\&' keys considered are `\fBbranch\fP' and `\fBrevision\fP'\&. +They are set to the values figured out so far by \fBvcs_info\fP and any +change will be used directly when the actual replacement is done\&. +.PP +If \fBret\fP is set to non\-zero, the string in +\fB${hook_com[branch\-replace]}\fP will be used unchanged as the +`\fB%b\fP\&' replacement in the variables set by \fBvcs_info\fP\&. +.RE +.TP +\fBset\-hgrev\-format\fP +Called before a `\fBhgrevformat\fP\&' is set\&. The only argument to the +hook is the format that is configured at this point\&. +.RS +.PP +The `\fBhook_com\fP\&' keys considered are `\fBhash\fP' and `\fBlocalrev\fP'\&. +They are set to the values figured out so far by \fBvcs_info\fP and any +change will be used directly when the actual replacement is done\&. +.PP +If \fBret\fP is set to non\-zero, the string in +\fB${hook_com[rev\-replace]}\fP will be used unchanged as the +`\fB%i\fP\&' replacement in the variables set by \fBvcs_info\fP\&. +.RE +.TP +\fBpre\-addon\-quilt\fP +This hook is used when \fBvcs_info\fP\&'s quilt functionality is active in "addon" +mode (quilt used on top of a real version control system)\&. It is activated +right before any quilt specific action is taken\&. +.RS +.PP +Setting the `\fBret\fP\&' variable in this hook to a non\-zero value avoids any +quilt specific actions from being run at all\&. +.RE +.TP +\fBset\-patch\-format\fP +This hook is used to control some of the possible expansions in +\fBpatch\-format\fP and \fBnopatch\-format\fP styles with patch queue systems such as +quilt, mqueue and the like\&. +.RS +.PP +This hook is used in the \fBgit\fP, \fBhg\fP and \fBquilt\fP backends\&. +.PP +The hook allows the control of the \fB%p\fP (\fB${hook_com[applied]}\fP) and \fB%u\fP +(\fB${hook_com[unapplied]}\fP) expansion in all backends that use the hook\&. With +the mercurial backend, the \fB%g\fP (\fB${hook_com[guards]}\fP) expansion is +controllable in addition to that\&. +.PP +If \fBret\fP is set to non\-zero, the string in \fB${hook_com[patch\-replace]}\fP +will be used unchanged instead of an expanded format from \fBpatch\-format\fP or +\fBnopatch\-format\fP\&. +.PP +This hook is, in concert with the \fBgen\-applied\-string\fP or +\fBgen\-unapplied\-string\fP hooks if they are defined, responsible for +\fB%\fP\-escaping the final \fBpatch\-format\fP value for use in the prompt\&. +(See the \fBOddities\fP section\&.) +.PP +The \fBquilt\fP backend passes to this hook the inputs +\fB${hook_com[quilt\-patches\-dir]}\fP and, if it has been +determined, \fB${hook_com[quilt\-pc\-dir]}\fP\&. +.RE +.TP +\fBset\-message\fP +Called each time before a `\fBvcs_info_msg_\fP\fIN\fP\fB_\fP\&' message is set\&. +It takes two arguments; the first being the `\fIN\fP\&' in the message +variable name, the second is the currently configured \fBformats\fP or +\fBactionformats\fP\&. +.RS +.PP +There are a number of `\fBhook_com\fP\&' keys, that are used here: +`\fBaction\fP\&', `\fBbranch\fP', `\fBbase\fP', `\fBbase\-name\fP', `\fBsubdir\fP', +`\fBstaged\fP\&', `\fBunstaged\fP', `\fBrevision\fP', `\fBmisc\fP', `\fBvcs\fP' +and one `\fBmiscN\fP\&' entry for each backend\-specific data field (\fBN\fP +starting at zero)\&. They are set to the values figured out so far by +\fBvcs_info\fP and any change will be used directly when the actual +replacement is done\&. +.PP +Since this hook is triggered multiple times (once for each configured +\fBformats\fP or \fBactionformats\fP), each of the `\fBhook_com\fP\&' keys mentioned +above (except for the \fBmiscN\fP entries) has an `\fB_orig\fP\&' counterpart, +so even if you changed a value to your liking you can still get the +original value in the next run\&. Changing the `\fB_orig\fP\&' values is +probably not a good idea\&. +.PP +If \fBret\fP is set to non\-zero, the string in +\fB${hook_com[message]}\fP will be used unchanged as the message by +\fBvcs_info\fP\&. +.RE +.PP +If all of this sounds rather confusing, take a look at +the \fBExamples\fP section below +and also in the \fBMisc/vcs_info\-examples\fP file in the Zsh source\&. +They contain some explanatory code\&. +.PP +.SS "Examples" +.PP +Don\&'t use \fBvcs_info\fP at all (even though it's in your prompt): +.RS +.nf +\fBzstyle \&':vcs_info:*' enable NONE\fP +.fi +.RE +.PP +Disable the backends for \fBbzr\fP and \fBsvk\fP: +.RS +.nf +\fBzstyle \&':vcs_info:*' disable bzr svk\fP +.fi +.RE +.PP +Disable everything \fIbut\fP \fBbzr\fP and \fBsvk\fP: +.RS +.nf +\fBzstyle \&':vcs_info:*' enable bzr svk\fP +.fi +.RE +.PP +Provide a special formats for \fBgit\fP: +.RS +.nf +\fBzstyle \&':vcs_info:git:*' formats ' GIT, BABY! [%b]' +zstyle \&':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]'\fP +.fi +.RE +.PP +All \fB%x\fP expansion in all sorts of formats (\fBformats\fP, \fBactionformats\fP, +\fBbranchformat\fP, you name it) are done using the `\fBzformat\fP\&' builtin from +the `\fBzsh/zutil\fP\&' module\&. That means you can do everything with these +\fB%x\fP items what zformat supports\&. In particular, if you want something +that is really long to have a fixed width, like a hash in a mercurial +branchformat, you can do this: \fB%12\&.12i\fP\&. That\&'ll shrink the 40 character +hash to its 12 leading characters\&. The form is actually +`\fB%\fP\fImin\fP\fB\&.\fP\fImax\fP\fBx\fP\&'\&. More is possible\&. +See the section `The zsh/zutil Module\&' in \fIzshmodules\fP(1) for details\&. +.PP +Use the quicker \fBbzr\fP backend +.RS +.nf +\fBzstyle \&':vcs_info:bzr:*' use\-simple true\fP +.fi +.RE +.PP +If you do use \fBuse\-simple\fP, please report if it does `the\-right\-thing[tm]\&'\&. +.PP +Display the revision number in yellow for \fBbzr\fP and \fBsvn\fP: +.RS +.nf +\fBzstyle \&':vcs_info:(svn|bzr):*' \e + branchformat \&'%b%%F{yellow}:%r'\fP +.fi +.RE +.PP +The doubled percent sign is explained in +the \fBOddities\fP section\&. +.PP +Alternatively, one can use the raw colour codes directly: +.PP +.RS +.nf +\fBzstyle \&':vcs_info:(svn|bzr):*' \e + branchformat \&'%b%{'${fg[yellow]}'%}:%r'\fP +.fi +.RE +.PP +Normally when a variable is interpolated into a format string, the variable +needs to be \fB%\fP\-escaped\&. In this example we skipped that because we assume +the value of \fB${fg[yellow]}\fP doesn\&'t contain any \fB%\fP signs\&. +.PP +Make sure you enclose the color codes in \fB%{\fP\fI\&.\&.\&.\fP\fB%}\fP +if you want to use the string provided by \fBvcs_info\fP in prompts\&. +.PP +Here is how to print the VCS information as a command (not in a prompt): +.RS +.nf +\fBvcsi() { vcs_info interactive; vcs_info_lastmsg }\fP +.fi +.RE +.PP +This way, you can even define different formats for output via +\fBvcs_info_lastmsg\fP in the \&'\fB:vcs_info:*:interactive:*\fP' namespace\&. +.PP +Now as promised, some code that uses hooks: +say, you\&'d like to replace the string `svn' by `subversion' in +\fBvcs_info\fP\&'s \fB%s\fP \fBformats\fP replacement\&. +.PP +First, we will tell \fBvcs_info\fP to call a function when populating +the message variables with the gathered information: +.RS +.nf +\fBzstyle \&':vcs_info:*+set\-message:*' hooks svn2subversion\fP +.fi +.RE +.PP +Nothing happens\&. Which is reasonable, since we didn\&'t define the actual +function yet\&. To see what the hooks subsystem is trying to do, enable the +`\fBdebug\fP\&' style: +.RS +.nf +\fBzstyle \&':vcs_info:*+*:*' debug true\fP +.fi +.RE +.PP +That should give you an idea what is going on\&. Specifically, the function +that we are looking for is `\fB+vi\-svn2subversion\fP\&'\&. Note, the `\fB+vi\-\fP' +prefix\&. So, everything is in order, just as documented\&. When you are done +checking out the debugging output, disable it again: +.RS +.nf +\fBzstyle \&':vcs_info:*+*:*' debug false\fP +.fi +.RE +.PP +Now, let\&'s define the function: +.RS +.nf +\fB +function +vi\-svn2subversion() { + [[ ${hook_com[vcs_orig]} == svn ]] && hook_com[vcs]=subversion +}\fP +.fi +.RE +.PP +Simple enough\&. And it could have even been simpler, if only we had +registered our function in a less generic context\&. If we do it only in +the `\fBsvn\fP\&' backend's context, we don't need to test which the active +backend is: +.RS +.nf +\fBzstyle \&':vcs_info:svn+set\-message:*' hooks svn2subversion\fP +.fi +.RE +.RS +.nf +\fB +function +vi\-svn2subversion() { + hook_com[vcs]=subversion +}\fP +.fi +.RE +.PP +And finally a little more elaborate example, that uses a hook to create +a customised bookmark string for the \fBhg\fP backend\&. +.PP +Again, we start off by registering a function: +.RS +.nf +\fBzstyle \&':vcs_info:hg+gen\-hg\-bookmark\-string:*' hooks hgbookmarks\fP +.fi +.RE +.PP +And then we define the `\fB+vi\-hgbookmarks\fP\&' function: +.RS +.nf +\fB +function +vi\-hgbookmarks() { + # The default is to connect all bookmark names by + # commas\&. This mixes things up a little\&. + # Imagine, there\&'s one type of bookmarks that is + # special to you\&. Say, because it\&'s *your* work\&. + # Those bookmarks look always like this: "sh/*" + # (because your initials are sh, for example)\&. + # This makes the bookmarks string use only those + # bookmarks\&. If there\&'s more than one, it + # concatenates them using commas\&. + # The bookmarks returned by `hg\&' are available in + # the function\&'s positional parameters\&. + local s="${(Mj:,:)@:#sh/*}" + # Now, the communication with the code that calls + # the hook functions is done via the hook_com[] + # hash\&. The key at which the `gen\-hg\-bookmark\-string\&' + # hook looks is `hg\-bookmark\-string\&'\&. So: + hook_com[hg\-bookmark\-string]=$s + # And to signal that we want to use the string we + # just generated, set the special variable `ret\&' to + # something other than the default zero: + ret=1 + return 0 +}\fP +.fi +.RE +.PP +Some longer examples and code snippets which might be useful are available in +the examples file located at Misc/vcs_info\-examples in the Zsh source +directory\&. +.PP +This concludes our guided tour through zsh\&'s \fBvcs_info\fP\&. +.PP +.SH "PROMPT THEMES" +.PP +.SS "Installation" +.PP +You should make sure all the functions from the \fBFunctions/Prompts\fP +directory of the source distribution are available; they all begin with +the string `\fBprompt_\fP\&' except for the special function `\fBpromptinit\fP'\&. +You also need the `\fBcolors\fP\&' and `\fBadd\-zsh\-hook\fP' functions from +\fBFunctions/Misc\fP\&. +All these functions may already be installed on your system; if not, +you will need to find them and copy them\&. The directory should appear as +one of the elements of the \fBfpath\fP array (this should already be the +case if they were installed), and at least the function \fBpromptinit\fP +should be autoloaded; it will autoload the rest\&. Finally, to initialize +the use of the system you need to call the \fBpromptinit\fP function\&. The +following code in your \fB\&.zshrc\fP will arrange for this; assume the +functions are stored in the directory \fB~/myfns\fP: +.PP +.RS +.nf +\fBfpath=(~/myfns $fpath) +autoload \-U promptinit +promptinit\fP +.fi +.RE +.PP +.SS "Theme Selection" +.PP +Use the \fBprompt\fP command to select your preferred theme\&. This command +may be added to your \fB\&.zshrc\fP following the call to \fBpromptinit\fP in +order to start zsh with a theme already selected\&. +.PP +.PD 0 +.TP +.PD 0 +\fBprompt\fP [ \fB\-c\fP | \fB\-l\fP ] +.TP +.PD 0 +\fBprompt\fP [ \fB\-p\fP | \fB\-h\fP ] [ \fItheme\fP \&.\&.\&. ] +.TP +.PD +\fBprompt\fP [ \fB\-s\fP ] \fItheme\fP [ \fIarg\fP \&.\&.\&. ] +Set or examine the prompt theme\&. With no options and a \fItheme\fP +argument, the theme with that name is set as the current theme\&. The +available themes are determined at run time; use the \fB\-l\fP option to see +a list\&. The special \fItheme\fP `\fBrandom\fP\&' selects at random one of the +available themes and sets your prompt to that\&. +.RS +.PP +In some cases the \fItheme\fP may be modified by one or more arguments, +which should be given after the theme name\&. See the help for each theme +for descriptions of these arguments\&. +.PP +Options are: +.PP +.PD 0 +.TP +\fB\-c\fP +Show the currently selected theme and its parameters, if any\&. +.TP +\fB\-l\fP +List all available prompt themes\&. +.TP +\fB\-p\fP +Preview the theme named by \fItheme\fP, or all themes if no +\fItheme\fP is given\&. +.TP +\fB\-h\fP +Show help for the theme named by \fItheme\fP, or for the +\fBprompt\fP function if no \fItheme\fP is given\&. +.TP +\fB\-s\fP +Set \fItheme\fP as the current theme and save state\&. +.PD +.RE +.TP +\fBprompt_\fP\fItheme\fP\fB_setup\fP +Each available \fItheme\fP has a setup function which is called by the +\fBprompt\fP function to install that theme\&. This function may define +other functions as necessary to maintain the prompt, including functions +used to preview the prompt or provide help for its use\&. You should not +normally call a theme\&'s setup function directly\&. +.PP +.SS "Utility Themes" +.PP +.PD 0 +.TP +.PD +\fBprompt off\fP +The theme `\fBoff\fP\&' sets all the prompt variables to minimal values with +no special effects\&. +.TP +\fBprompt default\fP +The theme `\fBdefault\fP\&' sets all prompt variables to the same state as +if an interactive zsh was started with no initialization files\&. +.TP +\fBprompt restore\fP +The special theme `\fBrestore\fP\&' erases all theme settings and sets prompt +variables to their state before the first time the `\fBprompt\fP\&' function +was run, provided each theme has properly defined its cleanup (see below)\&. +.RS +.PP +Note that you can undo `\fBprompt off\fP\&' and `\fBprompt default\fP' with +`\fBprompt restore\fP\&', but a second restore does not undo the first\&. +.RE +.PP +.SS "Writing Themes" +.PP +The first step for adding your own theme is to choose a name for it, +and create a file `\fBprompt_\fIname\fP_setup\fP\&' in a directory in your +\fBfpath\fP, such as \fB~/myfns\fP in the example above\&. The file should +at minimum contain assignments for the prompt variables that your +theme wishes to modify\&. By convention, themes use \fBPS1\fP, \fBPS2\fP, +\fBRPS1\fP, etc\&., rather than the longer \fBPROMPT\fP and \fBRPROMPT\fP\&. +.PP +The file is autoloaded as a function in the current shell context, so +it may contain any necessary commands to customize your theme, including +defining additional functions\&. To make some complex tasks easier, your +setup function may also do any of the following: +.PP +.PD 0 +.TP +.PD +Assign \fBprompt_opts\fP +The array \fBprompt_opts\fP may be assigned any of \fB"bang"\fP, \fB"cr"\fP, +\fB"percent"\fP, \fB"sp"\fP, and/or \fB"subst"\fP as values\&. The corresponding +setopts (\fBpromptbang\fP, etc\&.) are turned on, all other prompt\-related +options are turned off\&. The \fBprompt_opts\fP array preserves setopts even +beyond the scope of \fBlocaloptions\fP, should your function need that\&. +.TP +Modify hooks +Use of \fBadd\-zsh\-hook\fP and \fBadd\-zle\-hook\-widget\fP is recommended (see +the \fBManipulating Hook Functions\fP section above)\&. +All hooks that follow the naming pattern \fBprompt_\fP\fItheme\fP\fB_\fP\fIhook\fP +are automatically removed when the prompt theme changes or is disabled\&. +.TP +Declare cleanup +If your function makes any other changes that should be undone when the +theme is disabled, your setup function may call +.RS +.PP +.RS +.nf +\fBprompt_cleanup \fIcommand\fP\fP +.fi +.RE +.PP +where \fIcommand\fP should be suitably quoted\&. If your theme is ever +disabled or replaced by another, \fIcommand\fP is executed with \fBeval\fP\&. +You may declare more than one such cleanup hook\&. +.RE +.TP +Define preview +Define or autoload a function \fBprompt_\fP\fIname\fP\fB_preview\fP to display +a simulated version of your prompt\&. A simple default previewer is +defined by \fBpromptinit\fP for themes that do not define their own\&. +This preview function is called by `\fBprompt \-p\fP\&'\&. +.TP +Provide help +Define or autoload a function \fBprompt_\fP\fIname\fP\fB_help\fP to display +documentation or help text for your theme\&. +This help function is called by `\fBprompt \-h\fP\&'\&. +.PP +.SH "ZLE FUNCTIONS" +.PP +.SS "Widgets" +.PP +These functions all implement user\-defined ZLE widgets (see +\fIzshzle\fP(1)) which can be bound to keystrokes in interactive shells\&. To use them, +your \fB\&.zshrc\fP should contain lines of the form +.PP +.RS +.nf +\fBautoload \fIfunction\fP +zle \-N \fIfunction\fP\fP +.fi +.RE +.PP +followed by an appropriate \fBbindkey\fP command to associate the function +with a key sequence\&. Suggested bindings are described below\&. +.PP +.PD 0 +.TP +.PD +bash\-style word functions +If you are looking for functions to implement moving over and editing +words in the manner of bash, where only alphanumeric characters are +considered word characters, you can use the functions described in +the next section\&. The following is sufficient: +.RS +.PP +.RS +.nf +\fBautoload \-U select\-word\-style +select\-word\-style bash\fP +.fi +.RE +.PP +.RE +.TP +.PD 0 +\fBforward\-word\-match\fP, \fBbackward\-word\-match\fP +.TP +.PD 0 +\fBkill\-word\-match\fP, \fBbackward\-kill\-word\-match\fP +.TP +.PD 0 +\fBtranspose\-words\-match\fP, \fBcapitalize\-word\-match\fP +.TP +.PD 0 +\fBup\-case\-word\-match\fP, \fBdown\-case\-word\-match\fP +.TP +.PD 0 +\fBdelete\-whole\-word\-match\fP, \fBselect\-word\-match\fP +.TP +.PD +\fBselect\-word\-style\fP, \fBmatch\-word\-context\fP, \fBmatch\-words\-by\-style\fP +The first eight `\fB\-match\fP\&' functions are drop\-in replacements for the +builtin widgets without the suffix\&. By default they behave in a similar +way\&. However, by the use of styles and the function \fBselect\-word\-style\fP, +the way words are matched can be altered\&. \fBselect\-word\-match\fP is intended +to be used as a text object in vi mode but with custom word styles\&. For +comparison, the widgets described in \fIzshzle\fP(1) under Text Objects use fixed definitions of words, compatible +with the \fBvim\fP editor\&. +.RS +.PP +The simplest way of configuring the functions is to use +\fBselect\-word\-style\fP, which can either be called as a normal function with +the appropriate argument, or invoked as a user\-defined widget that will +prompt for the first character of the word style to be used\&. The first +time it is invoked, the first eight \fB\-match\fP functions will automatically +replace the builtin versions, so they do not need to be loaded explicitly\&. +.PP +The word styles available are as follows\&. Only the first character +is examined\&. +.PP +.PD 0 +.TP +.PD +\fBbash\fP +Word characters are alphanumeric characters only\&. +.TP +\fBnormal\fP +As in normal shell operation: word characters are alphanumeric characters +plus any characters present in the string given by the parameter +\fB$WORDCHARS\fP\&. +.TP +\fBshell\fP +Words are complete shell command arguments, possibly including complete +quoted strings, or any tokens special to the shell\&. +.TP +\fBwhitespace\fP +Words are any set of characters delimited by whitespace\&. +.TP +\fBdefault\fP +Restore the default settings; this is usually the same as `\fBnormal\fP\&'\&. +.PP +All but `\fBdefault\fP\&' can be input as an upper case character, which has +the same effect but with subword matching turned on\&. In this case, words +with upper case characters are treated specially: each separate run of +upper case characters, or an upper case character followed by any number of +other characters, is considered a word\&. The style \fBsubword\-range\fP +can supply an alternative character range to the default `\fB[:upper:]\fP\&'; +the value of the style is treated as the contents of a `\fB[\fP\fI\&.\&.\&.\fP\fB]\fP\&' +pattern (note that the outer brackets should not be supplied, only +those surrounding named ranges)\&. +.PP +More control can be obtained using the \fBzstyle\fP command, as described in +\fIzshmodules\fP(1)\&. Each style is looked up in the +context \fB:zle:\fP\fIwidget\fP where \fIwidget\fP is the name of the +user\-defined widget, not the name of the function implementing it, so in +the case of the definitions supplied by \fBselect\-word\-style\fP the +appropriate contexts are \fB:zle:forward\-word\fP, and so on\&. The function +\fBselect\-word\-style\fP itself always defines styles for the context +`\fB:zle:*\fP\&' which can be overridden by more specific (longer) patterns as +well as explicit contexts\&. +.PP +The style \fBword\-style\fP specifies the rules to use\&. This may have the +following values\&. +.PP +.PD 0 +.TP +.PD +\fBnormal\fP +Use the standard shell rules, i\&.e\&. alphanumerics and \fB$WORDCHARS\fP, unless +overridden by the styles \fBword\-chars\fP or \fBword\-class\fP\&. +.TP +\fBspecified\fP +Similar to \fBnormal\fP, but \fIonly\fP the specified characters, and not also +alphanumerics, are considered word characters\&. +.TP +\fBunspecified\fP +The negation of specified\&. The given characters are those which will +\fInot\fP be considered part of a word\&. +.TP +\fBshell\fP +Words are obtained by using the syntactic rules for generating shell +command arguments\&. In addition, special tokens which are never command +arguments such as `\fB()\fP\&' are also treated as words\&. +.TP +\fBwhitespace\fP +Words are whitespace\-delimited strings of characters\&. +.PP +The first three of those rules usually use \fB$WORDCHARS\fP, but the value +in the parameter can be overridden by the style \fBword\-chars\fP, which works +in exactly the same way as \fB$WORDCHARS\fP\&. In addition, the style +\fBword\-class\fP uses character class syntax to group characters and takes +precedence over \fBword\-chars\fP if both are set\&. The \fBword\-class\fP style +does not include the surrounding brackets of the character class; for +example, `\fB\-:[:alnum:]\fP\&' is a valid \fBword\-class\fP to include all +alphanumerics plus the characters `\fB\-\fP\&' and `\fB:\fP'\&. Be careful +including `\fB]\fP\&', `\fB^\fP' and `\fB\-\fP' as these are special inside +character classes\&. +.PP +\fBword\-style\fP may also have `\fB\-subword\fP\&' appended to its value to +turn on subword matching, as described above\&. +.PP +The style \fBskip\-chars\fP is mostly useful for +\fBtranspose\-words\fP and similar functions\&. If set, it gives a count of +characters starting at the cursor position which will not be considered +part of the word and are treated as space, regardless of what they actually +are\&. For example, if +.PP +.RS +.nf +\fBzstyle \&':zle:transpose\-words' skip\-chars 1\fP +.fi +.RE +.PP +has been set, and \fBtranspose\-words\-match\fP is called with the cursor on +the \fIX\fP of \fBfoo\fP\fIX\fP\fBbar\fP, where \fIX\fP can be any character, then +the resulting expression is \fBbar\fP\fIX\fP\fBfoo\fP\&. +.PP +Finer grained control can be obtained by setting the style \fBword\-context\fP +to an array of pairs of entries\&. Each pair of entries consists of a +\fIpattern\fP and a \fIsubcontext\fP\&. The shell argument the cursor is on is +matched against each \fIpattern\fP in turn until one matches; if it does, +the context is extended by a colon and the corresponding \fIsubcontext\fP\&. +Note that the test is made against the original word on the line, with no +stripping of quotes\&. Special handling is done between words: the current +context is examined and if it contains the string \fBbetween\fP the word +is set to a single space; else if it is contains the string \fBback\fP, +the word before the cursor is considered, else the word after cursor is +considered\&. Some examples are given below\&. +.PP +The style \fBskip\-whitespace\-first\fP is only used with the +\fBforward\-word\fP widget\&. If it is set to true, then \fBforward\-word\fP +skips any non\-word\-characters, followed by any non\-word\-characters: +this is similar to the behaviour of other word\-orientated widgets, +and also that used by other editors, however it differs from the +standard zsh behaviour\&. When using \fBselect\-word\-style\fP the widget +is set in the context \fB:zle:*\fP to \fBtrue\fP if the word style is +\fBbash\fP and \fBfalse\fP otherwise\&. It may be overridden by setting it in +the more specific context \fB:zle:forward\-word*\fP\&. +.PP +It is possible to create widgets with specific behaviour by defining +a new widget implemented by the appropriate generic function, then +setting a style for the context of the specific widget\&. For example, +the following defines a widget \fBbackward\-kill\-space\-word\fP using +\fBbackward\-kill\-word\-match\fP, the generic widget implementing +\fBbackward\-kill\-word\fP behaviour, and ensures that the new widget +always implements space\-delimited behaviour\&. +.PP +.RS +.nf +\fBzle \-N backward\-kill\-space\-word backward\-kill\-word\-match +zstyle :zle:backward\-kill\-space\-word word\-style space\fP +.fi +.RE +.PP +The widget \fBbackward\-kill\-space\-word\fP can now be bound to a key\&. +.PP +Here are some further examples of use of the styles, actually taken from the +simplified interface in \fBselect\-word\-style\fP: +.PP +.RS +.nf +\fBzstyle \&':zle:*' word\-style standard +zstyle \&':zle:*' word\-chars ''\fP +.fi +.RE +.PP +Implements bash\-style word handling for all widgets, i\&.e\&. only +alphanumerics are word characters; equivalent to setting +the parameter \fBWORDCHARS\fP empty for the given context\&. +.PP +.RS +.nf +\fBstyle \&':zle:*kill*' word\-style space\fP +.fi +.RE +.PP +Uses space\-delimited words for widgets with the word `kill\&' in the name\&. +Neither of the styles \fBword\-chars\fP nor \fBword\-class\fP is used in this case\&. +.PP +Here are some examples of use of the \fBword\-context\fP style to extend +the context\&. +.PP +.RS +.nf +\fBzstyle \&':zle:*' word\-context \e + "*/*" filename "[[:space:]]" whitespace +zstyle \&':zle:transpose\-words:whitespace' word\-style shell +zstyle \&':zle:transpose\-words:filename' word\-style normal +zstyle \&':zle:transpose\-words:filename' word\-chars ''\fP +.fi +.RE +.PP +This provides two different ways of using \fBtranspose\-words\fP depending on +whether the cursor is on whitespace between words or on a filename, here +any word containing a \fB/\fP\&. On whitespace, complete arguments as defined +by standard shell rules will be transposed\&. In a filename, only +alphanumerics will be transposed\&. Elsewhere, words will be transposed +using the default style for \fB:zle:transpose\-words\fP\&. +.PP +The word matching and all the handling of \fBzstyle\fP settings is actually +implemented by the function \fBmatch\-words\-by\-style\fP\&. This can be used to +create new user\-defined widgets\&. The calling function should set the local +parameter \fBcurcontext\fP to \fB:zle:\fP\fIwidget\fP, create the local +parameter \fBmatched_words\fP and call \fBmatch\-words\-by\-style\fP with no +arguments\&. On return, \fBmatched_words\fP will be set to an array with the +elements: (1) the start of the line (2) the word before the cursor (3) any +non\-word characters between that word and the cursor (4) any non\-word +character at the cursor position plus any remaining non\-word characters +before the next word, including all characters specified by the +\fBskip\-chars\fP style, (5) the word at or following the cursor (6) any +non\-word characters following that word (7) the remainder of the line\&. Any +of the elements may be an empty string; the calling function should test +for this to decide whether it can perform its function\&. +.PP +If the variable \fBmatched_words\fP is defined by the caller to +\fBmatch\-words\-by\-style\fP as an associative array (\fBlocal \-A +matched_words\fP), then the seven values given above should be retrieved +from it as elements named \fBstart\fP, \fBword\-before\-cursor\fP, +\fBws\-before\-cursor\fP, \fBws\-after\-cursor\fP, \fBword\-after\-cursor\fP, +\fBws\-after\-word\fP, and \fBend\fP\&. In addition the element +\fBis\-word\-start\fP is 1 if the cursor is on the start of a word or +subword, or on white space before it (the cases can be distinguished by +testing the \fBws\-after\-cursor\fP element) and 0 otherwise\&. This form is +recommended for future compatibility\&. +.PP +It is possible to pass options with arguments to \fBmatch\-words\-by\-style\fP +to override the use of styles\&. The options are: +.PD 0 +.TP +\fB\-w\fP +\fIword\-style\fP +.TP +\fB\-s\fP +\fIskip\-chars\fP +.TP +\fB\-c\fP +\fIword\-class\fP +.TP +\fB\-C\fP +\fIword\-chars\fP +.TP +\fB\-r\fP +\fIsubword\-range\fP +.PD +.PP +For example, \fBmatch\-words\-by\-style \-w shell \-c 0\fP may be used to +extract the command argument around the cursor\&. +.PP +The \fBword\-context\fP style is implemented by the function +\fBmatch\-word\-context\fP\&. This should not usually need to be called +directly\&. +.RE +.TP +\fBbracketed\-paste\-magic\fP +The \fBbracketed\-paste\fP widget (see the subsection `Miscellaneous\&' in +\fIzshzle\fP(1)) +inserts pasted text literally into the editor buffer rather than interpret +it as keystrokes\&. This disables some common usages where the self\-insert +widget is replaced in order to accomplish some extra processing\&. An +example is the contributed \fBurl\-quote\-magic\fP widget described below\&. +.RS +.PP +The \fBbracketed\-paste\-magic\fP widget is meant to replace \fBbracketed\-paste\fP +with a wrapper that re\-enables these self\-insert actions, and other +actions as selected by zstyles\&. Therefore this widget is installed with + +.RS +.nf +\fBautoload \-Uz bracketed\-paste\-magic +zle \-N bracketed\-paste bracketed\-paste\-magic\fP +.fi +.RE +.PP +Other than enabling some widget processing, \fBbracketed\-paste\-magic\fP +attempts to replicate \fBbracketed\-paste\fP as faithfully as possible\&. +.PP +The following zstyles may be set to control processing of pasted text\&. +All are looked up in the context `\fB:bracketed\-paste\-magic\fP\&'\&. +.PP +.PD 0 +.TP +.PD +\fBactive\-widgets\fP +A list of patterns matching widget names that should be activated during +the paste\&. All other key sequences are processed as self\-insert\-unmeta\&. +The default is `\fBself\-*\fP\&' so any user\-defined widgets named with that +prefix are active along with the builtin self\-insert\&. +.RS +.PP +If this style is not set (explicitly deleted) or set to an empty value, +no widgets are active and the pasted text is inserted literally\&. If the +value includes `\fBundefined\-key\fP\&', any unknown sequences are discarded +from the pasted text\&. +.RE +.TP +\fBinactive\-keys\fP +The inverse of \fBactive\-widgets\fP, a list of key sequences that always use +\fBself\-insert\-unmeta\fP even when bound to an active widget\&. Note that +this is a list of literal key sequences, not patterns\&. +.TP +\fBpaste\-init\fP +A list of function names, called in widget context (but not as widgets)\&. +The functions are called in order until one of them returns a non\-zero +status\&. The parameter `\fBPASTED\fP\&' contains the initial state of the +pasted text\&. All other ZLE parameters such as `\fBBUFFER\fP\&' have their +normal values and side\-effects, and full history is available, so for +example \fBpaste\-init\fP functions may move words from \fBBUFFER\fP into +\fBPASTED\fP to make those words visible to the \fBactive\-widgets\fP\&. +.RS +.PP +A non\-zero return from a \fBpaste\-init\fP function does \fInot\fP prevent the +paste itself from proceeding\&. +.PP +Loading \fBbracketed\-paste\-magic\fP defines \fBbackward\-extend\-paste\fP, a +helper function for use in \fBpaste\-init\fP\&. +.PP +.RS +.nf +\fBzstyle :bracketed\-paste\-magic paste\-init \e + backward\-extend\-paste\fP +.fi +.RE +.PP +When a paste would insert into the middle of a word or append text to a +word already on the line, \fBbackward\-extend\-paste\fP moves the prefix +from \fBLBUFFER\fP into \fBPASTED\fP so that the \fBactive\-widgets\fP see the +full word so far\&. This may be useful with \fBurl\-quote\-magic\fP\&. +.RE +.TP +\fBpaste\-finish\fP +Another list of function names called in order until one returns non\-zero\&. +These functions are called \fIafter\fP the pasted text has been processed +by the \fBactive\-widgets\fP, but \fIbefore\fP it is inserted into `\fBBUFFER\fP\&'\&. +ZLE parameters have their normal values and side\-effects\&. +.RS +.PP +A non\-zero return from a \fBpaste\-finish\fP function does \fInot\fP prevent +the paste itself from proceeding\&. +.PP +Loading \fBbracketed\-paste\-magic\fP also defines \fBquote\-paste\fP, a helper +function for use in \fBpaste\-finish\fP\&. +.PP +.RS +.nf +\fBzstyle :bracketed\-paste\-magic paste\-finish \e + quote\-paste +zstyle :bracketed\-paste\-magic:finish quote\-style \e + qqq\fP +.fi +.RE +.PP +When the pasted text is inserted into \fBBUFFER\fP, it is quoted per the +\fBquote\-style\fP value\&. To forcibly turn off the built\-in numeric prefix +quoting of \fBbracketed\-paste\fP, use: +.PP +.RS +.nf +\fBzstyle :bracketed\-paste\-magic:finish quote\-style \e + none\fP +.fi +.RE +.RE +.PP +\fIImportant:\fP During \fBactive\-widgets\fP processing of the paste (after +\fBpaste\-init\fP and before \fBpaste\-finish\fP), \fBBUFFER\fP starts empty and +history is restricted, so cursor motions, etc\&., may not pass outside of +the pasted content\&. Text assigned to \fBBUFFER\fP by the active widgets +is copied back into \fBPASTED\fP before \fBpaste\-finish\fP\&. +.RE +.TP +\fBcopy\-earlier\-word\fP +This widget works like a combination of \fBinsert\-last\-word\fP and +\fBcopy\-prev\-shell\-word\fP\&. Repeated invocations of the widget retrieve +earlier words on the relevant history line\&. With a numeric argument +\fIN\fP, insert the \fIN\fPth word from the history line; \fIN\fP may be +negative to count from the end of the line\&. +.RS +.PP +If \fBinsert\-last\-word\fP has been used to retrieve the last word on a +previous history line, repeated invocations will replace that word with +earlier words from the same line\&. +.PP +Otherwise, the widget applies to words on the line currently being edited\&. +The \fBwidget\fP style can be set to the name of another widget that should +be called to retrieve words\&. This widget must accept the same three +arguments as \fBinsert\-last\-word\fP\&. +.RE +.TP +\fBcycle\-completion\-positions\fP +After inserting an unambiguous string into the command line, the new +function based completion system may know about multiple places in +this string where characters are missing or differ from at least one +of the possible matches\&. It will then place the cursor on the +position it considers to be the most interesting one, i\&.e\&. the one +where one can disambiguate between as many matches as possible with as +little typing as possible\&. +.RS +.PP +This widget allows the cursor to be easily moved to the other interesting +spots\&. It can be invoked repeatedly to cycle between all positions +reported by the completion system\&. +.RE +.TP +\fBdelete\-whole\-word\-match\fP +This is another function which works like the \fB\-match\fP functions +described immediately above, i\&.e\&. using styles to decide the word +boundaries\&. However, it is not a replacement for any existing function\&. +.RS +.PP +The basic behaviour is to delete the word around the cursor\&. There is no +numeric argument handling; only the single word around the cursor is +considered\&. If the widget contains the string \fBkill\fP, the removed text +will be placed in the cutbuffer for future yanking\&. This can be obtained +by defining \fBkill\-whole\-word\-match\fP as follows: +.PP +.RS +.nf +\fBzle \-N kill\-whole\-word\-match delete\-whole\-word\-match\fP +.fi +.RE +.PP +and then binding the widget \fBkill\-whole\-word\-match\fP\&. +.RE +.TP +\fBup\-line\-or\-beginning\-search\fP, \fBdown\-line\-or\-beginning\-search\fP +These widgets are similar to the builtin functions \fBup\-line\-or\-search\fP +and \fBdown\-line\-or\-search\fP: if in a multiline buffer they move up or +down within the buffer, otherwise they search for a history line matching +the start of the current line\&. In this case, however, they search for +a line which matches the current line up to the current cursor position, in +the manner of \fBhistory\-beginning\-search\-backward\fP and \fB\-forward\fP, rather +than the first word on the line\&. +.TP +\fBedit\-command\-line\fP +Edit the command line using your visual editor, as in \fBksh\fP\&. +.RS +.PP +.RS +.nf +\fBbindkey \-M vicmd v edit\-command\-line\fP +.fi +.RE +.PP +The editor to be used can also be specified using the \fBeditor\fP style in +the context of the widget\&. It is specified as an array of command and +arguments: +.PP +.RS +.nf +\fBzstyle :zle:edit\-command\-line editor gvim \-f\fP +.fi +.RE +.RE +.TP +\fBexpand\-absolute\-path\fP +Expand the file name under the cursor to an absolute path, resolving +symbolic links\&. Where possible, the initial path segment is turned +into a named directory or reference to a user\&'s home directory\&. +.TP +\fBhistory\-search\-end\fP +This function implements the widgets +\fBhistory\-beginning\-search\-backward\-end\fP and +\fBhistory\-beginning\-search\-forward\-end\fP\&. These commands work by first +calling the corresponding builtin widget (see +`History Control\&' in \fIzshzle\fP(1)) and then moving the cursor to the end of the line\&. The original cursor +position is remembered and restored before calling the builtin widget a +second time, so that the same search is repeated to look farther through +the history\&. +.RS +.PP +Although you \fBautoload\fP only one function, the commands to use it are +slightly different because it implements two widgets\&. +.PP +.RS +.nf +\fBzle \-N history\-beginning\-search\-backward\-end \e + history\-search\-end +zle \-N history\-beginning\-search\-forward\-end \e + history\-search\-end +bindkey \&'\ee^P' history\-beginning\-search\-backward\-end +bindkey \&'\ee^N' history\-beginning\-search\-forward\-end\fP +.fi +.RE +.RE +.TP +\fBhistory\-beginning\-search\-menu\fP +This function implements yet another form of history searching\&. The +text before the cursor is used to select lines from the history, +as for \fBhistory\-beginning\-search\-backward\fP except that all matches are +shown in a numbered menu\&. Typing the appropriate digits inserts the +full history line\&. Note that leading zeroes must be typed (they are only +shown when necessary for removing ambiguity)\&. The entire history is +searched; there is no distinction between forwards and backwards\&. +.RS +.PP +With a numeric argument, the search is not anchored to the start of +the line; the string typed by the use may appear anywhere in the line +in the history\&. +.PP +If the widget name contains `\fB\-end\fP\&' the cursor is moved to the end of +the line inserted\&. If the widget name contains `\fB\-space\fP\&' any space +in the text typed is treated as a wildcard and can match anything (hence +a leading space is equivalent to giving a numeric argument)\&. Both +forms can be combined, for example: +.PP +.RS +.nf +\fBzle \-N history\-beginning\-search\-menu\-space\-end \e + history\-beginning\-search\-menu\fP +.fi +.RE +.RE +.TP +\fBhistory\-pattern\-search\fP +The function \fBhistory\-pattern\-search\fP implements widgets which prompt +for a pattern with which to search the history backwards or forwards\&. The +pattern is in the usual zsh format, however the first character may be +\fB^\fP to anchor the search to the start of the line, and the last character +may be \fB$\fP to anchor the search to the end of the line\&. If the +search was not anchored to the end of the line the cursor is positioned +just after the pattern found\&. +.RS +.PP +The commands to create bindable widgets are similar to those in the +example immediately above: +.PP +.RS +.nf +\fBautoload \-U history\-pattern\-search +zle \-N history\-pattern\-search\-backward history\-pattern\-search +zle \-N history\-pattern\-search\-forward history\-pattern\-search\fP +.fi +.RE +.RE +.TP +\fBincarg\fP +Typing the keystrokes for this widget with the cursor placed on or to the +left of an integer causes that integer to be incremented by one\&. With a +numeric argument, the number is incremented by the amount of the +argument (decremented if the numeric argument is negative)\&. The shell +parameter \fBincarg\fP may be set to change the default increment to +something other than one\&. +.RS +.PP +.RS +.nf +\fBbindkey \&'^X+' incarg\fP +.fi +.RE +.RE +.TP +\fBincremental\-complete\-word\fP +This allows incremental completion of a word\&. After starting this +command, a list of completion choices can be shown after every character +you type, which you can delete with \fB^H\fP or \fBDEL\fP\&. Pressing return +accepts the completion so far and returns you to normal editing (that is, +the command line is \fInot\fP immediately executed)\&. You can hit \fBTAB\fP to +do normal completion, \fB^G\fP to abort back to the state when you started, +and \fB^D\fP to list the matches\&. +.RS +.PP +This works only with the new function based completion system\&. +.PP +.RS +.nf +\fBbindkey \&'^Xi' incremental\-complete\-word\fP +.fi +.RE +.RE +.TP +\fBinsert\-composed\-char\fP +This function allows you to compose characters that don\&'t appear on the +keyboard to be inserted into the command line\&. The command is followed by +two keys corresponding to ASCII characters (there is no prompt)\&. For +accented characters, the two keys are a base character followed by a code +for the accent, while for other special characters the two characters +together form a mnemonic for the character to be inserted\&. The +two\-character codes are a subset of those given by RFC 1345 (see for +example \fBhttp://www\&.faqs\&.org/rfcs/rfc1345\&.html\fP)\&. +.RS +.PP +The function may optionally be followed by up to two characters which +replace one or both of the characters read from the keyboard; if both +characters are supplied, no input is read\&. For example, +\fBinsert\-composed\-char a:\fP can be used within a widget to insert an a with +umlaut into the command line\&. This has the advantages over use of a +literal character that it is more portable\&. +.PP +For best results zsh should have been built with support for multibyte +characters (configured with \fB\-\-enable\-multibyte\fP); however, the function +works for the limited range of characters available in single\-byte +character sets such as ISO\-8859\-1\&. +.PP +The character is converted into the local representation and +inserted into the command line at the cursor position\&. +(The conversion is done within the shell, using whatever facilities +the C library provides\&.) With a numeric argument, the character and its +code are previewed in the status line +.PP +The function may be run outside zle in which case it prints the character +(together with a newline) to standard output\&. Input is still read from +keystrokes\&. +.PP +See \fBinsert\-unicode\-char\fP for an alternative way of inserting Unicode +characters using their hexadecimal character number\&. +.PP +The set of accented characters is reasonably complete up to Unicode +character U+0180, the set of special characters less so\&. However, it +is very sporadic from that point\&. Adding new characters is easy, +however; see the function \fBdefine\-composed\-chars\fP\&. Please send any +additions to \fBzsh\-workers@zsh\&.org\fP\&. +.PP +The codes for the second character when used to accent the first are as +follows\&. Note that not every character can take every accent\&. +.PD 0 +.TP +\fB!\fP +Grave\&. +.TP +\fB\&'\fP +Acute\&. +.TP +\fB>\fP +Circumflex\&. +.TP +\fB?\fP +Tilde\&. (This is not \fB~\fP as RFC 1345 does not assume that +character is present on the keyboard\&.) +.TP +\fB\-\fP +Macron\&. (A horizontal bar over the base character\&.) +.TP +\fB(\fP +Breve\&. (A shallow dish shape over the base character\&.) +.TP +\fB\&.\fP +Dot above the base character, or in the case of \fBi\fP no dot, +or in the case of \fBL\fP and \fBl\fP a centered dot\&. +.TP +\fB:\fP +Diaeresis (Umlaut)\&. +.TP +\fBc\fP +Cedilla\&. +.TP +\fB_\fP +Underline, however there are currently no underlined characters\&. +.TP +\fB/\fP +Stroke through the base character\&. +.TP +\fB"\fP +Double acute (only supported on a few letters)\&. +.TP +\fB;\fP +Ogonek\&. (A little forward facing hook at the bottom right +of the character\&.) +.TP +\fB<\fP +Caron\&. (A little v over the letter\&.) +.TP +\fB0\fP +Circle over the base character\&. +.TP +\fB2\fP +Hook over the base character\&. +.TP +\fB9\fP +Horn over the base character\&. +.PD +.PP +The most common characters from the Arabic, Cyrillic, Greek and Hebrew +alphabets are available; consult RFC 1345 for the appropriate sequences\&. +In addition, a set of two letter codes not in RFC 1345 are available for +the double\-width characters corresponding to ASCII characters from \fB!\fP +to \fB~\fP (0x21 to 0x7e) by preceding the character with \fB^\fP, for +example \fB^A\fP for a double\-width \fBA\fP\&. +.PP +The following other two\-character sequences are understood\&. +.PP +.PD 0 +.TP +.PD +ASCII characters +These are already present on most keyboards: +.PD 0 +.TP +\fB<(\fP +Left square bracket +.TP +\fB//\fP +Backslash (solidus) +.TP +\fB)>\fP +Right square bracket +.TP +\fB(!\fP +Left brace (curly bracket) +.TP +\fB!!\fP +Vertical bar (pipe symbol) +.TP +\fB!)\fP +Right brace (curly bracket) +.TP +\fB\&'?\fP +Tilde +.PD +.TP +Special letters +Characters found in various variants of the Latin alphabet: +.PD 0 +.TP +\fBss\fP +Eszett (scharfes S) +.TP +\fBD\-\fP, \fBd\-\fP +Eth +.TP +\fBTH\fP, \fBth\fP +Thorn +.TP +\fBkk\fP +Kra +.TP +\fB\&'n\fP +\&'n +.TP +\fBNG\fP, \fBng\fP +Ng +.TP +\fBOI\fP, \fBoi\fP +Oi +.TP +\fByr\fP +yr +.TP +\fBED\fP +ezh +.PD +.TP +Currency symbols +.PD 0 +.TP +\fBCt\fP +Cent +.TP +\fBPd\fP +Pound sterling (also lira and others) +.TP +\fBCu\fP +Currency +.TP +\fBYe\fP +Yen +.TP +\fBEu\fP +Euro (N\&.B\&. not in RFC 1345) +.PD +.TP +Punctuation characters +References to "right" quotes indicate the shape (like a 9 rather than 6) +rather than their grammatical use\&. (For example, a "right" low double +quote is used to open quotations in German\&.) +.PD 0 +.TP +\fB!I\fP +Inverted exclamation mark +.TP +\fBBB\fP +Broken vertical bar +.TP +\fBSE\fP +Section +.TP +\fBCo\fP +Copyright +.TP +\fB\-a\fP +Spanish feminine ordinal indicator +.TP +\fB<<\fP +Left guillemet +.TP +\fB\-\fP\fB\-\fP +Soft hyphen +.TP +\fBRg\fP +Registered trade mark +.TP +\fBPI\fP +Pilcrow (paragraph) +.TP +\fB\-o\fP +Spanish masculine ordinal indicator +.TP +\fB>>\fP +Right guillemet +.TP +\fB?I\fP +Inverted question mark +.TP +\fB\-1\fP +Hyphen +.TP +\fB\-N\fP +En dash +.TP +\fB\-M\fP +Em dash +.TP +\fB\-3\fP +Horizontal bar +.TP +\fB:3\fP +Vertical ellipsis +.TP +\fB\&.3\fP +Horizontal midline ellipsis +.TP +\fB!2\fP +Double vertical line +.TP +\fB=2\fP +Double low line +.TP +\fB\&'6\fP +Left single quote +.TP +\fB\&'9\fP +Right single quote +.TP +\fB\&.9\fP +"Right" low quote +.TP +\fB9\&'\fP +Reversed "right" quote +.TP +\fB"6\fP +Left double quote +.TP +\fB"9\fP +Right double quote +.TP +\fB:9\fP +"Right" low double quote +.TP +\fB9"\fP +Reversed "right" double quote +.TP +\fB/\-\fP +Dagger +.TP +\fB/=\fP +Double dagger +.PD +.TP +Mathematical symbols +.PD 0 +.TP +\fBDG\fP +Degree +.TP +\fB\-2\fP, \fB+\-\fP, \fB\-+\fP +\- sign, +/\- sign, \-/+ sign +.TP +\fB2S\fP +Superscript 2 +.TP +\fB3S\fP +Superscript 3 +.TP +\fB1S\fP +Superscript 1 +.TP +\fBMy\fP +Micro +.TP +\fB\&.M\fP +Middle dot +.TP +\fB14\fP +Quarter +.TP +\fB12\fP +Half +.TP +\fB34\fP +Three quarters +.TP +\fB*X\fP +Multiplication +.TP +\fB\-:\fP +Division +.TP +\fB%0\fP +Per mille +.TP +\fBFA\fP, \fBTE\fP, \fB/0\fP +For all, there exists, empty set +.TP +\fBdP\fP, \fBDE\fP, \fBNB\fP +Partial derivative, delta (increment), del +(nabla) +.TP +\fB(\-\fP, \fB\-)\fP +Element of, contains +.TP +\fB*P\fP, \fB+Z\fP +Product, sum +.TP +\fB*\-\fP, \fBOb\fP, \fBSb\fP +Asterisk, ring, bullet +.TP +\fBRT\fP, \fB0(\fP, \fB00\fP +Root sign, proportional to, infinity +.PD +.TP +Other symbols +.PD 0 +.TP +\fBcS\fP, \fBcH\fP, \fBcD\fP, \fBcC\fP +Card suits: spades, hearts, diamonds, +clubs +.TP +\fBMd\fP, \fBM8\fP, \fBM2\fP, \fBMb\fP, \fBMx\fP, \fBMX\fP +Musical notation: +crotchet (quarter note), quaver (eighth note), semiquavers (sixteenth +notes), flag sign, natural sign, sharp sign +.TP +\fBFm\fP, \fBMl\fP +Female, male +.PD +.TP +Accents on their own +.PD 0 +.TP +\fB\&'>\fP +Circumflex (same as caret, \fB^\fP) +.TP +\fB\&'!\fP +Grave (same as backtick, \fB`\fP) +.TP +\fB\&',\fP +Cedilla +.TP +\fB\&':\fP +Diaeresis (Umlaut) +.TP +\fB\&'m\fP +Macron +.TP +\fB\&''\fP +Acute +.PD +.RE +.TP +\fBinsert\-files\fP +This function allows you type a file pattern, and see the results of the +expansion at each step\&. When you hit return, all expansions are inserted +into the command line\&. +.RS +.PP +.RS +.nf +\fBbindkey \&'^Xf' insert\-files\fP +.fi +.RE +.RE +.TP +\fBinsert\-unicode\-char\fP +When first executed, the user inputs a set of hexadecimal digits\&. +This is terminated with another call to \fBinsert\-unicode\-char\fP\&. +The digits are then turned into the corresponding Unicode character\&. +For example, if the widget is bound to \fB^XU\fP, the character sequence +`\fB^XU 4 c ^XU\fP\&' inserts \fBL\fP (Unicode U+004c)\&. +.RS +.PP +See \fBinsert\-composed\-char\fP for a way of inserting characters +using a two\-character mnemonic\&. +.RE + +.TP +.PD 0 +\fBnarrow\-to\-region \fP[ \fB\-p\fP \fIpre\fP ] [ \fB\-P\fP \fIpost\fP ] +.TP +.PD 0 +\fB \fP[ \fB\-S\fP \fIstatepm\fP | \fB\-R\fP \fIstatepm\fP | [ \fB\-l\fP \fIlbufvar\fP ] [ \fB\-r\fP \fIrbufvar\fP ] ] +.TP +.PD 0 +\fB \fP[ \fB\-n\fP ] [ \fIstart\fP \fIend\fP ] +.TP +.PD +\fBnarrow\-to\-region\-invisible\fP +Narrow the editable portion of the buffer to the region between the cursor +and the mark, which may be in either order\&. The region may not be empty\&. +.RS +.PP +\fBnarrow\-to\-region\fP may be used as a widget or called as a function from a +user\-defined widget; by default, the text outside the editable area remains +visible\&. A \fBrecursive\-edit\fP is performed and the original widening +status is then restored\&. Various options and arguments are available when +it is called as a function\&. +.PP +The options \fB\-p\fP \fIpretext\fP and \fB\-P\fP \fIposttext\fP may be +used to replace the text before and after the display for the duration of +the function; either or both may be an empty string\&. +.PP +If the option \fB\-n\fP is also given, \fIpretext\fP or \fIposttext\fP will only +be inserted if there is text before or after the region respectively which +will be made invisible\&. +.PP +Two numeric arguments may be given which will be used instead of the cursor +and mark positions\&. +.PP +The option \fB\-S\fP \fIstatepm\fP is used to narrow according to the other +options while saving the original state in the parameter with name +\fIstatepm\fP, while the option \fB\-R\fP \fIstatepm\fP is used to restore the +state from the parameter; note in both cases the \fIname\fP of the parameter +is required\&. In the second case, other options and arguments are +irrelevant\&. When this method is used, no \fBrecursive\-edit\fP is performed; +the calling widget should call this function with the option \fB\-S\fP, +perform its own editing on the command line or pass control to the user +via `\fBzle recursive\-edit\fP\&', then call this function with the option +\fB\-R\fP\&. The argument \fIstatepm\fP must be a suitable name for an ordinary +parameter, except that parameters beginning with the prefix \fB_ntr_\fP are +reserved for use within \fBnarrow\-to\-region\fP\&. Typically the parameter will +be local to the calling function\&. +.PP +The options \fB\-l\fP \fIlbufvar\fP and \fB\-r\fP \fIrbufvar\fP may be used to +specify parameters where the widget will store the resulting text from +the operation\&. The parameter \fIlbufvar\fP will contain \fBLBUFFER\fP +and \fIrbufvar\fP will contain \fBRBUFFER\fP\&. Neither of these two options +may be used with \fB\-S\fP or \fB\-R\fP\&. +.PP +\fBnarrow\-to\-region\-invisible\fP is a simple widget which calls +\fBnarrow\-to\-region\fP with arguments which replace any text outside the +region with `\fB\&.\&.\&.\fP\&'\&. It does not take any arguments\&. +.PP +The display is restored (and the widget returns) upon any zle command +which would usually cause the line to be accepted or aborted\&. Hence an +additional such command is required to accept or abort the current line\&. +.PP +The return status of both widgets is zero if the line was accepted, else +non\-zero\&. +.PP +Here is a trivial example of a widget using this feature\&. +.RS +.nf +\fBlocal state +narrow\-to\-region \-p $\&'Editing restricted region\en' \e + \-P \&'' \-S state +zle recursive\-edit +narrow\-to\-region \-R state\fP +.fi +.RE +.RE +.TP +\fBpredict\-on\fP +This set of functions implements predictive typing using history search\&. +After \fBpredict\-on\fP, typing characters causes the editor to look backward +in the history for the first line beginning with what you have typed so +far\&. After \fBpredict\-off\fP, editing returns to normal for the line found\&. +In fact, you often don\&'t even need to use \fBpredict\-off\fP, because if the +line doesn\&'t match something in the history, adding a key performs +standard completion, and then inserts itself if no completions were found\&. +However, editing in the middle of a line is liable to confuse prediction; +see the \fBtoggle\fP style below\&. +.RS +.PP +With the function based completion system (which is needed for this), you +should be able to type \fBTAB\fP at almost any point to advance the cursor +to the next ``interesting\&'' character position (usually the end of the +current word, but sometimes somewhere in the middle of the word)\&. And of +course as soon as the entire line is what you want, you can accept with +return, without needing to move the cursor to the end first\&. +.PP +The first time \fBpredict\-on\fP is used, it creates several additional +widget functions: +.PP +.PD 0 +.TP +\fBdelete\-backward\-and\-predict\fP +Replaces the \fBbackward\-delete\-char\fP +widget\&. You do not need to bind this yourself\&. +.TP +\fBinsert\-and\-predict\fP +Implements predictive typing by replacing the +\fBself\-insert\fP widget\&. You do not need to bind this yourself\&. +.TP +\fBpredict\-off\fP +Turns off predictive typing\&. +.PD +.PP +Although you \fBautoload\fP only the \fBpredict\-on\fP function, it is +necessary to create a keybinding for \fBpredict\-off\fP as well\&. +.PP +.RS +.nf +\fBzle \-N predict\-on +zle \-N predict\-off +bindkey \&'^X^Z' predict\-on +bindkey \&'^Z' predict\-off\fP +.fi +.RE +.RE +.TP +\fBread\-from\-minibuffer\fP +This is most useful when called as a function from inside a widget, but will +work correctly as a widget in its own right\&. It prompts for a value +below the current command line; a value may be input using all of the +standard zle operations (and not merely the restricted set available +when executing, for example, \fBexecute\-named\-cmd\fP)\&. The value is then +returned to the calling function in the parameter \fB$REPLY\fP and the +editing buffer restored to its previous state\&. If the read was aborted +by a keyboard break (typically \fB^G\fP), the function returns status 1 +and \fB$REPLY\fP is not set\&. +.RS +.PP +If one argument is supplied to the function it is taken as a prompt, +otherwise `\fB? \fP\&' is used\&. If two arguments are supplied, they are the +prompt and the initial value of \fB$LBUFFER\fP, and if a third argument is +given it is the initial value of \fB$RBUFFER\fP\&. This provides a default +value and starting cursor placement\&. Upon return the entire buffer is the +value of \fB$REPLY\fP\&. +.PP +One option is available: `\fB\-k\fP \fInum\fP\&' specifies that \fInum\fP +characters are to be read instead of a whole line\&. The line editor is not +invoked recursively in this case, so depending on the terminal settings +the input may not be visible, and only the input keys are placed in +\fB$REPLY\fP, not the entire buffer\&. Note that unlike the \fBread\fP builtin +\fInum\fP must be given; there is no default\&. +.PP +The name is a slight misnomer, as in fact the shell\&'s own minibuffer is +not used\&. Hence it is still possible to call \fBexecuted\-named\-cmd\fP and +similar functions while reading a value\&. +.RE +.TP +\fBreplace\-argument\fP, \fBreplace\-argument\-edit\fP +The function \fBreplace\-argument\fP can be used to replace a command +line argument in the current command line or, if the current command +line is empty, in the last command line executed (the new command line +is not executed)\&. Arguments are as delimited by standard shell syntax, +.RS +.PP +If a numeric argument is given, that specifies the argument to be +replaced\&. 0 means the command name, as in history expansion\&. +A negative numeric argument counts backward from the last word\&. +.PP +If no numeric argument is given, the current argument is replaced; +this is the last argument if the previous history line is being used\&. +.PP +The function prompts for a replacement argument\&. +.PP +If the widget contains the string \fBedit\fP, for example is defined as +.PP +.RS +.nf +\fBzle \-N replace\-argument\-edit replace\-argument\fP +.fi +.RE +.PP +then the function presents the current value of the argument for +editing, otherwise the editing buffer for the replacement is +initially empty\&. +.RE +.TP +.PD 0 +\fBreplace\-string\fP, \fBreplace\-pattern\fP +.TP +.PD +\fBreplace\-string\-again\fP, \fBreplace\-pattern\-again\fP +The function \fBreplace\-string\fP implements three widgets\&. +If defined under the same name as the function, it prompts for two +strings; the first (source) string will be replaced by the second +everywhere it occurs in the line editing buffer\&. +.RS +.PP +If the widget name contains the word `\fBpattern\fP\&', for example by +defining the widget using the command `\fBzle \-N replace\-pattern +replace\-string\fP\&', then the matching is performed using zsh patterns\&. All +zsh extended globbing patterns can be used in the source string; note +that unlike filename generation the pattern does not need to match an +entire word, nor do glob qualifiers have any effect\&. In addition, the +replacement string can contain parameter or command substitutions\&. +Furthermore, a `\fB&\fP\&' in the replacement string will be replaced with +the matched source string, and a backquoted digit `\fB\e\fP\fIN\fP\&' will be +replaced by the \fIN\fPth parenthesised expression matched\&. The form +`\fB\e{\fP\fIN\fP\fB}\fP\&' may be used to protect the digit from following +digits\&. +.PP +If the widget instead contains the word `\fBregex\fP\&' (or `\fBregexp\fP'), +then the matching is performed using regular expressions, respecting +the setting of the option \fBRE_MATCH_PCRE\fP (see the description of the +function \fBregexp\-replace\fP below)\&. The special replacement facilities +described above for pattern matching are available\&. +.PP +By default the previous source or replacement string will not be offered +for editing\&. However, this feature can be activated by setting the style +\fBedit\-previous\fP in the context \fB:zle:\fP\fIwidget\fP (for example, +\fB:zle:replace\-string\fP) to \fBtrue\fP\&. In addition, a positive +numeric argument forces the previous values to be offered, a negative or +zero argument forces them not to be\&. +.PP +The function \fBreplace\-string\-again\fP can be used to repeat the previous +replacement; no prompting is done\&. As with \fBreplace\-string\fP, if the name +of the widget contains the word `\fBpattern\fP\&' or `\fBregex\fP', pattern or +regular expression matching is performed, else a literal string +replacement\&. Note that the previous source and replacement text are the +same whether pattern, regular expression or string matching is used\&. +.PP +In addition, \fBreplace\-string\fP shows the previous replacement above +the prompt, so long as there was one during the current session; if the +source string is empty, that replacement will be repeated without +the widget prompting for a replacement string\&. +.PP +For example, starting from the line: +.PP +.RS +.nf +\fBprint This line contains fan and fond\fP +.fi +.RE +.PP +and invoking \fBreplace\-pattern\fP with the source string +`\fBf(?)n\fP\&' and +the replacement string `\fBc\e1r\fP\&' produces the not very useful line: +.PP +.RS +.nf +\fBprint This line contains car and cord\fP +.fi +.RE +.PP +The range of the replacement string can be limited by using the +\fBnarrow\-to\-region\-invisible\fP widget\&. One limitation of the current +version is that \fBundo\fP will cycle through changes to the replacement +and source strings before undoing the replacement itself\&. +.RE +.TP +\fBsend\-invisible\fP +This is similar to read\-from\-minibuffer in that it may be called as a +function from a widget or as a widget of its own, and interactively reads +input from the keyboard\&. However, the input being typed is concealed and +a string of asterisks (`\fB*\fP\&') is shown instead\&. The value is saved in +the parameter \fB$INVISIBLE\fP to which a reference is inserted into the +editing buffer at the restored cursor position\&. If the read was aborted +by a keyboard break (typically \fB^G\fP) or another escape from editing such +as \fBpush\-line\fP, \fB$INVISIBLE\fP is set to empty and the original buffer +is restored unchanged\&. +.RS +.PP +If one argument is supplied to the function it is taken as a prompt, +otherwise `\fBNon\-echoed text: \fP\&' is used (as in emacs)\&. If a second and +third argument are supplied they are used to begin and end the reference +to \fB$INVISIBLE\fP that is inserted into the buffer\&. The default is to +open with \fB${\fP, then \fBINVISIBLE\fP, and close with \fB}\fP, but many +other effects are possible\&. +.RE +.TP +\fBsmart\-insert\-last\-word\fP +This function may replace the \fBinsert\-last\-word\fP widget, like so: +.RS +.PP +.RS +.nf +\fBzle \-N insert\-last\-word smart\-insert\-last\-word\fP +.fi +.RE +.PP +With a numeric argument, or when passed command line arguments in a call +from another widget, it behaves like \fBinsert\-last\-word\fP, except that +words in comments are ignored when \fBINTERACTIVE_COMMENTS\fP is set\&. +.PP +Otherwise, the rightmost ``interesting\&'' word from the previous command is +found and inserted\&. The default definition of ``interesting\&'' is that the +word contains at least one alphabetic character, slash, or backslash\&. +This definition may be overridden by use of the \fBmatch\fP style\&. The +context used to look up the style is the widget name, so usually the +context is \fB:insert\-last\-word\fP\&. However, you can bind this function to +different widgets to use different patterns: +.PP +.RS +.nf +\fBzle \-N insert\-last\-assignment smart\-insert\-last\-word +zstyle :insert\-last\-assignment match \&'[[:alpha:]][][[:alnum:]]#=*' +bindkey \&'\ee=' insert\-last\-assignment\fP +.fi +.RE +.PP +If no interesting word is found and the \fBauto\-previous\fP style is set to +a true value, the search continues upward through the history\&. When +\fBauto\-previous\fP is unset or false (the default), the widget must be +invoked repeatedly in order to search earlier history lines\&. +.RE +.TP +\fBtranspose\-lines\fP +Only useful with a multi\-line editing buffer; the lines here are +lines within the current on\-screen buffer, not history lines\&. +The effect is similar to the function of the same name in Emacs\&. +.RS +.PP +Transpose the current line with the previous line and move the cursor +to the start of the next line\&. Repeating this (which can be done by +providing a positive numeric argument) has the effect of moving +the line above the cursor down by a number of lines\&. +.PP +With a negative numeric argument, requires two lines above the +cursor\&. These two lines are transposed and the cursor moved to the +start of the previous line\&. Using a numeric argument less than \-1 +has the effect of moving the line above the cursor up by minus that +number of lines\&. +.RE +.TP +\fBurl\-quote\-magic\fP +This widget replaces the built\-in \fBself\-insert\fP to make it easier to +type URLs as command line arguments\&. As you type, the input character is +analyzed and, if it may need quoting, the current word is checked for a +URI scheme\&. If one is found and the current word is not already in +quotes, a backslash is inserted before the input character\&. +.RS +.PP +Styles to control quoting behavior: +.PP +.PD 0 +.TP +.PD +\fBurl\-metas\fP +This style is looked up in the context `\fB:url\-quote\-magic:\fP\fIscheme\fP\&' +(where \fIscheme\fP is that of the current URL, e\&.g\&. "\fBftp\fP")\&. The value +is a string listing the characters to be treated as globbing +metacharacters when appearing in a URL using that scheme\&. The default is +to quote all zsh extended globbing characters, excluding \&'\fB<\fP' and +\&'\fB>\fP' but including braces (as in brace expansion)\&. See also +\fBurl\-seps\fP\&. +.TP +\fBurl\-seps\fP +Like \fBurl\-metas\fP, but lists characters that should be considered command +separators, redirections, history references, etc\&. The default is to +quote the standard set of shell separators, excluding those that overlap +with the extended globbing characters, but including \&'\fB<\fP' and +\&'\fB>\fP' and the first character of \fB$histchars\fP\&. +.TP +\fBurl\-globbers\fP +This style is looked up in the context `\fB:url\-quote\-magic\fP\&'\&. The values +form a list of command names that are expected to do their own globbing +on the URL string\&. This implies that they are aliased to use the +`\fBnoglob\fP\&' modifier\&. When the first word on the line matches one of the +values \fIand\fP the URL refers to a local file (see \fBurl\-local\-schema\fP), +only the \fBurl\-seps\fP characters are quoted; the \fBurl\-metas\fP are left +alone, allowing them to affect command\-line parsing, completion, etc\&. The +default values are a literal `\fBnoglob\fP\&' plus (when the \fBzsh/parameter\fP +module is available) any commands aliased to the helper function +`\fBurlglobber\fP\&' or its alias `\fBgloburl\fP'\&. +.TP +\fBurl\-local\-schema\fP +This style is always looked up in the context `\fB:urlglobber\fP\&', even +though it is used by both url\-quote\-magic and urlglobber\&. The values form +a list of URI schema that should be treated as referring to local files by +their real local path names, as opposed to files which are specified +relative to a web\-server\-defined document root\&. The defaults are +"\fBftp\fP" and "\fBfile\fP"\&. +.TP +\fBurl\-other\-schema\fP +Like \fBurl\-local\-schema\fP, but lists all other URI schema upon which +\fBurlglobber\fP and \fBurl\-quote\-magic\fP should act\&. If the URI on the +command line does not have a scheme appearing either in this list or in +\fBurl\-local\-schema\fP, it is not magically quoted\&. The default values are +"\fBhttp\fP", "\fBhttps\fP", and "\fBftp\fP"\&. When a scheme appears both here +and in \fBurl\-local\-schema\fP, it is quoted differently depending on whether +the command name appears in \fBurl\-globbers\fP\&. +.PP +Loading \fBurl\-quote\-magic\fP also defines a helper function `\fBurlglobber\fP\&' +and aliases `\fBgloburl\fP\&' to `\fBnoglob urlglobber\fP'\&. This function takes +a local URL apart, attempts to pattern\-match the local file portion of the +URL path, and then puts the results back into URL format again\&. +.RE +.TP +\fBvi\-pipe\fP +This function reads a movement command from the keyboard and then +prompts for an external command\&. The part of the buffer covered by +the movement is piped to the external command and then replaced by +the command\&'s output\&. If the movement command is bound to vi\-pipe, +the current line is used\&. +.RS +.PP +The function serves as an example for reading a vi movement command +from within a user\-defined widget\&. +.RE +.TP +\fBwhich\-command\fP +This function is a drop\-in replacement for the builtin widget +\fBwhich\-command\fP\&. It has enhanced behaviour, in that it correctly +detects whether or not the command word needs to be expanded as an +alias; if so, it continues tracing the command word from the expanded +alias until it reaches the command that will be executed\&. +.RS +.PP +The style \fBwhence\fP is available in the context \fB:zle:$WIDGET\fP; this +may be set to an array to give the command and options that will be used to +investigate the command word found\&. The default is \fBwhence \-c\fP\&. +.RE +.TP +\fBzcalc\-auto\-insert\fP +This function is useful together with the \fBzcalc\fP function described in +the section `Mathematical Functions\&'\&. +It should be bound to a key representing a binary operator such +as `\fB+\fP\&', `\fB\-\fP', `\fB*\fP' or `\fB/\fP'\&. When running in zcalc, +if the key occurs at the start of the line or immediately following +an open parenthesis, the text \fB"ans "\fP is inserted before the +representation of the key itself\&. This allows easy use of the +answer from the previous calculation in the current line\&. The +text to be inserted before the symbol typed can be modified by setting +the variable \fBZCALC_AUTO_INSERT_PREFIX\fP\&. +.RS +.PP +Hence, for example, typing `\fB+12\fP\&' followed by return adds 12 +to the previous result\&. +.PP +If zcalc is in RPN mode (\fB\-r\fP option) the effect of this binding is +automatically suppressed as operators alone on a line are meaningful\&. +.PP +When not in zcalc, the key simply inserts the symbol itself\&. +.RE +.PP +.SS "Utility Functions" +.PP +These functions are useful in constructing widgets\&. They +should be loaded with `\fBautoload \-U\fP \fIfunction\fP\&' and called +as indicated from user\-defined widgets\&. +.PP +.PD 0 +.TP +.PD +\fBsplit\-shell\-arguments\fP +This function splits the line currently being edited into shell arguments +and whitespace\&. The result is stored in the array \fBreply\fP\&. The array +contains all the parts of the line in order, starting with any whitespace +before the first argument, and finishing with any whitespace after the last +argument\&. Hence (so long as the option \fBKSH_ARRAYS\fP is not set) +whitespace is given by odd indices in the array and arguments by +even indices\&. Note that no stripping of quotes is done; joining together +all the elements of \fBreply\fP in order is guaranteed to produce the +original line\&. +.RS +.PP +The parameter \fBREPLY\fP is set to the index of the word in \fBreply\fP which +contains the character after the cursor, where the first element has index +1\&. The parameter \fBREPLY2\fP is set to the index of the character under the +cursor in that word, where the first character has index 1\&. +.PP +Hence \fBreply\fP, \fBREPLY\fP and \fBREPLY2\fP should all be made local to +the enclosing function\&. +.PP +See the function \fBmodify\-current\-argument\fP, described below, for +an example of how to call this function\&. +.RE +.TP +\fBmodify\-current\-argument\fP [ \fIexpr\-using\-\fP\fB$ARG\fP | \fIfunc\fP ] +This function provides a simple method of allowing user\-defined widgets +to modify the command line argument under the cursor (or immediately to the +left of the cursor if the cursor is between arguments)\&. +.RS +.PP +The argument can be an expression which when evaluated operates on the shell +parameter \fBARG\fP, which will have been set to the command line argument +under the cursor\&. The expression should be suitably quoted to prevent +it being evaluated too early\&. +.PP +Alternatively, if the argument does not contain the string \fBARG\fP, it +is assumed to be a shell function, to which the current command line +argument is passed as the only argument\&. The function should set the +variable \fBREPLY\fP to the new value for the command line argument\&. +If the function returns non\-zero status, so does the calling function\&. +.PP +For example, a user\-defined widget containing the following code +converts the characters in the argument under the cursor into all upper +case: +.PP +.RS +.nf +\fBmodify\-current\-argument \&'${(U)ARG}'\fP +.fi +.RE +.PP +The following strips any quoting from the current word (whether backslashes +or one of the styles of quotes), and replaces it with single quoting +throughout: +.PP +.RS +.nf +\fBmodify\-current\-argument \&'${(qq)${(Q)ARG}}'\fP +.fi +.RE +.PP +The following performs directory expansion on the command line +argument and replaces it by the absolute path: +.PP +.RS +.nf +\fBexpand\-dir() { + REPLY=${~1} + REPLY=${REPLY:a} +} +modify\-current\-argument expand\-dir\fP +.fi +.RE +.PP +In practice the function \fBexpand\-dir\fP would probably not be defined +within the widget where \fBmodify\-current\-argument\fP is called\&. +.RE +.PP +.SS "Styles" +.PP +The behavior of several of the above widgets can be controlled by the use +of the \fBzstyle\fP mechanism\&. In particular, widgets that interact with +the completion system pass along their context to any completions that +they invoke\&. +.PP +.PD 0 +.TP +.PD +\fBbreak\-keys\fP +This style is used by the \fBincremental\-complete\-word\fP widget\&. Its value +should be a pattern, and all keys matching this pattern will cause the +widget to stop incremental completion without the key having any further +effect\&. Like all styles used directly by +\fBincremental\-complete\-word\fP, this style is looked up using the +context `\fB:incremental\fP\&'\&. +.TP +\fBcompleter\fP +The \fBincremental\-complete\-word\fP and \fBinsert\-and\-predict\fP widgets set +up their top\-level context name before calling completion\&. This allows +one to define different sets of completer functions for normal completion +and for these widgets\&. For example, to use completion, approximation and +correction for normal completion, completion and correction for +incremental completion and only completion for prediction one could use: +.RS +.PP +.RS +.nf +\fBzstyle \&':completion:*' completer \e + _complete _correct _approximate +zstyle \&':completion:incremental:*' completer \e + _complete _correct +zstyle \&':completion:predict:*' completer \e + _complete\fP +.fi +.RE +.PP +It is a good idea to restrict the completers used in prediction, because +they may be automatically invoked as you type\&. The \fB_list\fP and +\fB_menu\fP completers should never be used with prediction\&. The +\fB_approximate\fP, \fB_correct\fP, \fB_expand\fP, and \fB_match\fP completers may +be used, but be aware that they may change characters anywhere in the word +behind the cursor, so you need to watch carefully that the result is what +you intended\&. +.RE +.TP +\fBcursor\fP +The \fBinsert\-and\-predict\fP widget uses this style, in the context +`\fB:predict\fP\&', to decide where to place the cursor after completion has +been tried\&. Values are: +.RS +.PP +.PD 0 +.TP +.PD +\fBcomplete\fP +The cursor is left where it was when completion finished, but only if +it is after a character equal to the one just inserted by the user\&. If +it is after another character, this value is the same as `\fBkey\fP\&'\&. +.TP +\fBkey\fP +The cursor is left +after the \fIn\fPth occurrence of the character just inserted, where +\fIn\fP is the number of times that character appeared in the word +before completion was attempted\&. In short, this has the effect of +leaving the cursor after the character just typed even if the +completion code found out that no other characters need to be inserted +at that position\&. +.PP +Any other value for this style unconditionally leaves the cursor at the +position where the completion code left it\&. +.RE +.TP +\fBlist\fP +When using the \fBincremental\-complete\-word\fP widget, this style says +if the matches should be listed on every key press (if they fit on the +screen)\&. Use the context prefix `\fB:completion:incremental\fP\&'\&. +.RS +.PP +The \fBinsert\-and\-predict\fP widget uses this style to decide if the +completion should be shown even if there is only one possible completion\&. +This is done if the value of this style is the string \fBalways\fP\&. In this +case the context is `\fB:predict\fP\&' (\fInot\fP `\fB:completion:predict\fP')\&. +.RE +.TP +\fBmatch\fP +This style is used by \fBsmart\-insert\-last\-word\fP to provide a pattern +(using full \fBEXTENDED_GLOB\fP syntax) that matches an interesting word\&. +The context is the name of the widget to which \fBsmart\-insert\-last\-word\fP +is bound (see above)\&. The default behavior of \fBsmart\-insert\-last\-word\fP +is equivalent to: +.RS +.PP +.RS +.nf +\fBzstyle :insert\-last\-word match \&'*[[:alpha:]/\e\e]*'\fP +.fi +.RE +.PP +However, you might want to include words that contain spaces: +.PP +.RS +.nf +\fBzstyle :insert\-last\-word match \&'*[[:alpha:][:space:]/\e\e]*'\fP +.fi +.RE +.PP +Or include numbers as long as the word is at least two characters long: +.PP +.RS +.nf +\fBzstyle :insert\-last\-word match \&'*([[:digit:]]?|[[:alpha:]/\e\e])*'\fP +.fi +.RE +.PP +The above example causes redirections like "2>" to be included\&. +.RE +.TP +\fBprompt\fP +The \fBincremental\-complete\-word\fP widget shows the value of this +style in the status line during incremental completion\&. The string +value may contain any of the following substrings in the manner of +the \fBPS1\fP and other prompt parameters: +.RS +.PP +.PD 0 +.TP +.PD +\fB%c\fP +Replaced by the name of the completer function that generated the +matches (without the leading underscore)\&. +.TP +\fB%l\fP +When the \fBlist\fP style is set, +replaced by `\fB\&.\&.\&.\fP\&' if the list of matches is too long to fit on the +screen and with an empty string otherwise\&. If the \fBlist\fP style is +`false\&' or not set, `\fB%l\fP' is always removed\&. +.TP +\fB%n\fP +Replaced by the number of matches generated\&. +.TP +\fB%s\fP +Replaced by `\fB\-no match\-\fP\&', `\fB\-no prefix\-\fP', or an empty string +if there is no completion matching the word on the line, if the +matches have no common prefix different from the word on the line, or +if there is such a common prefix, respectively\&. +.TP +\fB%u\fP +Replaced by the unambiguous part of all matches, if there +is any, and if it is different from the word on the line\&. +.PP +Like `\fBbreak\-keys\fP\&', this uses the `\fB:incremental\fP' context\&. +.RE +.TP +\fBstop\-keys\fP +This style is used by the \fBincremental\-complete\-word\fP widget\&. Its value +is treated similarly to the one for the \fBbreak\-keys\fP style (and uses +the same context: `\fB:incremental\fP\&')\&. However, in +this case all keys matching the pattern given as its value will stop +incremental completion and will then execute their usual function\&. +.TP +\fBtoggle\fP +This boolean style is used by \fBpredict\-on\fP and its related widgets in +the context `\fB:predict\fP\&'\&. If set to one of the standard `true' values, +predictive typing is automatically toggled off in situations where it is +unlikely to be useful, such as when editing a multi\-line buffer or after +moving into the middle of a line and then deleting a character\&. The +default is to leave prediction turned on until an explicit call to +\fBpredict\-off\fP\&. +.TP +\fBverbose\fP +This boolean style is used by \fBpredict\-on\fP and its related widgets in +the context `\fB:predict\fP\&'\&. If set to one of the standard `true' values, +these widgets display a message below the prompt when the predictive state +is toggled\&. This is most useful in combination with the \fBtoggle\fP style\&. +The default does not display these messages\&. +.TP +\fBwidget\fP +This style is similar to the \fBcommand\fP style: For widget functions that +use \fBzle\fP to call other widgets, this style can sometimes be used to +override the widget which is called\&. The context for this style is the +name of the calling widget (\fInot\fP the name of the calling function, +because one function may be bound to multiple widget names)\&. +.RS +.PP +.RS +.nf +\fBzstyle :copy\-earlier\-word widget smart\-insert\-last\-word\fP +.fi +.RE +.PP +Check the documentation for the calling widget or function to determine +whether the \fBwidget\fP style is used\&. +.RE +.PP +.SH "EXCEPTION HANDLING" +.PP +Two functions are provided to enable zsh to provide exception handling in a +form that should be familiar from other languages\&. +.PP +.PD 0 +.TP +.PD +\fBthrow\fP \fIexception\fP +The function \fBthrow\fP throws the named \fIexception\fP\&. The name is +an arbitrary string and is only used by the \fBthrow\fP and \fBcatch\fP +functions\&. An exception is for the most part treated the same as a +shell error, i\&.e\&. an unhandled exception will cause the shell to abort all +processing in a function or script and to return to the top level in an +interactive shell\&. +.TP +\fBcatch\fP \fIexception\-pattern\fP +The function \fBcatch\fP returns status zero if an exception was thrown and +the pattern \fIexception\-pattern\fP matches its name\&. Otherwise it +returns status 1\&. \fIexception\-pattern\fP is a standard +shell pattern, respecting the current setting of the \fBEXTENDED_GLOB\fP +option\&. An alias \fBcatch\fP is also defined to prevent the argument to the +function from matching filenames, so patterns may be used unquoted\&. Note +that as exceptions are not fundamentally different from other shell errors +it is possible to catch shell errors by using an empty string as the +exception name\&. The shell variable \fBCAUGHT\fP is set by \fBcatch\fP to the +name of the exception caught\&. It is possible to rethrow an exception by +calling the \fBthrow\fP function again once an exception has been caught\&. +.PP +The functions are designed to be used together with the \fBalways\fP construct +described in +\fIzshmisc\fP(1)\&. This is important as only this +construct provides the required support for exceptions\&. A typical example +is as follows\&. +.PP +.RS +.nf +\fB{ + # "try" block + # \&.\&.\&. nested code here calls "throw MyExcept" +} always { + # "always" block + if catch MyExcept; then + print "Caught exception MyExcept" + elif catch \&''; then + print "Caught a shell error\&. Propagating\&.\&.\&." + throw \&'' + fi + # Other exceptions are not handled but may be caught further + # up the call stack\&. +}\fP +.fi +.RE +.PP +If all exceptions should be caught, the following idiom might be +preferable\&. +.PP +.RS +.nf +\fB{ + # \&.\&.\&. nested code here throws an exception +} always { + if catch *; then + case $CAUGHT in + (MyExcept) + print "Caught my own exception" + ;; + (*) + print "Caught some other exception" + ;; + esac + fi +}\fP +.fi +.RE +.PP +In common with exception handling in other languages, the exception may be +thrown by code deeply nested inside the `try\&' block\&. However, note that it +must be thrown inside the current shell, not in a subshell forked for a +pipeline, parenthesised current\-shell construct, or some form of +command or process substitution\&. +.PP +The system internally uses the shell variable \fBEXCEPTION\fP to record the +name of the exception between throwing and catching\&. One drawback of this +scheme is that if the exception is not handled the variable \fBEXCEPTION\fP +remains set and may be incorrectly recognised as the name of an exception +if a shell error subsequently occurs\&. Adding \fBunset EXCEPTION\fP at the +start of the outermost layer of any code that uses exception handling will +eliminate this problem\&. +.PP +.SH "MIME FUNCTIONS" +.PP +Three functions are available to provide handling of files recognised by +extension, for example to dispatch a file \fBtext\&.ps\fP when executed as a +command to an appropriate viewer\&. +.PP +.PD 0 +.TP +.PD 0 +\fBzsh\-mime\-setup\fP [ \fB\-fv\fP ] [ \fB\-l\fP [ \fIsuffix\fP \&.\&.\&. ] ] +.TP +.PD +\fBzsh\-mime\-handler\fP [ \fB\-l\fP ] \fIcommand argument\fP \&.\&.\&. +These two functions use the files \fB~/\&.mime\&.types\fP and \fB/etc/mime\&.types\fP, +which associate types and extensions, as well as \fB~/\&.mailcap\fP and +\fB/etc/mailcap\fP files, which associate types and the programs that +handle them\&. These are provided on many systems with the Multimedia +Internet Mail Extensions\&. +.RS +.PP +To enable the system, the function \fBzsh\-mime\-setup\fP should be +autoloaded and run\&. This allows files with extensions to be treated +as executable; such files be completed by the function completion system\&. +The function \fBzsh\-mime\-handler\fP should not need to be called by the +user\&. +.PP +The system works by setting up suffix aliases with `\fBalias \-s\fP\&'\&. +Suffix aliases already installed by the user will not be overwritten\&. +.PP +For suffixes defined in lower case, upper case variants will also +automatically be handled (e\&.g\&. \fBPDF\fP is automatically handled if +handling for the suffix \fBpdf\fP is defined), but not vice versa\&. +.PP +Repeated calls to \fBzsh\-mime\-setup\fP do not override the existing +mapping between suffixes and executable files unless the option \fB\-f\fP +is given\&. Note, however, that this does not override existing suffix +aliases assigned to handlers other than \fBzsh\-mime\-handler\fP\&. +.PP +Calling \fBzsh\-mime\-setup\fP with the option \fB\-l\fP lists the existing +mappings without altering them\&. Suffixes to list (which may contain +pattern characters that should be quoted from immediate interpretation +on the command line) may be given as additional arguments, otherwise +all suffixes are listed\&. +.PP +Calling \fBzsh\-mime\-setup\fP with the option +\fB\-v\fP causes verbose output to be shown during the setup operation\&. +.PP +The system respects the \fBmailcap\fP flags \fBneedsterminal\fP and +\fBcopiousoutput\fP; see \fImailcap\fP(4) or \fImailcap\fP(5) +(the man page\&'s name varies across platforms)\&. +.PP +The functions use the following styles, which are defined with the +\fBzstyle\fP builtin command (see \fIzshmodules\fP(1))\&. They should be defined +before \fBzsh\-mime\-setup\fP is run\&. The contexts used all +start with \fB:mime:\fP, with additional components in some cases\&. +It is recommended that a trailing \fB*\fP (suitably quoted) be appended +to style patterns in case the system is extended in future\&. Some +examples are given below\&. +.PP +For files that have multiple suffixes, e\&.g\&. \fB\&.pdf\&.gz\fP, where the +context includes the suffix it will be looked up starting with the +longest possible suffix until a match for the style is found\&. +For example, if \fB\&.pdf\&.gz\fP produces a match for the handler, that +will be used; otherwise the handler for \fB\&.gz\fP will be used\&. Note +that, owing to the way suffix aliases work, it is always required that +there be a handler for the shortest possible suffix, so in this example +\fB\&.pdf\&.gz\fP can only be handled if \fB\&.gz\fP is also handled (though +not necessarily in the same way)\&. Alternatively, if no handling +for \fB\&.gz\fP on its own is needed, simply adding the command +.PP +.RS +.nf +\fBalias \-s gz=zsh\-mime\-handler\fP +.fi +.RE +.PP +to the initialisation code is sufficient; \fB\&.gz\fP will not be handled +on its own, but may be in combination with other suffixes\&. +.PP +.PD 0 +.TP +.PD +\fBcurrent\-shell\fP +If this boolean style is true, the mailcap handler for the context in +question is run using the \fBeval\fP builtin instead of by starting a new +\fBsh\fP process\&. This is more efficient, but may not work in the occasional +cases where the mailcap handler uses strict POSIX syntax\&. +.TP +\fBdisown\fP +If this boolean style is true, mailcap handlers started in the +background will be disowned, i\&.e\&. not subject to job control within +the parent shell\&. Such handlers nearly always produce their own +windows, so the only likely harmful side effect of setting the style is +that it becomes harder to kill jobs from within the shell\&. +.TP +\fBexecute\-as\-is\fP +This style gives a list of patterns to be matched against files +passed for execution with a handler program\&. If the file matches +the pattern, the entire command line is executed in its current form, +with no handler\&. This is useful for files which might have suffixes +but nonetheless be executable in their own right\&. If the style +is not set, the pattern \fB*(*) *(/)\fP is used; +hence executable files are executed directly and not passed to a +handler, and the option \fBAUTO_CD\fP may be used to change to directories +that happen to have MIME suffixes\&. +.TP +\fBexecute\-never\fP +This style is useful in combination with \fBexecute\-as\-is\fP\&. It is +set to an array of patterns corresponding to full paths to files that +should never be treated as executable, even if the file passed to +the MIME handler matches \fBexecute\-as\-is\fP\&. This is useful for file +systems that don\&'t handle execute permission or that contain executables +from another operating system\&. For example, if \fB/mnt/windows\fP is a +Windows mount, then +.RS +.PP +.RS +.nf +\fBzstyle \&':mime:*' execute\-never '/mnt/windows/*'\fP +.fi +.RE +.PP +will ensure that any files found in that area will be executed as MIME +types even if they are executable\&. As this example shows, the complete +file name is matched against the pattern, regardless of how the file +was passed to the handler\&. The file is resolved to a full path using +the \fB:P\fP modifier described in +the subsection `Modifiers\&' in \fIzshexpn\fP(1); +this means that symbolic links are resolved where possible, so that +links into other file systems behave in the correct fashion\&. +.RE +.TP +\fBfile\-path\fP +Used if the style \fBfind\-file\-in\-path\fP is true for the same context\&. +Set to an array of directories that are used for searching for the +file to be handled; the default is the command path given by the +special parameter \fBpath\fP\&. The shell option \fBPATH_DIRS\fP is respected; +if that is set, the appropriate path will be searched even if the +name of the file to be handled as it appears on the command line contains +a `\fB/\fP\&'\&. +The full context is \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP, as described for the style +\fBhandler\fP\&. +.TP +\fBfind\-file\-in\-path\fP +If set, allows files whose names do not contain absolute paths +to be searched for in the command path or the path specified by the +\fBfile\-path\fP style\&. If the file is not found in the path, it is looked +for locally (whether or not the current directory is in the path); if it is +not found locally, the handler will abort unless the \fBhandle\-nonexistent\fP +style is set\&. Files found in the path are tested as described for +the style \fBexecute\-as\-is\fP\&. +The full context is \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP, as described for the style +\fBhandler\fP\&. +.TP +\fBflags\fP +Defines flags to go with a handler; the context is as for the +\fBhandler\fP style, and the format is as for the flags in \fBmailcap\fP\&. +.TP +\fBhandle\-nonexistent\fP +By default, arguments that don\&'t correspond to files are not passed +to the MIME handler in order to prevent it from intercepting commands found +in the path that happen to have suffixes\&. This style may be set to +an array of extended glob patterns for arguments that will be passed to the +handler even if they don\&'t exist\&. If it is not explicitly set it +defaults to \fB[[:alpha:]]#:/*\fP which allows URLs to be passed to the MIME +handler even though they don\&'t exist in that format in the file system\&. +The full context is \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP, as described for the style +\fBhandler\fP\&. +.TP +\fBhandler\fP +Specifies a handler for a suffix; the suffix is given by the context as +\fB:mime:\&.\fP\fIsuffix\fP\fB:\fP, and the format of the handler is exactly +that in \fBmailcap\fP\&. Note in particular the `\fB\&.\fP\&' and trailing colon +to distinguish this use of the context\&. This overrides any handler +specified by the \fBmailcap\fP files\&. If the handler requires a terminal, +the \fBflags\fP style should be set to include the word \fBneedsterminal\fP, +or if the output is to be displayed through a pager (but not if the +handler is itself a pager), it should include \fBcopiousoutput\fP\&. +.TP +\fBmailcap\fP +A list of files in the format of \fB~/\&.mailcap\fP and +\fB/etc/mailcap\fP to be read during setup, replacing the default list +which consists of those two files\&. The context is \fB:mime:\fP\&. +A \fB+\fP in the list will be replaced by the default files\&. +.TP +\fBmailcap\-priorities\fP +This style is used to resolve multiple mailcap entries for the same MIME +type\&. It consists of an array of the following elements, in descending +order of priority; later entries will be used if earlier entries are +unable to resolve the entries being compared\&. If none of the tests +resolve the entries, the first entry encountered is retained\&. +.RS +.PP +.PD 0 +.TP +.PD +\fBfiles\fP +The order of files (entries in the \fBmailcap\fP style) read\&. Earlier +files are preferred\&. (Note this does not resolve entries in the same file\&.) +.TP +\fBpriority\fP +The priority flag from the mailcap entry\&. The priority is an integer +from 0 to 9 with the default value being 5\&. +.TP +\fBflags\fP +The test given by the \fBmailcap\-prio\-flags\fP option is used to resolve +entries\&. +.TP +\fBplace\fP +Later entries are preferred; as the entries are strictly ordered, this +test always succeeds\&. +.PP +Note that as this style is handled during initialisation, the context +is always \fB:mime:\fP, with no discrimination by suffix\&. +.RE +.TP +\fBmailcap\-prio\-flags\fP +This style is used when the keyword \fBflags\fP is encountered in the +list of tests specified by the \fBmailcap\-priorities\fP style\&. +It should be set to a list of patterns, each of which is tested against +the flags specified in the mailcap entry (in other words, the sets of +assignments found with some entries in the mailcap file)\&. Earlier +patterns in the list are preferred to later ones, and matched patterns +are preferred to unmatched ones\&. +.TP +\fBmime\-types\fP +A list of files in the format of \fB~/\&.mime\&.types\fP and +\fB/etc/mime\&.types\fP to be read during setup, replacing the default list +which consists of those two files\&. The context is \fB:mime:\fP\&. +A \fB+\fP in the list will be replaced by the default files\&. +.TP +\fBnever\-background\fP +If this boolean style is set, the handler for the given context is +always run in the foreground, even if the flags provided in the mailcap +entry suggest it need not be (for example, it doesn\&'t require a +terminal)\&. +.TP +\fBpager\fP +If set, will be used instead of \fB$PAGER\fP or \fBmore\fP to handle +suffixes where the \fBcopiousoutput\fP flag is set\&. The context is +as for \fBhandler\fP, i\&.e\&. \fB:mime:\&.\fP\fIsuffix\fP\fB:\fP for handling +a file with the given \fIsuffix\fP\&. +.PP +Examples: +.PP +.RS +.nf +\fBzstyle \&':mime:*' mailcap ~/\&.mailcap /usr/local/etc/mailcap +zstyle \&':mime:\&.txt:' handler less %s +zstyle \&':mime:\&.txt:' flags needsterminal\fP +.fi +.RE +.PP +When \fBzsh\-mime\-setup\fP is subsequently run, it will look for +\fBmailcap\fP entries in the two files given\&. Files of suffix \fB\&.txt\fP +will be handled by running `\fBless\fP \fIfile\&.txt\fP\&'\&. The flag +\fBneedsterminal\fP is set to show that this program must run attached to a +terminal\&. +.PP +As there are several steps to dispatching a command, the following +should be checked if attempting to execute a file by extension +\fB\&.\fP\fIext\fP does not have the expected effect\&. +.PP +The command `\fBalias \-s\fP \fIext\fP\&' should show +`\fBps=zsh\-mime\-handler\fP\&'\&. If it shows something else, another suffix +alias was already installed and was not overwritten\&. If it shows +nothing, no handler was installed: this is most likely because no +handler was found in the \fB\&.mime\&.types\fP and \fBmailcap\fP combination for +\fB\&.ext\fP files\&. In that case, appropriate handling should be added to +\fB~/\&.mime\&.types\fP and \fBmailcap\fP\&. +.PP +If the extension is handled by \fBzsh\-mime\-handler\fP but the file is +not opened correctly, either the handler defined for the type is +incorrect, or the flags associated with it are in appropriate\&. Running +\fBzsh\-mime\-setup \-l\fP will show the handler and, if there are any, the +flags\&. A \fB%s\fP in the handler is replaced by the file (suitably quoted +if necessary)\&. Check that the handler program listed lists and can +be run in the way shown\&. Also check that the flags \fBneedsterminal\fP or +\fBcopiousoutput\fP are set if the handler needs to be run under a +terminal; the second flag is used if the output should be sent to a pager\&. +An example of a suitable \fBmailcap\fP entry for such a program is: +.PP +.RS +.nf +\fBtext/html; /usr/bin/lynx \&'%s'; needsterminal\fP +.fi +.RE +.PP +Running `\fBzsh\-mime\-handler \-l\fP \fIcommand line\fP\&' prints the command +line that would be executed, simplified to remove the effect of any +flags, and quoted so that the output can be run as a complete zsh +command line\&. This is used by the completion system to decide how to +complete after a file handled by \fBzsh\-mime\-setup\fP\&. +.RE +.TP +\fBpick\-web\-browser\fP +This function is separate from the two MIME functions described above +and can be assigned directly to a suffix: +.RS +.PP +.RS +.nf +\fBautoload \-U pick\-web\-browser +alias \-s html=pick\-web\-browser\fP +.fi +.RE +.PP +It is provided as an intelligent front end to dispatch a web browser\&. +It may be run as either a function or a shell script\&. The status +255 is returned if no browser could be started\&. +.PP +Various styles are available to customize the choice of browsers: +.PP +.PD 0 +.TP +.PD +\fBbrowser\-style\fP +The value of the style is an array giving preferences in decreasing order +for the type of browser to use\&. The values of elements may be +.RS +.PP +.PD 0 +.TP +.PD +\fBrunning\fP +Use a GUI browser that is already running when an X Window display is +available\&. The browsers listed in the \fBx\-browsers\fP style are tried +in order until one is found; if it is, the file will be displayed in +that browser, so the user may need to check whether it has appeared\&. +If no running browser is found, one is not started\&. Browsers other than +Firefox, Opera and Konqueror are assumed to understand the Mozilla +syntax for opening a URL remotely\&. +.TP +\fBx\fP +Start a new GUI browser when an X Window display is available\&. Search for +the availability of one of the browsers listed in the \fBx\-browsers\fP style +and start the first one that is found\&. No check is made for an already +running browser\&. +.TP +\fBtty\fP +Start a terminal\-based browser\&. Search for the availability of one +of the browsers listed in the \fBtty\-browsers\fP style and start the +first one that is found\&. +.PP +If the style is not set the default \fBrunning x tty\fP is used\&. +.RE +.TP +\fBx\-browsers\fP +An array in decreasing order +of preference of browsers to use when running under the X Window System\&. +The array consists of the command name under which to start the +browser\&. They are looked up in the context \fB:mime:\fP (which may +be extended in future, so appending `\fB*\fP\&' is recommended)\&. For +example, +.RS +.PP +.RS +.nf +\fBzstyle \&':mime:*' x\-browsers opera konqueror firefox\fP +.fi +.RE +.PP +specifies that \fBpick\-web\-browser\fP should first look for a running +instance of Opera, Konqueror or Firefox, in that order, and if it +fails to find any should attempt to start Opera\&. The default is +\fBfirefox mozilla netscape opera konqueror\fP\&. +.RE +.TP +\fBtty\-browsers\fP +An array similar to \fBx\-browsers\fP, except that it gives browsers to +use when no X Window display is available\&. The default is +\fBelinks links lynx\fP\&. +.TP +\fBcommand\fP +If it is set this style is used to pick the command +used to open a page for a browser\&. The context is +\fB:mime:browser:new:$browser:\fP to start a new browser or +\fB:mime:browser:running:$browser:\fP to open a URL in a browser already +running on the current X display, where \fB$browser\fP is the value matched +in the \fBx\-browsers\fP or \fBtty\-browsers\fP style\&. The escape sequence +\fB%b\fP in the style\&'s value will be replaced by the browser, while \fB%u\fP +will be replaced by the URL\&. If the style is not set, the default for all +new instances is equivalent to \fB%b %u\fP and the defaults for using running +browsers are equivalent to the values \fBkfmclient openURL %u\fP for +Konqueror, \fBfirefox \-new\-tab %u\fP for Firefox, \fBopera \-newpage %u\fP +for Opera, and \fB%b \-remote "openUrl(%u)"\fP for all others\&. +.RE +.PP +.SH "MATHEMATICAL FUNCTIONS" +.PP +.PD 0 +.TP +.PD +\fBzcalc\fP [ \fB\-erf\fP ] [ \fIexpression\fP \&.\&.\&. ] +A reasonably powerful calculator based on zsh\&'s arithmetic evaluation +facility\&. The syntax is similar to that of formulae in most programming +languages; see +the section `Arithmetic Evaluation\&' in \fIzshmisc\fP(1) for details\&. +.RS +.PP +Non\-programmers should note that, as in many other programming +languages, expressions involving only integers (whether constants +without a `\fB\&.\fP\&', variables containing such constants as strings, or +variables declared to be integers) are by default evaluated using +integer arithmetic, which is not how an ordinary desk calculator +operates\&. To force floating point operation, pass the option \fB\-f\fP; +see further notes below\&. +.PP +If the file \fB~/\&.zcalcrc\fP exists it will be sourced inside the function +once it is set up and about to process the command line\&. This +can be used, for example, to set shell options; \fBemulate \-L zsh\fP +and \fBsetopt extendedglob\fP are in effect at this point\&. Any +failure to source the file if it exists is treated as fatal\&. +As with other initialisation files, the directory \fB$ZDOTDIR\fP is used +instead of \fB$HOME\fP if it is set\&. +.PP +The mathematical library \fBzsh/mathfunc\fP will be loaded if it is +available; see +the section `The zsh/mathfunc Module\&' in \fIzshmodules\fP(1)\&. The mathematical functions +correspond to the raw system libraries, so trigonometric functions are +evaluated using radians, and so on\&. +.PP +Each line typed is evaluated as an expression\&. The prompt shows a number, +which corresponds to a positional parameter where the result of that +calculation is stored\&. For example, the result of the calculation on the +line preceded by `\fB4> \fP\&' is available as \fB$4\fP\&. The last value +calculated is available as \fBans\fP\&. Full command line editing, including +the history of previous calculations, is available; the history is saved in +the file \fB~/\&.zcalc_history\fP\&. To exit, enter a blank line or type `\fB:q\fP\&' +on its own (`\fBq\fP\&' is allowed for historical compatibility)\&. +.PP +A line ending with a single backslash is treated in the same fashion +as it is in command line editing: the backslash is removed, the +function prompts for more input (the prompt is preceded by `\fB\&.\&.\&.\fP\&' +to indicate this), and the lines are combined into one to get the final +result\&. In addition, if the input so far contains more open than +close parentheses \fBzcalc\fP will prompt for more input\&. +.PP +If arguments are given to \fBzcalc\fP on start up, they are used to prime the +first few positional parameters\&. A visual indication of this is given when +the calculator starts\&. +.PP +The constants \fBPI\fP (3\&.14159\&.\&.\&.) and \fBE\fP (2\&.71828\&.\&.\&.) are provided\&. +Parameter assignment is possible, but note that all parameters will be +put into the global namespace unless the \fB:local\fP special command is +used\&. The function creates local variables whose names start with +\fB_\fP, so users should avoid doing so\&. The variables \fBans\fP (the last +answer) and \fBstack\fP (the stack in RPN mode) may be referred to +directly; \fBstack\fP is an array but elements of it are numeric\&. Various +other special variables are used locally with their standard meaning, +for example \fBcompcontext\fP, \fBmatch\fP, \fBmbegin\fP, \fBmend\fP, \fBpsvar\fP\&. +.PP +The output base can be initialised by passing the option `\fB\-#\fP\fIbase\fP\&', +for example `\fBzcalc \-#16\fP\&' (the `\fB#\fP' may have to be quoted, depending +on the globbing options set)\&. +.PP +If the option `\fB\-e\fP\&' is set, the function runs non\-interactively: +the arguments are treated as expressions to be evaluated as if entered +interactively line by line\&. +.PP +If the option `\fB\-f\fP\&' is set, all numbers are treated as floating +point, hence for example the expression `\fB3/4\fP\&' evaluates to 0\&.75 +rather than 0\&. Options must appear in separate words\&. +.PP +If the option `\fB\-r\fP\&' is set, RPN (Reverse Polish Notation) mode is +entered\&. This has various additional properties: +.PD 0 +.TP +.PD +Stack +Evaluated values are maintained in a stack; this is contained in +an array named \fBstack\fP with the most recent value in \fB${stack[1]}\fP\&. +.TP +Operators and functions +If the line entered matches an operator (\fB+\fP, \fB\-\fP, \fB*\fP, +\fB/\fP, \fB**\fP, \fB^\fP, \fB|\fP or \fB&\fP) or a function supplied by the +\fBzsh/mathfunc\fP library, the bottom element or elements of the stack +are popped to use as the argument or arguments\&. The higher elements +of stack (least recent) are used as earlier arguments\&. The result is +then pushed into \fB${stack[1]}\fP\&. +.TP +Expressions +Other expressions are evaluated normally, printed, and added to the +stack as numeric values\&. The syntax within expressions on a single line +is normal shell arithmetic (not RPN)\&. +.TP +Stack listing +If an integer follows the option \fB\-r\fP with no space, then +on every evaluation that many elements of the stack, where available, +are printed instead of just the most recent result\&. Hence, for example, +\fBzcalc \-r4\fP shows \fB$stack[4]\fP to \fB$stack[1]\fP each time results +are printed\&. +.TP +Duplication: \fB=\fP +The pseudo\-operator \fB=\fP causes the most recent element of +the stack to be duplicated onto the stack\&. +.TP +\fBpop\fP +The pseudo\-function \fBpop\fP causes the most recent element of +the stack to be popped\&. A `\fB>\fP\&' on its own has the same effect\&. +.TP +\fB>\fP\fIident\fP +The expression \fB>\fP followed (with no space) by a shell identifier +causes the most recent element of the stack to be popped and +assigned to the variable with that name\&. The variable is +local to the \fBzcalc\fP function\&. +.TP +\fB<\fP\fIident\fP +The expression \fB<\fP followed (with no space) by a shell identifier +causes the value of the variable with that name to be pushed +onto the stack\&. \fIident\fP may be an integer, in which +case the previous result with that number (as shown before +the \fB>\fP in the standard \fBzcalc\fP prompt) is put on the stack\&. +.TP +Exchange: \fBxy\fP +The pseudo\-function \fBxy\fP causes the most recent two elements of +the stack to be exchanged\&. `\fB<>\fP\&' has the same effect\&. +.PP +The prompt is configurable via the parameter \fBZCALCPROMPT\fP, which +undergoes standard prompt expansion\&. The index of the current entry is +stored locally in the first element of the array \fBpsvar\fP, which can be +referred to in \fBZCALCPROMPT\fP as `\fB%1v\fP\&'\&. The default prompt is +`\fB%1v> \fP\&'\&. +.PP +The variable \fBZCALC_ACTIVE\fP is set within the function and can +be tested by nested functions; it has the value \fBrpn\fP if RPN mode is +active, else 1\&. +.PP +A few special commands are available; these are introduced by a colon\&. +For backward compatibility, the colon may be omitted for certain +commands\&. Completion is available if \fBcompinit\fP has been run\&. +.PP +The output precision may be specified within zcalc by special commands +familiar from many calculators\&. +.PD 0 +.TP +.PD +\fB:norm\fP +The default output format\&. It corresponds to the printf \fB%g\fP +specification\&. Typically this shows six decimal digits\&. +.TP +\fB:sci\fP \fIdigits\fP +Scientific notation, corresponding to the printf \fB%g\fP output format with +the precision given by \fIdigits\fP\&. This produces either fixed point or +exponential notation depending on the value output\&. +.TP +\fB:fix\fP \fIdigits\fP +Fixed point notation, corresponding to the printf \fB%f\fP output format with +the precision given by \fIdigits\fP\&. +.TP +\fB:eng\fP \fIdigits\fP +Exponential notation, corresponding to the printf \fB%E\fP output format with +the precision given by \fIdigits\fP\&. +.TP +\fB:raw\fP +Raw output: this is the default form of the output from a math +evaluation\&. This may show more precision than the number actually +possesses\&. +.PP +Other special commands: +.PD 0 +.TP +.PD +\fB:!\fP\fIline\&.\&.\&.\fP +Execute \fIline\&.\&.\&.\fP as a normal shell command line\&. Note that it +is executed in the context of the function, i\&.e\&. with local variables\&. +Space is optional after \fB:!\fP\&. +.TP +\fB:local\fP \fIarg\fP \&.\&.\&. +Declare variables local to the function\&. Other variables +may be used, too, but they will be taken from or put into the global +scope\&. +.TP +\fB:function\fP \fIname\fP [ \fIbody\fP ] +Define a mathematical function or (with no \fIbody\fP) delete it\&. +\fB:function\fP may be abbreviated to \fB:func\fP or simply \fB:f\fP\&. +The \fIname\fP may contain the same characters as a shell function name\&. +The function is defined using \fBzmathfuncdef\fP, see below\&. +.RS +.PP +Note that \fBzcalc\fP takes care of all quoting\&. Hence for example: +.PP +.RS +.nf +\fB:f cube $1 * $1 * $1\fP +.fi +.RE +.PP +defines a function to cube the sole argument\&. Functions so defined, or +indeed any functions defined directly or indirectly using \fBfunctions +\-M\fP, are available to execute by typing only the name on the line in RPN +mode; this pops the appropriate number of arguments off the stack +to pass to the function, i\&.e\&. 1 in the case of the example \fBcube\fP +function\&. If there are optional arguments only the mandatory +arguments are supplied by this means\&. +.RE +.TP +\fB[#\fP\fIbase\fP\fB]\fP +This is not a special command, rather part of normal arithmetic +syntax; however, when this form appears on a line by itself the default +output radix is set to \fIbase\fP\&. Use, for example, `\fB[#16]\fP\&' to display +hexadecimal output preceded by an indication of the base, or `\fB[##16]\fP\&' +just to display the raw number in the given base\&. Bases themselves are +always specified in decimal\&. `\fB[#]\fP\&' restores the normal output format\&. +Note that setting an output base suppresses floating point output; use +`\fB[#]\fP\&' to return to normal operation\&. +.TP +\fB$\fP\fIvar\fP +Print out the value of var literally; does not affect the calculation\&. +To use the value of var, omit the leading `\fB$\fP\&'\&. +.PP +See the comments in the function for a few extra tips\&. +.RE +.TP +.PD 0 +\fBmin(\fP\fIarg\fP\fB, \&.\&.\&.)\fP +.TP +.PD 0 +\fBmax(\fP\fIarg\fP\fB, \&.\&.\&.)\fP +.TP +.PD 0 +\fBsum(\fP\fIarg\fP\fB, \&.\&.\&.)\fP +.TP +.PD +\fBzmathfunc\fP +The function \fBzmathfunc\fP defines the three mathematical functions +\fBmin\fP, \fBmax\fP, and \fBsum\fP\&. The functions \fBmin\fP and \fBmax\fP take +one or more arguments\&. The function \fBsum\fP takes zero or more arguments\&. +Arguments can be of different types (ints and floats)\&. +.RS +.PP +Not to be confused with the \fBzsh/mathfunc\fP module, described in +the section `The zsh/mathfunc Module\&' in \fIzshmodules\fP(1)\&. +.RE +.TP +\fBzmathfuncdef\fP [ \fImathfunc\fP [ \fIbody\fP ] ] +A convenient front end to \fBfunctions \-M\fP\&. +.RS +.PP +With two arguments, define a mathematical function named \fImathfunc\fP +which can be used in any form of arithmetic evaluation\&. \fIbody\fP +is a mathematical expression to implement the function\&. It may +contain references to position parameters \fB$1\fP, \fB$2\fP, \&.\&.\&. +to refer to mandatory parameters and \fB${1:\-\fP\fIdefvalue\fP\fB}\fP \&.\&.\&. +to refer to optional parameters\&. Note that the forms must be +strictly adhered to for the function to calculate the correct number +of arguments\&. The implementation is held in a shell function named +\fBzsh_math_func_\fP\fImathfunc\fP; usually the user will not need +to refer to the shell function directly\&. Any existing function +of the same name is silently replaced\&. +.PP +With one argument, remove the mathematical function \fImathfunc\fP +as well as the shell function implementation\&. +.PP +With no arguments, list all \fImathfunc\fP functions in a form +suitable for restoring the definition\&. +The functions have not necessarily been defined by \fBzmathfuncdef\fP\&. +.RE +.PP +.SH "USER CONFIGURATION FUNCTIONS" +.PP +The \fBzsh/newuser\fP module comes with a function to aid in configuring +shell options for new users\&. If the module is installed, this function can +also be run by hand\&. It is available even if the module\&'s default +behaviour, namely running the function for a new user logging in without +startup files, is inhibited\&. +.PP +.PD 0 +.TP +.PD +\fBzsh\-newuser\-install\fP [ \fB\-f\fP ] +The function presents the user with various options for customizing +their initialization scripts\&. Currently only \fB~/\&.zshrc\fP is handled\&. +\fB$ZDOTDIR/\&.zshrc\fP is used instead if the parameter \fBZDOTDIR\fP is +set; this provides a way for the user to configure a file without +altering an existing \fB\&.zshrc\fP\&. +.RS +.PP +By default the function exits immediately if it finds any of the files +\fB\&.zshenv\fP, \fB\&.zprofile\fP, \fB\&.zshrc\fP, or \fB\&.zlogin\fP in the appropriate +directory\&. The option \fB\-f\fP is required in order to force the function +to continue\&. Note this may happen even if \fB\&.zshrc\fP itself does not +exist\&. +.PP +As currently configured, the function will exit immediately if the +user has root privileges; this behaviour cannot be overridden\&. +.PP +Once activated, the function\&'s behaviour is supposed to be +self\-explanatory\&. Menus are present allowing the user to alter +the value of options and parameters\&. Suggestions for improvements are +always welcome\&. +.PP +When the script exits, the user is given the opportunity to save the new +file or not; changes are not irreversible until this point\&. However, +the script is careful to restrict changes to the file only to a group +marked by the lines `\fB# Lines configured by zsh\-newuser\-install\fP\&' and +`\fB# End of lines configured by zsh\-newuser\-install\fP\&'\&. In addition, +the old version of \fB\&.zshrc\fP is saved to a file with the suffix +\fB\&.zni\fP appended\&. +.PP +If the function edits an existing \fB\&.zshrc\fP, it is up to the user +to ensure that the changes made will take effect\&. For example, if +control usually returns early from the existing \fB\&.zshrc\fP the lines +will not be executed; or a later initialization file may override +options or parameters, and so on\&. The function itself does not attempt to +detect any such conflicts\&. +.RE +.PP +.SH "OTHER FUNCTIONS" +.PP +There are a large number of helpful functions in the \fBFunctions/Misc\fP +directory of the zsh distribution\&. Most are very simple and do not +require documentation here, but a few are worthy of special mention\&. +.PP +.SS "Descriptions" +.PP +.PD 0 +.TP +.PD +\fBcolors\fP +This function initializes several associative arrays to map color names to +(and from) the ANSI standard eight\-color terminal codes\&. These are used +by the prompt theme system (see above)\&. You seldom should need to run +\fBcolors\fP more than once\&. +.RS +.PP +The eight base colors are: \fBblack\fP, \fBred\fP, \fBgreen\fP, \fByellow\fP, +\fBblue\fP, \fBmagenta\fP, \fBcyan\fP, and \fBwhite\fP\&. Each of these has codes for +foreground and background\&. In addition there are seven intensity attributes: +\fBbold\fP, \fBfaint\fP, \fBstandout\fP, \fBunderline\fP, \fBblink\fP, \fBreverse\fP, +and \fBconceal\fP\&. Finally, there are seven codes used to negate attributes: +\fBnone\fP (reset all attributes to the defaults), \fBnormal\fP +(neither bold nor faint), \fBno\-standout\fP, \fBno\-underline\fP, \fBno\-blink\fP, +\fBno\-reverse\fP, and \fBno\-conceal\fP\&. +.PP +Some terminals do not support all combinations of colors and intensities\&. +.PP +The associative arrays are: +.PP +.PD 0 +.TP +.PD 0 +\fBcolor\fP +.TP +.PD +\fBcolour\fP +Map all the color names to their integer codes, and integer codes to the +color names\&. The eight base names map to the foreground color codes, as +do names prefixed with `\fBfg\-\fP\&', such as `\fBfg\-red\fP'\&. Names prefixed +with `\fBbg\-\fP\&', such as `\fBbg\-blue\fP', refer to the background codes\&. The +reverse mapping from code to color yields base name for foreground codes +and the \fBbg\-\fP form for backgrounds\&. +.RS +.PP +Although it is a misnomer to call them `colors\&', these arrays also map the +other fourteen attributes from names to codes and codes to names\&. +.RE +.TP +.PD 0 +\fBfg\fP +.TP +.PD 0 +\fBfg_bold\fP +.TP +.PD +\fBfg_no_bold\fP +Map the eight basic color names to ANSI terminal escape sequences that set +the corresponding foreground text properties\&. The \fBfg\fP sequences change +the color without changing the eight intensity attributes\&. +.TP +.PD 0 +\fBbg\fP +.TP +.PD 0 +\fBbg_bold\fP +.TP +.PD +\fBbg_no_bold\fP +Map the eight basic color names to ANSI terminal escape sequences that set +the corresponding background properties\&. The \fBbg\fP sequences change the +color without changing the eight intensity attributes\&. +.PP +In addition, the scalar parameters \fBreset_color\fP and \fBbold_color\fP are +set to the ANSI terminal escapes that turn off all attributes and turn on +bold intensity, respectively\&. +.RE +.TP +\fBfned\fP [ \fB\-x\fP \fInum\fP ] \fIname\fP +Same as \fBzed \-f\fP\&. This function does not appear in the zsh +distribution, but can be created by linking \fBzed\fP to the name \fBfned\fP +in some directory in your \fBfpath\fP\&. +.TP +\fBhisted\fP [ [ \fIname\fP ] \fIsize\fP ] +Same as \fBzed \-h\fP\&. This function does not appear in the zsh +distribution, but can be created by linking \fBzed\fP to the name \fBhisted\fP +in some directory in your \fBfpath\fP\&. +.TP +\fBis\-at\-least\fP \fIneeded\fP [ \fIpresent\fP ] +Perform a greater\-than\-or\-equal\-to comparison of two strings having the +format of a zsh version number; that is, a string of numbers and text with +segments separated by dots or dashes\&. If the \fIpresent\fP string is not +provided, \fB$ZSH_VERSION\fP is used\&. Segments are paired left\-to\-right in +the two strings with leading non\-number parts ignored\&. If one string has +fewer segments than the other, the missing segments are considered zero\&. +.RS +.PP +This is useful in startup files to set options and other state that are +not available in all versions of zsh\&. +.PP +.RS +.nf +\fBis\-at\-least 3\&.1\&.6\-15 && setopt NO_GLOBAL_RCS +is\-at\-least 3\&.1\&.0 && setopt HIST_REDUCE_BLANKS +is\-at\-least 2\&.6\-17 || print "You can\&'t use is\-at\-least here\&."\fP +.fi +.RE +.RE +.TP +\fBnslookup\fP [ \fIarg\fP \&.\&.\&. ] +This wrapper function for the \fBnslookup\fP command requires the +\fBzsh/zpty\fP module (see +\fIzshmodules\fP(1))\&. It behaves exactly like the standard \fBnslookup\fP +except that it provides customizable prompts (including a right\-side +prompt) and completion of nslookup commands, host names, etc\&. (if you use +the function\-based completion system)\&. Completion styles may be set with +the context prefix `\fB:completion:nslookup\fP\&'\&. +.RS +.PP +See also the \fBpager\fP, \fBprompt\fP and \fBrprompt\fP styles below\&. +.RE +.TP +\fBregexp\-replace\fP \fIvar\fP \fIregexp\fP \fIreplace\fP +Use regular expressions to perform a global search and replace operation +on a variable\&. POSIX extended regular expressions (ERE) are used, +unless the option \fBRE_MATCH_PCRE\fP has been set, in which case +Perl\-compatible regular expressions are used +(this requires the shell to be linked against the \fBpcre\fP +library)\&. +.RS +.PP +\fIvar\fP is the name of the variable containing the string to be matched\&. +The variable will be modified directly by the function\&. The +variables \fBMATCH\fP, \fBMBEGIN\fP, \fBMEND\fP, \fBmatch\fP, \fBmbegin\fP, \fBmend\fP +should be avoided as these are used by the regular expression code\&. +.PP +\fIregexp\fP is the regular expression to match against the string\&. +.PP +\fIreplace\fP is the replacement text\&. This can contain parameter, command +and arithmetic expressions which will be replaced: in particular, a +reference to \fB$MATCH\fP will be replaced by the text matched by the pattern\&. +.PP +The return status is 0 if at least one match was performed, else 1\&. +.PP +Note that if using POSIX EREs, the \fB^\fP or word boundary operators +(where available) may not work properly\&. +.RE +.TP +\fBrun\-help\fP \fIcmd\fP +This function is designed to be invoked by the \fBrun\-help\fP ZLE widget, +in place of the default alias\&. See `Accessing On\-Line Help\&' +above for setup instructions\&. +.RS +.PP +In the discussion which follows, if \fIcmd\fP is a file system path, it is +first reduced to its rightmost component (the file name)\&. +.PP +Help is first sought by looking for a file named \fIcmd\fP in the directory +named by the \fBHELPDIR\fP parameter\&. If no file is found, an assistant +function, alias, or command named \fBrun\-help\-\fIcmd\fP\fP is sought\&. If +found, the assistant is executed with the rest of the current command line +(everything after the command name \fIcmd\fP) as its arguments\&. When +neither file nor assistant is found, the external command +`\fBman\fP \fIcmd\fP\&' is run\&. +.PP +An example assistant for the "ssh" command: +.PP +.RS +.nf +\fBrun\-help\-ssh() { + emulate \-LR zsh + local \-a args + # Delete the "\-l username" option + zparseopts \-D \-E \-a args l: + # Delete other options, leaving: host command + args=(${@:#\-*}) + if [[ ${#args} \-lt 2 ]]; then + man ssh + else + run\-help $args[2] + fi +}\fP +.fi +.RE +.PP +Several of these assistants are provided in the \fBFunctions/Misc\fP +directory\&. These must be autoloaded, or placed as executable scripts in +your search path, in order to be found and used by \fBrun\-help\fP\&. +.PP +.PD 0 +.TP +.PD 0 +\fBrun\-help\-btrfs\fP +.TP +.PD 0 +\fBrun\-help\-git\fP +.TP +.PD 0 +\fBrun\-help\-ip\fP +.TP +.PD 0 +\fBrun\-help\-openssl\fP +.TP +.PD 0 +\fBrun\-help\-p4\fP +.TP +.PD 0 +\fBrun\-help\-sudo\fP +.TP +.PD 0 +\fBrun\-help\-svk\fP +.TP +.PD +\fBrun\-help\-svn\fP +Assistant functions for the +\fBbtrfs\fP, +\fBgit\fP, +\fBip\fP, +\fBopenssl\fP, +\fBp4\fP, +\fBsudo\fP, +\fBsvk\fP, +and +\fBsvn\fP, +commands\&. +.RE +.TP +\fBtetris\fP +Zsh was once accused of not being as complete as Emacs, +because it lacked a Tetris game\&. This function was written to +refute this vicious slander\&. +.RS +.PP +This function must be used as a ZLE widget: +.PP +.RS +.nf +\fBautoload \-U tetris +zle \-N tetris +bindkey \fIkeys\fP tetris\fP +.fi +.RE +.PP +To start a game, execute the widget by typing the \fIkeys\fP\&. Whatever command +line you were editing disappears temporarily, and your keymap is also +temporarily replaced by the Tetris control keys\&. The previous editor state +is restored when you quit the game (by pressing `\fBq\fP\&') or when you lose\&. +.PP +If you quit in the middle of a game, the next invocation of the \fBtetris\fP +widget will continue where you left off\&. If you lost, it will start a new +game\&. +.RE +.TP +\fBtetriscurses\fP +This is a port of the above to zcurses\&. The input handling is improved +a bit so that moving a block sideways doesn\&'t automatically advance a +timestep, and the graphics use unicode block graphics\&. +.RS +.PP +This version does not save the game state between invocations, and is not +invoked as a widget, but rather as: +.PP +.RS +.nf +\fBautoload \-U tetriscurses +tetriscurses\fP +.fi +.RE +.RE +.TP +\fBzargs\fP [ \fIoption\fP \&.\&.\&. \fB\-\fP\fB\-\fP ] [ \fIinput\fP \&.\&.\&. ] [ \fB\-\fP\fB\-\fP \fIcommand\fP [ \fIarg\fP \&.\&.\&. ] ] +This function has a similar purpose to GNU xargs\&. Instead of +reading lines of arguments from the standard input, it takes them from +the command line\&. This is useful because zsh, especially with recursive +glob operators, often can construct a command line for a shell function +that is longer than can be accepted by an external command\&. +.RS +.PP +The \fIoption\fP list represents options of the \fBzargs\fP command itself, +which are the same as those of \fBxargs\fP\&. The \fIinput\fP list is the +collection of strings (often file names) that become the arguments of the +\fBcommand\fP, analogous to the standard input of \fBxargs\fP\&. Finally, the +\fIarg\fP list consists of those arguments (usually options) that are +passed to the \fIcommand\fP each time it runs\&. The \fIarg\fP list precedes +the elements from the \fBinput\fP list in each run\&. If no \fIcommand\fP is +provided, then no \fIarg\fP list may be provided, and in that event the +default command is `\fBprint\fP\&' with arguments `\fB\-r \-\fP\fB\-\fP'\&. +.PP +For example, to get a long \fBls\fP listing of all non\-hidden plain files +in the current directory or its subdirectories: +.PP +.RS +.nf +\fBautoload \-U zargs +zargs \-\- **/*(\&.) \-\- ls \-ld \-\-\fP +.fi +.RE +.PP +The first and third occurrences of `\fB\-\fP\fB\-\fP\&' are used to mark the end +of options for \fBzargs\fP and \fBls\fP respectively to guard against +filenames starting with `\fB\-\fP\&', while the second is used to separate the +list of files from the command to run (`\fBls \-ld \-\-\fP\&')\&. +.PP +The first `\fB\-\fP\fB\-\fP\&' would also be needed if there was a chance the +list might be empty as in: +.PP +.RS +.nf +\fBzargs \-r \-\- \&./*\&.back(#qN) \-\- rm \-f\fP +.fi +.RE +.PP +In the event that the string `\fB\-\fP\fB\-\fP\&' is or may be an \fIinput\fP, the +\fB\-e\fP option may be used to change the end\-of\-inputs marker\&. Note that +this does \fInot\fP change the end\-of\-options marker\&. For example, to use +`\fB\&.\&.\fP\&' as the marker: +.PP +.RS +.nf +\fBzargs \-e\&.\&. \-\- **/*(\&.) \&.\&. ls \-ld \-\-\fP +.fi +.RE +.PP +This is a good choice in that example because no plain file can be named +`\fB\&.\&.\fP\&', but the best end\-marker depends on the circumstances\&. +.PP +The options \fB\-i\fP, \fB\-I\fP, \fB\-l\fP, \fB\-L\fP, and \fB\-n\fP differ slightly +from their usage in \fBxargs\fP\&. There are no input lines for \fBzargs\fP to +count, so \fB\-l\fP and \fB\-L\fP count through the \fIinput\fP list, and \fB\-n\fP +counts the number of arguments passed to each execution of \fIcommand\fP, +\fIincluding\fP any \fIarg\fP list\&. Also, any time \fB\-i\fP or \fB\-I\fP is used, +each \fIinput\fP is processed separately as if by `\fB\-L\fP \fB1\fP\&'\&. +.PP +For details of the other \fBzargs\fP options, see the \fIxargs\fP(1) man page (but note +the difference in function between \fBzargs\fP and \fBxargs\fP) or run +\fBzargs\fP with the \fB\-\fP\fB\-help\fP option\&. +.RE +.TP +.PD 0 +\fBzed\fP [ \fB\-f\fP [ \fB\-x\fP \fInum\fP ] ] \fIname\fP +.TP +.PD 0 +\fBzed\fP [ \fB\-h\fP [ \fIname\fP ] \fIsize\fP ] +.TP +.PD +\fBzed \-b\fP +This function uses the ZLE editor to edit a file or function\&. +.RS +.PP +Only one \fIname\fP argument is allowed\&. +If the \fB\-f\fP option is given, the name is taken to be that of +a function; if the function is marked for autoloading, \fBzed\fP searches +for it in the \fBfpath\fP and loads it\&. Note that functions edited this way +are installed into the current shell, but \fInot\fP written back to the +autoload file\&. In this case the \fB\-x\fP option specifies that leading +tabs indenting the function according to syntax should be converted into +the given number of spaces; `\fB\-x 2\fP\&' is consistent with the layout +of functions distributed with the shell\&. +.PP +Without \fB\-f\fP, \fIname\fP is the path name of the file to edit, which need +not exist; it is created on write, if necessary\&. With \fB\-h\fP, the file is +presumed to contain history events\&. +.PP +When no file name is provided for \fB\-h\fP the current shell history is edited +in place\&. The history is renumbered when zed exits successfully\&. +.PP +When editing history, multi\-line events must have a trailing backslash on +every line before the last\&. +.PP +While editing, the function sets the main keymap to \fBzed\fP and the +vi command keymap to \fBzed\-vicmd\fP\&. These will be copied from the existing +\fBmain\fP and \fBvicmd\fP keymaps if they do not exist the first time \fBzed\fP +is run\&. They can be used to provide special key bindings used only in zed\&. +.PP +If it creates the keymap, \fBzed\fP rebinds the return key to insert a line +break and `\fB^X^W\fP\&' to accept the edit in the \fBzed\fP keymap, and binds +`\fBZZ\fP\&' to accept the edit in the \fBzed\-vicmd\fP keymap\&. +.PP +The bindings alone can be installed by running `\fBzed \-b\fP\&'\&. This is +suitable for putting into a startup file\&. Note that, if rerun, +this will overwrite the existing \fBzed\fP and \fBzed\-vicmd\fP keymaps\&. +.PP +Completion is available, and styles may be set with the context prefix +`\fB:completion:zed:\fP\&'\&. +.PP +A zle widget \fBzed\-set\-file\-name\fP is available\&. This can be called +by name from within zed using `\fB\eex zed\-set\-file\-name\fP\&' or can be +bound to a key in either of the \fBzed\fP or \fBzed\-vicmd\fP keymaps after +`\fBzed \-b\fP\&' has been run\&. When the widget is called, it prompts for +a new name for the file being edited\&. When zed exits the file will be +written under that name and the original file will be left alone\&. The +widget has no effect when invoked from `\fBzed \-f\fP\&'\&. The completion +context is changed to `\fB:completion:zed\-set\-file\-name:\fP\&'\&. When editing +the current history with `\fBzed \-h\fP\&', the history is first updated and +then the file is written, but the global setting of \fBHISTFILE\fP is not +altered\&. +.PP +While \fBzed\-set\-file\-name\fP is running, zed uses the keymap +\fBzed\-normal\-keymap\fP, which is linked from the main keymap in effect +at the time zed initialised its bindings\&. (This is to make the return key +operate normally\&.) The result is that if the main keymap has been changed, +the widget won\&'t notice\&. This is not a concern for most users\&. +.RE +.TP +.PD 0 +\fBzcp\fP [ \fB\-finqQvwW\fP ] \fIsrcpat\fP \fIdest\fP +.TP +.PD +\fBzln\fP [ \fB\-finqQsvwW\fP ] \fIsrcpat\fP \fIdest\fP +Same as \fBzmv \-C\fP and \fBzmv \-L\fP, respectively\&. These functions do not +appear in the zsh distribution, but can be created by linking \fBzmv\fP to +the names \fBzcp\fP and \fBzln\fP in some directory in your \fBfpath\fP\&. +.TP +\fBzkbd\fP +See `Keyboard Definition\&' +above\&. + +.TP +.PD 0 +\fBzmv\fP [ \fB\-finqQsvwW\fP ] [ \fB\-C\fP | \fB\-L\fP | \fB\-M\fP | \-{\fBp\fP|\fBP\fP} \fIprogram\fP ] [ \fB\-o\fP \fIoptstring\fP ] +.TP +.PD +\fB \fP\fIsrcpat\fP \fIdest\fP +Move (usually, rename) files matching the pattern \fIsrcpat\fP to +corresponding files having names of the form given by \fIdest\fP, where +\fIsrcpat\fP contains parentheses surrounding patterns which will be +replaced in turn by \fB$1\fP, \fB$2\fP, \&.\&.\&. in \fIdest\fP\&. For example, +.RS +.PP +.RS +.nf +\fBzmv \&'(*)\&.lis' '$1\&.txt'\fP +.fi +.RE +.PP +renames `\fBfoo\&.lis\fP\&' to `\fBfoo\&.txt\fP', `\fBmy\&.old\&.stuff\&.lis\fP' to +`\fBmy\&.old\&.stuff\&.txt\fP\&', and so on\&. +.PP +The pattern is always treated as an \fBEXTENDED_GLOB\fP pattern\&. Any file +whose name is not changed by the substitution is simply ignored\&. Any +error (a substitution resulted in an empty string, two substitutions gave +the same result, the destination was an existing regular file and \fB\-f\fP +was not given) causes the entire function to abort without doing +anything\&. +.PP +In addition to pattern replacement, the variable \fB$f\fP can be referred +to in the second (replacement) argument\&. This makes it possible to +use variable substitution to alter the argument; see examples below\&. +.PP +Options: +.PP +.PD 0 +.TP +\fB\-f\fP +Force overwriting of destination files\&. Not currently +passed down to the \fBmv\fP/\fBcp\fP/\fBln\fP command due to vagaries of +implementations (but you can use \fB\-o\-f\fP to do that)\&. +.TP +\fB\-i\fP +Interactive: show each line to be executed and ask the user +whether to execute it\&. `\fBY\fP\&' or `\fBy\fP' will execute it, anything else will +skip it\&. Note that you just need to type one character\&. +.TP +\fB\-n\fP +No execution: print what would happen, but don\&'t do it\&. +.TP +\fB\-q\fP +Turn bare glob qualifiers off: now assumed by default, so +this has no effect\&. +.TP +\fB\-Q\fP +Force bare glob qualifiers on\&. Don\&'t turn this on unless +you are actually using glob qualifiers in a pattern\&. +.TP +\fB\-s\fP +Symbolic, passed down to \fBln\fP; only works with \fB\-L\fP\&. +.TP +\fB\-v\fP +Verbose: print each command as it\&'s being executed\&. +.TP +\fB\-w\fP +Pick out wildcard parts of the pattern, as described above, +and implicitly add parentheses for referring to them\&. +.TP +\fB\-W\fP +Just like \fB\-w\fP, with the addition of turning wildcards in +the replacement pattern into sequential \fB${1}\fP \&.\&. \fB${N}\fP references\&. +.TP +\fB\-C\fP +.TP +\fB\-L\fP +.TP +\fB\-M\fP +Force \fBcp\fP, \fBln\fP or \fBmv\fP, respectively, regardless of +the name of the function\&. +.TP +\fB\-p\fP \fIprogram\fP +Call \fIprogram\fP instead of \fBcp\fP, \fBln\fP or +\fBmv\fP\&. Whatever it does, it should at least understand the form +`\fIprogram\fP \fB\-\fP\fB\-\fP \fIoldname\fP \fInewname\fP\&' +where \fIoldname\fP and \fInewname\fP are filenames generated by \fBzmv\fP\&. +\fIprogram\fP will be split into words, so might be e\&.g\&. the name +of an archive tool plus a copy or rename subcommand\&. +.TP +\fB\-P\fP \fIprogram\fP +As \fB\-p\fP \fIprogram\fP, except that +\fIprogram\fP does not accept a following \fB\-\fP\fB\-\fP to indicate the +end of options\&. In this case filenames must already be in a sane +form for the program in question\&. +.TP +\fB\-o\fP \fIoptstring\fP +The \fIoptstring\fP is split into words and +passed down verbatim to the \fBcp\fP, \fBln\fP or \fBmv\fP command called to +perform the work\&. It should probably begin with a `\fB\-\fP\&'\&. +.PD +.PP +Further examples: +.PP +.RS +.nf +\fBzmv \-v \&'(* *)' '${1// /_}'\fP +.fi +.RE +.PP +For any file in the current directory with at least one space in the name, +replace every space by an underscore and display the commands executed\&. +.PP +.RS +.nf +\fBzmv \-v \&'* *' '${f// /_}'\fP +.fi +.RE +.PP +This does exactly the same by referring to the file name stored in \fB$f\fP\&. +.PP +For more complete examples and other implementation details, see the +\fBzmv\fP source file, usually located in one of the directories named in +your \fBfpath\fP, or in \fBFunctions/Misc/zmv\fP in the zsh distribution\&. +.RE +.TP +\fBzrecompile\fP +See `Recompiling Functions\&' +above\&. +.TP +\fBzstyle+\fP \fIcontext\fP \fIstyle\fP \fIvalue\fP [ \fB+\fP \fIsubcontext\fP \fIstyle\fP \fIvalue\fP \&.\&.\&. ] +This makes defining styles a bit simpler by using a single `\fB+\fP\&' as a +special token that allows you to append a context name to the previously +used context name\&. Like this: +.RS +.PP +.RS +.nf +\fBzstyle+ \&':foo:bar' \fIstyle1\fP \fIvalue1\fP \e + +\&':baz' \fIstyle2\fP \fIvalue2\fP \e + +\&':frob' \fIstyle3\fP \fIvalue3\fP\fP +.fi +.RE +.PP +This defines \fIstyle1\fP with \fIvalue1\fP for the context \fB:foo:bar\fP as usual, +but it also defines \fIstyle2\fP with \fIvalue2\fP for the context +\fB:foo:bar:baz\fP and \fIstyle3\fP with \fIvalue3\fP for \fB:foo:bar:frob\fP\&. Any +\fIsubcontext\fP may be the empty string to re\-use the first context +unchanged\&. +.RE +.PP +.SS "Styles" +.PP +.PD 0 +.TP +.PD +\fBinsert\-tab\fP +The \fBzed\fP function \fIsets\fP this style in context `\fB:completion:zed:*\fP\&' +to turn off completion when \fBTAB\fP is typed at the beginning of a line\&. +You may override this by setting your own value for this context and style\&. +.TP +\fBpager\fP +The \fBnslookup\fP function looks up this style in the context +`\fB:nslookup\fP\&' to determine the program used to display output that does +not fit on a single screen\&. +.TP +.PD 0 +\fBprompt\fP +.TP +.PD +\fBrprompt\fP +The \fBnslookup\fP function looks up this style in the context +`\fB:nslookup\fP\&' to set the prompt and the right\-side prompt, respectively\&. +The usual expansions for the \fBPS1\fP and \fBRPS1\fP parameters may be used +(see +EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1))\&. diff --git a/Doc/zshexpn.1 b/Doc/zshexpn.1 new file mode 100644 index 000000000..ccd132af4 --- /dev/null +++ b/Doc/zshexpn.1 @@ -0,0 +1,3237 @@ +.TH "ZSHEXPN" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshexpn \- zsh expansion and substitution +.\" Yodl file: Zsh/expn.yo +.SH "DESCRIPTION" +The following types of expansions are performed in the indicated order in +five steps: +.PP +.PD 0 +.TP +.PD +\fIHistory Expansion\fP +This is performed only in interactive shells\&. +.TP +\fIAlias Expansion\fP +Aliases are expanded immediately before the command line is parsed as +explained +under Aliasing in \fIzshmisc\fP(1)\&. +.TP +.PD 0 +\fIProcess Substitution\fP +.TP +.PD 0 +\fIParameter Expansion\fP +.TP +.PD 0 +\fICommand Substitution\fP +.TP +.PD 0 +\fIArithmetic Expansion\fP +.TP +.PD +\fIBrace Expansion\fP +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 `\fB\e\fP\&',`\fB'\fP' and `\fB"\fP' are +removed\&. +.TP +\fIFilename Expansion\fP +If the \fBSH_FILE_EXPANSION\fP option is set, the order of expansion is +modified for compatibility with \fBsh\fP and \fBksh\fP\&. In that case +\fIfilename expansion\fP is performed immediately after \fIalias expansion\fP, +preceding the set of five expansions mentioned above\&. +.TP +\fIFilename Generation\fP +This expansion, commonly referred to as \fBglobbing\fP, is always done last\&. +.PP +The following sections explain the types of expansion in detail\&. +.PP +.SH "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\&. +.PP +Immediately before execution, each command is saved in the history list, +the size of which is controlled by the \fBHISTSIZE\fP parameter\&. The one +most recent command is always retained in any case\&. Each saved command in +the history list is called a history \fIevent\fP 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 +EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)) is the number that is to be assigned to the \fInext\fP command\&. +.PP +.SS "Overview" +A history expansion begins with the first character of the \fBhistchars\fP +parameter, which is `\fB!\fP\&' by default, and may occur anywhere on the +command line, including inside double quotes (but not inside single quotes +\fB\&'\&.\&.\&.'\fP or C\-style quotes \fB$'\&.\&.\&.'\fP nor when escaped with a backslash)\&. +.PP +The first character is followed by an optional event designator +(see the section `Event Designators\&') and then an optional word +designator (the section `Word Designators\&'); if neither of these designators is +present, no history expansion occurs\&. +.PP +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\&. +.PP +History expansions do not nest\&. +.PP +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 \fBCSH_JUNKIE_HISTORY\fP is set, then every history +reference with no event specification \fIalways\fP refers to the previous +command\&. +.PP +For example, `\fB!\fP\&' is the event designator for the previous command, so +`\fB!!:1\fP\&' always refers to the first word of the previous command, and +`\fB!!$\fP\&' always refers to the last word of the previous command\&. With +\fBCSH_JUNKIE_HISTORY\fP set, then `\fB!:1\fP\&' and `\fB!$\fP' function in the +same manner as `\fB!!:1\fP\&' and `\fB!!$\fP', respectively\&. Conversely, if +\fBCSH_JUNKIE_HISTORY\fP is unset, then `\fB!:1\fP\&' and `\fB!$\fP' 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\&. +.PP +The character sequence `\fB^\fP\fIfoo\fP\fB^\fP\fIbar\fP\&' (where `\fB^\fP' is +actually the second character of the \fBhistchars\fP parameter) +repeats the last command, replacing the string \fIfoo\fP with \fIbar\fP\&. +More precisely, the sequence `\fB^\fP\fIfoo\fP\fB^\fP\fIbar\fP\fB^\fP\&' is +synonymous with `\fB!!:s\fP\fB^\fP\fIfoo\fP\fB^\fP\fIbar\fP\fB^\fP\&', hence other +modifiers (see the section `Modifiers\&') may follow the final `\fB^\fP'\&. +In particular, `\fB^\fP\fIfoo\fP\fB^\fP\fIbar\fP\fB^:G\fP\&' performs a global +substitution\&. +.PP +If the shell encounters the character sequence `\fB!"\fP\&' +in the input, the history mechanism is temporarily disabled until +the current list (see +\fIzshmisc\fP(1)) is fully parsed\&. The `\fB!"\fP\&' is removed from the input, and any +subsequent `\fB!\fP\&' characters have no special significance\&. +.PP +A less convenient but more comprehensible form of command history support +is provided by the \fBfc\fP builtin\&. +.SS "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 \fB`!\&'\fP in each item +may be changed to another character by setting the \fBhistchars\fP +parameter\&. +.PP +.PD 0 +.TP +.PD +\fB!\fP +Start a history expansion, except when followed by a blank, newline, +`\fB=\fP\&' or `\fB(\fP'\&. If followed immediately by a word designator +(see the section `Word Designators\&'), this forms a history reference +with no event designator (see the section `Overview\&')\&. +.TP +\fB!!\fP +Refer to the previous command\&. +By itself, this expansion +repeats the previous command\&. +.TP +\fB!\fP\fIn\fP +Refer to command\-line \fIn\fP\&. +.TP +\fB!\-\fP\fIn\fP +Refer to the current command\-line minus \fIn\fP\&. +.TP +\fB!\fP\fIstr\fP +Refer to the most recent command starting with \fIstr\fP\&. +.TP +\fB!?\fP\fIstr\fP[\fB?\fP] +Refer to the most recent command containing \fIstr\fP\&. The trailing +`\fB?\fP\&' 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 \fIstr\fP\&. +.TP +\fB!#\fP +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 `\fB!#\fP\&' reference\&. +.TP +\fB!{\fP\&.\&.\&.\fB}\fP +Insulate a history reference from adjacent characters (if necessary)\&. +.SS "Word Designators" +A word designator indicates which word or words of a given command line are +to be included in a history reference\&. A `\fB:\fP\&' usually +separates the event specification from the word designator\&. +It may be omitted only if the word designator begins with a +`\fB^\fP\&', `\fB$\fP', `\fB*\fP', `\fB\-\fP' or `\fB%\fP'\&. +Word designators include: +.PP +.PD 0 +.TP +\fB0\fP +The first input word (command)\&. +.TP +\fIn\fP +The \fIn\fPth argument\&. +.TP +\fB^\fP +The first argument\&. That is, \fB1\fP\&. +.TP +\fB$\fP +The last argument\&. +.TP +\fB%\fP +The word matched by (the most recent) \fB?\fP\fIstr\fP search\&. +.TP +\fIx\fP\fB\-\fP\fIy\fP +A range of words; \fIx\fP defaults to \fB0\fP\&. +.TP +\fB*\fP +All the arguments, or a null value if there are none\&. +.TP +\fIx\fP\fB*\fP +Abbreviates `\fIx\fP\fB\-$\fP\&'\&. +.TP +\fIx\fP\fB\-\fP +Like `\fIx\fP\fB*\fP\&' but omitting word \fB$\fP\&. +.PD +.PP +Note that a `\fB%\fP\&' word designator works only when used in one of +`\fB!%\fP\&', `\fB!:%\fP' or `\fB!?\fP\fIstr\fP\fB?:%\fP', and only when used after a +\fB!?\fP expansion (possibly in an earlier command)\&. Anything else results +in an error, although the error may not be the most obvious one\&. +.SS "Modifiers" +After the optional word designator, you can add +a sequence of one or more of the following modifiers, +each preceded by a `\fB:\fP\&'\&. These modifiers also work on the result +of \fIfilename generation\fP and \fIparameter expansion\fP, except where +noted\&. +.PP +.PD 0 +.TP +.PD +\fBa\fP +Turn a file name into an absolute path: prepends the current directory, +if necessary; remove `\fB\&.\fP\&' path segments; and remove `\fB\&.\&.\fP' path segments +and the segments that immediately precede them\&. +.RS +.PP +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 +\fBCHASE_DOTS\fP or \fBCHASE_LINKS\fP is set\&. For example, +`\fB/before/here/\&.\&./after\fP\&' is always transformed to +`\fB/before/after\fP\&', regardless of whether `\fB/before/here\fP' exists or what +kind of object (dir, file, symlink, etc\&.) it is\&. +.RE +.TP +\fBA\fP +Turn a file name into an absolute path as the `\fBa\fP\&' modifier does, and +\fIthen\fP pass the result through the \fBrealpath(3)\fP library +function to resolve symbolic links\&. +.RS +.PP +Note: on systems that do not have a \fBrealpath(3)\fP library +function, symbolic links are not resolved, so on those systems `\fBa\fP\&' and +`\fBA\fP\&' are equivalent\&. +.PP +Note: \fBfoo:A\fP and \fBrealpath(foo)\fP are different on some inputs\&. +For \fBrealpath(foo)\fP semantics, see the `\fBP\fP` modifier\&. +.RE +.TP +\fBc\fP +Resolve a command name into an absolute path by searching the command +path given by the \fBPATH\fP 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\&. +.TP +\fBe\fP +Remove all but the part of the filename extension following the `\fB\&.\fP\&'; +see the definition of the filename extension in the description of the +\fBr\fP modifier below\&. Note that according to that definition the result +will be empty if the string ends with a `\fB\&.\fP\&'\&. +.TP +\fBh\fP [ \fIdigits\fP ] +Remove a trailing pathname component, shortening the path by one +directory level: this is the `head\&' of the pathname\&. This works like +`\fBdirname\fP\&'\&. If the \fBh\fP 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 `\fB/\fP\&' is the first component, so, +for example, if \fBvar=/my/path/to/something\fP, then \fB${var:h3}\fP +substitutes \fB/my/path\fP\&. 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 \fB$var:h2\fP is treated as \fB${var:h}2\fP, not as +\fB${var:h2}\fP\&. 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)\&. +.TP +\fBl\fP +Convert the words to all lowercase\&. +.TP +\fBp\fP +Print the new command but do not execute it\&. Only works with history +expansion\&. +.TP +\fBP\fP +Turn a file name into an absolute path, like \fBrealpath(3)\fP\&. +The resulting path will be absolute, +will refer to the same directory entry as the input filename, +and none of its components will be symbolic links or equal to +`\fB\&.\fP\&' or `\fB\&.\&.\fP'\&. +.RS +.PP +Unlike \fBrealpath(3)\fP, non\-existent trailing components are +permitted and preserved\&. +.RE +.TP +\fBq\fP +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 \fBeval\fP\&. +.TP +\fBQ\fP +Remove one level of quotes from the substituted words\&. +.TP +\fBr\fP +Remove a filename extension leaving the root name\&. Strings with no +filename extension are not altered\&. A filename +extension is a `\fB\&.\fP\&' followed by any number of characters (including +zero) that are neither `\fB\&.\fP\&' nor `\fB/\fP' and that continue to the end +of the string\&. For example, the extension of +`\fBfoo\&.orig\&.c\fP\&' is `\fB\&.c\fP', and `\fBdir\&.c/foo\fP' has no extension\&. +.TP +\fBs/\fP\fIl\fP\fB/\fP\fIr\fP[\fB/\fP] +Substitute \fIr\fP for \fIl\fP as described below\&. +The substitution is done only for the +first string that matches \fIl\fP\&. For arrays and for filename +generation, this applies to each word of the expanded text\&. See +below for further notes on substitutions\&. +.RS +.PP +The forms `\fBgs/\fP\fIl\fP\fB/\fP\fIr\fP\&' and `\fBs/\fP\fIl\fP\fB/\fP\fIr\fP\fB/:G\fP' +perform global substitution, i\&.e\&. substitute every occurrence of \fIr\fP +for \fIl\fP\&. Note that the \fBg\fP or \fB:G\fP must appear in exactly the +position shown\&. +.PP +See further notes on this form of substitution below\&. +.RE +.TP +\fB&\fP +Repeat the previous \fBs\fP substitution\&. Like \fBs\fP, may be preceded +immediately by a \fBg\fP\&. In parameter expansion the \fB&\fP must appear +inside braces, and in filename generation it must be quoted with a +backslash\&. +.TP +\fBt\fP [ \fIdigits\fP ] +Remove all leading pathname components, leaving the final component (tail)\&. +This works like `\fBbasename\fP\&'\&. 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\&. +.TP +\fBu\fP +Convert the words to all uppercase\&. +.TP +\fBx\fP +Like \fBq\fP, but break into words at whitespace\&. Does not work with +parameter expansion\&. +.PP +The \fBs/\fP\fIl\fP\fB/\fP\fIr\fP\fB/\fP 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 `\fB/\fP\&'\&. A backslash quotes the delimiter character\&. The character +`\fB&\fP\&', in the right\-hand\-side \fIr\fP, is replaced by the text from the +left\-hand\-side \fIl\fP\&. The `\fB&\fP\&' can be quoted with a backslash\&. A +null \fIl\fP uses the previous string either from the previous \fIl\fP or +from the contextual scan string \fIs\fP from `\fB!?\fP\fIs\fP\&'\&. You can +omit the rightmost delimiter if a newline immediately follows \fIr\fP; +the rightmost `\fB?\fP\&' in a context scan can similarly be omitted\&. Note +the same record of the last \fIl\fP and \fIr\fP is maintained across all +forms of expansion\&. +.PP +Note that if a `\fB&\fP\&' is used within glob qualifiers an extra backslash +is needed as a \fB&\fP is a special character in this case\&. +.PP +Also note that the order of expansions affects the interpretation of +\fIl\fP and \fIr\fP\&. When used in a history expansion, which occurs before +any other expansions, \fIl\fP and \fIr\fP are treated as literal strings +(except as explained for \fBHIST_SUBST_PATTERN\fP below)\&. When used in +parameter expansion, the replacement of \fIr\fP 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 \fIl\fP 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 `\fB:s\fP\&' expression itself is divided into +\fIl\fP and \fIr\fP sides\&. +.PP +If the option \fBHIST_SUBST_PATTERN\fP is set, \fIl\fP is treated as +a pattern of the usual form described in +the section FILENAME GENERATION below\&. 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 +\fB(#q:s/\fP\fI\&.\&.\&.\fP\fB/\fP\fI\&.\&.\&.\fP\fB/)\fP 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 \fBNO_BAD_PATTERN\fP option so will cause an error\&. +.PP +When \fBHIST_SUBST_PATTERN\fP is set, \fIl\fP may start with a \fB#\fP +to indicate that the pattern must match at the start of the string +to be substituted, and a \fB%\fP may appear at the start or after an \fB#\fP +to indicate that the pattern must match at the end of the string +to be substituted\&. The \fB%\fP or \fB#\fP may be quoted with two +backslashes\&. +.PP +For example, the following piece of filename generation code +with the \fBEXTENDED_GLOB\fP option: +.PP +.RS +.nf +\fBprint \-r \-\- *\&.c(#q:s/#%(#b)s(*)\&.c/\&'S${match[1]}\&.C'/)\fP +.fi +.RE +.PP +takes the expansion of \fB*\&.c\fP and applies the glob qualifiers in the +\fB(#q\fP\fI\&.\&.\&.\fP\fB)\fP expression, which consists of a substitution +modifier anchored to the start and end of each word (\fB#%\fP)\&. This +turns on backreferences (\fB(#b)\fP), so that the parenthesised +subexpression is available in the replacement string as \fB${match[1]}\fP\&. +The replacement string is quoted so that the parameter is not substituted +before the start of filename generation\&. +.PP +The following \fBf\fP, \fBF\fP, \fBw\fP and \fBW\fP modifiers work only with +parameter expansion and filename generation\&. They are listed here to +provide a single point of reference for all modifiers\&. +.PP +.PD 0 +.TP +.PD +\fBf\fP +Repeats the immediately (without a colon) following modifier until the +resulting word doesn\&'t change any more\&. +.TP +\fBF:\fP\fIexpr\fP\fB:\fP +Like \fBf\fP, but repeats only \fIn\fP times if the expression +\fIexpr\fP evaluates to \fIn\fP\&. Any character can be used instead of +the `\fB:\fP\&'; if `\fB(\fP', `\fB[\fP', or `\fB{\fP' +is used as the opening delimiter, +the closing delimiter should be \&'\fB)\fP', `\fB]\fP', or `\fB}\fP', +respectively\&. +.TP +\fBw\fP +Makes the immediately following modifier work on each word in the +string\&. +.TP +\fBW:\fP\fIsep\fP\fB:\fP +Like \fBw\fP but words are considered to be the parts of the string +that are separated by \fIsep\fP\&. Any character can be used instead of +the `\fB:\fP\&'; opening parentheses are handled specially, see above\&. +.SH "PROCESS SUBSTITUTION" +Each part of a command argument that takes the form +`\fB<(\fP\fIlist\fP\fB)\fP\&', +`\fB>(\fP\fIlist\fP\fB)\fP\&' or +`\fB=(\fP\fIlist\fP\fB)\fP\&' +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\&. +.PP +Note that `\fB<<(\fP\fIlist\fP\fB)\fP\&' is not a special syntax; it +is equivalent to `\fB< <(\fP\fIlist\fP\fB)\fP\&', 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\&. +.PP +In the case of the \fB<\fP or \fB>\fP forms, the shell runs the commands in +\fIlist\fP as a subprocess of the job executing the shell command line\&. +If the system supports the \fB/dev/fd\fP +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 +\fB>\fP is selected then writing on this special file will provide input for +\fIlist\fP\&. If \fB<\fP is used, then the file passed as an argument will +be connected to the output of the \fIlist\fP process\&. For example, +.PP +.RS +.nf +\fB\fBpaste <(cut \-f1\fP \fIfile1\fP\fB) <(cut \-f3\fP \fIfile2\fP\fB) | +tee >(\fP\fIprocess1\fP\fB) >(\fP\fIprocess2\fP\fB) >/dev/null\fP\fP +.fi +.RE +.PP +cuts fields 1 and 3 from the files \fIfile1\fP and \fIfile2\fP respectively, +pastes the results together, and sends it to the processes +\fIprocess1\fP and \fIprocess2\fP\&. +.PP +If \fB=(\fP\fI\&.\&.\&.\fP\fB)\fP is used instead of +\fB<(\fP\fI\&.\&.\&.\fP\fB)\fP, +then the file passed as an argument will be the name +of a temporary file containing the output of the \fIlist\fP +process\&. This may be used instead of the \fB<\fP +form for a program that expects to lseek (see \fIlseek\fP(2)) +on the input file\&. +.PP +There is an optimisation for substitutions of the form +\fB=(<<<\fP\fIarg\fP\fB)\fP, where \fIarg\fP is a single\-word argument +to the here\-string redirection \fB<<<\fP\&. This form produces a file name +containing the value of \fIarg\fP after any substitutions have been +performed\&. This is handled entirely within the current shell\&. This is +effectively the reverse of the special form \fB$(<\fP\fIarg\fP\fB)\fP +which treats \fIarg\fP as a file name and replaces it with the file\&'s +contents\&. +.PP +The \fB=\fP form is useful as both the \fB/dev/fd\fP and the named pipe +implementation of \fB<(\fP\fI\&.\&.\&.\fP\fB)\fP 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 \fIlseek\fP(2)) on the file will not work\&. +.PP +Also note that the previous example can be more compactly and +efficiently written (provided the \fBMULTIOS\fP option is set) as: +.PP +.RS +.nf +\fB\fBpaste <(cut \-f1\fP \fIfile1\fP\fB) <(cut \-f3\fP \fIfile2\fP\fB)\fP \fB> >(\fP\fIprocess1\fP\fB) > >(\fP\fIprocess2\fP\fB)\fP\fP +.fi +.RE +.PP +The shell uses pipes instead of FIFOs to implement the latter +two process substitutions in the above example\&. +.PP +There is an additional problem with \fB>(\fP\fIprocess\fP\fB)\fP; when +this is attached to an external command, the parent shell does not wait +for \fIprocess\fP 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 \fIMULTIOS\fP in +\fIzshmisc\fP(1)\&. Hence in a simplified +version of the example above: +.PP +.RS +.nf +\fB\fBpaste <(cut \-f1\fP \fIfile1\fP\fB) <(cut \-f3\fP \fIfile2\fP\fB)\fP \fB> >(\fP\fIprocess\fP\fB)\fP\fP +.fi +.RE +.PP +(note that no \fBMULTIOS\fP are involved), \fIprocess\fP will be run +asynchronously as far as the parent shell is concerned\&. The workaround is: +.PP +.RS +.nf +\fB\fB{ paste <(cut \-f1\fP \fIfile1\fP\fB) <(cut \-f3\fP \fIfile2\fP\fB) }\fP \fB> >(\fP\fIprocess\fP\fB)\fP\fP +.fi +.RE +.PP +The extra processes here are +spawned from the parent shell which will wait for their completion\&. +.PP +Another problem arises any time a job with a substitution that requires +a temporary file is disowned by the shell, including the case where +`\fB&!\fP\&' or `\fB&|\fP' 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, +.PP +.RS +.nf +\fB(mycmd =(myoutput)) &!\fP +.fi +.RE +.PP +as the forked subshell will wait for the command to finish then remove +the temporary file\&. +.PP +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: +.PP +.RS +.nf +\fB() { + print File $1: + cat $1 +} =(print This be the verse)\fP +.fi +.RE +.PP +outputs something resembling the following +.PP +.RS +.nf +\fBFile /tmp/zsh6nU0kS: +This be the verse\fP +.fi +.RE +.PP +The temporary file created by the process substitution will be deleted +when the function exits\&. +.PP +.SH "PARAMETER EXPANSION" +The character `\fB$\fP\&' is used to introduce parameter expansions\&. +See +\fIzshparam\fP(1) +for a description of parameters, including arrays, associative arrays, +and subscript notation to access individual array elements\&. +.PP +Note in particular the fact that words of unquoted parameters are not +automatically split on whitespace unless the option \fBSH_WORD_SPLIT\fP 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\&. +.PP +With default options, after the assignments: +.PP +.RS +.nf +\fBarray=("first word" "" "third word") +scalar="only word"\fP +.fi +.RE +.PP +then \fB$array\fP substitutes two words, `\fBfirst word\fP\&' and `\fBthird +word\fP\&', and \fB$scalar\fP substitutes a single word `\fBonly word\fP'\&. Note +that second element of \fBarray\fP was elided\&. Scalar parameters can +be elided too if their value is null (empty)\&. To avoid elision, use quoting as +follows: \fB"$scalar"\fP for scalars and \fB"${array[@]}"\fP or \fB"${(@)array}"\fP +for arrays\&. (The last two forms are equivalent\&.) +.PP +Parameter expansions can involve \fIflags\fP, as in `\fB${(@kv)aliases}\fP\&', +and other operators, such as `\fB${PREFIX:\-"/usr/local"}\fP\&'\&. Parameter +expansions can also be nested\&. These topics will be introduced below\&. +The full rules are complicated and are noted at the end\&. +.PP +In the expansions discussed below that require a pattern, the form of +the pattern is the same as that used for filename generation; +see the section `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 +the section `Modifiers\&' in the section `History Expansion' can be +applied: for example, \fB${i:s/foo/bar/}\fP performs string +substitution on the expansion of parameter \fB$i\fP\&. +.PP +In the following descriptions, `\fIword\fP\&' refers to a single word +substituted on the command line, not necessarily a space delimited word\&. +.PP +.PD 0 +.TP +.PD +\fB${\fP\fIname\fP\fB}\fP +The value, if any, of the parameter \fIname\fP 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 \fIname\fP\&. In addition, more complicated forms of substitution +usually require the braces to be present; exceptions, which only apply if +the option \fBKSH_ARRAYS\fP is not set, are a single subscript or any colon +modifiers appearing after the name, or any of the characters `\fB^\fP\&', +`\fB=\fP\&', `\fB~\fP', `\fB#\fP' or `\fB+\fP' appearing before the name, all of +which work with or without braces\&. +.RS +.PP +If \fIname\fP is an array parameter, and the \fBKSH_ARRAYS\fP option is not +set, then the value of each +element of \fIname\fP is substituted, one element per word\&. Otherwise, the +expansion results in one word only; with \fBKSH_ARRAYS\fP, this is the first +element of an array\&. No field splitting is done on the result unless the +\fBSH_WORD_SPLIT\fP option is set\&. +See also the flags \fB=\fP and \fBs:\fP\fIstring\fP\fB:\fP\&. +.RE +.TP +\fB${+\fP\fIname\fP\fB}\fP +If \fIname\fP is the name of a set parameter `\fB1\fP\&' is substituted, +otherwise `\fB0\fP\&' is substituted\&. +.TP +.PD 0 +\fB${\fP\fIname\fP\fB\-\fP\fIword\fP\fB}\fP +.TP +.PD +\fB${\fP\fIname\fP\fB:\-\fP\fIword\fP\fB}\fP +If \fIname\fP is set, or in the second form is non\-null, then substitute +its value; otherwise substitute \fIword\fP\&. In the second form \fIname\fP +may be omitted, in which case \fIword\fP is always substituted\&. +.TP +.PD 0 +\fB${\fP\fIname\fP\fB+\fP\fIword\fP\fB}\fP +.TP +.PD +\fB${\fP\fIname\fP\fB:+\fP\fIword\fP\fB}\fP +If \fIname\fP is set, or in the second form is non\-null, then substitute +\fIword\fP; otherwise substitute nothing\&. +.TP +.PD 0 +\fB${\fP\fIname\fP\fB=\fP\fIword\fP\fB}\fP +.TP +.PD 0 +\fB${\fP\fIname\fP\fB:=\fP\fIword\fP\fB}\fP +.TP +.PD +\fB${\fP\fIname\fP\fB::=\fP\fIword\fP\fB}\fP +In the first form, if \fIname\fP is unset then set it to \fIword\fP; in the +second form, if \fIname\fP is unset or null then set it to \fIword\fP; and +in the third form, unconditionally set \fIname\fP to \fIword\fP\&. In all +forms, the value of the parameter is then substituted\&. +.TP +.PD 0 +\fB${\fP\fIname\fP\fB?\fP\fIword\fP\fB}\fP +.TP +.PD +\fB${\fP\fIname\fP\fB:?\fP\fIword\fP\fB}\fP +In the first form, if \fIname\fP is set, or in the second form if \fIname\fP +is both set and non\-null, then substitute its value; otherwise, print +\fIword\fP and exit from the shell\&. Interactive shells instead return to +the prompt\&. If \fIword\fP is omitted, then a standard message is printed\&. +.PP +In any of the above expressions that test a variable and substitute an +alternate \fIword\fP, note that you can use standard shell quoting in the +\fIword\fP value to selectively override the splitting done by the +\fBSH_WORD_SPLIT\fP option and the \fB=\fP flag, but not splitting by the +\fBs:\fP\fIstring\fP\fB:\fP flag\&. +.PP +In the following expressions, when \fIname\fP is an array and +the substitution is not quoted, or if the `\fB(@)\fP\&' flag or the +\fIname\fP\fB[@]\fP syntax is used, matching and replacement is +performed on each array element separately\&. +.PP +.PD 0 +.TP +.PD 0 +\fB${\fP\fIname\fP\fB#\fP\fIpattern\fP\fB}\fP +.TP +.PD +\fB${\fP\fIname\fP\fB##\fP\fIpattern\fP\fB}\fP +If the \fIpattern\fP matches the beginning of the value of +\fIname\fP, then substitute the value of \fIname\fP with +the matched portion deleted; otherwise, just +substitute the value of \fIname\fP\&. In the first +form, the smallest matching pattern is preferred; +in the second form, the largest matching pattern is +preferred\&. +.TP +.PD 0 +\fB${\fP\fIname\fP\fB%\fP\fIpattern\fP\fB}\fP +.TP +.PD +\fB${\fP\fIname\fP\fB%%\fP\fIpattern\fP\fB}\fP +If the \fIpattern\fP matches the end of the value of +\fIname\fP, then substitute the value of \fIname\fP with +the matched portion deleted; otherwise, just +substitute the value of \fIname\fP\&. In the first +form, the smallest matching pattern is preferred; +in the second form, the largest matching pattern is +preferred\&. +.TP +\fB${\fP\fIname\fP\fB:#\fP\fIpattern\fP\fB}\fP +If the \fIpattern\fP matches the value of \fIname\fP, then substitute +the empty string; otherwise, just substitute the value of \fIname\fP\&. +If \fIname\fP is an array +the matching array elements are removed (use the `\fB(M)\fP\&' flag to +remove the non\-matched elements)\&. +.TP +\fB${\fP\fIname\fP\fB:|\fP\fIarrayname\fP\fB}\fP +If \fIarrayname\fP is the name (N\&.B\&., not contents) of an array +variable, then any elements contained in \fIarrayname\fP are removed +from the substitution of \fIname\fP\&. If the substitution is scalar, +either because \fIname\fP is a scalar variable or the expression is +quoted, the elements of \fIarrayname\fP are instead tested against the +entire expression\&. +.TP +\fB${\fP\fIname\fP\fB:*\fP\fIarrayname\fP\fB}\fP +Similar to the preceding substitution, but in the opposite sense, +so that entries present in both the original substitution and as +elements of \fIarrayname\fP are retained and others removed\&. +.TP +.PD 0 +\fB${\fP\fIname\fP\fB:^\fP\fIarrayname\fP\fB}\fP +.TP +.PD +\fB${\fP\fIname\fP\fB:^^\fP\fIarrayname\fP\fB}\fP +Zips two arrays, such that the output array is twice as long as the +shortest (longest for `\fB:^^\fP\&') of \fBname\fP and \fBarrayname\fP, with +the elements alternatingly being picked from them\&. For `\fB:^\fP\&', if one +of the input arrays is longer, the output will stop when the end of the +shorter array is reached\&. Thus, +.RS +.PP +.RS +.nf +\fBa=(1 2 3 4); b=(a b); print ${a:^b}\fP +.fi +.RE +.PP +will output `\fB1 a 2 b\fP\&'\&. For `\fB:^^\fP', then the input is repeated +until all of the longer array has been used up and the above will output +`\fB1 a 2 b 3 a 4 b\fP\&'\&. +.PP +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\&. +.PP +Currently the following code will output `\fBa b\fP\&' and `\fB1\fP' as two separate +elements, which can be unexpected\&. The second print provides a workaround which +should continue to work if this is changed\&. +.PP +.RS +.nf +\fBa=(a b); b=(1 2); print \-l "${a:^b}"; print \-l "${${a:^b}}"\fP +.fi +.RE +.RE +.TP +.PD 0 +\fB${\fP\fIname\fP\fB:\fP\fIoffset\fP\fB}\fP +.TP +.PD +\fB${\fP\fIname\fP\fB:\fP\fIoffset\fP\fB:\fP\fIlength\fP\fB}\fP +This syntax gives effects similar to parameter subscripting +in the form \fB$\fP\fIname\fP\fB[\fP\fIstart\fP\fB,\fP\fIend\fP\fB]\fP, but is +compatible with other shells; note that both \fIoffset\fP and \fIlength\fP +are interpreted differently from the components of a subscript\&. +.RS +.PP +If \fIoffset\fP is non\-negative, then if the variable \fIname\fP is a +scalar substitute the contents starting \fIoffset\fP characters from the +first character of the string, and if \fIname\fP is an array substitute +elements starting \fIoffset\fP elements from the first element\&. If +\fIlength\fP is given, substitute that many characters or elements, +otherwise the entire rest of the scalar or array\&. +.PP +A positive \fIoffset\fP is always treated as the offset of a character or +element in \fIname\fP 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 \fBKSH_ARRAYS\fP\&. +.PP +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\&. +.PP +When positive, \fIlength\fP counts from the \fIoffset\fP position +toward the end of the scalar or array\&. When negative, \fIlength\fP +counts back from the end\&. If this results in a position smaller +than \fIoffset\fP, a diagnostic is printed and nothing is substituted\&. +.PP +The option \fBMULTIBYTE\fP is obeyed, i\&.e\&. the offset and length +count multibyte characters where appropriate\&. +.PP +\fIoffset\fP and \fIlength\fP undergo the same set of shell substitutions +as for scalar assignment; in addition, they are then subject to arithmetic +evaluation\&. Hence, for example +.PP +.RS +.nf +\fBprint ${foo:3} +print ${foo: 1 + 2} +print ${foo:$(( 1 + 2))} +print ${foo:$(echo 1 + 2)}\fP +.fi +.RE +.PP +all have the same effect, extracting the string starting at the fourth +character of \fB$foo\fP if the substitution would otherwise return a scalar, +or the array starting at the fourth element if \fB$foo\fP would return an +array\&. Note that with the option \fBKSH_ARRAYS\fP \fB$foo\fP always returns +a scalar (regardless of the use of the offset syntax) and a form +such as \fB${foo[*]:3}\fP is required to extract elements of an array named +\fBfoo\fP\&. +.PP +If \fIoffset\fP is negative, the \fB\-\fP may not appear immediately +after the \fB:\fP as this indicates the +\fB${\fP\fIname\fP\fB:\-\fP\fIword\fP\fB}\fP form of substitution\&. Instead, a space +may be inserted before the \fB\-\fP\&. Furthermore, neither \fIoffset\fP nor +\fIlength\fP may begin with an alphabetic character or \fB&\fP 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 \fB$\fP as this +signifies the intention (parameter substitution can easily be rendered +unreadable); however, as arithmetic substitution is performed, the +expression \fB${var: offs}\fP does work, retrieving the offset from +\fB$offs\fP\&. +.PP +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\&. \fB$@\fP or \fB$*\fP, then offset 0 +instead refers to \fB$0\fP, offset 1 refers to \fB$1\fP, and so on\&. In +other words, the positional parameter array is effectively extended by +prepending \fB$0\fP\&. Hence \fB${*:0:1}\fP substitutes \fB$0\fP and +\fB${*:1:1}\fP substitutes \fB$1\fP\&. +.RE +.TP +.PD 0 +\fB${\fP\fIname\fP\fB/\fP\fIpattern\fP\fB/\fP\fIrepl\fP\fB}\fP +.TP +.PD 0 +\fB${\fP\fIname\fP\fB//\fP\fIpattern\fP\fB/\fP\fIrepl\fP\fB}\fP +.TP +.PD +\fB${\fP\fIname\fP\fB:/\fP\fIpattern\fP\fB/\fP\fIrepl\fP\fB}\fP +Replace the longest possible match of \fIpattern\fP in the expansion of +parameter \fIname\fP by string \fIrepl\fP\&. The first form +replaces just the first occurrence, the second form all occurrences, +and the third form replaces only if \fIpattern\fP matches the entire string\&. +Both \fIpattern\fP and \fIrepl\fP are subject to double\-quoted substitution, +so that expressions like \fB${name/$opat/$npat}\fP will work, but obey the +usual rule that pattern characters in \fB$opat\fP are not treated specially +unless either the option \fBGLOB_SUBST\fP is set, or \fB$opat\fP is instead +substituted as \fB${~opat}\fP\&. +.RS +.PP +The \fIpattern\fP may begin with a `\fB#\fP\&', in which case the +\fIpattern\fP must match at the start of the string, or `\fB%\fP\&', in +which case it must match at the end of the string, or `\fB#%\fP\&' in which +case the \fIpattern\fP must match the entire string\&. The \fIrepl\fP may +be an empty string, in which case the final `\fB/\fP\&' may also be omitted\&. +To quote the final `\fB/\fP\&' in other cases it should be preceded by a +single backslash; this is not necessary if the +`\fB/\fP\&' occurs inside a substituted parameter\&. Note also that the `\fB#\fP', +`\fB%\fP\&' and `\fB#%\fP are not active if they occur inside a substituted +parameter, even at the start\&. +.PP +If, after quoting rules apply, \fB${\fP\fIname\fP\fB}\fP expands to an array, +the replacements act on each element individually\&. Note also the +effect of the \fBI\fP and \fBS\fP parameter expansion flags below; however, +the flags \fBM\fP, \fBR\fP, \fBB\fP, \fBE\fP and \fBN\fP are not useful\&. +.PP +For example, +.PP +.RS +.nf +\fBfoo="twinkle twinkle little star" sub="t*e" rep="spy" +print ${foo//${~sub}/$rep} +print ${(S)foo//${~sub}/$rep}\fP +.fi +.RE +.PP +Here, the `\fB~\fP\&' ensures that the text of \fB$sub\fP is treated as a +pattern rather than a plain string\&. In the first case, the longest +match for \fBt*e\fP is substituted and the result is `\fBspy star\fP\&', +while in the second case, the shortest matches are taken and the +result is `\fBspy spy lispy star\fP\&'\&. +.RE +.TP +\fB${#\fP\fIspec\fP\fB}\fP +If \fIspec\fP is one of the above substitutions, substitute +the length in characters of the result instead of +the result itself\&. If \fIspec\fP 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 \fIspec\fP\&. +Note that `\fB^\fP\&', `\fB=\fP', and `\fB~\fP', below, must appear +to the left of `\fB#\fP\&' when these forms are combined\&. +.RS +.PP +If the option \fBPOSIX_IDENTIFIERS\fP is not set, and \fIspec\fP is a +simple name, then the braces are optional; this is true even +for special parameters so e\&.g\&. \fB$#\-\fP and \fB$#*\fP take the length +of the string \fB$\-\fP and the array \fB$*\fP respectively\&. If +\fBPOSIX_IDENTIFIERS\fP is set, then braces are required for +the \fB#\fP to be treated in this fashion\&. +.RE +.TP +.PD 0 +\fB${^\fP\fIspec\fP\fB}\fP +.TP +.PD +\fB${^^\fP\fIspec\fP\fB}\fP +Turn on the \fBRC_EXPAND_PARAM\fP option for the +evaluation of \fIspec\fP; if the `\fB^\fP\&' is doubled, turn it off\&. +When this option is set, array expansions of the form +\fIfoo\fP\fB${\fP\fIxx\fP\fB}\fP\fIbar\fP, +where the parameter \fIxx\fP +is set to \fB(\fP\fIa b c\fP\fB)\fP, are substituted with +`\fIfooabar foobbar foocbar\fP\&' instead of the default +`\fIfooa b cbar\fP\&'\&. Note that an empty array will therefore cause +all arguments to be removed\&. +.RS +.PP +Internally, each such expansion is converted into the +equivalent list for brace expansion\&. E\&.g\&., \fB${^var}\fP becomes +\fB{$var[1],$var[2],\fP\&.\&.\&.\fB}\fP, and is processed as described in +the section `Brace Expansion\&' below: note, however, the expansion +happens immediately, with any explicit brace expansion +happening later\&. If word splitting is also in effect the +\fB$var[\fP\fIN\fP\fB]\fP may themselves be split into different list +elements\&. +.RE +.TP +.PD 0 +\fB${=\fP\fIspec\fP\fB}\fP +.TP +.PD +\fB${==\fP\fIspec\fP\fB}\fP +Perform word splitting using the rules for \fBSH_WORD_SPLIT\fP during the +evaluation of \fIspec\fP, but regardless of whether the parameter appears in +double quotes; if the `\fB=\fP\&' is doubled, turn it off\&. +This forces parameter expansions to be split into +separate words before substitution, using \fBIFS\fP as a delimiter\&. +This is done by default in most other shells\&. +.RS +.PP +Note that splitting is applied to \fIword\fP in the assignment forms +of \fIspec\fP \fIbefore\fP the assignment to \fIname\fP is performed\&. +This affects the result of array assignments with the \fBA\fP flag\&. +.RE +.TP +.PD 0 +\fB${~\fP\fIspec\fP\fB}\fP +.TP +.PD +\fB${~~\fP\fIspec\fP\fB}\fP +Turn on the \fBGLOB_SUBST\fP option for the evaluation of +\fIspec\fP; if the `\fB~\fP\&' 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 `\fB=\fP\&' and `\fB!=\fP' operators in conditions\&. +.RS +.PP +In nested substitutions, note that the effect of the \fB~\fP 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 \fBfoo\fP is set to \fB*\fP, \fB${~foo//\e*/*\&.c}\fP is substituted by +the pattern \fB*\&.c\fP, which may be expanded by filename generation, but +\fB${${~foo}//\e*/*\&.c}\fP substitutes to the string \fB*\&.c\fP, which will not +be further expanded\&. +.RE +.PP +If a \fB${\fP\&.\&.\&.\fB}\fP type parameter expression or a +\fB$(\fP\&.\&.\&.\fB)\fP type command substitution is used in place of +\fIname\fP above, it is expanded first and the result is used as if +it were the value of \fIname\fP\&. Thus it is +possible to perform nested operations: \fB${${foo#head}%tail}\fP +substitutes the value of \fB$foo\fP with both `\fBhead\fP\&' and `\fBtail\fP' +deleted\&. The form with \fB$(\fP\&.\&.\&.\fB)\fP is often useful in +combination with the flags described next; see the examples below\&. +Each \fIname\fP or nested \fB${\fP\&.\&.\&.\fB}\fP in a parameter expansion may +also be followed by a subscript expression as described in +\fIArray Parameters\fP in \fIzshparam\fP(1)\&. +.PP +Note that double quotes may appear around nested expressions, in which +case only the part inside is treated as quoted; for example, +\fB${(f)"$(foo)"}\fP quotes the result of \fB$(foo)\fP, but the flag `\fB(f)\fP\&' +(see below) is applied using the rules for unquoted expansions\&. Note +further that quotes are themselves nested in this context; for example, in +\fB"${(@f)"$(foo)"}"\fP, there are two sets of quotes, one surrounding the +whole expression, the other (redundant) surrounding the \fB$(foo)\fP as +before\&. +.PP +.SS "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, `(\fBq%q%q\fP)\&' +means the same thing as the more readable `(\fB%%qqq\fP)\&'\&. The +following flags are supported: +.PP +.PD 0 +.TP +.PD +\fB#\fP +Evaluate the resulting words as numeric expressions and interpret +these as character codes\&. Output the corresponding characters\&. Note +that this form is entirely distinct from use of the \fB#\fP without +parentheses\&. +.RS +.PP +If the \fBMULTIBYTE\fP option is set and the number is greater than 127 +(i\&.e\&. not an ASCII character) it is treated as a Unicode character\&. +.RE +.TP +\fB%\fP +Expand all \fB%\fP escapes in the resulting words in the same way as in +prompts (see +EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1))\&. If this flag is given twice, +full prompt expansion is done on the resulting words, depending on the +setting of the \fBPROMPT_PERCENT\fP, \fBPROMPT_SUBST\fP and \fBPROMPT_BANG\fP +options\&. +.TP +\fB@\fP +In double quotes, array elements are put into separate words\&. +E\&.g\&., `\fB"${(@)foo}"\fP\&' is equivalent to `\fB"${foo[@]}"\fP' and +`\fB"${(@)foo[1,2]}"\fP\&' is the same as `\fB"$foo[1]" "$foo[2]"\fP'\&. +This is distinct from \fIfield splitting\fP by the \fBf\fP, \fBs\fP +or \fBz\fP flags, which still applies within each array element\&. +.TP +\fBA\fP +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 \fB${${(A\fP\fB)\fP\fIname\fP\fB}[1]}\fP +yields the full value of \fIname\fP when \fIname\fP is scalar\&. +.RS +.PP +This assigns an array parameter with `\fB${\fP\&.\&.\&.\fB=\fP\&.\&.\&.\fB}\fP\&', +`\fB${\fP\&.\&.\&.\fB:=\fP\&.\&.\&.\fB}\fP\&' or `\fB${\fP\&.\&.\&.\fB::=\fP\&.\&.\&.\fB}\fP'\&. +If this flag is repeated (as in `\fBAA\fP\&'), assigns an associative +array parameter\&. Assignment is made before sorting or padding; +if field splitting is active, the \fIword\fP part is split before +assignment\&. The \fIname\fP part may be a subscripted range for +ordinary arrays; when assigning an associative array, the \fIword\fP +part \fImust\fP be converted to an array, for example by using +`\fB${(AA)=\fP\fIname\fP\fB=\fP\&.\&.\&.\fB}\fP\&' to activate field splitting\&. +.PP +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\&. +.RE +.TP +\fBa\fP +Sort in array index order; when combined with `\fBO\fP\&' sort in reverse +array index order\&. Note that `\fBa\fP\&' is therefore equivalent to the +default but `\fBOa\fP\&' is useful for obtaining an array's elements in reverse +order\&. +.TP +\fBb\fP +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 \fBGLOB_SUBST\fP, including the \fB${~\fP\fI\&.\&.\&.\fP\fB}\fP switch\&. +.RS +.PP +Quoting using one of the \fBq\fP family of flags does not work +for this purpose since quotes are not stripped from non\-pattern +characters by \fBGLOB_SUBST\fP\&. In other words, +.PP +.RS +.nf +\fBpattern=${(q)str} +[[ $str = ${~pattern} ]]\fP +.fi +.RE +.PP +works if \fB$str\fP is `\fBa*b\fP\&' but not if it is `\fBa b\fP', whereas +.PP +.RS +.nf +\fBpattern=${(b)str} +[[ $str = ${~pattern} ]]\fP +.fi +.RE +.PP +is always true for any possible value of \fB$str\fP\&. +.RE +.TP +\fBc\fP +With \fB${#\fP\fIname\fP\fB}\fP, 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\&. +.TP +\fBC\fP +Capitalize the resulting words\&. `Words\&' in this case refers to sequences +of alphanumeric characters separated by non\-alphanumerics, \fInot\fP to words +that result from field splitting\&. +.TP +\fBD\fP +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 `\fB~\fP\&' substitution: see +the section FILENAME EXPANSION below\&. +.TP +\fBe\fP +Perform single word shell expansions, namely \fIparameter expansion\fP, +\fIcommand substitution\fP and \fIarithmetic expansion\fP, on the +result\&. Such expansions can be nested but too deep recursion may have +unpredictable effects\&. +.TP +\fBf\fP +Split the result of the expansion at newlines\&. This is a shorthand +for `\fBps:\en:\fP\&'\&. +.TP +\fBF\fP +Join the words of arrays together using newline as a separator\&. +This is a shorthand for `\fBpj:\en:\fP\&'\&. +.TP +\fBg:\fP\fIopts\fP\fB:\fP +Process escape sequences like the echo builtin when no options are given +(\fBg::\fP)\&. With the \fBo\fP option, octal escapes don\&'t take a leading +zero\&. With the \fBc\fP option, sequences like `\fB^X\fP\&' are also processed\&. +With the \fBe\fP option, processes `\fB\eM\-t\fP\&' and similar sequences like the +print builtin\&. With both of the \fBo\fP and \fBe\fP options, behaves like the +print builtin except that in none of these modes is `\fB\ec\fP\&' interpreted\&. +.TP +\fBi\fP +Sort case\-insensitively\&. May be combined with `\fBn\fP\&' or `\fBO\fP'\&. +.TP +\fBk\fP +If \fIname\fP refers to an associative array, substitute the \fIkeys\fP +(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 +\fBKSH_ARRAYS\fP option a subscript `\fB[*]\fP\&' or `\fB[@]\fP' is needed +to operate on the whole array, as usual\&. +.TP +\fBL\fP +Convert all letters in the result to lower case\&. +.TP +\fBn\fP +Sort decimal integers numerically; if the first differing +characters of two test strings are not digits, sorting +is lexical\&. `\fB+\fP\&' and `\fB\-\fP' are not treated specially; they are treated as +any other non\-digit\&. Integers with more initial zeroes +are sorted before those with fewer or none\&. Hence the array `\fBfoo+24 foo1 foo02 +foo2 foo3 foo20 foo23\fP\&' is sorted into the order shown\&. +May be combined with `\fBi\fP\&' or `\fBO\fP'\&. +.TP +\fB\-\fP +As \fBn\fP, but a leading minus sign indicates a negative decimal +integer\&. A leading minus sign not followed by an integer does not trigger +numeric sorting\&. +Note that `\fB+\fP\&' signs are not handled specially (this may change in the +future)\&. +.TP +\fBo\fP +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 `\fBa\fP\&', `\fBi\fP', `\fBn\fP' or `\fB\-\fP'\&. +.TP +\fBO\fP +Sort the resulting words in descending order; `\fBO\fP\&' without `\fBa\fP', +`\fBi\fP\&', `\fBn\fP' or `\fB\-\fP' sorts in reverse lexical order\&. May be +combined with `\fBa\fP\&', `\fBi\fP', `\fBn\fP' or `\fB\-\fP' to reverse the +order of sorting\&. +.TP +\fBP\fP +This forces the value of the parameter \fIname\fP to be interpreted as a +further parameter name, whose value will be used where appropriate\&. +Note that flags set with one of the \fBtypeset\fP family of commands +(in particular case transformations) are not applied to the value of +\fIname\fP used in this fashion\&. +.RS +.PP +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 `\fBfoo=bar\fP\&' and `\fBbar=baz\fP', the strings \fB${(P)foo}\fP, +\fB${(P)${foo}}\fP, and \fB${(P)$(echo bar)}\fP will be expanded to +`\fBbaz\fP\&'\&. +.PP +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 `\fBname=assoc\fP\&' where the parameter +\fBassoc\fP is an associative array, then +`\fB${${(P)name}[elt]}\fP\&' refers to the element of the associative +subscripted `\fBelt\fP\&'\&. +.RE +.TP +\fBq\fP +Quote characters that are special to the shell in the resulting words with +backslashes; unprintable or invalid characters are quoted using the +\fB$\&'\e\fP\fINNN\fP\fB'\fP form, with separate quotes for each octet\&. +.RS +.PP +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 \fB$\fP\&. 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\&. +.PP +If a \fBq\-\fP is given (only a single \fBq\fP 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\&. +.PP +If a \fBq+\fP is given, an extended form of minimal quoting is used that +causes unprintable characters to be rendered using \fB$\&'\fP\fI\&.\&.\&.\fP\fB'\fP\&. +This quoting is similar to that used by the output of values by the +\fBtypeset\fP family of commands\&. +.RE +.TP +\fBQ\fP +Remove one level of quotes from the resulting words\&. +.TP +\fBt\fP +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 (`\fB\-\fP\&')\&. The first keyword in the string describes +the main type, it can be one of `\fBscalar\fP\&', `\fBarray\fP', `\fBinteger\fP', +`\fBfloat\fP\&' or `\fBassociation\fP'\&. The other keywords describe the type in +more detail: +.RS +.PP +.PD 0 +.TP +.PD +\fBlocal\fP +for local parameters +.TP +\fBleft\fP +for left justified parameters +.TP +\fBright_blanks\fP +for right justified parameters with leading blanks +.TP +\fBright_zeros\fP +for right justified parameters with leading zeros +.TP +\fBlower\fP +for parameters whose value is converted to all lower case when it is +expanded +.TP +\fBupper\fP +for parameters whose value is converted to all upper case when it is +expanded +.TP +\fBreadonly\fP +for readonly parameters +.TP +\fBtag\fP +for tagged parameters +.TP +\fBtied\fP +for parameters tied to another parameter in the manner of \fBPATH\fP +(colon\-separated list) and \fBpath\fP (array), whether these are +special parameters or user\-defined with `\fBtypeset \-T\fP\&' +.TP +\fBexport\fP +for exported parameters +.TP +\fBunique\fP +for arrays which keep only the first occurrence of duplicated values +.TP +\fBhide\fP +for parameters with the `hide\&' flag +.TP +\fBhideval\fP +for parameters with the `hideval\&' flag +.TP +\fBspecial\fP +for special parameters defined by the shell +.RE +.TP +\fBu\fP +Expand only the first occurrence of each unique word\&. +.TP +\fBU\fP +Convert all letters in the result to upper case\&. +.TP +\fBv\fP +Used with \fBk\fP, 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\&. +.TP +\fBV\fP +Make any special characters in the resulting words visible\&. +.TP +\fBw\fP +With \fB${#\fP\fIname\fP\fB}\fP, count words in arrays or strings; the \fBs\fP +flag may be used to set a word delimiter\&. +.TP +\fBW\fP +Similar to \fBw\fP with the difference that empty words between +repeated delimiters are also counted\&. +.TP +\fBX\fP +With this flag, parsing errors occurring with the \fBQ\fP, \fBe\fP and \fB#\fP +flags or the pattern matching forms such as +`\fB${\fP\fIname\fP\fB#\fP\fIpattern\fP\fB}\fP\&' are reported\&. Without the flag, +errors are silently ignored\&. +.TP +\fBz\fP +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 \fBINTERACTIVE_COMMENTS\fP option unset +(however, see the \fBZ\fP flag below for related options) +.RS +.PP +Note that this is done very late, even later than the `\fB(s)\fP\&' flag\&. So to +access single words in the result use nested expansions as +in `\fB${${(z)foo}[2]}\fP\&'\&. Likewise, to remove the quotes in the +resulting words use `\fB${(Q)${(z)foo}}\fP\&'\&. +.RE +.TP +\fB0\fP +Split the result of the expansion on null bytes\&. This is a shorthand +for `\fBps:\e0:\fP\&'\&. +.PP +The following flags (except \fBp\fP) are followed by one or more arguments +as shown\&. Any character, or the matching pairs `\fB(\fP\&.\&.\&.\fB)\fP\&', +`\fB{\fP\&.\&.\&.\fB}\fP\&', `\fB[\fP\&.\&.\&.\fB]\fP', or `\fB<\fP\&.\&.\&.\fB>\fP', 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\&. +.PP +.PD 0 +.TP +.PD +\fBp\fP +Recognize the same escape sequences as the \fBprint\fP builtin +in string arguments to any of the flags described below that +follow this argument\&. +.RS +.PP +Alternatively, with this option string arguments may be in the form +\fB$\fP\fIvar\fP in which case the value of the variable is substituted\&. +Note this form is strict; the string argument does not undergo general +parameter expansion\&. +.PP +For example, +.PP +.RS +.nf +\fBsep=: +val=a:b:c +print ${(ps\&.$sep\&.)val}\fP +.fi +.RE +.PP +splits the variable on a \fB:\fP\&. +.RE +.TP +\fB~\fP +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 \fB~\fP within the same set of parentheses\&. Compare with \fB~\fP +outside parentheses, which forces the entire substituted string to +be treated as a pattern\&. Hence, for example, +.RS +.PP +.RS +.nf +\fB[[ "?" = ${(~j\&.|\&.)array} ]]\fP +.fi +.RE +.PP +treats `\fB|\fP\&' as a pattern and succeeds if and only if \fB$array\fP +contains the string `\fB?\fP\&' as an element\&. The \fB~\fP may be +repeated to toggle the behaviour; its effect only lasts to the +end of the parenthesised group\&. +.RE +.TP +\fBj:\fP\fIstring\fP\fB:\fP +Join the words of arrays together using \fIstring\fP as a separator\&. +Note that this occurs before field splitting by the \fBs:\fP\fIstring\fP\fB:\fP +flag or the \fBSH_WORD_SPLIT\fP option\&. +.TP +\fBl:\fP\fIexpr\fP\fB::\fP\fIstring1\fP\fB::\fP\fIstring2\fP\fB:\fP +Pad the resulting words on the left\&. Each word will be truncated if +required and placed in a field \fIexpr\fP characters wide\&. +.RS +.PP +The arguments \fB:\fP\fIstring1\fP\fB:\fP and \fB:\fP\fIstring2\fP\fB:\fP 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 \fIstring1\fP (concatenated as +often as needed) or spaces if \fIstring1\fP is not given\&. If both +\fIstring1\fP and \fIstring2\fP are given, \fIstring2\fP is inserted once +directly to the left of each word, truncated if necessary, before +\fIstring1\fP is used to produce any remaining padding\&. +.PP +If either of \fIstring1\fP or \fIstring2\fP is present but empty, +i\&.e\&. there are two delimiters together at that point, the first +character of \fB$IFS\fP is used instead\&. +.PP +If the \fBMULTIBYTE\fP option is in effect, the flag \fBm\fP 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\&. +.PP +If the \fBMULTIBYTE\fP option is not in effect, each byte in the string is +treated as occupying one unit of width\&. +.PP +Control characters are always assumed to be one unit wide; this allows the +mechanism to be used for generating repetitions of control characters\&. +.RE +.TP +\fBm\fP +Only useful together with one of the flags \fBl\fP or \fBr\fP or with the +\fB#\fP length operator when the \fBMULTIBYTE\fP 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\&. +.RS +.PP +If the \fBm\fP 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)\&. +.RE +.TP +\fBr:\fP\fIexpr\fP\fB::\fP\fIstring1\fP\fB::\fP\fIstring2\fP\fB:\fP +As \fBl\fP, but pad the words on the right and insert \fIstring2\fP +immediately to the right of the string to be padded\&. +.RS +.PP +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\&. +.RE +.TP +\fBs:\fP\fIstring\fP\fB:\fP +Force field splitting at the +separator \fIstring\fP\&. Note that a \fIstring\fP 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 \fBIFS\fP parameter\&. +See also the \fB=\fP flag and the \fBSH_WORD_SPLIT\fP option\&. An empty +string may also be given in which case every character will be a separate +element\&. +.RS +.PP +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: +.PP +.RS +.nf +\fBline="one::three" +print \-l "${(s\&.:\&.)line}"\fP +.fi +.RE +.PP +produces two lines of output for \fBone\fP and \fBthree\fP and elides the +empty field\&. To override this behaviour, supply the `\fB(@)\fP\&' flag as well, +i\&.e\&. \fB"${(@s\&.:\&.)line}"\fP\&. +.RE +.TP +\fBZ:\fP\fIopts\fP\fB:\fP +As \fBz\fP but takes a combination of option letters between a following +pair of delimiter characters\&. With no options the effect is identical +to \fBz\fP\&. The following options are available: +.RS +.PP +.PD 0 +.TP +.PD +\fB(Z+c+)\fP +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\&. +.TP +\fB(Z+C+)\fP +causes comments to be parsed +and removed\&. The rule for comments is standard: anything between a word +starting with the third character of \fB$HISTCHARS\fP, default \fB#\fP, up to +the next newline is a comment\&. +.TP +\fB(Z+n+)\fP +causes +unquoted newlines to be treated as ordinary whitespace, else they are +treated as if they are shell code delimiters and converted to +semicolons\&. +.PP +Options are combined within the same set of delimiters, +e\&.g\&. \fB(Z+Cn+)\fP\&. +.RE +.TP +\fB_:\fP\fIflags\fP\fB:\fP +The underscore (\fB_\fP) flag is reserved for future use\&. As of this +revision of zsh, there are no valid \fIflags\fP; anything following an +underscore, other than an empty pair of delimiters, is treated as an +error, and the flag itself has no effect\&. +.PP +The following flags are meaningful with the \fB${\fP\&.\&.\&.\fB#\fP\&.\&.\&.\fB}\fP or +\fB${\fP\&.\&.\&.\fB%\fP\&.\&.\&.\fB}\fP forms\&. The \fBS\fP, \fBI\fP, and \fB*\fP flags may also be +used with the \fB${\fP\&.\&.\&.\fB/\fP\&.\&.\&.\fB}\fP forms\&. +.PP +.PD 0 +.TP +.PD +\fBS\fP +With \fB#\fP or \fB##\fP, search for the match that starts closest to the start of +the string (a `substring match\&')\&. Of all matches at a particular position, +\fB#\fP selects the shortest and \fB##\fP the longest: +.RS +.PP +.RS +.nf +\fB% str="aXbXc" +% echo ${(S)str#X*} +abXc +% echo ${(S)str##X*} +a +% \fP +.fi +.RE +.PP +With \fB%\fP or \fB%%\fP, search for the match that starts closest to the end of +the string: +.PP +.RS +.nf +\fB% str="aXbXc" +% echo ${(S)str%X*} +aXbc +% echo ${(S)str%%X*} +aXb +% \fP +.fi +.RE +.PP +(Note that \fB%\fP and \fB%%\fP don\&'t search for the match that ends closest to the +end of the string, as one might expect\&.) +.PP +With substitution via \fB${\fP\&.\&.\&.\fB/\fP\&.\&.\&.\fB}\fP or +\fB${\fP\&.\&.\&.\fB//\fP\&.\&.\&.\fB}\fP, specifies non\-greedy matching, i\&.e\&. that the +shortest instead of the longest match should be replaced: +.PP +.RS +.nf +\fB% str="abab" +% echo ${str/*b/_} +_ +% echo ${(S)str/*b/_} +_ab +% \fP +.fi +.RE +.RE +.TP +\fBI:\fP\fIexpr\fP\fB:\fP +Search the \fIexpr\fPth match (where \fIexpr\fP evaluates to a number)\&. +This only applies when searching for substrings, either with the \fBS\fP +flag, or with \fB${\fP\&.\&.\&.\fB/\fP\&.\&.\&.\fB}\fP (only the \fIexpr\fPth match is +substituted) or \fB${\fP\&.\&.\&.\fB//\fP\&.\&.\&.\fB}\fP (all matches from the +\fIexpr\fPth on are substituted)\&. The default is to take the first match\&. +.RS +.PP +The \fIexpr\fPth 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 \fB${\fP\&.\&.\&.\fB%\fP\&.\&.\&.\fB}\fP and \fB${\fP\&.\&.\&.\fB%%\fP\&.\&.\&.\fB}\fP 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\&. +.PP +Hence with the string +.RS +.nf +\fBwhich switch is the right switch for Ipswich?\fP +.fi +.RE +substitutions of the form +\fB${\fP(\fBSI:\fP\fIN\fP\fB:\fP)\fBstring#w*ch}\fP as \fIN\fP increases +from 1 will match and remove `\fBwhich\fP\&', `\fBwitch\fP', `\fBwitch\fP' and +`\fBwich\fP\&'; the form using `\fB##\fP' will match and remove `\fBwhich switch +is the right switch for Ipswich\fP\&', `\fBwitch is the right switch for +Ipswich\fP\&', `\fBwitch for Ipswich\fP' and `\fBwich\fP'\&. The form using `\fB%\fP' +will remove the same matches as for `\fB#\fP\&', but in reverse order, and the +form using `\fB%%\fP\&' will remove the same matches as for `\fB##\fP' in reverse +order\&. +.RE +.TP +\fB*\fP +Enable \fBEXTENDED_GLOB\fP for substitution via \fB${\fP\&.\&.\&.\fB/\fP\&.\&.\&.\fB}\fP or +\fB${\fP\&.\&.\&.\fB//\fP\&.\&.\&.\fB}\fP\&. Note that `\fB**\fP\&' does not disable extendedglob\&. +.TP +\fBB\fP +Include the index of the beginning of the match in the result\&. +.TP +\fBE\fP +Include the index one character past the end of the match in the result +(note this is inconsistent with other uses of parameter index)\&. +.TP +\fBM\fP +Include the matched portion in the result\&. +.TP +\fBN\fP +Include the length of the match in the result\&. +.TP +\fBR\fP +Include the unmatched portion in the result (the \fIR\fPest)\&. +.PP +.SS "Rules" +Here is a summary of the rules for substitution; this assumes that braces +are present around the substitution, i\&.e\&. \fB${\fP\fI\&.\&.\&.\fP\fB}\fP\&. Some particular +examples are given below\&. Note that the Zsh Development Group accepts +\fIno responsibility\fP for any brain damage which may occur during the +reading of the following rules\&. +.PP +.PD 0 +.TP +.PD +\fB1\&.\fP \fINested substitution\fP +If multiple nested \fB${\fP\fI\&.\&.\&.\fP\fB}\fP 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\&. +.RS +.PP +Note that, unless the `\fB(P)\fP\&' flag is present, the flags and any +subscripts apply directly to the value of the nested substitution; for +example, the expansion \fB${${foo}}\fP behaves exactly the same as +\fB${foo}\fP\&. When the `\fB(P)\fP\&' flag is present in a nested substitution, +the other substitution rules are applied to the value \fIbefore\fP it is +interpreted as a name, so \fB${${(P)foo}}\fP may differ from \fB${(P)foo}\fP\&. +.PP +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 \fB~\fP and \fB=\fP)\&. Thus, for example, \fB${${:\-=cat}:h}\fP +expands to the directory where the \fBcat\fP program resides\&. (Explanation: +the internal substitution has no parameter but a default value \fB=cat\fP, +which is expanded by filename expansion to a full path; the outer +substitution then applies the modifier \fB:h\fP and takes the directory part +of the path\&.) +.RE +.TP +\fB2\&.\fP \fIInternal parameter flags\fP +Any parameter flags set by one of the \fBtypeset\fP family of commands, in +particular the \fB\-L\fP, \fB\-R\fP, \fB\-Z\fP, \fB\-u\fP and \fB\-l\fP options for +padding and capitalization, are applied directly to the parameter value\&. +Note these flags are options to the command, e\&.g\&. `\fBtypeset \-Z\fP\&'; they +are not the same as the flags used within parameter substitutions\&. +.RS +.PP +At the outermost level of substitution, the `\fB(P)\fP\&' flag (rule \fB4\&.\fP) +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 +\fB${${(P)foo}}\fP form (rule \fB25\&.\fP)\&. +.RE +.TP +\fB3\&.\fP \fIParameter subscripting\fP +If the value is a raw parameter reference with a subscript, such as +\fB${\fP\fIvar\fP\fB[3]}\fP, 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 \fBvar\fP is an array, \fB${var[1][2]}\fP is the second +character of the first word, but \fB${var[2,4][2]}\fP 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 +`\fB(k)\fP\&' and `\fB(v)\fP' which alter the result of subscripting are applied\&. +.TP +\fB4\&.\fP \fIParameter name replacement\fP +At the outermost level of nesting only, the `\fB(P)\fP\&' 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 `\fB(P)\fP\&' flag appears in a nested +substitution\&. +.RS +.PP +If the value so far names a parameter that has internal flags (rule \fB2\&.\fP), +those internal flags are applied to the new value after replacement\&. +.RE +.TP +\fB5\&.\fP \fIDouble\-quoted joining\fP +If the value after this process is an array, and the substitution +appears in double quotes, and neither an `\fB(@)\fP\&' flag nor a `\fB#\fP' +length operator is present at the current level, then words of the +value are joined with the first character of the parameter \fB$IFS\fP, +by default a space, between each word (single word arrays are not +modified)\&. If the `\fB(j)\fP\&' flag is present, that is used for joining +instead of \fB$IFS\fP\&. +.TP +\fB6\&.\fP \fINested subscripting\fP +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 +\fB3\&.\fP, multiple subscripts can appear\&. Note that \fB${foo[2,4][2]}\fP is +thus equivalent to \fB${${foo[2,4]}[2]}\fP and also to +\fB"${${(@)foo[2,4]}[2]}"\fP (the nested substitution returns an array in +both cases), but not to \fB"${${foo[2,4]}[2]}"\fP (the nested substitution +returns a scalar because of the quotes)\&. +.TP +\fB7\&.\fP \fIModifiers\fP +Any modifiers, as specified by a trailing `\fB#\fP\&', `\fB%\fP', `\fB/\fP' +(possibly doubled) or by a set of modifiers of the form `\fB:\&.\&.\&.\fP\&' (see +the section `Modifiers\&' in the section `History Expansion'), are applied to the words +of the value at this level\&. +.TP +\fB8\&.\fP \fICharacter evaluation\fP +Any `\fB(#)\fP\&' flag is applied, evaluating the result so far numerically +as a character\&. +.TP +\fB9\&.\fP \fILength\fP +Any initial `\fB#\fP\&' modifier, i\&.e\&. in the form \fB${#\fP\fIvar\fP\fB}\fP, is +used to evaluate the length of the expression so far\&. +.TP +\fB10\&.\fP \fIForced joining\fP +If the `\fB(j)\fP\&' flag is present, or no `\fB(j)\fP' flag is present but +the string is to be split as given by rule \fB11\&.\fP, and joining +did not take place at rule \fB5\&.\fP, any words in the value are joined +together using the given string or the first character of \fB$IFS\fP if none\&. +Note that the `\fB(F)\fP\&' flag implicitly supplies a string for joining in this +manner\&. +.TP +\fB11\&.\fP \fISimple word splitting\fP +If one of the `\fB(s)\fP\&' or `\fB(f)\fP' flags are present, or the `\fB=\fP' +specifier was present (e\&.g\&. \fB${=\fP\fIvar\fP\fB}\fP), the word is split on +occurrences of the specified string, or (for \fB=\fP with neither of the two +flags present) any of the characters in \fB$IFS\fP\&. +.RS +.PP +If no `\fB(s)\fP\&', `\fB(f)\fP' or `\fB=\fP' was given, but the word is not +quoted and the option \fBSH_WORD_SPLIT\fP is set, the word is split on +occurrences of any of the characters in \fB$IFS\fP\&. Note this step, too, +takes place at all levels of a nested substitution\&. +.RE +.TP +\fB12\&.\fP \fICase modification\fP +Any case modification from one of the flags `\fB(L)\fP\&', `\fB(U)\fP' or `\fB(C)\fP' +is applied\&. +.TP +\fB13\&.\fP \fIEscape sequence replacement\fP +First any replacements from the `\fB(g)\fP\&' flag are performed, then any +prompt\-style formatting from the `\fB(%)\fP\&' family of flags is applied\&. +.TP +\fB14\&.\fP \fIQuote application\fP +Any quoting or unquoting using `\fB(q)\fP\&' and `\fB(Q)\fP' and related flags +is applied\&. +.TP +\fB15\&.\fP \fIDirectory naming\fP +Any directory name substitution using `\fB(D)\fP\&' flag is applied\&. +.TP +\fB16\&.\fP \fIVisibility enhancement\fP +Any modifications to make characters visible using the `\fB(V)\fP\&' flag +are applied\&. +.TP +\fB17\&.\fP \fILexical word splitting\fP +If the \&'\fB(z)\fP' flag or one of the forms of the '\fB(Z)\fP' 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 \fB11\&.\fP: it does not use \fB$IFS\fP, and +does not cause forced joining\&. +.TP +\fB18\&.\fP \fIUniqueness\fP +If the result is an array and the `\fB(u)\fP\&' flag was present, duplicate +elements are removed from the array\&. +.TP +\fB19\&.\fP \fIOrdering\fP +If the result is still an array and one of the `\fB(o)\fP\&' or `\fB(O)\fP' flags +was present, the array is reordered\&. +.TP +\fB20\&.\fP \fBRC_EXPAND_PARAM\fP +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 \fBRC_EXPAND_PARAM\fP option or the `\fB^\fP\&' flag\&. +.TP +\fB21\&.\fP \fIRe\-evaluation\fP +Any `\fB(e)\fP\&' flag is applied to the value, forcing it to be re\-examined +for new parameter substitutions, but also for command and arithmetic +substitutions\&. +.TP +\fB22\&.\fP \fIPadding\fP +Any padding of the value by the `\fB(l\&.\fP\fIfill\fP\fB\&.)\fP\&' or +`\fB(r\&.\fP\fIfill\fP\fB\&.)\fP\&' flags is applied\&. +.TP +\fB23\&.\fP \fISemantic joining\fP +In contexts where expansion semantics requires a single word to +result, all words are rejoined with the first character of \fBIFS\fP +between\&. So in `\fB${(P\fP\fB)${(f\fP\fB)lines}}\fP\&' +the value of \fB${lines}\fP is split at newlines, but then must be +joined again before the `\fB(P)\fP\&' flag can be applied\&. +.RS +.PP +If a single word is not required, this rule is skipped\&. +.RE +.TP +\fB24\&.\fP \fIEmpty argument removal\fP +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\&. +.RS +.PP +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\&. +.RE +.TP +\fB25\&.\fP \fINested parameter name replacement\fP +If the `\fB(P)\fP\&' flag is present and rule \fB4\&.\fP 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 \fB2\&.\fP) applied to the new value\&. +.PP +.SS "Examples" +The flag \fBf\fP is useful to split a double\-quoted substitution line by +line\&. For example, \fB${(f)"$(<\fP\fIfile\fP\fB)"}\fP +substitutes the contents of \fIfile\fP divided so that each line is +an element of the resulting array\&. Compare this with the effect of +\fB$\fP\fB(<\fP\fIfile\fP\fB)\fP 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\&. +.PP +The following illustrates the rules for nested parameter expansions\&. +Suppose that \fB$foo\fP contains the array \fB(bar baz\fP\fB)\fP: +.PP +.PD 0 +.TP +.PD +\fB"${(@)${foo}[1]}"\fP +This produces the result \fBb\fP\&. First, the inner substitution +\fB"${foo}"\fP, which has no array (\fB@\fP) flag, produces a single word +result \fB"bar baz"\fP\&. The outer substitution \fB"${(@)\&.\&.\&.[1]}"\fP detects +that this is a scalar, so that (despite the `\fB(@)\fP\&' flag) the subscript +picks the first character\&. +.TP +\fB"${${(@)foo}[1]}"\fP +This produces the result `\fBbar\fP\&'\&. In this case, the inner substitution +\fB"${(@)foo}"\fP produces the array `\fB(bar baz\fP\fB)\fP\&'\&. The outer +substitution \fB"${\&.\&.\&.[1]}"\fP detects that this is an array and picks the +first word\&. This is similar to the simple case \fB"${foo[1]}"\fP\&. +.PP +As an example of the rules for word splitting and joining, suppose \fB$foo\fP +contains the array `\fB(ax1 bx1\fP\fB)\fP\&'\&. Then +.PP +.PD 0 +.TP +.PD +\fB${(s/x/)foo}\fP +produces the words `\fBa\fP\&', `\fB1 b\fP' and `\fB1\fP'\&. +.TP +\fB${(j/x/s/x/)foo}\fP +produces `\fBa\fP\&', `\fB1\fP', `\fBb\fP' and `\fB1\fP'\&. +.TP +\fB${(s/x/)foo%%1*}\fP +produces `\fBa\fP\&' and `\fB b\fP' (note the extra space)\&. As substitution +occurs before either joining or splitting, the operation first generates +the modified array \fB(ax bx\fP\fB)\fP, which is joined to give +\fB"ax bx"\fP, and then split to give `\fBa\fP\&', `\fB b\fP' and `'\&. The final +empty string will then be elided, as it is not in double quotes\&. +.PP +.SH "COMMAND SUBSTITUTION" +A command enclosed in parentheses preceded by a dollar sign, like +`\fB$(\fP\&.\&.\&.\fB)\fP\&', or quoted with grave +accents, like `\fB`\fP\&.\&.\&.\fB`\fP\&', 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 \fBIFS\fP parameter\&. +.PP +The substitution `\fB$(cat\fP \fIfoo\fP\fB)\fP\&' may be replaced +by the faster `\fB$(<\fP\fIfoo\fP\fB)\fP\&'\&. In this case \fIfoo\fP +undergoes single word shell expansions (\fIparameter expansion\fP, +\fIcommand substitution\fP and \fIarithmetic expansion\fP), but not +filename generation\&. +.PP +If the option \fBGLOB_SUBST\fP is set, the result of any unquoted command +substitution, including the special form just mentioned, is eligible for +filename generation\&. +.PP +.SH "ARITHMETIC EXPANSION" +A string of the form `\fB$[\fP\fIexp\fP\fB]\fP\&' or +`\fB$((\fP\fIexp\fP\fB))\fP\&' is substituted +with the value of the arithmetic expression \fIexp\fP\&. \fIexp\fP is +subjected to \fIparameter expansion\fP, \fIcommand substitution\fP +and \fIarithmetic expansion\fP before it is evaluated\&. +See the section `Arithmetic Evaluation\&'\&. +.SH "BRACE EXPANSION" +A string of the form +`\fIfoo\fP\fB{\fP\fIxx\fP\fB,\fP\fIyy\fP\fB,\fP\fIzz\fP\fB}\fP\fIbar\fP\&' +is expanded to the individual words +`\fIfooxxbar\fP\&', `\fIfooyybar\fP' and `\fIfoozzbar\fP'\&. +Left\-to\-right order is preserved\&. This construct +may be nested\&. Commas may be quoted in order to +include them literally in a word\&. +.PP +An expression of the form `\fB{\fP\fIn1\fP\fB\&.\&.\fP\fIn2\fP\fB}\fP\&', +where \fIn1\fP and \fIn2\fP are integers, +is expanded to every number between +\fIn1\fP and \fIn2\fP 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 \fB\-\fP character is also +included in the width\&. If the numbers are in decreasing order the +resulting sequence will also be in decreasing order\&. +.PP +An expression of the form `\fB{\fP\fIn1\fP\fB\&.\&.\fP\fIn2\fP\fB\&.\&.\fP\fIn3\fP\fB}\fP\&', +where \fIn1\fP, \fIn2\fP, and \fIn3\fP are integers, +is expanded as above, but only every \fIn3\fPth number starting from \fIn1\fP +is output\&. If \fIn3\fP is negative the numbers are output in reverse order, +this is slightly different from simply swapping \fIn1\fP and \fIn2\fP in the case +that the step \fIn3\fP 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 `\fB{\-99\&.\&.100\&.\&.01}\fP\&' which is not possible to specify by putting a +0 on either of the first two numbers (i\&.e\&. pad to two characters)\&. +.PP +An expression of the form `\fB{\fP\fIc1\fP\fB\&.\&.\fP\fIc2\fP\fB}\fP\&', where +\fIc1\fP and \fIc2\fP are single characters (which may be multibyte +characters), is expanded to every character in the range from \fIc1\fP to +\fIc2\fP 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\&. `\fB{d\&.\&.a}\fP\&' is substituted as `\fBd c b a\fP'\&. +.PP +If a brace expression matches none of the above forms, it is left +unchanged, unless the option \fBBRACE_CCL\fP (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 +\fB[\fP\&.\&.\&.\fB]\fP expression in filename generation: +`\fB\-\fP\&' is treated specially to denote a range of characters, but `\fB^\fP' or +`\fB!\fP\&' as the first character is treated normally\&. For example, +`\fB{abcdef0\-9}\fP\&' expands to 16 words \fB0 1 2 3 4 5 6 7 8 9 a b c d e f\fP\&. +.PP +Note that brace expansion is not part of filename generation (globbing); an +expression such as \fB*/{foo,bar}\fP is split into two separate words +\fB*/foo\fP and \fB*/bar\fP before filename generation takes place\&. In +particular, note that this is liable to produce a `no match\&' error if +\fIeither\fP of the two expressions does not match; this is to be contrasted +with \fB*/(foo|bar)\fP, which is treated as a single pattern but otherwise +has similar effects\&. +.PP +To combine brace expansion with array expansion, see the +\fB${^\fP\fIspec\fP\fB}\fP form described +in the section `Parameter Expansion\&' +above\&. +.PP +.SH "FILENAME EXPANSION" +Each word is checked to see if it begins with an unquoted `\fB~\fP\&'\&. +If it does, then the word up to a `\fB/\fP\&', +or the end of the word if there is no `\fB/\fP\&', +is checked to see if it can be substituted in one of the ways +described here\&. If so, then the `\fB~\fP\&' and the checked portion are +replaced with the appropriate substitute value\&. +.PP +A `\fB~\fP\&' by itself is replaced by the value of \fB$HOME\fP\&. +A `\fB~\fP\&' followed by a `\fB+\fP' or a `\fB\-\fP' is replaced by current +or previous working directory, respectively\&. +.PP +A `\fB~\fP\&' followed by a number is replaced by the directory at that +position in the directory stack\&. +`\fB~0\fP\&' is equivalent to `\fB~+\fP', +and `\fB~1\fP\&' is the top of the stack\&. +`\fB~+\fP\&' followed by a number is replaced by the directory at that +position in the directory stack\&. +`\fB~+0\fP\&' is equivalent to `\fB~+\fP', +and `\fB~+1\fP\&' is the top of the stack\&. +`\fB~\-\fP\&' followed by a number is replaced by the directory that +many positions from the bottom of the stack\&. +`\fB~\-0\fP\&' is the bottom of the stack\&. +The \fBPUSHD_MINUS\fP +option exchanges the effects of `\fB~+\fP\&' and `\fB~\-\fP' where they are +followed by a number\&. +.PP +.PP +.SS "Dynamic named directories" +If the function \fBzsh_directory_name\fP exists, or the shell variable +\fBzsh_directory_name_functions\fP 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\&. +.PP +A `\fB~\fP\&' followed by a string \fInamstr\fP in unquoted square brackets is +treated specially as a dynamic directory name\&. Note that the first +unquoted closing square bracket always terminates \fInamstr\fP\&. The shell +function is passed two arguments: the string \fBn\fP (for name) and +\fInamstr\fP\&. It should either set the array \fBreply\fP 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 \fBNOMATCH\fP is set, +an error results\&. +.PP +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 \fB%~\fP in prompts\&. In this case each function is passed two +arguments: the string \fBd\fP (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 `\fB~[\fP\fI\&.\&.\&.\fP\fB]\fP\&'), and the second is the +prefix length of the directory to be replaced\&. For example, if the trial +directory is \fB/home/myname/src/zsh\fP and the dynamic name for +\fB/home/myname/src\fP (which has 16 characters) is \fBs\fP, then the function +sets +.PP +.RS +.nf +\fBreply=(s 16)\fP +.fi +.RE +.PP +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\&. +.PP +It is not a requirement that a function implements both +\fBn\fP and \fBd\fP 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 \fBd\fP should cause a non\-zero status to +be returned\&. +.PP +The completion system calls `\fBzsh_directory_name c\fP\&' followed by +equivalent calls to elements of the array +\fBzsh_directory_name_functions\fP, 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 +\fIzshcompsys\fP(1)\&. +.PP +As a working example, here is a function that expands any dynamic names +beginning with the string \fBp:\fP to directories below +\fB/home/pws/perforce\fP\&. In this simple case a static name for the +directory would be just as effective\&. +.PP +.RS +.nf +\fBzsh_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\e] \-a dirs + return + else + return 1 + fi + return 0 +}\fP +.fi +.RE +.PP +.SS "Static named directories" +A `\fB~\fP\&' followed by anything not already covered consisting +of any number of alphanumeric characters or underscore (`\fB_\fP\&'), +hyphen (`\fB\-\fP\&'), or dot (`\fB\&.\fP') 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 `\fB~\fP\&' is the name +of a string shell parameter whose value begins with a `\fB/\fP\&'\&. +Note that trailing slashes will be removed from the path to the directory +(though the original parameter is not modified)\&. +.PP +It is also possible to define directory names using the \fB\-d\fP option to the +\fBhash\fP builtin\&. +.PP +When the shell prints a path (e\&.g\&. when expanding \fB%~\fP 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 +`\fB~\fP\&' 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 \fB$PWD\fP and \fB$OLDPWD\fP are never abbreviated in this fashion\&. +.PP +.SS "`=\&' expansion" +.PP +If a word begins with an unquoted `\fB=\fP\&' +and the \fBEQUALS\fP 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\&. +.PP +.SS "Notes" +Filename expansion is performed on the right hand side of a parameter +assignment, including those appearing after commands of the +\fBtypeset\fP family\&. In this case, the right hand side will be treated +as a colon\-separated list in the manner of the \fBPATH\fP parameter, +so that a `\fB~\fP\&' or an `\fB=\fP' following a `\fB:\fP' is eligible for expansion\&. +All such behaviour can be +disabled by quoting the `\fB~\fP\&', the `\fB=\fP', or the whole expression (but not +simply the colon); the \fBEQUALS\fP option is also respected\&. +.PP +If the option \fBMAGIC_EQUAL_SUBST\fP is set, any unquoted shell +argument in the form `\fIidentifier\fP\fB=\fP\fIexpression\fP\&' becomes eligible +for file expansion as described in the previous paragraph\&. Quoting the +first `\fB=\fP\&' also inhibits this\&. +.PP +.SH "FILENAME GENERATION" +If a word contains an unquoted instance of one of the characters +`\fB*\fP\&', `\fB(\fP', `\fB|\fP', `\fB<\fP', `\fB[\fP', or `\fB?\fP', it is regarded +as a pattern for filename generation, unless the \fBGLOB\fP option is unset\&. +If the \fBEXTENDED_GLOB\fP option is set, +the `\fB^\fP\&' and `\fB#\fP' characters also denote a pattern; otherwise +they are not treated specially by the shell\&. +.PP +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 \fBNULL_GLOB\fP option is set, +in which case the word is deleted; or unless the \fBNOMATCH\fP +option is unset, in which case the word is left unchanged\&. +.PP +In filename generation, +the character `\fB/\fP\&' must be matched explicitly; +also, a `\fB\&.\fP\&' must be matched +explicitly at the beginning of a pattern or after a `\fB/\fP\&', unless the +\fBGLOB_DOTS\fP option is set\&. +No filename generation pattern +matches the files `\fB\&.\fP\&' or `\fB\&.\&.\fP'\&. In other instances of pattern +matching, the `\fB/\fP\&' and `\fB\&.\fP' are not treated specially\&. +.SS "Glob Operators" +.PD 0 +.TP +.PD +\fB*\fP +Matches any string, including the null string\&. +.TP +\fB?\fP +Matches any character\&. +.TP +\fB[\fP\&.\&.\&.\fB]\fP +Matches any of the enclosed characters\&. Ranges of characters +can be specified by separating two characters by a `\fB\-\fP\&'\&. +A `\fB\-\fP\&' or `\fB]\fP' may be matched by including it as the +first character in the list\&. +There are also several named classes of characters, in the form +`\fB[:\fP\fIname\fP\fB:]\fP\&' 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 +\fIctype\fP(3): +.RS +.PP +.PD 0 +.TP +.PD +\fB[:alnum:]\fP +The character is alphanumeric +.TP +\fB[:alpha:]\fP +The character is alphabetic +.TP +\fB[:ascii:]\fP +The character is 7\-bit, i\&.e\&. is a single\-byte character without +the top bit set\&. +.TP +\fB[:blank:]\fP +The character is a blank character +.TP +\fB[:cntrl:]\fP +The character is a control character +.TP +\fB[:digit:]\fP +The character is a decimal digit +.TP +\fB[:graph:]\fP +The character is a printable character other than whitespace +.TP +\fB[:lower:]\fP +The character is a lowercase letter +.TP +\fB[:print:]\fP +The character is printable +.TP +\fB[:punct:]\fP +The character is printable but neither alphanumeric nor whitespace +.TP +\fB[:space:]\fP +The character is whitespace +.TP +\fB[:upper:]\fP +The character is an uppercase letter +.TP +\fB[:xdigit:]\fP +The character is a hexadecimal digit +.PP +Another set of named classes is handled internally by the shell and +is not sensitive to the locale: +.PP +.PD 0 +.TP +.PD +\fB[:IDENT:]\fP +The character is allowed to form part of a shell identifier, such +as a parameter name; this test respects the \fBPOSIX_IDENTIFIERS\fP +option +.TP +\fB[:IFS:]\fP +The character is used as an input field separator, i\&.e\&. is contained in the +\fBIFS\fP parameter +.TP +\fB[:IFSSPACE:]\fP +The character is an IFS white space character; see the documentation +for \fBIFS\fP in +the \fIzshparam\fP(1) manual page\&. +.TP +\fB[:INCOMPLETE:]\fP +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 +`\fB[[:INCOMPLETE:]]*\fP\&'\&. This will never match a sequence starting +with a valid multibyte character\&. +.TP +\fB[:INVALID:]\fP +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\&. +.TP +\fB[:WORD:]\fP +The character is treated as part of a word; this test is sensitive +to the value of the \fBWORDCHARS\fP parameter +.PP +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 `\fB[[:alnum:]]\fP\&'\&. Named +character sets can be used alongside other types, +e\&.g\&. `\fB[[:alpha:]0\-9]\fP\&'\&. +.RE +.TP +.PD 0 +\fB[^\fP\&.\&.\&.\fB]\fP +.TP +.PD +\fB[!\fP\&.\&.\&.\fB]\fP +Like \fB[\fP\&.\&.\&.\fB]\fP, except that it matches any character which is +not in the given set\&. +.TP +\fB<\fP[\fIx\fP]\fB\-\fP[\fIy\fP]\fB>\fP +Matches any number in the range \fIx\fP to \fIy\fP, inclusive\&. +Either of the numbers may be omitted to make the range open\-ended; +hence `\fB<\->\fP\&' matches any number\&. To match individual digits, the +\fB[\fP\&.\&.\&.\fB]\fP form is more efficient\&. +.RS +.PP +Be careful when using other wildcards adjacent to patterns of this form; +for example, \fB<0\-9>*\fP will actually match any number whatsoever at the +start of the string, since the `\fB<0\-9>\fP\&' will match the first digit, and +the `\fB*\fP\&' 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 `\fB<0\-9>[^[:digit:]]*\fP\&' can be +used instead\&. +.RE +.TP +\fB(\fP\&.\&.\&.\fB)\fP +Matches the enclosed pattern\&. This is used for grouping\&. +If the \fBKSH_GLOB\fP option is set, then a +`\fB@\fP\&', `\fB*\fP', `\fB+\fP', `\fB?\fP' or `\fB!\fP' immediately preceding +the `\fB(\fP\&' is treated specially, as detailed below\&. The option +\fBSH_GLOB\fP prevents bare parentheses from being used in this way, though +the \fBKSH_GLOB\fP option is still available\&. +.RS +.PP +Note that grouping cannot extend over multiple directories: it is an error +to have a `\fB/\fP\&' within a group (this only applies for patterns used in +filename generation)\&. There is one exception: a group of the form +\fB(\fP\fIpat\fP\fB/)#\fP appearing as a complete path segment can +match a sequence of directories\&. For example, \fBfoo/(a*/)#bar\fP matches +\fBfoo/bar\fP, \fBfoo/any/bar\fP, \fBfoo/any/anyother/bar\fP, and so on\&. +.RE +.TP +\fIx\fP\fB|\fP\fIy\fP +Matches either \fIx\fP or \fIy\fP\&. +This operator has lower precedence than any other\&. +The `\fB|\fP\&' character +must be within parentheses, to avoid interpretation as a pipeline\&. +The alternatives are tried in order from left to right\&. +.TP +\fB^\fP\fIx\fP +(Requires \fBEXTENDED_GLOB\fP to be set\&.) +Matches anything except the pattern \fIx\fP\&. +This has a higher precedence than `\fB/\fP\&', so `\fB^foo/bar\fP' +will search directories in `\fB\&.\fP\&' except `\fB\&./foo\fP' +for a file named `\fBbar\fP\&'\&. +.TP +\fIx\fP\fB~\fP\fIy\fP +(Requires \fBEXTENDED_GLOB\fP to be set\&.) +Match anything that matches the pattern \fIx\fP but does not match \fIy\fP\&. +This has lower precedence than any operator except `\fB|\fP\&', so +`\fB*/*~foo/bar\fP\&' will search for all files in all directories in `\fB\&.\fP' +and then exclude `\fBfoo/bar\fP\&' if there was such a match\&. +Multiple patterns can be excluded by +`\fIfoo\fP\fB~\fP\fIbar\fP\fB~\fP\fIbaz\fP\&'\&. +In the exclusion pattern (\fIy\fP), `\fB/\fP\&' and `\fB\&.\fP' are not treated +specially the way they usually are in globbing\&. +.TP +\fIx\fP\fB#\fP +(Requires \fBEXTENDED_GLOB\fP to be set\&.) +Matches zero or more occurrences of the pattern \fIx\fP\&. +This operator has high precedence; `\fB12#\fP\&' is equivalent to `\fB1(2#)\fP', +rather than `\fB(12)#\fP\&'\&. It is an error for an unquoted `\fB#\fP' to follow +something which cannot be repeated; this includes an empty string, a +pattern already followed by `\fB##\fP\&', or parentheses when part of a +\fBKSH_GLOB\fP pattern (for example, `\fB!(\fP\fIfoo\fP\fB)#\fP\&' is +invalid and must be replaced by +`\fB*(!(\fP\fIfoo\fP\fB))\fP\&')\&. +.TP +\fIx\fP\fB##\fP +(Requires \fBEXTENDED_GLOB\fP to be set\&.) +Matches one or more occurrences of the pattern \fIx\fP\&. +This operator has high precedence; `\fB12##\fP\&' is equivalent to `\fB1(2##)\fP', +rather than `\fB(12)##\fP\&'\&. No more than two active `\fB#\fP' characters may +appear together\&. (Note the potential clash with glob qualifiers in the +form `\fB1(2##)\fP\&' which should therefore be avoided\&.) +.SS "ksh\-like Glob Operators" +If the \fBKSH_GLOB\fP option is set, the effects of parentheses can be +modified by a preceding `\fB@\fP\&', `\fB*\fP', `\fB+\fP', `\fB?\fP' or `\fB!\fP'\&. +This character need not be unquoted to have special effects, +but the `\fB(\fP\&' must be\&. +.PP +.PD 0 +.TP +.PD +\fB@(\fP\&.\&.\&.\fB)\fP +Match the pattern in the parentheses\&. (Like `\fB(\fP\&.\&.\&.\fB)\fP\&'\&.) +.TP +\fB*(\fP\&.\&.\&.\fB)\fP +Match any number of occurrences\&. (Like `\fB(\fP\&.\&.\&.\fB)#\fP\&', +except that recursive directory searching is not supported\&.) +.TP +\fB+(\fP\&.\&.\&.\fB)\fP +Match at least one occurrence\&. (Like `\fB(\fP\&.\&.\&.\fB)##\fP\&', +except that recursive directory searching is not supported\&.) +.TP +\fB?(\fP\&.\&.\&.\fB)\fP +Match zero or one occurrence\&. (Like `\fB(|\fP\&.\&.\&.\fB)\fP\&'\&.) +.TP +\fB!(\fP\&.\&.\&.\fB)\fP +Match anything but the expression in parentheses\&. +(Like `\fB(^(\fP\&.\&.\&.\fB))\fP\&'\&.) +.SS "Precedence" +The precedence of the operators given above is (highest) `\fB^\fP\&', `\fB/\fP', +`\fB~\fP\&', `\fB|\fP' (lowest); the +remaining operators are simply treated from left to right as part of a +string, with `\fB#\fP\&' and `\fB##\fP' applying to the shortest possible +preceding unit (i\&.e\&. a character, `\fB?\fP\&', `\fB[\fP\&.\&.\&.\fB]\fP', +`\fB<\fP\&.\&.\&.\fB>\fP\&', or a parenthesised expression)\&. As mentioned +above, a `\fB/\fP\&' used as a directory separator may not appear inside +parentheses, while a `\fB|\fP\&' must do so; in patterns used in other contexts +than filename generation (for example, in \fBcase\fP statements and tests +within `\fB[[\fP\&.\&.\&.\fB]]\fP\&'), a `\fB/\fP' is not special; and `\fB/\fP' is also +not special after a `\fB~\fP\&' appearing outside parentheses in a filename +pattern\&. +.SS "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 \fBEXTENDED_GLOB\fP option\&. All take the form +\fB(#\fP\fIX\fP\fB)\fP where \fIX\fP may have one of the following +forms: +.PP +.PD 0 +.TP +.PD +\fBi\fP +Case insensitive: upper or lower case characters in the pattern match +upper or lower case characters\&. +.TP +\fBl\fP +Lower case characters in the pattern match upper or lower case +characters; upper case characters in the pattern still only match +upper case characters\&. +.TP +\fBI\fP +Case sensitive: locally negates the effect of \fBi\fP or \fBl\fP from +that point on\&. +.TP +\fBb\fP +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 \fB$match\fP, the indices of the beginning of the matched +parentheses in the array \fB$mbegin\fP, and the indices of the end in the array +\fB$mend\fP, 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 \fB$mend\fP and \fB$mbegin\fP may be used in +subscripts; the \fBKSH_ARRAYS\fP option is respected\&. Sets of globbing flags +are not considered parenthesised groups; only the first nine active +parentheses can be referenced\&. +.RS +.PP +For example, +.PP +.RS +.nf +\fBfoo="a_string_with_a_message" +if [[ $foo = (a|an)_(#b)(*) ]]; then + print ${foo[$mbegin[1],$mend[1]]} +fi\fP +.fi +.RE +.PP +prints `\fBstring_with_a_message\fP\&'\&. +Note that the first set of parentheses is before the +\fB(#b)\fP and does not create a backreference\&. +.PP +Backreferences work with all forms of pattern matching other than filename +generation, but note that when performing matches on an entire array, such +as \fB${\fP\fIarray\fP\fB#\fP\fIpattern\fP\fB}\fP, or a global substitution, such +as \fB${\fP\fIparam\fP\fB//\fP\fIpat\fP\fB/\fP\fIrepl\fP\fB}\fP, 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 \fBm\fP flag below\&. +.PP +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 `\fB#\fP\&' or `\fB##\fP'\&. Only the last match of the parenthesis is +remembered: for example, in `\fB[[ abab = (#b)([ab])# ]]\fP\&', only the final +`\fBb\fP\&' is stored in \fBmatch[1]\fP\&. Thus extra parentheses may be necessary +to match the complete segment: for example, use +`\fBX((ab|cd)#)Y\fP\&' to match +a whole string of either `\fBab\fP\&' or `\fBcd\fP' between `\fBX\fP' and `\fBY\fP', +using the value of \fB$match[1]\fP rather than \fB$match[2]\fP\&. +.PP +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 \fB#\fP and matched +zero times \-\- then the matched string is set to the empty string, and the +start and end indices are set to \-1\&. +.PP +Pattern matching with backreferences is slightly slower than without\&. +.RE +.TP +\fBB\fP +Deactivate backreferences, negating the effect of the \fBb\fP flag from that +point on\&. +.TP +\fBc\fP\fIN\fP\fB,\fP\fIM\fP +The flag \fB(#c\fP\fIN\fP\fB,\fP\fIM\fP\fB)\fP can be used anywhere +that the \fB#\fP or \fB##\fP operators can be used except in the expressions +`\fB(*/)#\fP\&' and `\fB(*/)##\fP' in filename generation, where `\fB/\fP' +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 \fB{\fP\fIN\fP\fB,\fP\fIM\fP\fB}\fP in regular expressions\&. The previous +character or group is required to match between \fIN\fP and \fIM\fP times, +inclusive\&. The form \fB(#c\fP\fIN\fP\fB)\fP requires exactly \fBN\fP +matches; \fB(#c,\fP\fIM\fP\fB)\fP is equivalent to specifying \fIN\fP +as 0; \fB(#c\fP\fIN\fP\fB,)\fP specifies that there is no maximum +limit on the number of matches\&. +.TP +\fBm\fP +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 \fB$MATCH\fP, \fB$MBEGIN\fP and \fB$MEND\fP 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\&. +.RS +.PP +For example, +.PP +.RS +.nf +\fBarr=(veldt jynx grimps waqf zho buck) +print ${arr//(#m)[aeiou]/${(U)MATCH}}\fP +.fi +.RE +.PP +forces all the matches (i\&.e\&. all vowels) into uppercase, printing +`\fBvEldt jynx grImps wAqf zhO bUck\fP\&'\&. +.PP +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\&. +.RE +.TP +\fBM\fP +Deactivate the \fBm\fP flag, hence no references to match data will be +created\&. +.TP +\fBa\fP\fInum\fP +Approximate matching: \fInum\fP errors are allowed in the string matched by +the pattern\&. The rules for this are described in the next subsection\&. +.TP +\fBs\fP, \fBe\fP +Unlike the other flags, these have only a local effect, and each must +appear on its own: `\fB(#s)\fP\&' and `\fB(#e)\fP' are the only valid forms\&. +The `\fB(#s)\fP\&' flag succeeds only at the start of the test string, and the +`\fB(#e)\fP\&' flag succeeds only at the end of the test string; they +correspond to `\fB^\fP\&' and `\fB$\fP' 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, `\fB*((#s)|/)test((#e)|/)*\fP\&' matches +a path segment `\fBtest\fP\&' in any of the following strings: \fBtest\fP, +\fBtest/at/start\fP, \fBat/end/test\fP, \fBin/test/middle\fP\&. +.RS +.PP +Another use is in parameter substitution; for example +`\fB${array/(#s)A*Z(#e)}\fP\&' will remove only elements of an +array which +match the complete pattern `\fBA*Z\fP\&'\&. There are other ways of performing +many operations of this type, however the combination of the substitution +operations `\fB/\fP\&' and `\fB//\fP' with the `\fB(#s)\fP' and `\fB(#e)\fP' flags +provides a single simple and memorable method\&. +.PP +Note that assertions of the form `\fB(^(#s))\fP\&' 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 `\fB(""~(#s))\fP\&' to match a zero\-length portion of the string +not at the start\&. +.RE +.TP +\fBq\fP +A `\fBq\fP\&' 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 `\fB(#b)(*)\&.c(#q\&.)\fP\&' can be used both for globbing +and for +matching against a string\&. In the former case, the `\fB(#q\&.)\fP\&' will be +treated as a glob qualifier and the `\fB(#b)\fP\&' will not be useful, while in +the latter case the `\fB(#b)\fP\&' is useful for backreferences and the +`\fB(#q\&.)\fP\&' will be ignored\&. Note that colon modifiers in the glob +qualifiers are also not applied in ordinary pattern matching\&. +.TP +\fBu\fP +Respect the current locale in determining the presence of multibyte +characters in a pattern, provided the shell was compiled with +\fBMULTIBYTE_SUPPORT\fP\&. This overrides the \fBMULTIBYTE\fP +option; the default behaviour is taken from the option\&. Compare \fBU\fP\&. +(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\&.) +.TP +\fBU\fP +All characters are considered to be a single byte long\&. The opposite +of \fBu\fP\&. This overrides the \fBMULTIBYTE\fP option\&. +.PP +For example, the test string \fBfooxx\fP can be matched by the pattern +\fB(#i\fP\fB)FOOXX\fP, but not by \fB(#l\fP\fB)FOOXX\fP, +\fB(#i\fP\fB)FOO\fP\fB(#I\fP\fB)XX\fP or +\fB((#i\fP\fB)FOOX\fP\fB)X\fP\&. The string +\fB(#ia2\fP\fB)readme\fP specifies case\-insensitive matching of +\fBreadme\fP with up to two errors\&. +.PP +When using the ksh syntax for grouping both \fBKSH_GLOB\fP and +\fBEXTENDED_GLOB\fP must be set and the left parenthesis should be +preceded by \fB@\fP\&. Note also that the flags do not affect letters +inside \fB[\fP\&.\&.\&.\fB]\fP groups, in other words \fB(#i\fP\fB)[a\-z]\fP +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 +\fB(#i\fP\fB)/foo/bar/\&.\&.\&.\fP is potentially slow\&. +.PP +.SS "Approximate Matching" +When matching approximately, the shell keeps a count of the errors found, +which cannot exceed the number specified in the +\fB(#a\fP\fInum\fP\fB)\fP flags\&. Four types of error are recognised: +.PP +.PD 0 +.TP +.PD +1\&. +Different characters, as in \fBfooxbar\fP and \fBfooybar\fP\&. +.TP +2\&. +Transposition of characters, as in \fBbanana\fP and \fBabnana\fP\&. +.TP +3\&. +A character missing in the target string, as with the pattern \fBroad\fP and +target string \fBrod\fP\&. +.TP +4\&. +An extra character appearing in the target string, as with \fBstove\fP +and \fBstrove\fP\&. +.PP +Thus, the pattern \fB(#a3\fP\fB)abcd\fP matches \fBdcba\fP, with the +errors occurring by using the first rule twice and the second once, +grouping the string as \fB[d][cb][a]\fP and \fB[a][bc][d]\fP\&. +.PP +Non\-literal parts of the pattern must match exactly, including characters +in character ranges: hence \fB(#a1\fP\fB)???\fP 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 \fB?\fP must match\&. Other characters +which must match exactly are initial dots in filenames (unless the +\fBGLOB_DOTS\fP option is set), and all slashes in filenames, so that +\fBa/bc\fP is two errors from \fBab/c\fP (the slash cannot be transposed with +another character)\&. Similarly, errors are counted separately for +non\-contiguous strings in the pattern, so that \fB(ab|cd\fP\fB)ef\fP +is two errors from \fBaebf\fP\&. +.PP +When using exclusion via the \fB~\fP operator, approximate matching is +treated entirely separately for the excluded part and must be activated +separately\&. Thus, \fB(#a1\fP\fB)README~READ_ME\fP matches +\fBREAD\&.ME\fP but not \fBREAD_ME\fP, as the trailing \fBREAD_ME\fP is matched +without approximation\&. However, +\fB(#a1\fP\fB)README~(#a1\fP\fB)READ_ME\fP +does not match any pattern of the form \fBREAD\fP\fI?\fP\fBME\fP as all +such forms are now excluded\&. +.PP +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, +\fB(#a1\fP\fB)cat\fP\fB((#a0\fP\fB)dog\fP\fB)fox\fP +allows one error in total, which may not occur in the \fBdog\fP section, and +the pattern +\fB(#a1\fP\fB)cat\fP\fB(#a0\fP\fB)dog\fP\fB(#a1\fP\fB)fox\fP +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, +\fB(#a1)abc(#a0)xyz\fP will not match \fBabcdxyz\fP, because the +error occurs at the `\fBx\fP\&', where approximation is turned off\&. +.PP +Entire path segments may be matched approximately, so that +`\fB(#a1)/foo/d/is/available/at/the/bar\fP\&' allows one error in any path +segment\&. This is much less efficient than without the \fB(#a1)\fP, however, +since every directory in the path must be scanned for a possible +approximate match\&. It is best to place the \fB(#a1)\fP after any path +segments which are known to be correct\&. +.PP +.SS "Recursive Globbing" +A pathname component of the form `\fB(\fP\fIfoo\fP\fB/)#\fP\&' +matches a path consisting of zero or more directories +matching the pattern \fIfoo\fP\&. +.PP +As a shorthand, `\fB**/\fP\&' is equivalent to `\fB(*/)#\fP'; note that this +therefore matches files in the current directory as well as +subdirectories\&. +Thus: +.PP +.RS +.nf +\fBls \-ld \-\- (*/)#bar\fP +.fi +.RE +.PP +or +.PP +.RS +.nf +\fBls \-ld \-\- **/bar\fP +.fi +.RE +.PP +does a recursive directory search for files named `\fBbar\fP\&' (potentially +including the file `\fBbar\fP\&' in the current directory)\&. This form does not +follow symbolic links; the alternative form `\fB***/\fP\&' 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 `\fB*\fP\&' +operators revert to their usual effect\&. +.PP +Even shorter forms are available when the option \fBGLOB_STAR_SHORT\fP is +set\&. In that case if no \fB/\fP immediately follows a \fB**\fP or \fB***\fP +they are treated as if both a \fB/\fP plus a further \fB*\fP are present\&. +Hence: +.PP +.RS +.nf +\fBsetopt GLOBSTARSHORT +ls \-ld \-\- **\&.c\fP +.fi +.RE +.PP +is equivalent to +.PP +.RS +.nf +\fBls \-ld \-\- **/*\&.c\fP +.fi +.RE +.SS "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\&. +.PP +If the option \fBBARE_GLOB_QUAL\fP is set, then a trailing set of parentheses +containing no `\fB|\fP\&' or `\fB(\fP' characters (or `\fB~\fP' 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 `\fB(^x)\fP\&', can be forced to be treated as part of +the glob pattern by doubling the parentheses, in this case producing +`\fB((^x))\fP\&'\&. +.PP +If the option \fBEXTENDED_GLOB\fP is set, a different syntax for glob +qualifiers is available, namely `\fB(#q\fP\fIx\fP\fB)\fP\&' +where \fIx\fP 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 `\fB|\fP\&', `\fB(\fP' or +`\fB~\fP\&' 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 `\fB*(#q*)(\&.)\fP\&' 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 +`\fB[[\fP\&' form the presence of a parenthesised expression +\fB(#q\fP\fI\&.\&.\&.\fP\fB)\fP 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 \fB(#q)\fP\&. This does +not apply to the right hand side of pattern match operators as the +syntax already has special significance\&. +.PP +A qualifier may be any one of the following: +.PP +.PD 0 +.TP +.PD +\fB/\fP +directories +.TP +\fBF\fP +`full\&' (i\&.e\&. non\-empty) directories\&. Note that the +opposite sense \fB(^F\fP\fB)\fP expands to empty directories +and all non\-directories\&. Use \fB(/^F\fP\fB)\fP for +empty directories\&. +.TP +\fB\&.\fP +plain files +.TP +\fB@\fP +symbolic links +.TP +\fB=\fP +sockets +.TP +\fBp\fP +named pipes (FIFOs) +.TP +\fB*\fP +executable plain files (0100 or 0010 or 0001) +.TP +\fB%\fP +device files (character or block special) +.TP +\fB%b\fP +block special files +.TP +\fB%c\fP +character special files +.TP +\fBr\fP +owner\-readable files (0400) +.TP +\fBw\fP +owner\-writable files (0200) +.TP +\fBx\fP +owner\-executable files (0100) +.TP +\fBA\fP +group\-readable files (0040) +.TP +\fBI\fP +group\-writable files (0020) +.TP +\fBE\fP +group\-executable files (0010) +.TP +\fBR\fP +world\-readable files (0004) +.TP +\fBW\fP +world\-writable files (0002) +.TP +\fBX\fP +world\-executable files (0001) +.TP +\fBs\fP +setuid files (04000) +.TP +\fBS\fP +setgid files (02000) +.TP +\fBt\fP +files with the sticky bit (01000) +.TP +\fBf\fP\fIspec\fP +files with access rights matching \fIspec\fP\&. This \fIspec\fP may be a +octal number optionally preceded by a `\fB=\fP\&', a `\fB+\fP', or a +`\fB\-\fP\&'\&. If none of these characters is given, the behavior is the +same as for `\fB=\fP\&'\&. The octal number describes the mode bits to be +expected, if combined with a `\fB=\fP\&', the value given must match the +file\-modes exactly, with a `\fB+\fP\&', at least the bits in the +given number must be set in the file\-modes, and with a `\fB\-\fP\&', the +bits in the number must not be set\&. Giving a `\fB?\fP\&' 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 `\fB=\fP\&'\&. +.RS +.PP +If the qualifier `\fBf\fP\&' is followed by any other character anything +up to the next matching character (`\fB[\fP\&', `\fB{\fP', and `\fB<\fP' match +`\fB]\fP\&', `\fB}\fP', and `\fB>\fP' respectively, any other character +matches itself) is taken as a list of comma\-separated +\fIsub\-spec\fPs\&. Each \fIsub\-spec\fP may be either an octal number as +described above or a list of any of the characters `\fBu\fP\&', `\fBg\fP', +`\fBo\fP\&', and `\fBa\fP', followed by a `\fB=\fP', a `\fB+\fP', or a +`\fB\-\fP\&', followed by a list of any of the characters `\fBr\fP', `\fBw\fP', +`\fBx\fP\&', `\fBs\fP', and `\fBt\fP', or an octal digit\&. The first list of +characters specify which access rights are to be checked\&. If a `\fBu\fP\&' +is given, those for the owner of the file are used, if a `\fBg\fP\&' is +given, those of the group are checked, a `\fBo\fP\&' means to test those +of other users, and the `\fBa\fP\&' says to test all three groups\&. The +`\fB=\fP\&', `\fB+\fP', and `\fB\-\fP' 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: `\fBr\fP\&' for read access, `\fBw\fP' for write access, +`\fBx\fP\&' for the right to execute the file (or to search a directory), +`\fBs\fP\&' for the setuid and setgid bits, and `\fBt\fP' for the sticky +bit\&. +.PP +Thus, `\fB*(f70?)\fP\&' 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 +`\fB*(f\-100)\fP\&' gives all files for which the owner does not have +execute permission, and `\fB*(f:gu+w,o\-rx:)\fP\&' 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\&. +.RE +.TP +.PD 0 +\fBe\fP\fIstring\fP +.TP +.PD +\fB+\fP\fIcmd\fP +The \fIstring\fP 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)\&. +.RS +.PP +In the first form, the first character after the `\fBe\fP\&' +will be used as a separator and anything up to the next matching separator +will be taken as the \fIstring\fP; `\fB[\fP\&', `\fB{\fP', and `\fB<\fP' match +`\fB]\fP\&', `\fB}\fP', and `\fB>\fP', respectively, while any other character +matches itself\&. Note that expansions must be quoted in the \fIstring\fP +to prevent them from being expanded before globbing is done\&. +\fIstring\fP is then executed as shell code\&. The string \fBglobqual\fP +is appended to the array \fBzsh_eval_context\fP the duration of +execution\&. +.PP +During the execution of \fIstring\fP the filename currently being tested is +available in the parameter \fBREPLY\fP; the parameter may be altered to +a string to be inserted into the list instead of the original +filename\&. In addition, the parameter \fBreply\fP may be set to an array or a +string, which overrides the value of \fBREPLY\fP\&. If set to an array, the +latter is inserted into the command line word by word\&. +.PP +For example, suppose a directory contains a single file `\fBlonely\fP\&'\&. Then +the expression `\fB*(e:\&'reply=(${REPLY}{1,2})':)\fP' will cause the words +`\fBlonely1\fP\&' and `\fBlonely2\fP' to be inserted into the command line\&. Note +the quoting of \fIstring\fP\&. +.PP +The form \fB+\fP\fIcmd\fP has the same effect, but no delimiters appear +around \fIcmd\fP\&. Instead, \fIcmd\fP is taken as the longest sequence of +characters following the \fB+\fP that are alphanumeric or underscore\&. +Typically \fIcmd\fP will be the name of a shell function that contains the +appropriate test\&. For example, +.PP +.RS +.nf +\fBnt() { [[ $REPLY \-nt $NTREF ]] } +NTREF=reffile +ls \-ld \-\- *(+nt)\fP +.fi +.RE +.PP +lists all files in the directory that have been modified more recently than +\fBreffile\fP\&. +.RE +.TP +\fBd\fP\fIdev\fP +files on the device \fIdev\fP +.TP +\fBl\fP[\fB\-\fP|\fB+\fP]\fIct\fP +files having a link count less than \fIct\fP (\fB\-\fP), greater than +\fIct\fP (\fB+\fP), or equal to \fIct\fP +.TP +\fBU\fP +files owned by the effective user ID +.TP +\fBG\fP +files owned by the effective group ID +.TP +\fBu\fP\fIid\fP +files owned by user ID \fIid\fP if that is a number\&. Otherwise, +\fIid\fP specifies a user name: the +character after the `\fBu\fP\&' 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 `\fB[\fP\&', `\fB{\fP', and `\fB<\fP' +match the final separators `\fB]\fP\&', `\fB}\fP', and `\fB>\fP', respectively; +any other character matches itself\&. The selected files are those +owned by this user\&. For example, `\fBu:foo:\fP\&' or `\fBu[foo]\fP' selects +files owned by user `\fBfoo\fP\&'\&. +.TP +\fBg\fP\fIid\fP +like \fBu\fP\fIid\fP but with group IDs or names +.TP +\fBa\fP[\fBMwhms\fP][\fB\-\fP|\fB+\fP]\fIn\fP +files accessed exactly \fIn\fP days ago\&. Files accessed within the last +\fIn\fP days are selected using a negative value for \fIn\fP (\fB\-\fP\fIn\fP)\&. +Files accessed more than \fIn\fP days ago are selected by a positive \fIn\fP +value (\fB+\fP\fIn\fP)\&. Optional unit specifiers `\fBM\fP\&', `\fBw\fP', +`\fBh\fP\&', `\fBm\fP' or `\fBs\fP' (e\&.g\&. `\fBah5\fP') cause the check to be +performed with months (of 30 days), weeks, hours, minutes or seconds +instead of days, respectively\&. An explicit `\fBd\fP\&' for days is also +allowed\&. +.RS +.PP +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, `\fBecho *(ah\-5)\fP\&' would echo files accessed within the last +five hours, while `\fBecho *(ah+5)\fP\&' would echo files accessed at least +six hours ago, as times strictly between five and six hours are treated +as five hours\&. +.RE +.TP +\fBm\fP[\fBMwhms\fP][\fB\-\fP|\fB+\fP]\fIn\fP +like the file access qualifier, except that it uses the file modification +time\&. +.TP +\fBc\fP[\fBMwhms\fP][\fB\-\fP|\fB+\fP]\fIn\fP +like the file access qualifier, except that it uses the file inode change +time\&. +.TP +\fBL\fP[\fB+\fP|\fB\-\fP]\fIn\fP +files less than \fIn\fP bytes (\fB\-\fP), more than \fIn\fP bytes (\fB+\fP), or +exactly \fIn\fP bytes in length\&. +.RS +.PP +If this flag is directly followed by a \fIsize specifier\fP `\fBk\fP\&' (`\fBK\fP'), +`\fBm\fP\&' (`\fBM\fP'), or `\fBp\fP' (`\fBP\fP') (e\&.g\&. `\fBLk\-50\fP') the check is +performed with kilobytes, megabytes, or blocks (of 512 bytes) instead\&. +(On some systems additional specifiers are available for gigabytes, +`\fBg\fP\&' or `\fBG\fP', and terabytes, `\fBt\fP' or `\fBT\fP'\&.) 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 `\fB*(Lm1)\fP\&' +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 `\fB*(Lm\-1)\fP\&' only matches +files of zero size\&. +.RE +.TP +\fB^\fP +negates all qualifiers following it +.TP +\fB\-\fP +toggles between making the qualifiers work on symbolic links (the +default) and the files they point to, if any; any symbolic link for +whose target the `\fBstat\fP\&' system call fails (whatever the cause of the +failure) is treated as a file in its own right +.TP +\fBM\fP +sets the \fBMARK_DIRS\fP option for the current pattern +.TP +\fBT\fP +appends a trailing qualifier mark to the filenames, analogous to the +\fBLIST_TYPES\fP option, for the current pattern (overrides \fBM\fP) +.TP +\fBN\fP +sets the \fBNULL_GLOB\fP option for the current pattern +.TP +\fBD\fP +sets the \fBGLOB_DOTS\fP option for the current pattern +.TP +\fBn\fP +sets the \fBNUMERIC_GLOB_SORT\fP option for the current pattern +.TP +\fBY\fP\fIn\fP +enables short\-circuit mode: the pattern will expand to at most \fIn\fP +filenames\&. If more than \fIn\fP matches exist, only the first \fIn\fP +matches in directory traversal order will be considered\&. +.RS +.PP +Implies \fBoN\fP when no \fBo\fP\fIc\fP qualifier is used\&. +.RE +.TP +\fBo\fP\fIc\fP +specifies how the names of the files should be sorted\&. The following values +of \fIc\fP sort in the following ways: +.RS +.PP +.PD 0 +.TP +\fBn\fP +By name\&. +.TP +\fBL\fP +By the size (length) of the files\&. +.TP +\fBl\fP +By number of links\&. +.TP +\fBa\fP +By time of last access, youngest first\&. +.TP +\fBm\fP +By time of last modification, youngest first\&. +.TP +\fBc\fP +By time of last inode change, youngest first\&. +.TP +\fBd\fP +By directories: 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 `\fBodon\fP\&' to sort on names for +files within the same directory\&. +.TP +\fBN\fP +No sorting is performed\&. +.TP +.PD 0 +\fBe\fP\fIstring\fP +.TP +\fB+\fP\fIcmd\fP +Sort by shell code (see below)\&. +.PD +.PP +Note that the modifiers \fB^\fP and \fB\-\fP are used, +so `\fB*(^\-oL)\fP\&' gives a list of all files sorted by file size in descending +order, following any symbolic links\&. Unless \fBoN\fP is used, multiple order +specifiers may occur to resolve ties\&. +.PP +The default sorting is \fBn\fP (by name) unless the \fBY\fP glob qualifier is used, +in which case it is \fBN\fP (unsorted)\&. +.PP +\fBoe\fP and \fBo+\fP are special cases; they are each followed by shell code, +delimited as for the \fBe\fP glob qualifier and the \fB+\fP glob qualifier +respectively (see above)\&. The code is executed for each matched file with +the parameter \fBREPLY\fP set to the name of the file on entry and +\fBglobsort\fP appended to \fBzsh_eval_context\fP\&. The code +should modify the parameter \fBREPLY\fP 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, \fBoe\fP and \fBo+\fP may be +repeated, but note that the maximum number of sort operators of any kind +that may appear in any glob expression is 12\&. +.RE +.TP +.PD +\fBO\fP\fIc\fP +like `\fBo\fP\&', but sorts in descending order; i\&.e\&. `\fB*(^o\fP\fIc\fP\fB)\fP' is the +same as `\fB*(O\fP\fIc\fP\fB)\fP\&' and `\fB*(^O\fP\fIc\fP\fB)\fP' is the same as `\fB*(o\fP\fIc\fP\fB)\fP'; `\fBOd\fP' +puts files in the current directory before those in subdirectories at each +level of the search\&. +.TP +\fB[\fP\fIbeg\fP[\fB,\fP\fIend\fP]\fB]\fP +specifies which of the matched filenames should be included in the +returned list\&. The syntax is the same as for array +subscripts\&. \fIbeg\fP and the optional \fIend\fP may be mathematical +expressions\&. As in parameter subscripting they may be negative to make +them count from the last match backward\&. E\&.g\&.: `\fB*(\-OL[1,3])\fP\&' +gives a list of the names of the three largest files\&. +.TP +\fBP\fP\fIstring\fP +The \fIstring\fP will be prepended to each glob match as a separate +word\&. \fIstring\fP is delimited in the same way as arguments to the +\fBe\fP 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\&. +.RS +.PP +A typical use for this is to prepend an option before all occurrences +of a file name; for example, the pattern `\fB*(P:\-f:)\fP\&' produces the +command line arguments `\fB\-f\fP \fIfile1\fP \fB\-f\fP \fIfile2\fP \&.\&.\&.\&' +.PP +If the modifier \fB^\fP is active, then \fIstring\fP 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 +`\fB*(P:foo:^P:bar:^P:baz:)\fP\&' which produces the command line arguments +`\fBfoo\fP \fBbaz\fP \fIfile1\fP \fBbar\fP \&.\&.\&.\&' +.RE +.PP +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 `\fBM\fP\&', `\fBT\fP', +`\fBN\fP\&', `\fBD\fP', `\fBn\fP', `\fBo\fP', `\fBO\fP' and the subscripts given +in brackets (`\fB[\fP\fI\&.\&.\&.\fP\fB]\fP\&')\&. +.PP +If a `\fB:\fP\&' appears in a qualifier list, the remainder of the expression in +parenthesis is interpreted as a modifier (see the section `Modifiers\&' +in the section `History Expansion\&')\&. Each modifier must be introduced by a +separate `\fB:\fP\&'\&. 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 `\fB(:\fP\fI\&.\&.\&.\fP\fB)\fP\&' +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 \fBNULL_GLOB\fP\&. Thus: +.PP +.RS +.nf +\fBls \-ld \-\- *(\-/)\fP +.fi +.RE +.PP +lists all directories and symbolic links that point to directories, +and +.PP +.RS +.nf +\fBls \-ld \-\- *(\-@)\fP +.fi +.RE +.PP +lists all broken symbolic links, and +.PP +.RS +.nf +\fBls \-ld \-\- *(%W)\fP +.fi +.RE +.PP +lists all world\-writable device files in the current directory, and +.PP +.RS +.nf +\fBls \-ld \-\- *(W,X)\fP +.fi +.RE +.PP +lists all files in the current directory that are +world\-writable or world\-executable, and +.PP +.RS +.nf +\fBprint \-rC1 /tmp/foo*(u0^@:t)\fP +.fi +.RE +.PP +outputs the basename of all root\-owned files beginning with the string +`\fBfoo\fP\&' in \fB/tmp\fP, ignoring symlinks, and +.PP +.RS +.nf +\fBls \-ld \-\- *\&.*~(lex|parse)\&.[ch](^D^l1)\fP +.fi +.RE +.PP +lists all files having a link count of one whose names contain a dot +(but not those starting with a dot, since \fBGLOB_DOTS\fP is explicitly +switched off) except for \fBlex\&.c\fP, \fBlex\&.h\fP, \fBparse\&.c\fP and \fBparse\&.h\fP\&. +.PP +.RS +.nf +\fBprint \-rC1 b*\&.pro(#q:s/pro/shmo/)(#q\&.:s/builtin/shmiltin/)\fP +.fi +.RE +.PP +demonstrates how colon modifiers and other qualifiers may be chained +together\&. The ordinary qualifier `\fB\&.\fP\&' is applied first, then the colon +modifiers in order from left to right\&. So if \fBEXTENDED_GLOB\fP is set and +the base pattern matches the regular file \fBbuiltin\&.pro\fP, the shell will +print `\fBshmiltin\&.shmo\fP\&'\&. diff --git a/Doc/zshmisc.1 b/Doc/zshmisc.1 new file mode 100644 index 000000000..dac720b87 --- /dev/null +++ b/Doc/zshmisc.1 @@ -0,0 +1,2814 @@ +.TH "ZSHMISC" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshmisc \- everything and then some +.\" Yodl file: Zsh/grammar.yo +.SH "SIMPLE COMMANDS & PIPELINES" +A \fIsimple command\fP 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 +\fIzshparam\fP(1)\&. +.PP +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, +.PP +.RS +.nf +\fBecho foo\fP +.fi +.RE +.PP +is a simple command with arguments\&. +.PP +A \fIpipeline\fP is either a simple command, or a sequence of two or more +simple commands where each command is separated from the next by `\fB|\fP\&' +or `\fB|&\fP\&'\&. Where commands are separated by `\fB|\fP', the standard +output of the first command is connected to the +standard input of the next\&. `\fB|&\fP\&' is shorthand for `\fB2>&1 |\fP', 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 +`\fB!\fP\&' in which case the value is the logical inverse of the value of the +last command\&. +For example, +.PP +.RS +.nf +\fBecho foo | sed \&'s/foo/bar/'\fP +.fi +.RE +.PP +is a pipeline, where the output (`\fBfoo\fP\&' plus a newline) of the first +command will be passed to the input of the second\&. +.PP +If a pipeline is preceded by `\fBcoproc\fP\&', 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 `\fB>&p\fP\&' +and `\fB<&p\fP\&' redirection operators or with `\fBprint \-p\fP' and `\fBread \-p\fP'\&. +A pipeline cannot be preceded by both `\fBcoproc\fP\&' and `\fB!\fP'\&. +If job control is active, the coprocess can be treated in other than input +and output as an ordinary background job\&. +.PP +A \fIsublist\fP is either a single pipeline, or a sequence of two or more +pipelines separated by `\fB&&\fP\&' or `\fB||\fP'\&. If two pipelines are separated +by `\fB&&\fP\&', the second pipeline is executed only if the first succeeds +(returns a zero status)\&. If two pipelines are separated by `\fB||\fP\&', 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, +.PP +.RS +.nf +\fBdmesg | grep panic && print yes\fP +.fi +.RE +.PP +is a sublist consisting of two pipelines, the second just a simple command +which will be executed if and only if the \fBgrep\fP 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 \fBprint\fP (almost certainly zero)\&. +.PP +A \fIlist\fP is a sequence of zero or more sublists, in which each sublist +is terminated by `\fB;\fP\&', `\fB&\fP', `\fB&|\fP', `\fB&!\fP', 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 `\fB(\fP\&.\&.\&.\fB)\fP\&' +or `\fB{\fP\&.\&.\&.\fB}\fP\&'\&. When a +sublist is terminated by `\fB;\fP\&' or newline, the shell waits for it to +finish before executing the next sublist\&. If a sublist is terminated +by a `\fB&\fP\&', `\fB&|\fP', or `\fB&!\fP', +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\&. +.PP +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\&. +.SH "PRECOMMAND MODIFIERS" +A simple command may be preceded by a \fIprecommand modifier\fP, +which will alter how the command is interpreted\&. These modifiers are +shell builtin commands with the exception of \fBnocorrect\fP which is +a reserved word\&. +.PP +.PD 0 +.TP +.PD +\fB\-\fP +The command is executed with a `\fB\-\fP\&' prepended to its +\fBargv[0]\fP string\&. +.TP +\fBbuiltin\fP +The command word is taken to be the name of a builtin command, +rather than a shell function or external command\&. +.TP +\fBcommand\fP [ \fB\-pvV\fP ] +The command word is taken to be the name of an external command, +rather than a shell function or builtin\&. If the \fBPOSIX_BUILTINS\fP option +is set, builtins will also be executed but certain special properties +of them are suppressed\&. The \fB\-p\fP flag causes a default path to be +searched instead of that in \fB$path\fP\&. With the \fB\-v\fP flag, \fBcommand\fP +is similar to \fBwhence\fP and with \fB\-V\fP, it is equivalent to \fBwhence +\-v\fP\&. +.TP +\fBexec\fP [ \fB\-cl\fP ] [ \fB\-a\fP \fIargv0\fP ] +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 \fBTRAPEXIT\fP, nor does it +source \fBzlogout\fP files\&. +The options are provided for compatibility with other shells\&. +.RS +.PP +The \fB\-c\fP option clears the environment\&. +.PP +The \fB\-l\fP option is equivalent to the \fB\-\fP precommand modifier, to +treat the replacement command as a login shell; the command is executed +with a \fB\-\fP prepended to its \fBargv[0]\fP string\&. This flag has no effect +if used together with the \fB\-a\fP option\&. +.PP +The \fB\-a\fP option is used to specify explicitly the \fBargv[0]\fP 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 \fBARGV0\fP environment variable\&. +.RE +.TP +\fBnocorrect\fP +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\&. +.TP +\fBnoglob\fP +Filename generation (globbing) is not performed on any of +the words\&. +.SH "COMPLEX COMMANDS" +A \fIcomplex command\fP in zsh is one of the following: +.PP +.PD 0 +.TP +.PD +\fBif\fP \fIlist\fP \fBthen\fP \fIlist\fP [ \fBelif\fP \fIlist\fP \fBthen\fP \fIlist\fP ] \&.\&.\&. [ \fBelse\fP \fIlist\fP ] \fBfi\fP +The \fBif\fP \fIlist\fP is executed, and if it returns a zero exit status, +the \fBthen\fP \fIlist\fP is executed\&. +Otherwise, the \fBelif\fP \fIlist\fP is executed and if its status is zero, +the \fBthen\fP \fIlist\fP is executed\&. +If each \fBelif\fP \fIlist\fP returns nonzero status, the \fBelse\fP \fIlist\fP +is executed\&. +.TP +\fBfor\fP \fIname\fP \&.\&.\&. [ \fBin\fP \fIword\fP \&.\&.\&. ] \fIterm\fP \fBdo\fP \fIlist\fP \fBdone\fP +Expand the list of \fIword\fPs, and set the parameter +\fIname\fP to each of them in turn, executing \fIlist\fP +each time\&. If the `\fBin\fP \fIword\fP\&' is omitted, +use the positional parameters instead of the \fIword\fPs\&. +.RS +.PP +The \fIterm\fP consists of one or more newline or \fB;\fP +which terminate the \fIword\fPs, and are optional when the +`\fBin\fP \fIword\fP\&' is omitted\&. +.PP +More than one parameter \fIname\fP can appear before the list of +\fIword\fPs\&. If \fIN\fP \fIname\fPs are given, then on each execution of the +loop the next \fIN\fP \fIword\fPs are assigned to the corresponding +parameters\&. If there are more \fIname\fPs than remaining \fIword\fPs, the +remaining parameters are each set to the empty string\&. Execution of the +loop ends when there is no remaining \fIword\fP to assign to the first +\fIname\fP\&. It is only possible for \fBin\fP to appear as the first \fIname\fP +in the list, else it will be treated as marking the end of the list\&. +.RE +.TP +\fBfor ((\fP [\fIexpr1\fP] \fB;\fP [\fIexpr2\fP] \fB;\fP [\fIexpr3\fP] \fB)) do\fP \fIlist\fP \fBdone\fP +The arithmetic expression \fIexpr1\fP is evaluated first (see +the section `Arithmetic Evaluation\&')\&. The arithmetic expression +\fIexpr2\fP is repeatedly evaluated until it evaluates to zero and +when non\-zero, \fIlist\fP is executed and the arithmetic expression +\fIexpr3\fP evaluated\&. If any expression is omitted, then it behaves +as if it evaluated to 1\&. +.TP +\fBwhile\fP \fIlist\fP \fBdo\fP \fIlist\fP \fBdone\fP +Execute the \fBdo\fP \fIlist\fP as long as the \fBwhile\fP \fIlist\fP +returns a zero exit status\&. +.TP +\fBuntil\fP \fIlist\fP \fBdo\fP \fIlist\fP \fBdone\fP +Execute the \fBdo\fP \fIlist\fP as long as \fBuntil\fP \fIlist\fP +returns a nonzero exit status\&. +.TP +\fBrepeat\fP \fIword\fP \fBdo\fP \fIlist\fP \fBdone\fP +\fIword\fP is expanded and treated as an arithmetic expression, +which must evaluate to a number \fIn\fP\&. +\fIlist\fP is then executed \fIn\fP times\&. +.RS +.PP +The \fBrepeat\fP syntax is disabled by default when the +shell starts in a mode emulating another shell\&. It can be enabled +with the command `\fBenable \-r repeat\fP\&' +.RE +.TP +\fBcase\fP \fIword\fP \fBin\fP [ [\fB(\fP] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \&.\&.\&. \fB)\fP \fIlist\fP (\fB;;\fP|\fB;&\fP|\fB;|\fP) ] \&.\&.\&. \fBesac\fP +Execute the \fIlist\fP associated with the first \fIpattern\fP +that matches \fIword\fP, if any\&. The form of the patterns +is the same as that used for filename generation\&. See +the section `Filename Generation\&'\&. +.RS +.PP +Note further that, unless the \fBSH_GLOB\fP 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 \fBSH_GLOB\fP 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)\&. +.PP +If the \fIlist\fP that is executed is terminated with \fB;&\fP rather than +\fB;;\fP, the following list is also executed\&. The rule for +the terminator of the following list \fB;;\fP, \fB;&\fP or \fB;|\fP is +applied unless the \fBesac\fP is reached\&. +.PP +If the \fIlist\fP that is executed is terminated with \fB;|\fP the +shell continues to scan the \fIpattern\fPs looking for the next match, +executing the corresponding \fIlist\fP, and applying the rule for +the corresponding terminator \fB;;\fP, \fB;&\fP or \fB;|\fP\&. +Note that \fIword\fP is not re\-expanded; all applicable \fIpattern\fPs +are tested with the same \fIword\fP\&. +.RE +.TP +\fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP \&.\&.\&. \fIterm\fP ] \fBdo\fP \fIlist\fP \fBdone\fP +where \fIterm\fP is one or more newline or \fB;\fP to terminate the \fIword\fPs\&. +Print the set of \fIword\fPs, each preceded by a number\&. +If the \fBin\fP \fIword\fP is omitted, use the positional parameters\&. +The \fBPROMPT3\fP 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 \fIword\fPs, then the parameter \fIname\fP +is set to the \fIword\fP corresponding to this number\&. +If this line is empty, the selection list is printed again\&. +Otherwise, the value of the parameter \fIname\fP is set to null\&. +The contents of the line read from standard input is saved +in the parameter \fBREPLY\fP\&. \fIlist\fP is executed +for each selection until a break or end\-of\-file is encountered\&. +.TP +\fB(\fP \fIlist\fP \fB)\fP +Execute \fIlist\fP in a subshell\&. Traps set by the \fBtrap\fP builtin +are reset to their default values while executing \fIlist\fP; an +exception is that ignored signals will continue to be ignored +if the option \fBPOSIXTRAPS\fP is set\&. +.TP +\fB{\fP \fIlist\fP \fB}\fP +Execute \fIlist\fP\&. +.TP +\fB{\fP \fItry\-list\fP \fB} always {\fP \fIalways\-list\fP \fB}\fP +First execute \fItry\-list\fP\&. Regardless of errors, or \fBbreak\fP or +\fBcontinue\fP commands encountered within \fItry\-list\fP, +execute \fIalways\-list\fP\&. Execution then continues from the +result of the execution of \fItry\-list\fP; in other words, any error, +or \fBbreak\fP or \fBcontinue\fP command is treated in the +normal way, as if \fIalways\-list\fP were not present\&. The two +chunks of code are referred to as the `try block\&' and the `always block'\&. +.RS +.PP +Optional newlines or semicolons may appear after the \fBalways\fP; +note, however, that they may \fInot\fP appear between the preceding +closing brace and the \fBalways\fP\&. +.PP +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 \fIalways\-list\fP to be executed\&. For example, +an erroneously constructed \fBif\fP block in \fItry\-list\fP would cause the +shell to abort during parsing, so that \fIalways\-list\fP would not be +executed, while an erroneous substitution such as \fB${*foo*}\fP would +cause a run\-time error, after which \fIalways\-list\fP would be executed\&. +.PP +An error condition can be tested and reset with the special integer +variable \fBTRY_BLOCK_ERROR\fP\&. Outside an \fIalways\-list\fP the value is +irrelevant, but it is initialised to \fB\-1\fP\&. Inside \fIalways\-list\fP, the +value is 1 if an error occurred in the \fItry\-list\fP, else 0\&. If +\fBTRY_BLOCK_ERROR\fP is set to 0 during the \fIalways\-list\fP, the error +condition caused by the \fItry\-list\fP is reset, and shell execution +continues normally after the end of \fIalways\-list\fP\&. Altering the value +during the \fItry\-list\fP is not useful (unless this forms part of an +enclosing \fBalways\fP block)\&. +.PP +Regardless of \fBTRY_BLOCK_ERROR\fP, after the end of \fIalways\-list\fP the +normal shell status \fB$?\fP is the value returned from \fItry\-list\fP\&. +This will be non\-zero if there was an error, even if \fBTRY_BLOCK_ERROR\fP +was set to zero\&. +.PP +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\&. +.PP +.RS +.nf +\fB{ + # 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\&.\fP +.fi +.RE +.PP +When a \fBtry\fP block occurs outside of any function, +a \fBreturn\fP or a \fBexit\fP encountered in \fItry\-list\fP does \fInot\fP cause +the execution of \fIalways\-list\fP\&. Instead, the shell exits immediately +after any \fBEXIT\fP trap has been executed\&. +Otherwise, a \fBreturn\fP command encountered in \fItry\-list\fP will cause the +execution of \fIalways\-list\fP, just like \fBbreak\fP and \fBcontinue\fP\&. +.PP + +.RE +.TP +.PD 0 +\fBfunction\fP [ \fB\-T\fP ] \fIword\fP \&.\&.\&. [ \fB()\fP ] [ \fIterm\fP ] \fB{\fP \fIlist\fP \fB}\fP +.TP +.PD 0 +\fIword\fP \&.\&.\&. \fB()\fP [ \fIterm\fP ] \fB{\fP \fIlist\fP \fB}\fP +.TP +.PD +\fIword\fP \&.\&.\&. \fB()\fP [ \fIterm\fP ] \fIcommand\fP +where \fIterm\fP is one or more newline or \fB;\fP\&. +Define a function which is referenced by any one of \fIword\fP\&. +Normally, only one \fIword\fP is provided; multiple \fIword\fPs +are usually only useful for setting traps\&. +The body of the function is the \fIlist\fP between +the \fB{\fP and \fB}\fP\&. See the section `Functions\&'\&. +.RS +.PP +The options of \fBfunction\fP have the following meanings: +.PP +.PD 0 +.TP +.PD +\-T +Enable tracing for this function, as though with \fBfunctions \-T\fP\&. See the +documentation of the \fB\-f\fP option to the \fBtypeset\fP builtin, in +\fIzshbuiltins\fP(1)\&. +.PP +If the option \fBSH_GLOB\fP is set for compatibility with other shells, then +whitespace may appear between the left and right parentheses when +there is a single \fIword\fP; otherwise, the parentheses will be treated as +forming a globbing pattern in that case\&. +.PP +In any of the forms above, a redirection may appear outside the +function body, for example +.PP +.RS +.nf +\fBfunc() { \&.\&.\&. } 2>&1\fP +.fi +.RE +.PP +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\&. +.RE +.TP +\fBtime\fP [ \fIpipeline\fP ] +The \fIpipeline\fP is executed, and timing statistics are +reported on the standard error in the form specified +by the \fBTIMEFMT\fP parameter\&. +If \fIpipeline\fP is omitted, print statistics about the +shell process and its children\&. +.TP +\fB[[\fP \fIexp\fP \fB]]\fP +Evaluates the conditional expression \fIexp\fP +and return a zero exit status if it is true\&. +See the section `Conditional Expressions\&' +for a description of \fIexp\fP\&. +.SH "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\&. +.PP +The short versions below only work if \fIsublist\fP is of the form `\fB{\fP +\fIlist\fP \fB}\fP\&' or if the \fBSHORT_LOOPS\fP option is set\&. For the \fBif\fP, +\fBwhile\fP and \fBuntil\fP commands, in both these cases the test part of the +loop must also be suitably delimited, such as by `\fB[[\fP \fI\&.\&.\&.\fP \fB]]\fP\&' or +`\fB((\fP \fI\&.\&.\&.\fP \fB))\fP\&', +else the end of the test will not be recognized\&. For the +\fBfor\fP, \fBrepeat\fP, \fBcase\fP and \fBselect\fP commands no such special form +for the arguments is necessary, but the other condition (the special form +of \fIsublist\fP or use of the \fBSHORT_LOOPS\fP option) still applies\&. +The \fBSHORT_REPEAT\fP option is available to enable the short version only +for the \fBrepeat\fP command\&. +.PP +.PD 0 +.TP +.PD +\fBif\fP \fIlist\fP \fB{\fP \fIlist\fP \fB}\fP [ \fBelif\fP \fIlist\fP \fB{\fP \fIlist\fP \fB}\fP ] \&.\&.\&. [ \fBelse {\fP \fIlist\fP \fB}\fP ] +An alternate form of \fBif\fP\&. The rules mean that +.RS +.PP +.RS +.nf +\fBif [[ \-o ignorebraces ]] { + print yes +}\fP +.fi +.RE +.PP +works, but +.PP +.RS +.nf +\fBif true { # Does not work! + print yes +}\fP +.fi +.RE +.PP +does \fInot\fP, since the test is not suitably delimited\&. +.RE +.TP +\fBif\fP \fIlist\fP \fIsublist\fP +A short form of the alternate \fBif\fP\&. The same limitations on the form of +\fIlist\fP apply as for the previous form\&. +.TP +\fBfor\fP \fIname\fP \&.\&.\&. \fB(\fP \fIword\fP \&.\&.\&. \fB)\fP \fIsublist\fP +A short form of \fBfor\fP\&. +.TP +\fBfor\fP \fIname\fP \&.\&.\&. [ \fBin\fP \fIword\fP \&.\&.\&. ] \fIterm\fP \fIsublist\fP +where \fIterm\fP is at least one newline or \fB;\fP\&. +Another short form of \fBfor\fP\&. +.TP +\fBfor ((\fP [\fIexpr1\fP] \fB;\fP [\fIexpr2\fP] \fB;\fP [\fIexpr3\fP] \fB))\fP \fIsublist\fP +A short form of the arithmetic \fBfor\fP command\&. +.TP +\fBforeach\fP \fIname\fP \&.\&.\&. \fB(\fP \fIword\fP \&.\&.\&. \fB)\fP \fIlist\fP \fBend\fP +Another form of \fBfor\fP\&. +.TP +\fBwhile\fP \fIlist\fP \fB{\fP \fIlist\fP \fB}\fP +An alternative form of \fBwhile\fP\&. Note the limitations on the form of +\fIlist\fP mentioned above\&. +.TP +\fBuntil\fP \fIlist\fP \fB{\fP \fIlist\fP \fB}\fP +An alternative form of \fBuntil\fP\&. Note the limitations on the form of +\fIlist\fP mentioned above\&. +.TP +\fBrepeat\fP \fIword\fP \fIsublist\fP +This is a short form of \fBrepeat\fP\&. +.TP +\fBcase\fP \fIword\fP \fB{\fP [ [\fB(\fP] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \&.\&.\&. \fB)\fP \fIlist\fP (\fB;;\fP|\fB;&\fP|\fB;|\fP) ] \&.\&.\&. \fB}\fP +An alternative form of \fBcase\fP\&. +.TP +\fBselect\fP \fIname\fP [ \fBin\fP \fIword\fP \&.\&.\&. \fIterm\fP ] \fIsublist\fP +where \fIterm\fP is at least one newline or \fB;\fP\&. +A short form of \fBselect\fP\&. +.TP +\fBfunction\fP \fIword\fP \&.\&.\&. [ \fB()\fP ] [ \fIterm\fP ] \fIsublist\fP +This is a short form of \fBfunction\fP\&. +.SH "RESERVED WORDS" +The following words are recognized as reserved words when used as the first +word of a command unless quoted or disabled using \fBdisable \-r\fP: +.PP +\fBdo 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\fP +.PP +Additionally, `\fB}\fP\&' is recognized in any position if neither the +\fBIGNORE_BRACES\fP option nor the \fBIGNORE_CLOSE_BRACES\fP option is set\&. +.SH "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 \fBCONTINUE_ON_ERROR\fP\&. +.PP +Fatal errors found in non\-interactive shells include: +.PP +.PD 0 +.TP +.PD +\(bu +Failure to parse shell options passed when invoking the shell +.TP +\(bu +Failure to change options with the \fBset\fP builtin +.TP +\(bu +Parse errors of all sorts, including failures to parse +mathematical expressions +.TP +\(bu +Failures to set or modify variable behaviour with \fBtypeset\fP, +\fBlocal\fP, \fBdeclare\fP, \fBexport\fP, \fBinteger\fP, \fBfloat\fP +.TP +\(bu +Execution of incorrectly positioned loop control structures +(\fBcontinue\fP, \fBbreak\fP) +.TP +\(bu +Attempts to use regular expression with no regular expression +module available +.TP +\(bu +Disallowed operations when the \fBRESTRICTED\fP options is set +.TP +\(bu +Failure to create a pipe needed for a pipeline +.TP +\(bu +Failure to create a multio +.TP +\(bu +Failure to autoload a module needed for a declared shell feature +.TP +\(bu +Errors creating command or process substitutions +.TP +\(bu +Syntax errors in glob qualifiers +.TP +\(bu +File generation errors where not caught by the option \fBBAD_PATTERN\fP +.TP +\(bu +All bad patterns used for matching within case statements +.TP +\(bu +File generation failures where not caused by \fBNO_MATCH\fP or +similar options +.TP +\(bu +All file generation errors where the pattern was used to create a +multio +.TP +\(bu +Memory errors where detected by the shell +.TP +\(bu +Invalid subscripts to shell variables +.TP +\(bu +Attempts to assign read\-only variables +.TP +\(bu +Logical errors with variables such as assignment to the wrong type +.TP +\(bu +Use of invalid variable names +.TP +\(bu +Errors in variable substitution syntax +.TP +\(bu +Failure to convert characters in \fB$\&'\fP\&.\&.\&.\fB'\fP expressions +.PP +If the \fBPOSIX_BUILTINS\fP option is set, more errors associated with +shell builtin commands are treated as fatal, as specified by the POSIX +standard\&. +.PP +.SH "COMMENTS" +In non\-interactive shells, or in interactive shells with the +\fBINTERACTIVE_COMMENTS\fP option set, a word beginning +with the third character of the \fBhistchars\fP parameter +(`\fB#\fP\&' by default) causes that word and all the following +characters up to a newline to be ignored\&. +.SH "ALIASING" +Every eligible \fIword\fP 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\&. +.PP +It is an error for the function name, \fIword\fP, in the sh\-compatible function +definition syntax `\fIword\fP \fB()\fP \&.\&.\&.\&' to be a word that resulted +from alias expansion, unless the \fBALIAS_FUNC_DEF\fP option is set\&. +.PP +An alias is defined using the \fBalias\fP builtin; global aliases +may be defined using the \fB\-g\fP option to that builtin\&. +.PP +A \fIword\fP is defined as: +.PP +.PD 0 +.TP +.PD +\(bu +Any plain string or glob pattern +.TP +\(bu +Any quoted string, using any quoting method (note that the quotes +must be part of the alias definition for this to be eligible) +.TP +\(bu +Any parameter reference or command substitution +.TP +\(bu +Any series of the foregoing, concatenated without whitespace or +other tokens between them +.TP +\(bu +Any reserved word (\fBcase\fP, \fBdo\fP, \fBelse\fP, etc\&.) +.TP +\(bu +With global aliasing, any command separator, any redirection +operator, and `\fB(\fP\&' or `\fB)\fP' when not part of a glob pattern +.PP +Alias expansion is done on the shell input before any other expansion +except history expansion\&. Therefore, if an alias is defined for the +word \fBfoo\fP, alias expansion may be avoided by quoting part of the +word, e\&.g\&. \fB\efoo\fP\&. Any form of quoting works, although there is +nothing to prevent an alias being defined for the quoted form such as +\fB\efoo\fP as well\&. +.PP +In particular, note that quoting must be used when using \fBunalias\fP to remove +global aliases: +.PP +.RS +.nf +\fB% alias \-g foo=bar +% unalias foo +unalias: no such hash table element: bar +% unalias \efoo +% \fP +.fi +.RE +.PP +When \fBPOSIX_ALIASES\fP is set, only plain unquoted strings are eligible +for aliasing\&. The \fBalias\fP builtin does not reject ineligible aliases, +but they are not expanded\&. +.PP +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\&. \fB\&'foo\fP; completion will +automatically add the trailing single quote\&. +.PP +.SS "Alias difficulties" +.PP +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\&. +.PP +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 \fBaliases\fP described in +the section THE ZSH/PARAMETER MODULE in \fIzshmodules\fP(1))\&. +However, as noted in the case of \fBPOSIX_ALIASES\fP above, the shell does +not attempt to deduce whether the string corresponds to a word at the +time the alias is created\&. +.PP +For example, an expression containing an \fB=\fP at the start of +a command line is an assignment and cannot be expanded as an alias; +a lone \fB=\fP is not an assignment but can only be set as an alias +using the parameter, as otherwise the \fB=\fP is taken part of the +syntax of the builtin command\&. +.PP +It is not presently possible to alias the `\fB((\fP\&' token that +introduces arithmetic expressions, because until a full statement has been +parsed, it cannot be distinguished from two consecutive `\fB(\fP\&' +tokens introducing nested subshells\&. +Also, if a separator such as \fB&&\fP is aliased, +\fB\e&&\fP turns into the two tokens \fB\e&\fP and \fB&\fP, each of which may +have been aliased separately\&. Similarly for \fB\e<<\fP, \fB\e>|\fP, etc\&. +.PP +There is a commonly encountered problem with aliases +illustrated by the following code: +.PP +.RS +.nf +\fBalias echobar=\&'echo bar'; echobar\fP +.fi +.RE +.PP +This prints a message that the command \fBechobar\fP 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 \fBechobar\fP 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 `\fBsource\fP\&' +or `\fB\&.\fP\&'\&. Consequently, use of functions rather than aliases is +recommended in non\-interactive code\&. +.PP +.SH "QUOTING" +A character may be \fIquoted\fP (that is, made +to stand for itself) by preceding it with a `\fB\e\fP\&'\&. +`\fB\e\fP\&' followed by a newline is ignored\&. +.PP +A string enclosed between `\fB$\&'\fP' and `\fB'\fP' is +processed the same way as the string arguments of the +\fBprint\fP builtin, and the resulting string is considered to be +entirely quoted\&. A literal `\fB\&'\fP' character can be included in the +string by using the `\fB\e\&'\fP' escape\&. +.PP +All characters enclosed between a pair of single quotes (\fB\&''\fP) that +is not preceded by a `\fB$\fP\&' are quoted\&. A single quote cannot appear +within single quotes unless the option \fBRC_QUOTES\fP is set, in which case +a pair of single quotes are turned into a single quote\&. For example, +.PP +.RS +.nf +\fBprint \&''''\fP +.fi +.RE +.PP +outputs nothing apart from a newline if \fBRC_QUOTES\fP is not set, but one +single quote if it is set\&. +.PP +Inside double quotes (\fB""\fP), parameter and +command substitution occur, and `\fB\e\fP\&' quotes the characters +`\fB\e\fP\&', `\fB`\fP', `\fB"\fP', `\fB$\fP', and the first character +of \fB$histchars\fP (default `\fB!\fP\&')\&. +.\" Yodl file: Zsh/redirect.yo +.SH "REDIRECTION" +If a command is followed by \fB&\fP +and job control is not active, +then the default standard input +for the command is the empty file \fB/dev/null\fP\&. +Otherwise, the environment for the execution of a command contains the +file descriptors of the invoking shell as modified by +input/output specifications\&. +.PP +The following may appear anywhere in a simple command +or may precede or follow a complex command\&. +Expansion occurs before \fIword\fP or \fIdigit\fP +is used except as noted below\&. +If the result of substitution on \fIword\fP +produces more than one filename, +redirection occurs for each +separate filename in turn\&. +.PP +.PD 0 +.TP +.PD +\fB<\fP \fIword\fP +Open file \fIword\fP for reading as standard input\&. +It is an error to open a file in this fashion if it does not exist\&. +.TP +\fB<>\fP \fIword\fP +Open file \fIword\fP for reading and writing as standard input\&. +If the file does not exist then it is created\&. +.TP +\fB>\fP \fIword\fP +Open file \fIword\fP for writing as standard output\&. +If the file does not exist then it is created\&. +If the file exists, and the \fBCLOBBER\fP option is unset, +this causes an error; +otherwise, it is truncated to zero length\&. +.TP +.PD 0 +\fB>|\fP \fIword\fP +.TP +.PD +\fB>!\fP \fIword\fP +Same as \fB>\fP, except that the file is truncated to zero length +if it exists, regardless of \fBCLOBBER\fP\&. +.TP +\fB>>\fP \fIword\fP +Open file \fIword\fP for writing in append mode as standard output\&. +If the file does not exist, and the \fBCLOBBER\fP and \fBAPPEND_CREATE\fP +options are both unset, this causes an error; +otherwise, the file is created\&. +.TP +.PD 0 +\fB>>|\fP \fIword\fP +.TP +.PD +\fB>>!\fP \fIword\fP +Same as \fB>>\fP, except that the file is created if it does not +exist, regardless of \fBCLOBBER\fP and \fBAPPEND_CREATE\fP\&. +.TP +\fB<<\fP[\fB\-\fP] \fIword\fP +The shell input is read up to a line that is the same as +\fIword\fP, or to an end\-of\-file\&. +No parameter expansion, command substitution or +filename generation is performed on \fIword\fP\&. +The resulting document, called a +\fIhere\-document\fP, becomes the standard input\&. +.RS +.PP +If any character of \fIword\fP is quoted with +single or double quotes or a `\fB\e\fP\&', +no interpretation is placed upon the characters of the document\&. +Otherwise, parameter and command substitution +occurs, `\fB\e\fP\&' followed by a newline is removed, +and `\fB\e\fP\&' must be used to quote the characters +`\fB\e\fP\&', `\fB$\fP', `\fB`\fP' and the first character of \fIword\fP\&. +.PP +Note that \fIword\fP itself does not undergo shell expansion\&. Backquotes +in \fIword\fP 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 +\fB$\&'\fP\fI\&.\&.\&.\fP\fB'\fP have their standard effect of expanding backslashed +references to special characters\&. +.PP +If \fB<<\-\fP is used, then all leading +tabs are stripped from \fIword\fP and from the document\&. +.RE +.TP +\fB<<<\fP \fIword\fP +Perform shell expansion on \fIword\fP and pass the result +to standard input\&. This is known as a \fIhere\-string\fP\&. +Compare the use of \fIword\fP in here\-documents above, where \fIword\fP +does not undergo shell expansion\&. The result will have a trailing newline +after it\&. +.TP +.PD 0 +\fB<&\fP \fInumber\fP +.TP +.PD +\fB>&\fP \fInumber\fP +The standard input/output is duplicated from file descriptor +\fInumber\fP (see \fIdup2\fP(2))\&. +.TP +.PD 0 +\fB<& \-\fP +.TP +.PD +\fB>& \-\fP +Close the standard input/output\&. +.TP +.PD 0 +\fB<& p\fP +.TP +.PD +\fB>& p\fP +The input/output from/to the coprocess is moved to the standard input/output\&. +.TP +.PD 0 +\fB>&\fP \fIword\fP +.TP +.PD +\fB&>\fP \fIword\fP +(Except where `\fB>&\fP \fIword\fP\&' matches one of the above syntaxes; +`\fB&>\fP\&' can always be used to avoid this ambiguity\&.) +Redirects both standard output and standard error (file descriptor 2) +in the manner of `\fB>\fP \fIword\fP\&'\&. +Note that this does \fInot\fP have the same effect as `\fB>\fP \fIword\fP \fB2>&1\fP\&' +in the presence of multios (see the section below)\&. +.TP +.PD 0 +\fB>&|\fP \fIword\fP +.TP +.PD 0 +\fB>&!\fP \fIword\fP +.TP +.PD 0 +\fB&>|\fP \fIword\fP +.TP +.PD +\fB&>!\fP \fIword\fP +Redirects both standard output and standard error (file descriptor 2) +in the manner of `\fB>|\fP \fIword\fP\&'\&. +.TP +.PD 0 +\fB>>&\fP \fIword\fP +.TP +.PD +\fB&>>\fP \fIword\fP +Redirects both standard output and standard error (file descriptor 2) +in the manner of `\fB>>\fP \fIword\fP\&'\&. +.TP +.PD 0 +\fB>>&|\fP \fIword\fP +.TP +.PD 0 +\fB>>&!\fP \fIword\fP +.TP +.PD 0 +\fB&>>|\fP \fIword\fP +.TP +.PD +\fB&>>!\fP \fIword\fP +Redirects both standard output and standard error (file descriptor 2) +in the manner of `\fB>>|\fP \fIword\fP\&'\&. +.PP +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 +(\fIfile descriptor\fP, \fIfile\fP) +association at the time of evaluation\&. +For example: +.PP +.RS +.nf +\&.\&.\&. \fB1>\fP\fIfname\fP \fB2>&1\fP +.fi +.RE +.PP +first associates file descriptor 1 with file \fIfname\fP\&. +It then associates file descriptor 2 with the file associated with file +descriptor 1 (that is, \fIfname\fP)\&. +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 \fIfname\fP\&. +.PP +The `\fB|&\fP\&' command separator described in +\fISimple Commands & Pipelines\fP in \fIzshmisc\fP(1) +is a shorthand for `\fB2>&1 |\fP\&'\&. +.PP +The various forms of process substitution, `\fB<(\fP\fIlist\fP\fB)\fP\&', +and `\fB=(\fP\fIlist\fP\fB)\fP\&' for input and +`\fB>(\fP\fIlist\fP\fB)\fP\&' for output, are often used together with +redirection\&. For example, if \fIword\fP in an output redirection is of the +form `\fB>(\fP\fIlist\fP\fB)\fP\&' then the output is piped to the +command represented by \fIlist\fP\&. See +\fIProcess Substitution\fP in \fIzshexpn\fP(1)\&. +.SH "OPENING FILE DESCRIPTORS USING PARAMETERS" +.PP +When the shell is parsing arguments to a command, and the shell option +\fBIGNORE_BRACES\fP 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: +.PP +.RS +.nf +\&.\&.\&. \fB{myfd}>&1\fP +.fi +.RE +.PP +This opens a new file descriptor that is a duplicate of file descriptor +1 and sets the parameter \fBmyfd\fP to the number of the file descriptor, +which will be at least 10\&. The new file descriptor can be written to using +the syntax \fB>&$myfd\fP\&. The file descriptor remains open in subshells +and forked external executables\&. +.PP +The syntax \fB{\fP\fIvarid\fP\fB}>&\-\fP, for example \fB{myfd}>&\-\fP, may be used +to close a file descriptor opened in this fashion\&. Note that the +parameter given by \fIvarid\fP must previously be set to a file descriptor +in this case\&. +.PP +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 \fB<&$\fP\fIparam\fP or \fB>&$\fP\fIparam\fP if \fIparam\fP is +readonly\&. +.PP +If the option \fBCLOBBER\fP 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\&. +.PP +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 \fBexec\fP\&. +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\&. +.PP +The following shows a typical sequence of allocation, use, and closing of a +file descriptor: +.PP +.RS +.nf +\fBinteger myfd +exec {myfd}>~/logs/mylogfile\&.txt +print This is a log message\&. >&$myfd +exec {myfd}>&\-\fP +.fi +.RE +.PP +Note that the expansion of the variable in the expression \fB>&$myfd\fP +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\&. +.SH "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 \fBtee\fP, +provided the \fBMULTIOS\fP option is set, as it is by default\&. Thus: +.PP +.RS +.nf +\fBdate >foo >bar\fP +.fi +.RE +.PP +writes the date to two files, named `\fBfoo\fP\&' and `\fBbar\fP'\&. +Note that a pipe is an implicit redirection; thus +.PP +.RS +.nf +\fBdate >foo | cat\fP +.fi +.RE +.PP +writes the date to the file `\fBfoo\fP\&', and also pipes it to cat\&. +.PP +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\&. +.PP +Note also that redirections are always expanded in order\&. This happens +regardless of the setting of the \fBMULTIOS\fP option, but with the option +in effect there are additional consequences\&. For example, +the meaning of the expression \fB>&1\fP will change after a previous +redirection: +.PP +.RS +.nf +\fBdate >&1 >output\fP +.fi +.RE +.PP +In the case above, the \fB>&1\fP refers to the standard output at the +start of the line; the result is similar to the \fBtee\fP command\&. +However, consider: +.PP +.RS +.nf +\fBdate >output >&1\fP +.fi +.RE +.PP +As redirections are evaluated in order, when the \fB>&1\fP is encountered +the standard output is set to the file \fBoutput\fP and another copy of +the output is therefore sent to that file\&. This is unlikely to be what +is intended\&. +.PP +If the \fBMULTIOS\fP +option is set, the word after a redirection operator is also subjected +to filename generation (globbing)\&. Thus +.PP +.RS +.nf +\fB: > *\fP +.fi +.RE +.PP +will truncate all files in the current directory, +assuming there\&'s at least one\&. (Without the \fBMULTIOS\fP +option, it would create an empty file called `\fB*\fP\&'\&.) +Similarly, you can do +.PP +.RS +.nf +\fBecho exit 0 >> *\&.sh\fP +.fi +.RE +.PP +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 \fBMULTIOS\fP 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 \fBcat\fP, so if strictly standard behaviour +is needed, \fBcat\fP should be used instead\&. +.PP +Thus +.PP +.RS +.nf +\fBsort <foo <fubar\fP +.fi +.RE +.PP +or even +.PP +.RS +.nf +\fBsort <f{oo,ubar}\fP +.fi +.RE +.PP +is equivalent to `\fBcat foo fubar | sort\fP\&'\&. +.PP +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 \fB>&$myfd\fP\&. +.PP +Note that a pipe is an implicit redirection; thus +.PP +.RS +.nf +\fBcat bar | sort <foo\fP +.fi +.RE +.PP +is equivalent to `\fBcat bar foo | sort\fP\&' (note the order of the inputs)\&. +.PP +If the \fBMULTIOS\fP option is \fIun\fPset, +each redirection replaces the previous redirection for that file descriptor\&. +However, all files redirected to are actually opened, so +.PP +.RS +.nf +\fBecho Hello > bar > baz\fP +.fi +.RE +.PP +when \fBMULTIOS\fP is unset will truncate `\fBbar\fP\&', and write `\fBHello\fP' +into `\fBbaz\fP\&'\&. +.PP +There is a problem when an output multio is attached to an external +program\&. A simple example shows this: +.PP +.RS +.nf +\fBcat file >file1 >file2 +cat file1 file2\fP +.fi +.RE +.PP +Here, it is possible that the second `\fBcat\fP\&' will not display the full +contents of \fBfile1\fP and \fBfile2\fP (i\&.e\&. the original contents of +\fBfile\fP repeated twice)\&. +.PP +The reason for this is that the multios are spawned after the \fBcat\fP +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 \fBfile1\fP and \fBfile2\fP are completely written\&. +As a workaround, it is possible to run the \fBcat\fP process as part of a +job in the current shell: +.PP +.RS +.nf +\fB{ cat file } >file >file2\fP +.fi +.RE +.PP +Here, the \fB{\fP\fI\&.\&.\&.\fP\fB}\fP job will pause to wait for both files to be +written\&. +.PP +.SH "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\&. +.PP +If the parameter \fBNULLCMD\fP is not set or the option \fBCSH_NULLCMD\fP is +set, an error is caused\&. This is the \fBcsh\fP behavior and \fBCSH_NULLCMD\fP +is set by default when emulating \fBcsh\fP\&. +.PP +If the option \fBSH_NULLCMD\fP is set, the builtin `\fB:\fP\&' is inserted as a +command with the given redirections\&. This is the default when emulating +\fBsh\fP or \fBksh\fP\&. +.PP +Otherwise, if the parameter \fBNULLCMD\fP is set, its value will be used as a +command with the given redirections\&. If both \fBNULLCMD\fP and +\fBREADNULLCMD\fP 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 +\fBNULLCMD\fP is `\fBcat\fP\&' and for \fBREADNULLCMD\fP is `\fBmore\fP'\&. Thus +.PP +.RS +.nf +\fB< file\fP +.fi +.RE +.PP +shows the contents of \fBfile\fP on standard output, with paging if that is a +terminal\&. \fBNULLCMD\fP and \fBREADNULLCMD\fP may refer to shell functions\&. +.PP +.\" Yodl file: Zsh/exec.yo +.SH "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 the section `Functions\&'\&. If there exists +a shell builtin by that name, the builtin is invoked\&. +.PP +Otherwise, the shell searches each element of \fB$path\fP for a +directory containing an executable file by that name\&. +.PP +If execution fails: an error message is printed, and one of the +following values is returned\&. +.PP +.PD 0 +.TP +127 +The search was unsuccessful\&. The error message is +`\fBcommand not found:\fP \fIcmd\fP\&'\&. +.TP +126 +The executable file has insufficient permissions, is a +directory or special file, or is not a script and is in a format +unrecognized by the operating system\&. The exact conditions and error +message are operating system\-dependent; see +\fIexecve\fP(2)\&. +.PD +.PP +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\&. \fB/bin/sh\fP is spawned to execute it\&. If the program +is a file beginning with `\fB#!\fP\&', 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\&. +.PP +If no external command is found but a function \fBcommand_not_found_handler\fP +exists the shell executes this function with all +command line arguments\&. The return status of the function becomes the +status of the command\&. 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\&. +.\" Yodl file: Zsh/func.yo +.SH "FUNCTIONS" +Shell functions are defined with the \fBfunction\fP reserved word or the +special syntax `\fIfuncname\fP \fB()\fP\&'\&. +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 the section `Command Execution\&'\&.) +.PP +Functions execute in the same process as the caller and +share all files +and present working directory with the +caller\&. A trap on \fBEXIT\fP set inside a function +is executed after the function completes in the environment +of the caller\&. +.PP +The \fBreturn\fP builtin is used to return from function calls\&. +.PP +Function identifiers can be listed with the \fBfunctions\fP builtin\&. +Functions can be undefined with the \fBunfunction\fP builtin\&. +.SH "AUTOLOADING FUNCTIONS" +.PP +A function can be marked as \fIundefined\fP using the \fBautoload\fP builtin +(or `\fBfunctions \-u\fP\&' or `\fBtypeset \-fu\fP')\&. Such a function has no +body\&. When the function is first executed, the shell searches for its +definition using the elements of the \fBfpath\fP variable\&. Thus to define +functions for autoloading, a typical sequence is: +.PP +.RS +.nf +\fBfpath=(~/myfuncs $fpath) +autoload myfunc1 myfunc2 \&.\&.\&.\fP +.fi +.RE +.PP +The usual alias expansion during reading will be suppressed if the +\fBautoload\fP builtin or its equivalent is given the option \fB\-U\fP\&. This is +recommended for the use of functions supplied with the zsh distribution\&. +Note that for functions precompiled with the \fBzcompile\fP builtin command +the flag \fB\-U\fP must be provided when the \fB\&.zwc\fP file is created, as the +corresponding information is compiled into the latter\&. +.PP +For each \fIelement\fP in \fBfpath\fP, the shell looks for three possible +files, the newest of which is used to load the definition for the function: +.PP +.PD 0 +.TP +.PD +\fIelement\fP\fB\&.zwc\fP +A file created with the \fBzcompile\fP builtin command, which is expected to +contain the definitions for all functions in the directory named +\fIelement\fP\&. 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\&. +.RS +.PP +If \fIelement\fP already includes a \fB\&.zwc\fP extension (i\&.e\&. the extension +was explicitly given by the user), \fIelement\fP 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 \fIelement\fP +without the suffix\&. Thus including an element such as +`\fB/usr/local/funcs\&.zwc\fP\&' in \fBfpath\fP 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\&. +.RE +.TP +\fIelement\fP\fB/\fP\fIfunction\fP\fB\&.zwc\fP +A file created with \fBzcompile\fP, which is expected to contain the +definition for \fIfunction\fP\&. It may include other function definitions +as well, but those are neither loaded nor executed; a file found in this +way is searched \fIonly\fP for the definition of \fIfunction\fP\&. +.TP +\fIelement\fP\fB/\fP\fIfunction\fP +A file of zsh command text, taken to be the definition for \fIfunction\fP\&. +.PP +In summary, the order of searching is, first, in the \fIparents of\fP +directories in \fBfpath\fP for the newer of either a compiled directory or +a directory in \fBfpath\fP; second, if more than one of these contains a +definition for the function that is sought, the leftmost in the \fBfpath\fP +is chosen; and third, within a directory, the newer of either a compiled +function or an ordinary function definition is used\&. +.PP +If the \fBKSH_AUTOLOAD\fP 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\&. +.PP +Otherwise, the function body (with no surrounding `\fIfuncname\fP\fB() +{\fP\fI\&.\&.\&.\fP\fB}\fP\&') 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\&. +.PP +For example, suppose the autoload file \fBfunc\fP contains +.PP +.RS +.nf +\fBfunc() { print This is func; } +print func is initialized\fP +.fi +.RE +.PP +then `\fBfunc; func\fP\&' with \fBKSH_AUTOLOAD\fP set will produce both messages +on the first call, but only the message `\fBThis is func\fP\&' on the second +and subsequent calls\&. Without \fBKSH_AUTOLOAD\fP set, it will produce +the initialization message on the first call, and the other message on the +second and subsequent calls\&. +.PP +It is also possible to create a function that is not marked as autoloaded, +but which loads its own definition by searching \fBfpath\fP, by using +`\fBautoload \-X\fP\&' within a shell function\&. For example, the following are +equivalent: +.PP +.RS +.nf +\fBmyfunc() { + autoload \-X +} +myfunc args\&.\&.\&.\fP +.fi +.RE +.PP +and +.PP +.RS +.nf +\fBunfunction myfunc # if myfunc was defined +autoload myfunc +myfunc args\&.\&.\&.\fP +.fi +.RE +.PP +In fact, the \fBfunctions\fP command outputs `\fBbuiltin autoload \-X\fP\&' as +the body of an autoloaded function\&. This is done so that +.PP +.RS +.nf +\fBeval "$(functions)"\fP +.fi +.RE +.PP +produces a reasonable result\&. A true autoloaded function can be +identified by the presence of the comment `\fB# undefined\fP\&' in the body, +because all comments are discarded from defined functions\&. +.PP +To load the definition of an autoloaded function \fBmyfunc\fP without +executing \fBmyfunc\fP, use: +.PP +.RS +.nf +\fBautoload +X myfunc\fP +.fi +.RE +.PP +.SH "ANONYMOUS FUNCTIONS" +.PP +If no name is given for a function, it is `anonymous\&' and is handled +specially\&. Either form of function definition may be used: a `\fB()\fP\&' with +no preceding name, or a `\fBfunction\fP\&' 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 `\fB(anon)\fP\&'\&. +.PP +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 \fB$0\fP) are set\&. This is a difference from the +way other functions are parsed: normal function definitions may be +followed by certain keywords such as `\fBelse\fP\&' or `\fBfi\fP', which will +be treated as arguments to anonymous functions, so that a newline or +semicolon is needed to force keyword interpretation\&. +.PP +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)\&. +.PP +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\&. +.PP +For example, +.PP +.RS +.nf +\fBvariable=outside +function { + local variable=inside + print "I am $variable with arguments $*" +} this and that +print "I am $variable"\fP +.fi +.RE +.PP +outputs the following: +.PP +.RS +.nf +\fBI am inside with arguments this and that +I am outside\fP +.fi +.RE +.PP +Note that function definitions with arguments that expand to nothing, +for example `\fBname=; function $name { \fP\fI\&.\&.\&.\fP\fB }\fP\&', are not +treated as anonymous functions\&. Instead, they are treated as normal +function definitions where the definition is silently discarded\&. +.PP +.SH "SPECIAL FUNCTIONS" +Certain functions, if defined, have special meaning to the shell\&. +.PP +.SS "Hook Functions" +.PP +For the functions below, it is possible to define an array that has the +same name as the function with `\fB_functions\fP\&' 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 and same initial value of \fB$?\fP +as the basic function\&. For +example, if \fB$chpwd_functions\fP is an array containing the values +`\fBmychpwd\fP\&', `\fBchpwd_save_dirstack\fP', then the shell attempts to +execute the functions `\fBchpwd\fP\&', `\fBmychpwd\fP' and +`\fBchpwd_save_dirstack\fP\&', in that order\&. Any function that does not exist +is silently ignored\&. A function found by this mechanism is referred to +elsewhere as a \fIhook function\fP\&. An error in any function causes subsequent +functions not to be run\&. Note further that an error in a \fBprecmd\fP hook +causes an immediately following \fBperiodic\fP function not to run (though +it may run at the next opportunity)\&. +.PP +.PD 0 +.TP +.PD +\fBchpwd\fP +Executed whenever the current working directory is changed\&. +.TP +\fBperiodic\fP +If the parameter \fBPERIOD\fP +is set, this function is executed every \fB$PERIOD\fP +seconds, just before a prompt\&. Note that if multiple functions +are defined using the array \fBperiodic_functions\fP 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\&. +.TP +\fBprecmd\fP +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\&. +.TP +\fBpreexec\fP +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\&. +.TP +\fBzshaddhistory\fP +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)\&. +.RS +.PP +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\&. +.PP +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\&. +.PP +A hook function may call `\fBfc \-p\fP \fI\&.\&.\&.\fP\&' to switch the history +context so that the history is saved in a different file from +that in the global \fBHISTFILE\fP parameter\&. This is handled specially: +the history context is automatically restored after the processing +of the history line is finished\&. +.PP +The following example function works with one of the options +\fBINC_APPEND_HISTORY\fP or \fBSHARE_HISTORY\fP 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\&. +.PP +.RS +.nf +\fBzshaddhistory() { + print \-sr \-\- ${1%%$\&'\en'} + fc \-p \&.zsh_local_history +}\fP +.fi +.RE +.RE +.TP +\fBzshexit\fP +Executed at the point where the main shell is about to exit normally\&. +This is not called by exiting subshells, nor when the \fBexec\fP +precommand modifier is used before an external command\&. Also, unlike +\fBTRAPEXIT\fP, it is not called when functions exit\&. +.PP +.SS "Trap Functions" +.PP +The functions below are treated specially but do not have corresponding +hook arrays\&. +.PP +.PD 0 +.TP +.PD +\fBTRAP\fP\fINAL\fP +If defined and non\-null, +this function will be executed whenever the shell +catches a signal \fBSIG\fP\fINAL\fP, where \fINAL\fP is a signal +name as specified for the \fBkill\fP builtin\&. +The signal number will be passed as the first parameter to the function\&. +.RS +.PP +If a function of this form is defined and null, +the shell and processes spawned by it will ignore \fBSIG\fP\fINAL\fP\&. +.PP +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\&. +.PP +Programs terminated by uncaught signals typically return the status 128 +plus the signal number\&. Hence the following causes the handler for +\fBSIGINT\fP to print a message, then mimic the usual effect of the signal\&. +.PP +.RS +.nf +\fBTRAPINT() { + print "Caught SIGINT, aborting\&." + return $(( 128 + $1 )) +}\fP +.fi +.RE +.PP +The functions \fBTRAPZERR\fP, \fBTRAPDEBUG\fP and \fBTRAPEXIT\fP are never +executed inside other traps\&. +.RE +.TP +\fBTRAPDEBUG\fP +If the option \fBDEBUG_BEFORE_CMD\fP is set (as it is by default), executed +before each command; otherwise executed after each command\&. See +the description of the \fBtrap\fP builtin in +\fIzshbuiltins\fP(1) for details of additional features provided +in debug traps\&. +.TP +\fBTRAPEXIT\fP +Executed when the shell exits, +or when the current function exits if defined inside a function\&. +The value of \fB$?\fP at the start of execution is the exit status of the +shell or the return status of the function exiting\&. +.TP +\fBTRAPZERR\fP +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 +`\fB&&\fP\&' or `\fB||\fP'; only the final command in a sublist of this type +causes the trap to be executed\&. The function \fBTRAPERR\fP acts the same as +\fBTRAPZERR\fP on systems where there is no \fBSIGERR\fP (this is the usual +case)\&. +.PP +The functions beginning `\fBTRAP\fP\&' may alternatively be defined with the +\fBtrap\fP 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 +.PP +.RS +.nf +\fBTRAPNAL() { + # code +}\fP +.fi +.RE +.PP +(\&'function traps') and +.PP +.RS +.nf +\fBtrap \&' + # code +\&' NAL\fP +.fi +.RE +.PP +(\&'list traps') are equivalent in most ways, the exceptions being the +following: +.PP +.PD 0 +.TP +.PD +\(bu +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\&. +.TP +\(bu +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\&. +.TP +\(bu +Function traps are not reset within subshells, in accordance with +zsh behaviour; list traps are reset, in accordance with POSIX +behaviour\&. +.\" Yodl file: Zsh/jobs.yo +.SH "JOBS" +If the \fBMONITOR\fP option is set, +an interactive shell associates a \fIjob\fP with each pipeline\&. +It keeps a table of current jobs, printed by the \fBjobs\fP +command, and assigns them small integer numbers\&. +When a job is started asynchronously with `\fB&\fP\&', +the shell prints a line to standard error which looks like: +.PP +.RS +.nf +\fB[1] 1234\fP +.fi +.RE +.PP +indicating that the job which was started asynchronously was job number +1 and had one (top\-level) process, whose process ID was 1234\&. +.PP +If a job is started with `\fB&|\fP\&' or `\fB&!\fP', +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\&. +.PP +If you are running a job and wish to do something else you may hit the key +^Z (control\-Z) which sends a \fBTSTP\fP signal to the current job: this key +may be redefined by the \fBsusp\fP option of the external \fBstty\fP 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 \fBbg\fP command, or run some other +commands and then eventually bring the job back into the foreground with +the foreground command \fBfg\fP\&. A ^Z takes effect immediately and +is like an interrupt in that pending output and unread input are discarded +when it is typed\&. +.PP +A job being run in the background will suspend if it tries to read +from the terminal\&. +.PP +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 \fBfg\fP 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\&. +.PP +One additional side effect is that use of \fBdisown\fP 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\&. +.PP +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 +\fBif\fP, \fBfor\fP, 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 `\fBstty tostop\fP\&'\&. +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\&. +.PP +When a command is suspended and continued later with the \fBfg\fP or +\fBwait\fP builtins, zsh restores tty modes that were in effect when it was +suspended\&. This (intentionally) does not apply if the command is +continued via `\fBkill \-CONT\fP\&', nor when it is continued with \fBbg\fP\&. +.PP +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: +.PP +.PD 0 +.TP +\fB%\fP\fInumber\fP +The job with the given number\&. +.TP +\fB%\fP\fIstring\fP +The last job whose command line begins with \fIstring\fP\&. +.TP +\fB%?\fP\fIstring\fP +The last job whose command line contains \fIstring\fP\&. +.TP +\fB%%\fP +Current job\&. +.TP +\fB%+\fP +Equivalent to `\fB%%\fP\&'\&. +.TP +\fB%\-\fP +Previous job\&. +.PD +.PP +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 \fBNOTIFY\fP 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\&. +.PP +When the monitor mode is on, each background job that completes +triggers any trap set for \fBCHLD\fP\&. +.PP +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 \fBjobs\fP 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 \fBSIGHUP\fP signal, if the \fBHUP\fP option is set\&. +.PP +To avoid having the shell terminate the running jobs, either +use the \fInohup\fP(1) command +or the \fBdisown\fP builtin\&. +.SH "SIGNALS" +The \fBINT\fP and \fBQUIT\fP signals for an invoked +command are ignored if the command is followed by +`\fB&\fP\&' and the \fBMONITOR\fP option is not active\&. +The shell itself always ignores the \fBQUIT\fP signal\&. +Otherwise, signals have the values +inherited by the shell from its parent +(but see the \fBTRAP\fP\fINAL\fP special functions in the section `Functions\&')\&. +.PP +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 \fBexit\fP command +or exit due to the option \fBERR_EXIT\fP will cause the shell to +exit without waiting\&. Examples of such asynchronous jobs are +process substitution, see +the section PROCESS SUBSTITUTION in the \fIzshexpn\fP(1) manual page, and the handler processes for +multios, see +the section MULTIOS in the \fIzshmisc\fP(1) manual page\&. +.\" Yodl file: Zsh/arith.yo +.SH "ARITHMETIC EVALUATION" +The shell can perform integer and floating point arithmetic, either using +the builtin \fBlet\fP, or via a substitution of the form +\fB$((\fP\fI\&.\&.\&.\fP\fB))\fP\&. 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 `\fBprint \- $(( 12345678901 ))\fP\&'; 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\&. +.PP +The \fBlet\fP 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 `\fB((\fP\&', all the characters until a +matching `\fB))\fP\&' are treated as a double\-quoted expression and +arithmetic expansion performed as for an argument of \fBlet\fP\&. More +precisely, `\fB((\fP\fI\&.\&.\&.\fP\fB))\fP\&' is equivalent to +`\fBlet "\fP\fI\&.\&.\&.\fP\fB"\fP\&'\&. 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\&. +.PP +For example, the following statement +.PP +.RS +.nf +\fB(( val = 2 + 1 ))\fP +.fi +.RE +.PP +is equivalent to +.PP +.RS +.nf +\fBlet "val = 2 + 1"\fP +.fi +.RE +.PP +both assigning the value 3 to the shell variable \fBval\fP and returning a +zero status\&. +.PP +Integers can be in bases other than 10\&. +A leading `\fB0x\fP\&' or `\fB0X\fP' denotes hexadecimal and a leading +`\fB0b\fP\&' or `\fB0B\fP' binary\&. +Integers may also be of the form `\fIbase\fP\fB#\fP\fIn\fP\&', +where \fIbase\fP is a decimal number between two and thirty\-six +representing the arithmetic base and \fIn\fP +is a number in that base (for example, `\fB16#ff\fP\&' is 255 in hexadecimal)\&. +The \fIbase\fP\fB#\fP may also be omitted, in which case +base 10 is used\&. For backwards compatibility the form +`\fB[\fP\fIbase\fP\fB]\fP\fIn\fP\&' is also accepted\&. +.PP +An integer expression or a base given in the form +`\fIbase\fP\fB#\fP\fIn\fP\&' may contain underscores (`\fB_\fP') after the +leading digit for visual guidance; these are ignored in computation\&. +Examples are \fB1_000_000\fP or \fB0xffff_ffff\fP which are equivalent to +\fB1000000\fP and \fB0xffffffff\fP respectively\&. +.PP +It is also possible to specify a base to be used for output in the form +`\fB[#\fP\fIbase\fP\fB]\fP\&', for example `\fB[#16]\fP'\&. 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 `\fB\-i\fP \fIbase\fP' to +the \fBtypeset\fP 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: +.PP +.RS +.nf +\fBtypeset \-i 16 y +print $(( [#8] x = 32, y = 32 )) +print $x $y\fP +.fi +.RE +.PP +outputs first `\fB8#40\fP\&', the rightmost value in the given output base, and +then `\fB8#40 16#20\fP\&', because \fBy\fP has been explicitly declared to +have output base 16, while \fBx\fP (assuming it does not already exist) is +implicitly typed by the arithmetic evaluation, where it acquires the output +base 8\&. +.PP +The \fIbase\fP 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: +.PP +.RS +.nf +\fBsetopt cbases +print $(( [#16_4] 65536 ** 2 ))\fP +.fi +.RE +.PP +outputs `\fB0x1_0000_0000\fP\&'\&. +.PP +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, +.PP +.RS +.nf +\fBzmodload zsh/mathfunc +print $(( [#_] sqrt(1e7) ))\fP +.fi +.RE +.PP +outputs `\fB3_162\&.277_660_168_379_5\fP\&' (the number of decimal places +shown may vary)\&. +.PP +If the \fBC_BASES\fP option is set, hexadecimal numbers are output in the standard C +format, for example `\fB0xFF\fP\&' instead of the usual `\fB16#FF\fP'\&. If the +option \fBOCTAL_ZEROES\fP is also set (it is not by default), octal numbers +will be treated similarly and hence appear as `\fB077\fP\&' instead of +`\fB8#77\fP\&'\&. This option has no effect on the output of bases other than +hexadecimal and octal, and these formats are always understood on input\&. +.PP +When an output base is specified using the `\fB[#\fP\fIbase\fP\fB]\fP\&' syntax, +an appropriate base prefix will be output if necessary, so that the value +output is valid syntax for input\&. If the \fB#\fP is doubled, for example +`\fB[##16]\fP\&', then no base prefix is output\&. +.PP +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 \fBe\fP or \fBE\fP 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\&. +.PP +An arithmetic expression uses nearly the same syntax and +associativity of expressions as in C\&. +.PP +In the native mode of operation, the following operators are supported +(listed in decreasing order of precedence): +.PP +.PD 0 +.TP +\fB+ \- ! ~ ++ \-\-\fP +unary plus/minus, logical NOT, complement, {pre,post}{in,de}crement +.TP +\fB<< >>\fP +bitwise shift left, right +.TP +\fB&\fP +bitwise AND +.TP +\fB^\fP +bitwise XOR +.TP +\fB|\fP +bitwise OR +.TP +\fB**\fP +exponentiation +.TP +\fB* / %\fP +multiplication, division, modulus (remainder) +.TP +\fB+ \-\fP +addition, subtraction +.TP +\fB< > <= >=\fP +comparison +.TP +\fB== !=\fP +equality and inequality +.TP +\fB&&\fP +logical AND +.TP +\fB|| ^^\fP +logical OR, XOR +.TP +\fB? :\fP +ternary operator +.TP +\fB= += \-= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=\fP +assignment +.TP +\fB,\fP +comma operator +.PD +.PP +The operators `\fB&&\fP\&', `\fB||\fP', `\fB&&=\fP', and `\fB||=\fP' 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\&. +.PP +With the option \fBC_PRECEDENCES\fP 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: +.PP +.PD 0 +.TP +\fB+ \- ! ~ ++ \-\-\fP +unary plus/minus, logical NOT, complement, {pre,post}{in,de}crement +.TP +\fB**\fP +exponentiation +.TP +\fB* / %\fP +multiplication, division, modulus (remainder) +.TP +\fB+ \-\fP +addition, subtraction +.TP +\fB<< >>\fP +bitwise shift left, right +.TP +\fB< > <= >=\fP +comparison +.TP +\fB== !=\fP +equality and inequality +.TP +\fB&\fP +bitwise AND +.TP +\fB^\fP +bitwise XOR +.TP +\fB|\fP +bitwise OR +.TP +\fB&&\fP +logical AND +.TP +\fB^^\fP +logical XOR +.TP +\fB||\fP +logical OR +.TP +\fB? :\fP +ternary operator +.TP +\fB= += \-= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=\fP +assignment +.TP +\fB,\fP +comma operator +.PD +.PP +Note the precedence of exponentiation in both cases is below +that of unary operators, hence `\fB\-3**2\fP\&' evaluates as `\fB9\fP', not +`\fB\-9\fP\&'\&. Use parentheses where necessary: `\fB\-(3**2)\fP'\&. This is +for compatibility with other shells\&. +.PP +Mathematical functions can be called with the syntax +`\fIfunc\fP\fB(\fP\fIargs\fP\fB)\fP\&', where the function decides +if the \fIargs\fP 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 \fBzsh/mathfunc\fP may be loaded with +the \fBzmodload\fP builtin to provide standard floating point mathematical +functions\&. +.PP +An expression of the form `\fB##\fP\fIx\fP\&' where \fIx\fP is any character +sequence such as `\fBa\fP\&', `\fB^A\fP', or `\fB\eM\-\eC\-x\fP' gives the value of +this character and an expression of the form `\fB#\fP\fIname\fP\&' gives the +value of the first character of the contents of the parameter \fIname\fP\&. +Character values are according to the character set used in the current +locale; for multibyte character handling the option \fBMULTIBYTE\fP must be +set\&. Note that this form is different from `\fB$#\fP\fIname\fP\&', a standard +parameter substitution which gives the length of the parameter \fIname\fP\&. +`\fB#\e\fP\&' is accepted instead of `\fB##\fP', but its use is deprecated\&. +.PP +Named parameters and subscripted arrays can be referenced by name within an +arithmetic expression without using the parameter expansion syntax\&. For +example, +.PP +.RS +.nf +\fB((val2 = val1 * 2))\fP +.fi +.RE +.PP +assigns twice the value of \fB$val1\fP to the parameter named \fBval2\fP\&. +.PP +An internal integer representation of a named parameter +can be specified with the \fBinteger\fP 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\&. +.PP +Likewise, floating point numbers can be declared with the \fBfloat\fP +builtin; there are two types, differing only in their output format, as +described for the \fBtypeset\fP builtin\&. The output format can be bypassed +by using arithmetic substitution instead of the parameter substitution, +i\&.e\&. `\fB${\fP\fIfloat\fP\fB}\fP\&' uses the defined format, but +`\fB$((\fP\fIfloat\fP\fB))\fP\&' uses a generic floating point +format\&. +.PP +Promotion of integer to floating point values is performed where +necessary\&. In addition, if any operator which requires an integer +(`\fB&\fP\&', `\fB|\fP', `\fB^\fP', `\fB<<\fP', `\fB>>\fP' and their equivalents with +assignment) is given a floating point argument, it will be silently rounded +towards zero except for `\fB~\fP\&' which rounds down\&. +.PP +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 \fB6/8\fP is truncated, +in this being rounded towards 0\&. The \fBFORCE_FLOAT\fP shell option can +be used in scripts or functions where floating point evaluation is +required throughout\&. +.PP +Scalar variables can hold integer or floating point values at different +times; there is no memory of the numeric type in this case\&. +.PP +If a variable is first assigned in a numeric context without previously +being declared, it will be implicitly typed as \fBinteger\fP or \fBfloat\fP 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 +.PP +.RS +.nf +\fBfor (( f = 0; f < 1; f += 0\&.1 )); do +# use $f +done\fP +.fi +.RE +.PP +if \fBf\fP has not already been declared, the first assignment will cause it +to be created as an integer, and consequently the operation `\fBf += 0\&.1\fP\&' +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 `\fBf = 0\&.0\fP\&'\&. +It is therefore best to declare numeric variables with explicit types\&. +.\" Yodl file: Zsh/cond.yo +.SH "CONDITIONAL EXPRESSIONS" +A \fIconditional expression\fP is used with the \fB[[\fP +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: +.PP +.PD 0 +.TP +.PD +\fB\-a\fP \fIfile\fP +true if \fIfile\fP exists\&. +.TP +\fB\-b\fP \fIfile\fP +true if \fIfile\fP exists and is a block special file\&. +.TP +\fB\-c\fP \fIfile\fP +true if \fIfile\fP exists and is a character special file\&. +.TP +\fB\-d\fP \fIfile\fP +true if \fIfile\fP exists and is a directory\&. +.TP +\fB\-e\fP \fIfile\fP +true if \fIfile\fP exists\&. +.TP +\fB\-f\fP \fIfile\fP +true if \fIfile\fP exists and is a regular file\&. +.TP +\fB\-g\fP \fIfile\fP +true if \fIfile\fP exists and has its setgid bit set\&. +.TP +\fB\-h\fP \fIfile\fP +true if \fIfile\fP exists and is a symbolic link\&. +.TP +\fB\-k\fP \fIfile\fP +true if \fIfile\fP exists and has its sticky bit set\&. +.TP +\fB\-n\fP \fIstring\fP +true if length of \fIstring\fP is non\-zero\&. +.TP +\fB\-o\fP \fIoption\fP +true if option named \fIoption\fP is on\&. \fIoption\fP +may be a single character, in which case it is a single letter option name\&. +(See the section `Specifying Options\&'\&.) +.RS +.PP +When no option named \fIoption\fP exists, and the \fBPOSIX_BUILTINS\fP option +hasn\&'t been set, return 3 with a warning\&. If that option is set, return 1 +with no warning\&. +.RE +.TP +\fB\-p\fP \fIfile\fP +true if \fIfile\fP exists and is a FIFO special file (named pipe)\&. +.TP +\fB\-r\fP \fIfile\fP +true if \fIfile\fP exists and is readable by current process\&. +.TP +\fB\-s\fP \fIfile\fP +true if \fIfile\fP exists and has size greater than zero\&. +.TP +\fB\-t\fP \fIfd\fP +true if file descriptor number \fIfd\fP +is open and associated with a terminal device\&. +(note: \fIfd\fP is not optional) +.TP +\fB\-u\fP \fIfile\fP +true if \fIfile\fP exists and has its setuid bit set\&. +.TP +\fB\-v\fP \fIvarname\fP +true if shell variable \fIvarname\fP is set\&. +.TP +\fB\-w\fP \fIfile\fP +true if \fIfile\fP exists and is writable by current process\&. +.TP +\fB\-x\fP \fIfile\fP +true if \fIfile\fP exists and is executable by current process\&. +If \fIfile\fP exists and is a directory, then the current process +has permission to search in the directory\&. +.TP +\fB\-z\fP \fIstring\fP +true if length of \fIstring\fP is zero\&. +.TP +\fB\-L\fP \fIfile\fP +true if \fIfile\fP exists and is a symbolic link\&. +.TP +\fB\-O\fP \fIfile\fP +true if \fIfile\fP exists and is owned by the effective user ID of this process\&. +.TP +\fB\-G\fP \fIfile\fP +true if \fIfile\fP exists and its group matches +the effective group ID of this process\&. +.TP +\fB\-S\fP \fIfile\fP +true if \fIfile\fP exists and is a socket\&. +.TP +\fB\-N\fP \fIfile\fP +true if \fIfile\fP exists and its access time is +not newer than its modification time\&. +.TP +\fIfile1\fP \fB\-nt\fP \fIfile2\fP +true if \fIfile1\fP exists and is newer than \fIfile2\fP\&. +.TP +\fIfile1\fP \fB\-ot\fP \fIfile2\fP +true if \fIfile1\fP exists and is older than \fIfile2\fP\&. +.TP +\fIfile1\fP \fB\-ef\fP \fIfile2\fP +true if \fIfile1\fP and \fIfile2\fP exist and refer to the same file\&. +.TP +.PD 0 +\fIstring\fP \fB=\fP \fIpattern\fP +.TP +.PD +\fIstring\fP \fB==\fP \fIpattern\fP +true if \fIstring\fP matches \fIpattern\fP\&. +The two forms are exactly equivalent\&. The `\fB=\fP\&' form is +the traditional shell syntax (and hence the only one generally used +with the \fBtest\fP and \fB[\fP builtins); the `\fB==\fP\&' form provides +compatibility with other sorts of computer language\&. +.TP +\fIstring\fP \fB!=\fP \fIpattern\fP +true if \fIstring\fP does not match \fIpattern\fP\&. +.TP +\fIstring\fP \fB=~\fP \fIregexp\fP +true if \fIstring\fP matches the regular expression +\fIregexp\fP\&. If the option \fBRE_MATCH_PCRE\fP is set +\fIregexp\fP is tested as a PCRE regular expression using +the \fBzsh/pcre\fP module, else it is tested as a POSIX +extended regular expression using the \fBzsh/regex\fP module\&. +Upon successful match, some variables will be updated; no variables +are changed if the matching fails\&. +.RS +.PP +If the option \fBBASH_REMATCH\fP is not set the scalar parameter +\fBMATCH\fP is set to the substring that matched the pattern and +the integer parameters \fBMBEGIN\fP and \fBMEND\fP to the index of the start +and end, respectively, of the match in \fIstring\fP, such that if +\fIstring\fP is contained in variable \fBvar\fP the expression +`\fB${var[$MBEGIN,$MEND]}\fP\&' is identical to `\fB$MATCH\fP'\&. The setting +of the option \fBKSH_ARRAYS\fP is respected\&. Likewise, the array +\fBmatch\fP is set to the substrings that matched parenthesised +subexpressions and the arrays \fBmbegin\fP and \fBmend\fP to the indices of +the start and end positions, respectively, of the substrings within +\fIstring\fP\&. The arrays are not set if there were no parenthesised +subexpressions\&. For example, if the string `\fBa short string\fP\&' is matched +against the regular expression `\fBs(\&.\&.\&.)t\fP\&', then (assuming the +option \fBKSH_ARRAYS\fP is not set) \fBMATCH\fP, \fBMBEGIN\fP +and \fBMEND\fP are `\fBshort\fP\&', \fB3\fP and \fB7\fP, respectively, while \fBmatch\fP, +\fBmbegin\fP and \fBmend\fP are single entry arrays containing +the strings `\fBhor\fP\&', `\fB4\fP' and `\fB6\fP', respectively\&. +.PP +If the option \fBBASH_REMATCH\fP is set the array +\fBBASH_REMATCH\fP is set to the substring that matched the pattern +followed by the substrings that matched parenthesised +subexpressions within the pattern\&. +.RE +.TP +\fIstring1\fP \fB<\fP \fIstring2\fP +true if \fIstring1\fP comes before \fIstring2\fP +based on ASCII value of their characters\&. +.TP +\fIstring1\fP \fB>\fP \fIstring2\fP +true if \fIstring1\fP comes after \fIstring2\fP +based on ASCII value of their characters\&. +.TP +\fIexp1\fP \fB\-eq\fP \fIexp2\fP +true if \fIexp1\fP is numerically equal to \fIexp2\fP\&. +Note that for purely numeric comparisons use of the +\fB((\fP\fI\&.\&.\&.\fP\fB))\fP builtin described in +the section `ARITHMETIC EVALUATION\&' is more convenient than +conditional expressions\&. +.TP +\fIexp1\fP \fB\-ne\fP \fIexp2\fP +true if \fIexp1\fP is numerically not equal to \fIexp2\fP\&. +.TP +\fIexp1\fP \fB\-lt\fP \fIexp2\fP +true if \fIexp1\fP is numerically less than \fIexp2\fP\&. +.TP +\fIexp1\fP \fB\-gt\fP \fIexp2\fP +true if \fIexp1\fP is numerically greater than \fIexp2\fP\&. +.TP +\fIexp1\fP \fB\-le\fP \fIexp2\fP +true if \fIexp1\fP is numerically less than or equal to \fIexp2\fP\&. +.TP +\fIexp1\fP \fB\-ge\fP \fIexp2\fP +true if \fIexp1\fP is numerically greater than or equal to \fIexp2\fP\&. +.TP +\fB(\fP \fIexp\fP \fB)\fP +true if \fIexp\fP is true\&. +.TP +\fB!\fP \fIexp\fP +true if \fIexp\fP is false\&. +.TP +\fIexp1\fP \fB&&\fP \fIexp2\fP +true if \fIexp1\fP and \fIexp2\fP are both true\&. +.TP +\fIexp1\fP \fB||\fP \fIexp2\fP +true if either \fIexp1\fP or \fIexp2\fP is true\&. +.PP +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, \fB[[ $var ]]\fP is the same as \fB[[ \-n +$var ]]\fP\&. It is recommended that the second, explicit, form be used +where possible\&. +.PP +Normal shell expansion is performed on the \fIfile\fP, \fIstring\fP and +\fIpattern\fP arguments, but the result of each expansion is constrained to +be a single word, similar to the effect of double quotes\&. +.PP +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 \fBEXTENDED_GLOB\fP is in effect by +using an explicit glob qualifier of the form \fB(#q)\fP at the +end of the string\&. A normal glob qualifier expression may appear +between the `\fBq\fP\&' 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\&. +.PP +This special use of filename generation is only available with the +\fB[[\fP syntax\&. If the condition occurs within the \fB[\fP or \fBtest\fP +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\&. +.PP +For example, +.PP +.RS +.nf +\fB[[ \-n file*(#qN) ]]\fP +.fi +.RE +.PP +produces status zero if and only if there is at least one file in the +current directory beginning with the string `\fBfile\fP\&'\&. The globbing +qualifier \fBN\fP ensures that the expression is empty if there is +no matching file\&. +.PP +Pattern metacharacters are active for the \fIpattern\fP arguments; +the patterns are the same as those used for filename generation, see +\fIzshexpn\fP(1), but there is no special behaviour +of `\fB/\fP\&' nor initial dots, and no glob qualifiers are allowed\&. +.PP +In each of the above expressions, if +\fIfile\fP is of the form `\fB/dev/fd/\fP\fIn\fP\&', +where \fIn\fP is an integer, +then the test applied to the open file whose +descriptor number is \fIn\fP, +even if the underlying system does not support +the \fB/dev/fd\fP directory\&. +.PP +In the forms which do numeric comparison, the expressions \fIexp\fP +undergo arithmetic expansion as if they were enclosed in +\fB$((\fP\fI\&.\&.\&.\fP\fB))\fP\&. +.PP +For example, the following: +.PP +.RS +.nf +\fB[[ ( \-f foo || \-f bar ) && $report = y* ]] && print File exists\&.\fP +.fi +.RE +.PP +tests if either file \fBfoo\fP or file \fBbar\fP exists, and if so, if the +value of the parameter \fBreport\fP begins with `\fBy\fP\&'; if the complete +condition is true, the message `\fBFile exists\&.\fP\&' is printed\&. +.\" Yodl file: Zsh/prompt.yo +.SH "EXPANSION OF PROMPT SEQUENCES" +Prompt sequences undergo a special form of expansion\&. This type of expansion +is also available using the \fB\-P\fP option to the \fBprint\fP builtin\&. +.PP +If the \fBPROMPT_SUBST\fP option is set, the prompt string is first subjected to +\fIparameter expansion\fP, +\fIcommand substitution\fP and +\fIarithmetic expansion\fP\&. +See +\fIzshexpn\fP(1)\&. + +Certain escape sequences may be recognised in the prompt string\&. +.PP +If the \fBPROMPT_BANG\fP option is set, a `\fB!\fP\&' in the prompt is replaced +by the current history event number\&. A literal `\fB!\fP\&' may then be +represented as `\fB!!\fP\&'\&. +.PP +If the \fBPROMPT_PERCENT\fP option is set, certain escape sequences that +start with `\fB%\fP\&' are expanded\&. +Many escapes are followed by a single character, although some of these +take an optional integer argument that +should appear between the `\fB%\fP\&' and the next character of the +sequence\&. More complicated escape sequences are available to provide +conditional expansion\&. +.PP +.SH "SIMPLE PROMPT ESCAPES" +.PP +.SS "Special characters" +.PD 0 +.TP +.PD +\fB%%\fP +A `\fB%\fP\&'\&. +.TP +\fB%)\fP +A `\fB)\fP\&'\&. +.PP +.SS "Login information" +.PD 0 +.TP +.PD +\fB%l\fP +The line (tty) the user is logged in on, without `\fB/dev/\fP\&' prefix\&. +If the name starts with `\fB/dev/tty\fP\&', that prefix is stripped\&. +.TP +\fB%M\fP +The full machine hostname\&. +.TP +\fB%m\fP +The hostname up to the first `\fB\&.\fP\&'\&. +An integer may follow the `\fB%\fP\&' to specify +how many components of the hostname are desired\&. With a negative integer, +trailing components of the hostname are shown\&. +.TP +\fB%n\fP +\fB$USERNAME\fP\&. +.TP +\fB%y\fP +The line (tty) the user is logged in on, without `\fB/dev/\fP\&' prefix\&. +This does not treat `\fB/dev/tty\fP\&' names specially\&. +.PP +.SS "Shell state" +.PD 0 +.TP +.PD +\fB%#\fP +A `\fB#\fP\&' if the shell is running with privileges, a `\fB%\fP' if not\&. +Equivalent to `\fB%(!\&.#\&.%%)\fP\&'\&. +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\&. +.TP +\fB%?\fP +The return status of the last command executed just before the prompt\&. +.TP +\fB%_\fP +The status of the parser, i\&.e\&. the shell constructs (like `\fBif\fP\&' and +`\fBfor\fP\&') 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 \fBPS2\fP for +continuation lines and \fBPS4\fP for debugging with the \fBXTRACE\fP option; in +the latter case it will also work non\-interactively\&. +.TP +\fB%^\fP +The status of the parser in reverse\&. This is the same as `\fB%_\fP\&' other than +the order of strings\&. It is often used in \fBRPS2\fP\&. +.TP +.PD 0 +\fB%d\fP +.TP +.PD +\fB%/\fP +Current working directory\&. If an integer follows the `\fB%\fP\&', +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\&. \fB%\-1d\fP specifies the first component\&. +.TP +\fB%~\fP +As \fB%d\fP and \fB%/\fP, but if the current working directory starts with +\fB$HOME\fP, that part is replaced by a `\fB~\fP\&'\&. Furthermore, if it has a named +directory as its prefix, that part is replaced by a `\fB~\fP\&' followed by +the name of the directory, but only if the result is shorter than +the full path; +see \fIDynamic\fP and \fIStatic named directories\fP in \fIzshexpn\fP(1)\&. +.TP +\fB%e\fP +Evaluation depth of the current sourced file, shell function, or \fBeval\fP\&. +This is incremented or decremented every time the value of \fB%N\fP is +set or reverted to a previous value, respectively\&. This is most useful +for debugging as part of \fB$PS4\fP\&. +.TP +.PD 0 +\fB%h\fP +.TP +.PD +\fB%!\fP +Current history event number\&. +.TP +\fB%i\fP +The line number currently being executed in the script, sourced file, or +shell function given by \fB%N\fP\&. This is most useful for debugging as part +of \fB$PS4\fP\&. +.TP +\fB%I\fP +The line number currently being executed in the file \fB%x\fP\&. This is +similar to \fB%i\fP, 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\&. +.TP +\fB%j\fP +The number of jobs\&. +.TP +\fB%L\fP +The current value of \fB$SHLVL\fP\&. +.TP +\fB%N\fP +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 \fB$0\fP\&. An integer may follow +the `\fB%\fP\&' to specify a number of trailing path components to show; zero +means the full path\&. A negative integer specifies leading components\&. +.TP +\fB%x\fP +The name of the file containing the source code currently being +executed\&. This behaves as \fB%N\fP except that function and eval command +names are not shown, instead the file where they were defined\&. +.TP +.PD 0 +\fB%c\fP +.TP +.PD 0 +\fB%\&.\fP +.TP +.PD +\fB%C\fP +Trailing component of the current working directory\&. +An integer may follow the `\fB%\fP\&' to get more than one component\&. +Unless `\fB%C\fP\&' is used, tilde contraction is performed first\&. These are +deprecated as \fB%c\fP and \fB%C\fP are equivalent to \fB%1~\fP and \fB%1/\fP, +respectively, while explicit positive integers have the same effect as for +the latter two sequences\&. +.PP +.SS "Date and time" +.PD 0 +.TP +.PD +\fB%D\fP +The date in \fIyy\fP\fB\-\fP\fImm\fP\fB\-\fP\fIdd\fP format\&. +.TP +\fB%T\fP +Current time of day, in 24\-hour format\&. +.TP +.PD 0 +\fB%t\fP +.TP +.PD +\fB%@\fP +Current time of day, in 12\-hour, am/pm format\&. +.TP +\fB%*\fP +Current time of day in 24\-hour format, with seconds\&. +.TP +\fB%w\fP +The date in \fIday\fP\fB\-\fP\fIdd\fP format\&. +.TP +\fB%W\fP +The date in \fImm\fP\fB/\fP\fIdd\fP\fB/\fP\fIyy\fP format\&. +.TP +\fB%D{\fP\fIstring\fP\fB}\fP +\fIstring\fP is formatted using the \fBstrftime\fP function\&. +See \fIstrftime\fP(3) for more details\&. Various zsh +extensions provide numbers with no leading zero or space +if the number is a single digit: +.RS +.PP +.PD 0 +.TP +\fB%f\fP +a day of the month +.TP +\fB%K\fP +the hour of the day on the 24\-hour clock +.TP +\fB%L\fP +the hour of the day on the 12\-hour clock +.PD +.PP +In addition, if the system supports the POSIX \fBgettimeofday\fP system +call, \fB%\&.\fP 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 \fB%\fP; hence \fB%6\&.\fP +outputs microseconds, and \fB%9\&.\fP outputs nanoseconds\&. (The latter +requires a nanosecond\-precision \fBclock_gettime\fP; systems lacking this +will return a value multiplied by the appropriate power of 10\&.) A typical +example of this is the format `\fB%D{%H:%M:%S\&.%\&.}\fP\&'\&. +.PP +The GNU extension \fB%N\fP is handled as a synonym for \fB%9\&.\fP\&. +.PP +Additionally, the GNU extension that a `\fB\-\fP\&' between the \fB%\fP and the +format character causes a leading zero or space to be stripped +is handled directly by the shell for the format characters \fBd\fP, \fBf\fP, +\fBH\fP, \fBk\fP, \fBl\fP, \fBm\fP, \fBM\fP, \fBS\fP and \fBy\fP; any other format +characters are provided to the system\&'s strftime(3) +with any leading `\fB\-\fP\&' 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\&. +.RE +.PP +.SS "Visual effects" +.PD 0 +.TP +.PD +\fB%B\fP (\fB%b\fP) +Start (stop) boldface mode\&. +.TP +\fB%E\fP +Clear to end of line\&. +.TP +\fB%U\fP (\fB%u\fP) +Start (stop) underline mode\&. +.TP +\fB%S\fP (\fB%s\fP) +Start (stop) standout mode\&. +.TP +\fB%F\fP (\fB%f\fP) +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 \fB%F\fP, for example \fB%F{red}\fP\&. In the latter case +the values allowed are as described for the \fBfg\fP \fBzle_highlight\fP +attribute; +see \fICharacter Highlighting\fP in \fIzshzle\fP(1)\&. This means that numeric +colours are allowed in the second format also\&. +.TP +\fB%K\fP (\fB%k\fP) +Start (stop) using a different bacKground colour\&. The syntax is +identical to that for \fB%F\fP and \fB%f\fP\&. +.TP +\fB%{\fP\&.\&.\&.\fB%}\fP +Include a string as a literal escape sequence\&. +The string within the braces should not change the cursor +position\&. Brace pairs can nest\&. +.RS +.PP +A positive numeric argument between the \fB%\fP and the \fB{\fP is treated as +described for \fB%G\fP below\&. +.RE +.TP +\fB%G\fP +Within a \fB%{\fP\&.\&.\&.\fB%}\fP 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 \fB%{\fP\&.\&.\&.\fB%}\fP +sequence together with the appropriate number of \fB%G\fP sequences to +indicate the correct width\&. An integer between the `\fB%\fP\&' and `\fBG\fP' +indicates a character width other than one\&. Hence \fB%{\fP\fIseq\fP\fB%2G%}\fP +outputs \fIseq\fP and assumes it takes up the width of two standard +characters\&. +.RS +.PP +Multiple uses of \fB%G\fP accumulate in the obvious fashion; the position +of the \fB%G\fP is unimportant\&. Negative integers are not handled\&. +.PP +Note that when prompt truncation is in use it is advisable to divide up +output into single characters within each \fB%{\fP\&.\&.\&.\fB%}\fP group so that +the correct truncation point can be found\&. +.RE +.PP +.SH "CONDITIONAL SUBSTRINGS IN PROMPTS" +.PD 0 +.TP +.PD +\fB%v\fP +The value of the first element of the \fBpsvar\fP array parameter\&. Following +the `\fB%\fP\&' with an integer gives that element of the array\&. Negative +integers count from the end of the array\&. +.TP +\fB%(\fP\fIx\fP\fB\&.\fP\fItrue\-text\fP\fB\&.\fP\fIfalse\-text\fP\fB)\fP +Specifies a ternary expression\&. The character following the \fIx\fP 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 \fItrue\-text\fP, except as part of a +%\-escape +sequence\&. A `\fB)\fP\&' may appear in the \fIfalse\-text\fP as `\fB%)\fP'\&. +\fItrue\-text\fP +and \fIfalse\-text\fP may both contain arbitrarily\-nested escape +sequences, including further ternary expressions\&. +.RS +.PP +The left parenthesis may be preceded or followed by a positive integer \fIn\fP, +which defaults to zero\&. A negative integer will be multiplied by \-1, except +as noted below for `\fBl\fP\&'\&. +The test character \fIx\fP may be any of the following: +.PP +.PD 0 +.TP +\fB!\fP +True if the shell is running with privileges\&. +.TP +\fB#\fP +True if the effective uid of the current process is \fIn\fP\&. +.TP +\fB?\fP +True if the exit status of the last command was \fIn\fP\&. +.TP +\fB_\fP +True if at least \fIn\fP shell constructs were started\&. +.TP +\fBC\fP +.TP +\fB/\fP +True if the current absolute path has at least \fIn\fP elements +relative to the root directory, hence \fB/\fP is counted as 0 elements\&. +.TP +\fBc\fP +.TP +\fB\&.\fP +.TP +\fB~\fP +True if the current path, with prefix replacement, has at +least \fIn\fP elements relative to the root directory, hence \fB/\fP is +counted as 0 elements\&. +.TP +\fBD\fP +True if the month is equal to \fIn\fP (January = 0)\&. +.TP +\fBd\fP +True if the day of the month is equal to \fIn\fP\&. +.TP +\fBe\fP +True if the evaluation depth is at least \fIn\fP\&. +.TP +\fBg\fP +True if the effective gid of the current process is \fIn\fP\&. +.TP +\fBj\fP +True if the number of jobs is at least \fIn\fP\&. +.TP +\fBL\fP +True if the \fBSHLVL\fP parameter is at least \fIn\fP\&. +.TP +\fBl\fP +True if at least \fIn\fP characters have already been +printed on the current line\&. When \fIn\fP is negative, true if at least +\fBabs\fP\fB(\fP\fIn\fP\fB)\fP characters remain before the opposite +margin (thus the left margin for \fBRPROMPT\fP)\&. +.TP +\fBS\fP +True if the \fBSECONDS\fP parameter is at least \fIn\fP\&. +.TP +\fBT\fP +True if the time in hours is equal to \fIn\fP\&. +.TP +\fBt\fP +True if the time in minutes is equal to \fIn\fP\&. +.TP +\fBv\fP +True if the array \fBpsvar\fP has at least \fIn\fP elements\&. +.TP +\fBV\fP +True if element \fIn\fP of the array \fBpsvar\fP is set and +non\-empty\&. +.TP +\fBw\fP +True if the day of the week is equal to \fIn\fP (Sunday = 0)\&. +.PD +.RE +.TP +.PD 0 +\fB%<\fP\fIstring\fP\fB<\fP +.TP +.PD 0 +\fB%>\fP\fIstring\fP\fB>\fP +.TP +.PD +\fB%[\fP\fIxstring\fP\fB]\fP +Specifies truncation behaviour for the remainder of the prompt string\&. +The third, deprecated, form is equivalent to `\fB%\fP\fIxstringx\fP\&', +i\&.e\&. \fIx\fP may be `\fB<\fP\&' or `\fB>\fP'\&. +The \fIstring\fP will be displayed in +place of the truncated portion of any string; note this does not +undergo prompt expansion\&. +.RS +.PP +The numeric argument, which in the third form may appear immediately +after the `\fB[\fP\&', 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 \fIn\fP characters +remain before the right margin (left margin for \fBRPROMPT\fP)\&. +.PP +The forms with `\fB<\fP\&' truncate at the left of the string, +and the forms with `\fB>\fP\&' truncate at the right of the string\&. +For example, if the current directory is `\fB/home/pike\fP\&', +the prompt `\fB%8<\&.\&.<%/\fP\&' will expand to `\fB\&.\&.e/pike\fP'\&. +In this string, the terminating character (`\fB<\fP\&', `\fB>\fP' or `\fB]\fP'), +or in fact any character, may be quoted by a preceding `\fB\e\fP\&'; note +when using \fBprint \-P\fP, however, that this must be doubled as the +string is also subject to standard \fBprint\fP processing, in addition +to any backslashes removed by a double quoted string: the worst case +is therefore `\fBprint \-P "%<\e\e\e\e<<\&.\&.\&."\fP\&'\&. +.PP +If the \fIstring\fP is longer than the specified truncation length, +it will appear in full, completely replacing the truncated string\&. +.PP +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 `\fB%(\fP\&' +construct, or to the next truncation encountered at the same grouping +level (i\&.e\&. truncations inside a `\fB%(\fP\&' are separate), which +ever comes first\&. In particular, a truncation with argument zero +(e\&.g\&., `\fB%<<\fP\&') marks the end of the range of the string to be +truncated while turning off truncation from there on\&. For example, the +prompt `\fB%10<\&.\&.\&.<%~%<<%# \fP\&' will print a truncated representation of the +current directory, followed by a `\fB%\fP\&' or `\fB#\fP', followed by a +space\&. Without the `\fB%<<\fP\&', those two characters would be included +in the string to be truncated\&. Note that `\fB%\-0<<\fP\&' is not equivalent +to `\fB%<<\fP\&' but specifies that the prompt is truncated at the right margin\&. +.PP +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 +`\fB%\-\fP\fIn\fP\fB(l\&.\fP\fItrue\-text\fP\fB\&.\fP\fIfalse\-text\fP\fB)\fP\&' to remove parts +of the prompt when the available space is less than \fIn\fP\&. +.RE diff --git a/Doc/zshmodules.1 b/Doc/zshmodules.1 new file mode 100644 index 000000000..6c167fc8d --- /dev/null +++ b/Doc/zshmodules.1 @@ -0,0 +1,4543 @@ +.TH "ZSHMODULES" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshmodules \- zsh loadable modules +.\" Yodl file: Zsh/modules.yo +.SH "DESCRIPTION" +Some optional parts of zsh are in modules, separate from the core +of the shell\&. Each of these modules may be linked in to the +shell at build time, +or can be dynamically linked while the shell is running +if the installation supports this feature\&. +Modules are linked at runtime with the \fBzmodload\fP command, +see \fIzshbuiltins\fP(1)\&. +.PP +The modules that are bundled with the zsh distribution are: +.PP +.\" Yodl file: Zsh/modlist.yo +.PD 0 +.TP +.PD +\fBzsh/attr\fP +Builtins for manipulating extended attributes (xattr)\&. +.TP +\fBzsh/cap\fP +Builtins for manipulating POSIX\&.1e (POSIX\&.6) capability (privilege) sets\&. +.TP +\fBzsh/clone\fP +A builtin that can clone a running shell onto another terminal\&. +.TP +\fBzsh/compctl\fP +The \fBcompctl\fP builtin for controlling completion\&. +.TP +\fBzsh/complete\fP +The basic completion code\&. +.TP +\fBzsh/complist\fP +Completion listing extensions\&. +.TP +\fBzsh/computil\fP +A module with utility builtins needed for the shell function based +completion system\&. +.TP +\fBzsh/curses\fP +curses windowing commands +.TP +\fBzsh/datetime\fP +Some date/time commands and parameters\&. +.TP +\fBzsh/db/gdbm\fP +Builtins for managing associative array parameters tied to GDBM databases\&. +.TP +\fBzsh/deltochar\fP +A ZLE function duplicating EMACS\&' \fBzap\-to\-char\fP\&. +.TP +\fBzsh/example\fP +An example of how to write a module\&. +.TP +\fBzsh/files\fP +Some basic file manipulation commands as builtins\&. +.TP +\fBzsh/langinfo\fP +Interface to locale information\&. +.TP +\fBzsh/mapfile\fP +Access to external files via a special associative array\&. +.TP +\fBzsh/mathfunc\fP +Standard scientific functions for use in mathematical evaluations\&. +.TP +\fBzsh/nearcolor\fP +Map colours to the nearest colour in the available palette\&. +.TP +\fBzsh/newuser\fP +Arrange for files for new users to be installed\&. +.TP +\fBzsh/parameter\fP +Access to internal hash tables via special associative arrays\&. +.TP +\fBzsh/pcre\fP +Interface to the PCRE library\&. +.TP +\fBzsh/param/private\fP +Builtins for managing private\-scoped parameters in function context\&. +.TP +\fBzsh/regex\fP +Interface to the POSIX regex library\&. +.TP +\fBzsh/sched\fP +A builtin that provides a timed execution facility within the shell\&. +.TP +\fBzsh/net/socket\fP +Manipulation of Unix domain sockets +.TP +\fBzsh/stat\fP +A builtin command interface to the \fBstat\fP system call\&. +.TP +\fBzsh/system\fP +A builtin interface to various low\-level system features\&. +.TP +\fBzsh/net/tcp\fP +Manipulation of TCP sockets +.TP +\fBzsh/termcap\fP +Interface to the termcap database\&. +.TP +\fBzsh/terminfo\fP +Interface to the terminfo database\&. +.TP +\fBzsh/watch\fP +Reporting of login and logout events\&. +.TP +\fBzsh/zftp\fP +A builtin FTP client\&. +.TP +\fBzsh/zle\fP +The Zsh Line Editor, including the \fBbindkey\fP and \fBvared\fP builtins\&. +.TP +\fBzsh/zleparameter\fP +Access to internals of the Zsh Line Editor via parameters\&. +.TP +\fBzsh/zprof\fP +A module allowing profiling for shell functions\&. +.TP +\fBzsh/zpty\fP +A builtin for starting a command in a pseudo\-terminal\&. +.TP +\fBzsh/zselect\fP +Block and return when file descriptors are ready\&. +.TP +\fBzsh/zutil\fP +Some utility builtins, e\&.g\&. the one for supporting configuration via +styles\&. +.\" Yodl file: Zsh/modmenu.yo +.SH "THE ZSH/ATTR MODULE" +.\" Yodl file: Zsh/mod_attr.yo + +The \fBzsh/attr\fP module is used for manipulating extended attributes\&. +The \fB\-h\fP option causes all commands to operate on symbolic links instead +of their targets\&. +The builtins in this module are: +.PP +.PD 0 +.TP +.PD +\fBzgetattr\fP [ \fB\-h\fP ] \fIfilename\fP \fIattribute\fP [ \fIparameter\fP ] +Get the extended attribute \fIattribute\fP from the specified +\fIfilename\fP\&. If the optional argument \fIparameter\fP is given, the +attribute is set on that parameter instead of being printed to stdout\&. +.TP +\fBzsetattr\fP [ \fB\-h\fP ] \fIfilename\fP \fIattribute\fP \fIvalue\fP +Set the extended attribute \fIattribute\fP on the specified +\fIfilename\fP to \fIvalue\fP\&. +.TP +\fBzdelattr\fP [ \fB\-h\fP ] \fIfilename\fP \fIattribute\fP +Remove the extended attribute \fIattribute\fP from the specified +\fIfilename\fP\&. +.TP +\fBzlistattr\fP [ \fB\-h\fP ] \fIfilename\fP [ \fIparameter\fP ] +List the extended attributes currently set on the specified +\fIfilename\fP\&. If the optional argument \fIparameter\fP is given, the +list of attributes is set on that parameter instead of being printed to stdout\&. +.PP +\fBzgetattr\fP and \fBzlistattr\fP allocate memory dynamically\&. If the +attribute or list of attributes grows between the allocation and the call +to get them, they return 2\&. On all other errors, 1 is returned\&. This +allows the calling function to check for this case and retry\&. +.SH "THE ZSH/CAP MODULE" +.\" Yodl file: Zsh/mod_cap.yo + +The \fBzsh/cap\fP module is used for manipulating POSIX\&.1e (POSIX\&.6) capability +sets\&. If the operating system does not support this interface, the +builtins defined by this module will do nothing\&. +The builtins in this module are: +.PP +.PD 0 +.TP +.PD +\fBcap\fP [ \fIcapabilities\fP ] +Change the shell\&'s process capability sets to the specified \fIcapabilities\fP, +otherwise display the shell\&'s current capabilities\&. +.TP +\fBgetcap\fP \fIfilename\fP \&.\&.\&. +This is a built\-in implementation of the POSIX standard utility\&. It displays +the capability sets on each specified \fIfilename\fP\&. +.TP +\fBsetcap\fP \fIcapabilities\fP \fIfilename\fP \&.\&.\&. +This is a built\-in implementation of the POSIX standard utility\&. It sets +the capability sets on each specified \fIfilename\fP to the specified +\fIcapabilities\fP\&. +.SH "THE ZSH/CLONE MODULE" +.\" Yodl file: Zsh/mod_clone.yo + +The \fBzsh/clone\fP module makes available one builtin command: +.PP +.PD 0 +.TP +.PD +\fBclone\fP \fItty\fP +Creates a forked instance of the current shell, attached to the specified +\fItty\fP\&. In the new shell, the \fBPID\fP, \fBPPID\fP and \fBTTY\fP special +parameters are changed appropriately\&. \fB$!\fP is set to zero in the new +shell, and to the new shell\&'s PID in the original shell\&. +.RS +.PP +The return status of the builtin is zero in both shells if successful, +and non\-zero on error\&. +.PP +The target of \fBclone\fP should be an unused terminal, such as an unused virtual +console or a virtual terminal created by +.PP +.RS +.nf +\fBxterm \-e sh \-c \&'trap : INT QUIT TSTP; tty; + while :; do sleep 100000000; done\&'\fP +.fi +.RE +.PP +Some words of explanation are warranted about this long xterm command +line: when doing clone on a pseudo\-terminal, some other session +("session" meant as a unix session group, or SID) is already owning +the terminal\&. Hence the cloned zsh cannot acquire the pseudo\-terminal +as a controlling tty\&. That means two things: +.PP +.PD 0 +.TP +.PD +\(bu +the job control signals will go to the sh\-started\-by\-xterm process +group (that\&'s why we disable INT QUIT and TSTP with trap; otherwise +the while loop could get suspended or killed) +.TP +\(bu +the cloned shell will have job control disabled, and the job +control keys (control\-C, control\-\e and control\-Z) will not work\&. +.PP +This does not apply when cloning to an \fIunused\fP vc\&. +.PP +Cloning to a used (and unprepared) terminal will result in two +processes reading simultaneously from the same terminal, with +input bytes going randomly to either process\&. +.PP +\fBclone\fP is mostly useful as a shell built\-in replacement for +openvt\&. +.RE +.SH "THE ZSH/COMPCTL MODULE" +.\" Yodl file: Zsh/mod_compctl.yo + +The \fBzsh/compctl\fP module makes available two builtin commands\&. \fBcompctl\fP, +is the old, deprecated way to control completions for ZLE\&. See +\fIzshcompctl\fP(1)\&. +The other builtin command, \fBcompcall\fP can be used in user\-defined +completion widgets, see +\fIzshcompwid\fP(1)\&. +.SH "THE ZSH/COMPLETE MODULE" +.\" Yodl file: Zsh/mod_complete.yo + +The \fBzsh/complete\fP module makes available several builtin commands which +can be used in user\-defined completion widgets, see +\fIzshcompwid\fP(1)\&. +.SH "THE ZSH/COMPLIST MODULE" +.\" Yodl file: Zsh/mod_complist.yo + +The \fBzsh/complist\fP module offers three extensions to completion listings: +the ability to highlight matches in such a list, the ability to +scroll through long lists and a different style of menu completion\&. +.PP +.SS "Colored completion listings" +Whenever one of the parameters \fBZLS_COLORS\fP or \fBZLS_COLOURS\fP is set +and the \fBzsh/complist\fP module is loaded or linked into the shell, +completion lists will be colored\&. Note, however, that \fBcomplist\fP will +not automatically be loaded if it is not linked in: on systems with +dynamic loading, `\fBzmodload zsh/complist\fP\&' is required\&. +.PP +The parameters \fBZLS_COLORS\fP and \fBZLS_COLOURS\fP describe how matches +are highlighted\&. To turn on highlighting an empty value suffices, in +which case all the default values given below will be used\&. The format of +the value of these parameters is the same as used by the GNU version of the +\fBls\fP command: a colon\-separated list of specifications of the form +`\fIname\fP\fB=\fP\fIvalue\fP\&'\&. The \fIname\fP may be one of the following strings, +most of which specify file types for which the \fIvalue\fP will be used\&. +The strings and their default values are: +.PP +.PD 0 +.TP +.PD +\fBno 0\fP +for normal text (i\&.e\&. when displaying something other than a matched file) +.TP +\fBfi 0\fP +for regular files +.TP +\fBdi 32\fP +for directories +.TP +\fBln 36\fP +for symbolic links\&. If this has the special value \fBtarget\fP, +symbolic links are dereferenced and the target file used to +determine the display format\&. +.TP +\fBpi 31\fP +for named pipes (FIFOs) +.TP +\fBso 33\fP +for sockets +.TP +\fBbd 44;37\fP +for block devices +.TP +\fBcd 44;37\fP +for character devices +.TP +\fBor\fP \fInone\fP +for a symlink to nonexistent file (default is the value defined for \fBln\fP) +.TP +\fBmi\fP \fInone\fP +for a non\-existent file (default is the value defined for \fBfi\fP); this code +is currently not used +.TP +\fBsu 37;41\fP +for files with setuid bit set +.TP +\fBsg 30;43\fP +for files with setgid bit set +.TP +\fBtw 30;42\fP +for world writable directories with sticky bit set +.TP +\fBow 34;43\fP +for world writable directories without sticky bit set +.TP +\fBsa\fP \fInone\fP +for files with an associated suffix alias; this is only tested +after specific suffixes, as described below +.TP +\fBst 37;44\fP +for directories with sticky bit set but not world writable +.TP +\fBex 35\fP +for executable files +.TP +\fBlc \ee[\fP +for the left code (see below) +.TP +\fBrc m\fP +for the right code +.TP +\fBtc 0\fP +for the character indicating the file type printed after filenames if +the \fBLIST_TYPES\fP option is set +.TP +\fBsp 0\fP +for the spaces printed after matches to align the next column +.TP +\fBec\fP \fInone\fP +for the end code +.PP +Apart from these strings, the \fIname\fP may also be an asterisk +(`\fB*\fP\&') followed by any string\&. The \fIvalue\fP given for such a +string will be used for all files whose name ends with the string\&. +The \fIname\fP may also be an equals sign (`\fB=\fP\&') followed by a +pattern; the \fBEXTENDED_GLOB\fP option will be turned on for evaluation +of the pattern\&. The \fIvalue\fP given for this pattern will be used for all +matches (not just filenames) whose display string are matched by +the pattern\&. Definitions for the form with the leading equal sign take +precedence over the values defined for file types, which in turn take +precedence over the form with the leading asterisk (file extensions)\&. +.PP +The leading\-equals form also allows different parts of the displayed +strings to be colored differently\&. For this, the pattern has to use the +`\fB(#b)\fP\&' globbing flag and pairs of parentheses surrounding the +parts of the strings that are to be colored differently\&. In this case +the \fIvalue\fP may consist of more than one color code separated by +equal signs\&. The first code will be used for all parts for which no +explicit code is specified and the following codes will be used for +the parts matched by the sub\-patterns in parentheses\&. For example, +the specification `\fB=(#b)(?)*(?)=0=3=7\fP\&' will be used for all +matches which are at least two characters long and will use +the code `\fB3\fP\&' for the first character, `\fB7\fP' for the last +character and `\fB0\fP\&' for the rest\&. +.PP +All three forms of \fIname\fP may be preceded by a pattern in +parentheses\&. If this is given, the \fIvalue\fP will be used +only for matches in groups whose names are matched by the pattern +given in the parentheses\&. For example, `\fB(g*)m*=43\fP\&' highlights all +matches beginning with `\fBm\fP\&' in groups whose names begin with +`\fBg\fP\&' using the color code `\fB43\fP'\&. In case of the `\fBlc\fP', +`\fBrc\fP\&', and `\fBec\fP' codes, the group pattern is ignored\&. +.PP +Note also that all patterns are tried in the order in which they +appear in the parameter value until the first one matches which is +then used\&. Patterns may be matched against completions, descriptions +(possibly with spaces appended for padding), or lines consisting of a +completion followed by a description\&. For consistent coloring it may be +necessary to use more than one pattern or a pattern with backreferences\&. +.PP +When printing a match, the code prints the value of \fBlc\fP, the value +for the file\-type or the last matching specification with a `\fB*\fP\&', +the value of \fBrc\fP, the string to display for the match itself, and +then the value of \fBec\fP if that is defined or the values of \fBlc\fP, +\fBno\fP, and \fBrc\fP if \fBec\fP is not defined\&. +.PP +The default values are ISO 6429 (ANSI) compliant and can be used on +vt100 compatible terminals such as \fBxterm\fPs\&. On monochrome terminals +the default values will have no visible effect\&. The \fBcolors\fP +function from the contribution can be used to get associative arrays +containing the codes for ANSI terminals (see +the section `Other Functions\&' in \fIzshcontrib\fP(1))\&. For example, after loading \fBcolors\fP, one could use +`\fB$color[red]\fP\&' to get the code for foreground color red and +`\fB$color[bg\-green]\fP\&' for the code for background color green\&. +.PP +If the completion system invoked by compinit is used, these +parameters should not be set directly because the system controls them +itself\&. Instead, the \fBlist\-colors\fP style should be used (see +the section `Completion System Configuration\&' in \fIzshcompsys\fP(1))\&. +.PP +.SS "Scrolling in completion listings" +To enable scrolling through a completion list, the \fBLISTPROMPT\fP +parameter must be set\&. Its value will be used as the prompt; if it +is the empty string, a default prompt will be used\&. The value may +contain escapes of the form `\fB%x\fP\&'\&. It supports the escapes +`\fB%B\fP\&', `\fB%b\fP', `\fB%S\fP', `\fB%s\fP', `\fB%U\fP', `\fB%u\fP', `\fB%F\fP', +`\fB%f\fP\&', `\fB%K\fP', `\fB%k\fP' and +`\fB%{\fP\fI\&.\&.\&.\fP\fB%}\fP\&' used also in shell prompts as well as three pairs of +additional sequences: a `\fB%l\fP\&' or `\fB%L\fP' is replaced by the number +of the last line shown and the total number of lines in the form +`\fInumber\fP\fB/\fP\fItotal\fP\&'; a `\fB%m\fP' or `\fB%M\fP' is replaced with +the number of the last match shown and the total number of matches; and +`\fB%p\fP\&' or `\fB%P\fP' is replaced with `\fBTop\fP', `\fBBottom\fP' or the +position of the first line shown in percent of the total number of +lines, respectively\&. In each of these cases the form with the uppercase +letter will be replaced with a string of fixed width, padded to the +right with spaces, while the lowercase form will not be padded\&. +.PP +If the parameter \fBLISTPROMPT\fP is set, the completion code will not ask if +the list should be shown\&. Instead it immediately starts displaying the +list, stopping after the first screenful, showing the prompt at the bottom, +waiting for a keypress after temporarily switching to the \fBlistscroll\fP +keymap\&. Some of the zle functions have a special meaning while scrolling +lists: +.PP +.PD 0 +.TP +.PD +\fBsend\-break\fP +stops listing discarding the key pressed +.TP +.PD 0 +\fBaccept\-line\fP, \fBdown\-history\fP, \fBdown\-line\-or\-history\fP +.TP +.PD +\fBdown\-line\-or\-search\fP, \fBvi\-down\-line\-or\-history\fP +scrolls forward one line +.TP +.PD 0 +\fBcomplete\-word\fP, \fBmenu\-complete\fP, \fBexpand\-or\-complete\fP +.TP +.PD +\fBexpand\-or\-complete\-prefix\fP, \fBmenu\-complete\-or\-expand\fP +scrolls forward one screenful +.TP +\fBaccept\-search\fP +stop listing but take no other action +.PP +Every other character stops listing and immediately processes the key +as usual\&. Any key that is not bound in the \fBlistscroll\fP keymap or +that is bound to \fBundefined\-key\fP is looked up in the keymap +currently selected\&. +.PP +As for the \fBZLS_COLORS\fP and \fBZLS_COLOURS\fP parameters, +\fBLISTPROMPT\fP should not be set directly when using the shell +function based completion system\&. Instead, the \fBlist\-prompt\fP style +should be used\&. +.PP +.SS "Menu selection" +The \fBzsh/complist\fP module also offers an alternative style of selecting +matches from a list, called menu selection, which can be used if the +shell is set up to return to the last prompt after showing a +completion list (see the \fBALWAYS_LAST_PROMPT\fP option in +\fIzshoptions\fP(1))\&. +.PP +Menu selection can be invoked directly by +the widget \fBmenu\-select\fP defined by this module\&. This is a standard +ZLE widget that can be bound to a key in the usual way as described +in \fIzshzle\fP(1)\&. +.PP +Alternatively, +the parameter \fBMENUSELECT\fP can be set to an integer, which gives the +minimum number of matches that must be present before menu selection is +automatically turned on\&. This second method requires that menu completion +be started, either directly from a widget such as \fBmenu\-complete\fP, or due +to one of the options \fBMENU_COMPLETE\fP or \fBAUTO_MENU\fP being set\&. If +\fBMENUSELECT\fP is set, but is 0, 1 or empty, menu selection will always be +started during an ambiguous menu completion\&. +.PP +When using the completion system based on shell functions, the +\fBMENUSELECT\fP parameter should not be used (like the \fBZLS_COLORS\fP +and \fBZLS_COLOURS\fP parameters described above)\&. Instead, the \fBmenu\fP +style should be used with the \fBselect=\fP\fI\&.\&.\&.\fP keyword\&. +.PP +After menu selection is started, the matches will be listed\&. If there +are more matches than fit on the screen, only the first screenful is +shown\&. The +matches to insert into the command line can be selected from this +list\&. In the list one match is highlighted using the value for \fBma\fP +from the \fBZLS_COLORS\fP or \fBZLS_COLOURS\fP parameter\&. The default +value for this is `\fB7\fP\&' which forces the selected match to be +highlighted using standout mode on a vt100\-compatible terminal\&. If +neither \fBZLS_COLORS\fP nor \fBZLS_COLOURS\fP is set, the same terminal +control sequence as for the `\fB%S\fP\&' escape in prompts is used\&. +.PP +If there are more matches than fit on the screen and the parameter +\fBMENUPROMPT\fP is set, its value will be shown below the matches\&. It +supports the same escape sequences as \fBLISTPROMPT\fP, but the number +of the match or line shown will be that of the one where the mark is +placed\&. If its value is the empty string, a default prompt will be +used\&. +.PP +The \fBMENUSCROLL\fP parameter can be used to specify how the list is +scrolled\&. If the parameter is unset, this is done line by line, if it +is set to `\fB0\fP\&' (zero), the list will scroll half the number of +lines of the screen\&. If the value is positive, it gives the number of +lines to scroll and if it is negative, the list will be scrolled +the number of lines of the screen minus the (absolute) value\&. +.PP +As for the \fBZLS_COLORS\fP, \fBZLS_COLOURS\fP and \fBLISTPROMPT\fP +parameters, neither \fBMENUPROMPT\fP nor \fBMENUSCROLL\fP should be +set directly when using the shell function based completion +system\&. Instead, the \fBselect\-prompt\fP and \fBselect\-scroll\fP styles +should be used\&. +.PP +The completion code sometimes decides not to show all of the matches +in the list\&. These hidden matches are either matches for which the +completion function which added them explicitly requested that they +not appear in the list (using the \fB\-n\fP option of the \fBcompadd\fP +builtin command) or they are matches which duplicate a string already +in the list (because they differ only in things like prefixes or +suffixes that are not displayed)\&. In the list used for menu selection, +however, even these matches are shown so that it is possible to select +them\&. To highlight such matches the \fBhi\fP and \fBdu\fP capabilities in +the \fBZLS_COLORS\fP and \fBZLS_COLOURS\fP parameters are supported for +hidden matches of the first and second kind, respectively\&. +.PP +Selecting matches is done by moving the mark around using the zle movement +functions\&. When not all matches can be shown on the screen at the same +time, the list will scroll up and down when crossing the top or +bottom line\&. The following zle functions have special meaning during +menu selection\&. Note that the following always +perform the same task within the menu selection map and cannot be +replaced by user defined widgets, nor can the set of functions +be extended: +.PP +.PD 0 +.TP +.PD +\fBaccept\-line\fP, \fBaccept\-search\fP +accept the current match and leave menu selection (but do +not cause the command line to be accepted) +.TP +\fBsend\-break\fP +leaves menu selection and restores the previous contents of the +command line +.TP +\fBredisplay\fP, \fBclear\-screen\fP +execute their normal function without leaving menu selection +.TP +\fBaccept\-and\-hold\fP, \fBaccept\-and\-menu\-complete\fP +accept the currently inserted match and continue selection allowing to +select the next match to insert into the line +.TP +\fBaccept\-and\-infer\-next\-history\fP +accepts the current match and then tries completion with +menu selection again; in the case of files this allows one to select +a directory and immediately attempt to complete files in it; if there +are no matches, a message is shown and one can use \fBundo\fP to go back +to completion on the previous level, every other key leaves menu +selection (including the other zle functions which are otherwise +special during menu selection) +.TP +\fBundo\fP +removes matches inserted during the menu selection by one of the three +functions before +.TP +.PD 0 +\fBdown\-history\fP, \fBdown\-line\-or\-history\fP +.TP +.PD +\fBvi\-down\-line\-or\-history\fP, \fBdown\-line\-or\-search\fP +moves the mark one line down +.TP +.PD 0 +\fBup\-history\fP, \fBup\-line\-or\-history\fP +.TP +.PD +\fBvi\-up\-line\-or\-history\fP, \fBup\-line\-or\-search\fP +moves the mark one line up +.TP +\fBforward\-char\fP, \fBvi\-forward\-char\fP +moves the mark one column right +.TP +\fBbackward\-char\fP, \fBvi\-backward\-char\fP +moves the mark one column left +.TP +.PD 0 +\fBforward\-word\fP, \fBvi\-forward\-word\fP +.TP +.PD +\fBvi\-forward\-word\-end\fP, \fBemacs\-forward\-word\fP +moves the mark one screenful down +.TP +\fBbackward\-word\fP, \fBvi\-backward\-word\fP, \fBemacs\-backward\-word\fP +moves the mark one screenful up +.TP +\fBvi\-forward\-blank\-word\fP, \fBvi\-forward\-blank\-word\-end\fP +moves the mark to the first line of the next group of matches +.TP +\fBvi\-backward\-blank\-word\fP +moves the mark to the last line of the previous group of matches +.TP +\fBbeginning\-of\-history\fP +moves the mark to the first line +.TP +\fBend\-of\-history\fP +moves the mark to the last line +.TP +.PD 0 +\fBbeginning\-of\-buffer\-or\-history\fP, \fBbeginning\-of\-line\fP +.TP +.PD +\fBbeginning\-of\-line\-hist\fP, \fBvi\-beginning\-of\-line\fP +moves the mark to the leftmost column +.TP +.PD 0 +\fBend\-of\-buffer\-or\-history\fP, \fBend\-of\-line\fP +.TP +.PD +\fBend\-of\-line\-hist\fP, \fBvi\-end\-of\-line\fP +moves the mark to the rightmost column +.TP +.PD 0 +\fBcomplete\-word\fP, \fBmenu\-complete\fP, \fBexpand\-or\-complete\fP +.TP +.PD +\fBexpand\-or\-complete\-prefix\fP, \fBmenu\-expand\-or\-complete\fP +moves the mark to the next match +.TP +\fBreverse\-menu\-complete\fP +moves the mark to the previous match +.TP +\fBvi\-insert\fP +this toggles between normal and interactive mode; in interactive mode +the keys bound to \fBself\-insert\fP and \fBself\-insert\-unmeta\fP insert +into the command line as in normal editing mode but without leaving +menu selection; after each character completion is tried again and the +list changes to contain only the new matches; the completion widgets +make the longest unambiguous string be inserted in the command line +and \fBundo\fP and \fBbackward\-delete\-char\fP go back to the previous set +of matches +.TP +.PD 0 +\fBhistory\-incremental\-search\-forward\fP +.TP +.PD +\fBhistory\-incremental\-search\-backward\fP +this starts incremental searches in the list of completions displayed; +in this mode, \fBaccept\-line\fP only leaves incremental search, going +back to the normal menu selection mode +.PP +All movement functions wrap around at the edges; any other zle function not +listed leaves menu selection and executes that function\&. It is possible to +make widgets in the above list do the same by using the form of the widget +with a `\fB\&.\fP\&' in front\&. For example, the widget `\fB\&.accept\-line\fP' has +the effect of leaving menu selection and accepting the entire command line\&. +.PP +During this selection the widget uses the keymap \fBmenuselect\fP\&. Any +key that is not defined in this keymap or that is bound to +\fBundefined\-key\fP is looked up in the keymap currently selected\&. This +is used to ensure that the most important keys used during selection +(namely the cursor keys, return, and TAB) have sensible defaults\&. However, +keys in the \fBmenuselect\fP keymap can be modified directly using the +\fBbindkey\fP builtin command (see +\fIzshmodules\fP(1))\&. For example, to make the return key leave menu selection without +accepting the match currently selected one could call +.PP +.RS +.nf +\fBbindkey \-M menuselect \&'^M' send\-break\fP +.fi +.RE +.PP +after loading the \fBzsh/complist\fP module\&. +.SH "THE ZSH/COMPUTIL MODULE" +.\" Yodl file: Zsh/mod_computil.yo + +The \fBzsh/computil\fP module adds several builtin commands that are used by +some of the completion functions in the completion system based on shell +functions (see +\fIzshcompsys\fP(1) +)\&. Except for \fBcompquote\fP these builtin commands are very +specialised and thus not very interesting when writing your own +completion functions\&. In summary, these builtin commands are: +.PP +.PD 0 +.TP +.PD +\fBcomparguments\fP +This is used by the \fB_arguments\fP function to do the argument and +command line parsing\&. Like \fBcompdescribe\fP it has an option \fB\-i\fP to +do the parsing and initialize some internal state and various options +to access the state information to decide what should be completed\&. +.TP +\fBcompdescribe\fP +This is used by the \fB_describe\fP function to build the displays for +the matches and to get the strings to add as matches with their +options\&. On the first call one of the options \fB\-i\fP or \fB\-I\fP should be +supplied as the first argument\&. In the first case, display strings without +the descriptions will be generated, in the second case, the string used to +separate the matches from their descriptions must be given as the +second argument and the descriptions (if any) will be shown\&. All other +arguments are like the definition arguments to \fB_describe\fP itself\&. +.RS +.PP +Once \fBcompdescribe\fP has been called with either the \fB\-i\fP or the +\fB\-I\fP option, it can be repeatedly called with the \fB\-g\fP option and +the names of four parameters as its arguments\&. This will step through +the different sets of matches and store the value of \fBcompstate[list]\fP +in the first scalar, the options for \fBcompadd\fP in the second array, +the matches in the third array, and the strings to be displayed in the +completion listing in the fourth array\&. The arrays may then be directly +given to \fBcompadd\fP to register the matches with the completion code\&. +.RE +.TP +\fBcompfiles\fP +Used by the \fB_path_files\fP function to optimize complex recursive +filename generation (globbing)\&. It does three things\&. With the +\fB\-p\fP and \fB\-P\fP options it builds the glob patterns to use, +including the paths already handled and trying to optimize the +patterns with respect to the prefix and suffix from the line and the +match specification currently used\&. The \fB\-i\fP option does the +directory tests for the \fBignore\-parents\fP style and the \fB\-r\fP option +tests if a component for some of the matches are equal to the string +on the line and removes all other matches if that is true\&. +.TP +\fBcompgroups\fP +Used by the \fB_tags\fP function to implement the internals of the +\fBgroup\-order\fP style\&. This only takes its arguments as names of +completion groups and creates the groups for it (all six types: sorted +and unsorted, both without removing duplicates, with removing all +duplicates and with removing consecutive duplicates)\&. +.TP +\fBcompquote\fP [ \fB\-p\fP ] \fInames\fP \&.\&.\&. +There may be reasons to write completion functions that have to add +the matches using the \fB\-Q\fP option to \fBcompadd\fP and perform quoting +themselves\&. Instead of interpreting the first character of the +\fBall_quotes\fP key of the \fBcompstate\fP special association and using +the \fBq\fP flag for parameter expansions, one can use this builtin +command\&. The arguments are the names of scalar or array parameters +and the values of these parameters are quoted as needed for the +innermost quoting level\&. If the \fB\-p\fP option is given, quoting is +done as if there is some prefix before the values of the parameters, +so that a leading equal sign will not be quoted\&. +.RS +.PP +The return status is non\-zero in case of an error and zero otherwise\&. +.RE +.TP +.PD 0 +\fBcomptags\fP +.TP +.PD +\fBcomptry\fP +These implement the internals of the tags mechanism\&. +.TP +\fBcompvalues\fP +Like \fBcomparguments\fP, but for the \fB_values\fP function\&. +.SH "THE ZSH/CURSES MODULE" +.\" Yodl file: Zsh/mod_curses.yo + +The \fBzsh/curses\fP module makes available one builtin command and +various parameters\&. +.PP +.SS "Builtin" +.PP +.PD 0 +.TP +.PD 0 +\fBzcurses\fP \fBinit\fP +.TP +.PD 0 +\fBzcurses\fP \fBend\fP +.TP +.PD 0 +\fBzcurses\fP \fBaddwin\fP \fItargetwin\fP \fInlines\fP \fIncols\fP \fIbegin_y\fP \fIbegin_x\fP [ \fIparentwin\fP ] +.TP +.PD 0 +\fBzcurses\fP \fBdelwin\fP \fItargetwin\fP +.TP +.PD 0 +\fBzcurses\fP \fBrefresh\fP [ \fItargetwin\fP \&.\&.\&. ] +.TP +.PD 0 +\fBzcurses\fP \fBtouch\fP \fItargetwin\fP \&.\&.\&. +.TP +.PD 0 +\fBzcurses\fP \fBmove\fP \fItargetwin\fP \fInew_y\fP \fInew_x\fP +.TP +.PD 0 +\fBzcurses\fP \fBclear\fP \fItargetwin\fP [ \fBredraw\fP | \fBeol\fP | \fBbot\fP ] +.TP +.PD 0 +\fBzcurses\fP \fBposition\fP \fItargetwin\fP \fIarray\fP +.TP +.PD 0 +\fBzcurses\fP \fBchar\fP \fItargetwin\fP \fIcharacter\fP +.TP +.PD 0 +\fBzcurses\fP \fBstring\fP \fItargetwin\fP \fIstring\fP +.TP +.PD 0 +\fBzcurses\fP \fBborder\fP \fItargetwin\fP \fIborder\fP +.TP +.PD 0 +\fBzcurses\fP \fBattr\fP \fItargetwin\fP [ [\fB+\fP|\fB\-\fP]\fIattribute\fP | \fIfg_col\fP\fB/\fP\fIbg_col\fP ] [\&.\&.\&.] +.TP +.PD 0 +\fBzcurses\fP \fBbg\fP \fItargetwin\fP [ [\fB+\fP|\fB\-\fP]\fIattribute\fP | \fIfg_col\fP\fB/\fP\fIbg_col\fP | \fB@\fP\fIchar\fP ] [\&.\&.\&.] +.TP +.PD 0 +\fBzcurses\fP \fBscroll\fP \fItargetwin\fP [ \fBon\fP | \fBoff\fP | [\fB+\fP|\fB\-\fP]\fIlines\fP ] +.TP +.PD 0 +\fBzcurses\fP \fBinput\fP \fItargetwin\fP [ \fIparam\fP [ \fIkparam\fP [ \fImparam\fP ] ] ] +.TP +.PD 0 +\fBzcurses\fP \fBmouse\fP [ \fBdelay\fP \fInum\fP | [\fB+\fP|\fB\-\fP]\fBmotion\fP ] +.TP +.PD 0 +\fBzcurses\fP \fBtimeout\fP \fItargetwin\fP \fIintval\fP +.TP +.PD 0 +\fBzcurses\fP \fBquerychar\fP \fItargetwin\fP [ \fIparam\fP ] +.TP +.PD +\fBzcurses\fP \fBresize\fP \fIheight\fP \fIwidth\fP [ \fBendwin\fP | \fBnosave\fP | \fBendwin_nosave\fP ] +Manipulate curses windows\&. All uses of this command should be +bracketed by `\fBzcurses init\fP\&' to initialise use of curses, and +`\fBzcurses end\fP\&' to end it; omitting `\fBzcurses end\fP' can cause +the terminal to be in an unwanted state\&. +.RS +.PP +The subcommand \fBaddwin\fP creates a window with \fInlines\fP lines and +\fIncols\fP columns\&. Its upper left corner will be placed at row +\fIbegin_y\fP and column +\fIbegin_x\fP of the screen\&. \fItargetwin\fP is a string and refers +to the name of a window that is not currently assigned\&. Note +in particular the curses convention that vertical values appear +before horizontal values\&. +.PP +If \fBaddwin\fP is given an existing window as the final argument, the new +window is created as a subwindow of \fIparentwin\fP\&. This differs from an +ordinary new window in that the memory of the window contents is shared +with the parent\&'s memory\&. Subwindows must be deleted before their parent\&. +Note that the coordinates of subwindows are relative to the screen, not +the parent, as with other windows\&. +.PP +Use the subcommand \fBdelwin\fP to delete a window created with +\fBaddwin\fP\&. Note that \fBend\fP does \fInot\fP implicitly delete windows, +and that \fBdelwin\fP does not erase the screen image of the window\&. +.PP +The window corresponding to the full visible screen is called +\fBstdscr\fP; it always exists after `\fBzcurses init\fP\&' and cannot +be delete with \fBdelwin\fP\&. +.PP +The subcommand \fBrefresh\fP will refresh window \fItargetwin\fP; this is +necessary to make any pending changes (such as characters you have +prepared for output with \fBchar\fP) visible on the screen\&. \fBrefresh\fP +without an argument causes the screen to be cleared and redrawn\&. +If multiple windows are given, the screen is updated once at the end\&. +.PP +The subcommand \fBtouch\fP marks the \fItargetwin\fPs listed as changed\&. +This is necessary before \fBrefresh\fPing windows if a window that +was in front of another window (which may be \fBstdscr\fP) is deleted\&. +.PP +The subcommand \fBmove\fP moves the cursor position in \fItargetwin\fP to +new coordinates \fInew_y\fP and \fInew_x\fP\&. Note that the +subcommand \fBstring\fP (but not the subcommand \fBchar\fP) advances the +cursor position over the characters added\&. +.PP +The subcommand \fBclear\fP erases the contents of \fItargetwin\fP\&. One +(and no more than one) of three options may be specified\&. With the +option \fBredraw\fP, in addition the next \fBrefresh\fP of \fItargetwin\fP +will cause the screen to be cleared and repainted\&. With the option +\fBeol\fP, \fItargetwin\fP is only cleared to the end of the current cursor +line\&. With the option +\fBbot\fP, \fItargetwin\fP is cleared to the end of the window, i\&.e +everything to the right and below the cursor is cleared\&. +.PP +The subcommand \fBposition\fP writes various positions associated with +\fItargetwin\fP into the array named \fIarray\fP\&. +These are, in order: +.PD 0 +.TP +\- +The y and x coordinates of the cursor relative to the top left +of \fItargetwin\fP +.TP +\- +The y and x coordinates of the top left of \fItargetwin\fP on the +screen +.TP +\- +The size of \fItargetwin\fP in y and x dimensions\&. +.PD +.PP +Outputting characters and strings are achieved by \fBchar\fP and \fBstring\fP +respectively\&. +.PP +To draw a border around window \fItargetwin\fP, use \fBborder\fP\&. Note +that the border is not subsequently handled specially: in other words, +the border is simply a set of characters output at the edge of the +window\&. Hence it can be overwritten, can scroll off the window, etc\&. +.PP +The subcommand \fBattr\fP will set \fItargetwin\fP\&'s attributes or +foreground/background color pair for any successive character output\&. +Each \fIattribute\fP given on the line may be prepended by a \fB+\fP to set +or a \fB\-\fP to unset that attribute; \fB+\fP is assumed if absent\&. The +attributes supported are \fBblink\fP, \fBbold\fP, \fBdim\fP, \fBreverse\fP, +\fBstandout\fP, and \fBunderline\fP\&. +.PP +Each \fIfg_col\fP\fB/\fP\fIbg_col\fP attribute (to be read as +`\fIfg_col\fP on \fIbg_col\fP\&') sets the foreground and background color +for character output\&. The color \fBdefault\fP is sometimes available +(in particular if the library is ncurses), specifying the foreground +or background color with which the terminal started\&. The color pair +\fBdefault/default\fP is always available\&. To use more than the 8 named +colors (red, green, etc\&.) construct the \fIfg_col\fP\fB/\fP\fIbg_col\fP +pairs where \fIfg_col\fP and \fIbg_col\fP are decimal integers, e\&.g +\fB128/200\fP\&. The maximum color value is 254 if the terminal supports +256 colors\&. +.PP +\fBbg\fP overrides the color and other attributes of all characters in the +window\&. Its usual use is to set the background initially, but it will +overwrite the attributes of any characters at the time when it is called\&. +In addition to the arguments allowed with \fBattr\fP, an argument \fB@\fP\fIchar\fP +specifies a character to be shown in otherwise blank areas of the window\&. +Owing to limitations of curses this cannot be a multibyte character +(use of ASCII characters only is recommended)\&. As the specified set +of attributes override the existing background, turning attributes +off in the arguments is not useful, though this does not cause an error\&. +.PP +The subcommand \fBscroll\fP can be used with \fBon\fP or \fBoff\fP to enabled +or disable scrolling of a window when the cursor would otherwise move +below the window due to typing or output\&. It can also be used with a +positive or negative integer to scroll the window up or down the given +number of lines without changing the current cursor position (which +therefore appears to move in the opposite direction relative to the +window)\&. In the second case, if scrolling is \fBoff\fP it is temporarily +turned \fBon\fP to allow the window to be scrolled\&. +.PP +The subcommand \fBinput\fP reads a single character from the window +without echoing it back\&. If \fIparam\fP is supplied the character is +assigned to the parameter \fIparam\fP, else it is assigned to the +parameter \fBREPLY\fP\&. +.PP +If both \fIparam\fP and \fIkparam\fP are supplied, the key is read in +`keypad\&' mode\&. In this mode special keys such as function keys and +arrow keys return the name of the key in the parameter \fIkparam\fP\&. The +key names are the macros defined in the \fBcurses\&.h\fP or \fBncurses\&.h\fP +with the prefix `\fBKEY_\fP\&' removed; see also the description of the +parameter \fBzcurses_keycodes\fP below\&. Other keys cause a value to be +set in \fIparam\fP as before\&. On a successful return only one of +\fIparam\fP or \fIkparam\fP contains a non\-empty string; the other is set +to an empty string\&. +.PP +If \fImparam\fP is also supplied, \fBinput\fP attempts to handle mouse +input\&. This is only available with the ncurses library; mouse handling +can be detected by checking for the exit status of `\fBzcurses mouse\fP\&' with +no arguments\&. If a mouse +button is clicked (or double\- or triple\-clicked, or pressed or released with +a configurable delay from being clicked) then \fIkparam\fP is set to the string +\fBMOUSE\fP, and \fImparam\fP is set to an array consisting of the +following elements: +.PD 0 +.TP +\- +An identifier to discriminate different input devices; this +is only rarely useful\&. +.TP +\- +The x, y and z coordinates of the mouse click relative to +the full screen, as three elements in that order (i\&.e\&. the y coordinate +is, unusually, after the x coordinate)\&. The z coordinate is only +available for a few unusual input devices and is otherwise set to zero\&. +.TP +\- +Any events that occurred as separate items; usually +there will be just one\&. An event consists of \fBPRESSED\fP, \fBRELEASED\fP, +\fBCLICKED\fP, \fBDOUBLE_CLICKED\fP or \fBTRIPLE_CLICKED\fP followed +immediately (in the same element) by the number of the button\&. +.TP +\- +If the shift key was pressed, the string \fBSHIFT\fP\&. +.TP +\- +If the control key was pressed, the string \fBCTRL\fP\&. +.TP +\- +If the alt key was pressed, the string \fBALT\fP\&. +.PD +.PP +Not all mouse events may be passed through to the terminal window; +most terminal emulators handle some mouse events themselves\&. Note +that the ncurses manual implies that using input both with and +without mouse handling may cause the mouse cursor to appear and +disappear\&. +.PP +The subcommand \fBmouse\fP can be used to configure the use of the mouse\&. +There is no window argument; mouse options are global\&. +`\fBzcurses mouse\fP\&' with no arguments returns status 0 if mouse handling +is possible, else status 1\&. Otherwise, the possible arguments (which +may be combined on the same command line) are as follows\&. +\fBdelay\fP \fInum\fP sets the maximum delay in milliseconds between press and +release events to be considered as a click; the value 0 disables click +resolution, and the default is one sixth of a second\&. \fBmotion\fP proceeded +by an optional `\fB+\fP\&' (the default) or \fB\-\fP turns on or off +reporting of mouse motion in addition to clicks, presses and releases, +which are always reported\&. However, it appears reports for mouse +motion are not currently implemented\&. +.PP +The subcommand \fBtimeout\fP specifies a timeout value for input from +\fItargetwin\fP\&. If \fIintval\fP is negative, `\fBzcurses input\fP\&' waits +indefinitely for a character to be typed; this is the default\&. If +\fIintval\fP is zero, `\fBzcurses input\fP\&' returns immediately; if there +is typeahead it is returned, else no input is done and status 1 is +returned\&. If \fIintval\fP is positive, `\fBzcurses input\fP\&' waits +\fIintval\fP milliseconds for input and if there is none at the end of +that period returns status 1\&. +.PP +The subcommand \fBquerychar\fP queries the character at the current cursor +position\&. The return values are stored in the array named \fIparam\fP if +supplied, else in the array \fBreply\fP\&. The first value is the character +(which may be a multibyte character if the system supports them); the +second is the color pair in the usual \fIfg_col\fP\fB/\fP\fIbg_col\fP +notation, or \fB0\fP if color is not supported\&. Any attributes other than +color that apply to the character, as set with the subcommand \fBattr\fP, +appear as additional elements\&. +.PP +The subcommand \fBresize\fP resizes \fBstdscr\fP and all windows to given +dimensions (windows that stick out from the new dimensions are resized +down)\&. The underlying curses extension (\fBresize_term call\fP) can be +unavailable\&. To verify, zeroes can be used for \fIheight\fP and +\fIwidth\fP\&. If the result of the subcommand is \fB0\fP, resize_term is +available (\fB2\fP otherwise)\&. Tests show that resizing can be normally +accomplished by calling \fBzcurses end\fP and \fBzcurses refresh\fP\&. The +\fBresize\fP subcommand is provided for versatility\&. Multiple system +configurations have been checked and \fBzcurses end\fP and \fBzcurses +refresh\fP are still needed for correct terminal state after resize\&. To +invoke them with \fBresize\fP, use \fIendwin\fP argument\&. Using +\fInosave\fP argument will cause new terminal state to not be saved +internally by \fBzcurses\fP\&. This is also provided for versatility and +should normally be not needed\&. +.RE +.PP +.SS "Parameters" +.PP +.PD 0 +.TP +.PD +\fBZCURSES_COLORS\fP +Readonly integer\&. The maximum number of colors the terminal +supports\&. This value is initialised by the curses library and is not +available until the first time \fBzcurses init\fP is run\&. +.TP +\fBZCURSES_COLOR_PAIRS\fP +Readonly integer\&. The maximum number of color pairs +\fIfg_col\fP\fB/\fP\fIbg_col\fP that may be defined in `\fBzcurses attr\fP\&' +commands; note this limit applies to all color pairs that have been +used whether or not they are currently active\&. This value is initialised +by the curses library and is not available until the first time \fBzcurses +init\fP is run\&. +.TP +\fBzcurses_attrs\fP +Readonly array\&. The attributes supported by \fBzsh/curses\fP; available +as soon as the module is loaded\&. +.TP +\fBzcurses_colors\fP +Readonly array\&. The colors supported by \fBzsh/curses\fP; available +as soon as the module is loaded\&. +.TP +\fBzcurses_keycodes\fP +Readonly array\&. The values that may be returned in the second +parameter supplied to `\fBzcurses input\fP\&' in the order in which they +are defined internally by curses\&. Not all function keys +are listed, only \fBF0\fP; curses reserves space for \fBF0\fP up to \fBF63\fP\&. +.TP +\fBzcurses_windows\fP +Readonly array\&. The current list of windows, i\&.e\&. all windows that +have been created with `\fBzcurses addwin\fP\&' and not removed with +`\fBzcurses delwin\fP\&'\&. +.SH "THE ZSH/DATETIME MODULE" +.\" Yodl file: Zsh/mod_datetime.yo + +The \fBzsh/datetime\fP module makes available one builtin command: +.PP +.PD 0 +.TP +.PD 0 +\fBstrftime\fP [ \fB\-s\fP \fIscalar\fP | \fB\-n\fP ] \fIformat\fP [ \fIepochtime\fP [ \fInanoseconds\fP ] ] +.TP +.PD +\fBstrftime\fP \fB\-r\fP [ \fB\-q\fP ] [ \fB\-s\fP \fIscalar\fP | \fB\-n\fP ] \fIformat\fP \fItimestring\fP +Output the date in the \fIformat\fP specified\&. With no \fIepochtime\fP, the +current system date/time is used; optionally, \fIepochtime\fP may be used to +specify the number of seconds since the epoch, and \fInanoseconds\fP may +additionally be used to specify the number of nanoseconds past the second +(otherwise that number is assumed to be 0)\&. +See \fIstrftime\fP(3) for details\&. The zsh extensions described in +the section EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1) are also available\&. +.RS +.PP +.PD 0 +.TP +.PD +\fB\-n\fP +Suppress printing a newline after the formatted string\&. +.TP +\fB\-q\fP +Run quietly; suppress printing of all error messages described below\&. +Errors for invalid \fIepochtime\fP values are always printed\&. +.TP +\fB\-r\fP +With the option \fB\-r\fP (reverse), use \fIformat\fP to parse the input +string \fItimestring\fP and output the number of seconds since the epoch at +which the time occurred\&. The parsing is implemented by the system +function \fBstrptime\fP; see \fIstrptime\fP(3)\&. This means that zsh +format extensions are not available, but for reverse lookup they are not +required\&. +.RS +.PP +In most implementations of \fBstrftime\fP any timezone in the +\fItimestring\fP is ignored and the local timezone declared by the \fBTZ\fP +environment variable is used; other parameters are set to zero if not +present\&. +.PP +If \fItimestring\fP does not match \fIformat\fP the command returns status 1 +and prints an error message\&. If \fItimestring\fP matches \fIformat\fP but +not all characters in \fItimestring\fP were used, the conversion succeeds +but also prints an error message\&. +.PP +If either of the system functions \fBstrptime\fP or \fBmktime\fP is not +available, status 2 is returned and an error message is printed\&. +.RE +.TP +\fB\-s\fP \fIscalar\fP +Assign the date string (or epoch time in seconds if \fB\-r\fP is given) to +\fIscalar\fP instead of printing it\&. +.PP +Note that depending on the system\&'s declared integral time type, +\fBstrftime\fP may produce incorrect results for epoch times greater than +2147483647 which corresponds to 2038\-01\-19 03:14:07 +0000\&. +.RE +.PP +The \fBzsh/datetime\fP module makes available several parameters; +all are readonly: +.PP +.PD 0 +.TP +.PD +\fBEPOCHREALTIME\fP +A floating point value representing the number of seconds since +the epoch\&. The notional accuracy is to nanoseconds if the +\fBclock_gettime\fP call is available and to microseconds otherwise, +but in practice the range of double precision floating point and +shell scheduling latencies may be significant effects\&. +.TP +\fBEPOCHSECONDS\fP +An integer value representing the number of seconds since the +epoch\&. +.TP +\fBepochtime\fP +An array value containing the number of seconds since the epoch +in the first element and the remainder of the time since the epoch +in nanoseconds in the second element\&. To ensure the two elements +are consistent the array should be copied or otherwise referenced +as a single substitution before the values are used\&. The following +idiom may be used: +.RS +.PP +.RS +.nf +\fBfor secs nsecs in $epochtime; do + \&.\&.\&. +done\fP +.fi +.RE +.PP +.RE +.SH "THE ZSH/DB/GDBM MODULE" +.\" Yodl file: Zsh/mod_db_gdbm.yo + +The \fBzsh/db/gdbm\fP module is used to create "tied" associative arrays +that interface to database files\&. If the GDBM interface is not available, +the builtins defined by this module will report an error\&. This module is +also intended as a prototype for creating additional database interfaces, +so the \fBztie\fP builtin may move to a more generic module in the future\&. +.PP +The builtins in this module are: +.PP +.PD 0 +.TP +.PD +\fBztie \-d db/gdbm \-f\fP \fIfilename\fP [ \fB\-r\fP ] \fIarrayname\fP +Open the GDBM database identified by \fIfilename\fP and, if successful, +create the associative array \fIarrayname\fP linked to the file\&. To create +a local tied array, the parameter must first be declared, so commands +similar to the following would be executed inside a function scope: +.RS +.PP +.RS +.nf +\fBlocal \-A sampledb +ztie \-d db/gdbm \-f sample\&.gdbm sampledb\fP +.fi +.RE +.PP +The \fB\-r\fP option opens the database file for reading only, creating a +parameter with the readonly attribute\&. Without this option, using +`\fBztie\fP\&' on a file for which the user does not have write permission is +an error\&. If writable, the database is opened synchronously so fields +changed in \fIarrayname\fP are immediately written to \fIfilename\fP\&. +.PP +Changes to the file modes \fIfilename\fP after it has been opened do not +alter the state of \fIarrayname\fP, but `\fBtypeset \-r\fP \fIarrayname\fP\&' +works as expected\&. +.RE +.TP +\fBzuntie\fP [ \fB\-u\fP ] \fIarrayname\fP \&.\&.\&. +Close the GDBM database associated with each \fIarrayname\fP and then +unset the parameter\&. The \fB\-u\fP option forces an unset of parameters +made readonly with `\fBztie \-r\fP\&'\&. +.RS +.PP +This happens automatically if the parameter is explicitly unset or its +local scope (function) ends\&. Note that a readonly parameter may not be +explicitly unset, so the only way to unset a global parameter created with +`\fBztie \-r\fP\&' is to use `\fBzuntie \-u\fP'\&. +.RE +.TP +\fBzgdbmpath\fP \fIparametername\fP +Put path to database file assigned to \fIparametername\fP into \fBREPLY\fP +scalar\&. +.TP +\fBzgdbm_tied\fP +Array holding names of all tied parameters\&. +.PP +The fields of an associative array tied to GDBM are neither cached nor +otherwise stored in memory, they are read from or written to the database +on each reference\&. Thus, for example, the values in a readonly array may +be changed by a second writer of the same database file\&. +.SH "THE ZSH/DELTOCHAR MODULE" +.\" Yodl file: Zsh/mod_deltochar.yo + +The \fBzsh/deltochar\fP module makes available two ZLE functions: +.PP +.PD 0 +.TP +.PD +\fBdelete\-to\-char\fP +Read a character from the keyboard, and +delete from the cursor position up to and including the next +(or, with repeat count \fIn\fP, the \fIn\fPth) instance of that character\&. +Negative repeat counts mean delete backwards\&. +.TP +\fBzap\-to\-char\fP +This behaves like \fBdelete\-to\-char\fP, except that the final occurrence of +the character itself is not deleted\&. +.SH "THE ZSH/EXAMPLE MODULE" +.\" Yodl file: Zsh/mod_example.yo + +The \fBzsh/example\fP module makes available one builtin command: +.PP +.PD 0 +.TP +.PD +\fBexample\fP [ \fB\-flags\fP ] [ \fIargs\fP \&.\&.\&. ] +Displays the flags and arguments it is invoked with\&. +.PP +The purpose of the module is to serve as an example of how to write a +module\&. +.SH "THE ZSH/FILES MODULE" +.\" Yodl file: Zsh/mod_files.yo + +The \fBzsh/files\fP module makes available some common commands for file +manipulation as builtins; these commands are probably not needed for +many normal situations but can be useful in emergency recovery +situations with constrained resources\&. The commands do not implement +all features now required by relevant standards committees\&. +.PP +For all commands, a variant beginning \fBzf_\fP is also available and loaded +automatically\&. Using the features capability of zmodload will let you load +only those names you want\&. Note that it\&'s possible to load only the +builtins with zsh\-specific names using the following command: +.PP +.RS +.nf +\fBzmodload \-m \-F zsh/files b:zf_\e*\fP +.fi +.RE +.PP +The commands loaded by default are: +.PP +.PD 0 +.TP +.PD +\fBchgrp\fP [ \fB\-hRs\fP ] \fIgroup\fP \fIfilename\fP \&.\&.\&. +Changes group of files specified\&. This is equivalent to \fBchown\fP with +a \fIuser\-spec\fP argument of `\fB:\fP\fIgroup\fP\&'\&. +.TP +\fBchmod\fP [ \fB\-Rs\fP ] \fImode\fP \fIfilename\fP \&.\&.\&. +Changes mode of files specified\&. +.RS +.PP +The specified \fImode\fP must be in octal\&. +.PP +The \fB\-R\fP option causes \fBchmod\fP to recursively descend into directories, +changing the mode of all files in the directory after +changing the mode of the directory itself\&. +.PP +The \fB\-s\fP option is a zsh extension to \fBchmod\fP functionality\&. It enables +paranoid behaviour, intended to avoid security problems involving +a \fBchmod\fP being tricked into affecting files other than the ones +intended\&. It will refuse to follow symbolic links, so that (for example) +``\fBchmod 600 /tmp/foo/passwd\fP\&'' can't accidentally chmod \fB/etc/passwd\fP +if \fB/tmp/foo\fP happens to be a link to \fB/etc\fP\&. It will also check +where it is after leaving directories, so that a recursive chmod of +a deep directory tree can\&'t end up recursively chmoding \fB/usr\fP as +a result of directories being moved up the tree\&. +.RE +.TP +\fBchown\fP [ \fB\-hRs\fP ] \fIuser\-spec\fP \fIfilename\fP \&.\&.\&. +Changes ownership and group of files specified\&. +.RS +.PP +The \fIuser\-spec\fP can be in four forms: +.PP +.PD 0 +.TP +\fIuser\fP +change owner to \fIuser\fP; do not change group +.TP +\fIuser\fP\fB::\fP +change owner to \fIuser\fP; do not change group +.TP +\fIuser\fP\fB:\fP +change owner to \fIuser\fP; change group to \fIuser\fP\&'s primary group +.TP +\fIuser\fP\fB:\fP\fIgroup\fP +change owner to \fIuser\fP; change group to \fIgroup\fP +.TP +\fB:\fP\fIgroup\fP +do not change owner; change group to \fIgroup\fP +.PD +.PP +In each case, the `\fB:\fP\&' may instead be a `\fB\&.\fP'\&. The rule is that +if there is a `\fB:\fP\&' then the separator is `\fB:\fP', otherwise +if there is a `\fB\&.\fP\&' then the separator is `\fB\&.\fP', otherwise +there is no separator\&. +.PP +Each of \fIuser\fP and \fIgroup\fP may be either a username (or group name, as +appropriate) or a decimal user ID (group ID)\&. Interpretation as a name +takes precedence, if there is an all\-numeric username (or group name)\&. +.PP +If the target is a symbolic link, the \fB\-h\fP option causes \fBchown\fP to set +the ownership of the link instead of its target\&. +.PP +The \fB\-R\fP option causes \fBchown\fP to recursively descend into directories, +changing the ownership of all files in the directory after +changing the ownership of the directory itself\&. +.PP +The \fB\-s\fP option is a zsh extension to \fBchown\fP functionality\&. It enables +paranoid behaviour, intended to avoid security problems involving +a \fBchown\fP being tricked into affecting files other than the ones +intended\&. It will refuse to follow symbolic links, so that (for example) +``\fBchown luser /tmp/foo/passwd\fP\&'' can't accidentally chown \fB/etc/passwd\fP +if \fB/tmp/foo\fP happens to be a link to \fB/etc\fP\&. It will also check +where it is after leaving directories, so that a recursive chown of +a deep directory tree can\&'t end up recursively chowning \fB/usr\fP as +a result of directories being moved up the tree\&. +.RE +.TP +.PD 0 +\fBln\fP [ \fB\-dfhins\fP ] \fIfilename\fP \fIdest\fP +.TP +.PD +\fBln\fP [ \fB\-dfhins\fP ] \fIfilename\fP \&.\&.\&. \fIdir\fP +Creates hard (or, with \fB\-s\fP, symbolic) links\&. In the first form, the +specified \fIdest\fPination is created, as a link to the specified +\fIfilename\fP\&. In the second form, each of the \fIfilename\fPs is +taken in turn, and linked to a pathname in the specified \fIdir\fPectory +that has the same last pathname component\&. +.RS +.PP +Normally, \fBln\fP will not attempt to create hard links to +directories\&. This check can be overridden using the \fB\-d\fP option\&. +Typically only the super\-user can actually succeed in creating +hard links to directories\&. +This does not apply to symbolic links in any case\&. +.PP +By default, existing files cannot be replaced by links\&. +The \fB\-i\fP option causes the user to be queried about replacing +existing files\&. The \fB\-f\fP option causes existing files to be +silently deleted, without querying\&. \fB\-f\fP takes precedence\&. +.PP +The \fB\-h\fP and \fB\-n\fP options are identical and both exist for +compatibility; either one indicates that if the target is a symlink +then it should not be dereferenced\&. +Typically this is used in combination with \fB\-sf\fP so that if an +existing link points to a directory then it will be removed, +instead of followed\&. +If this option is used with multiple filenames and the target +is a symbolic link pointing to a directory then the result is +an error\&. +.RE +.TP +\fBmkdir\fP [ \fB\-p\fP ] [ \fB\-m\fP \fImode\fP ] \fIdir\fP \&.\&.\&. +Creates directories\&. With the \fB\-p\fP option, non\-existing parent +directories are first created if necessary, and there will be +no complaint if the directory already exists\&. +The \fB\-m\fP option can be used to specify (in octal) a set of file permissions +for the created directories, otherwise mode 777 modified by the current +\fBumask\fP (see \fIumask\fP(2)) is used\&. +.TP +.PD 0 +\fBmv\fP [ \fB\-fi\fP ] \fIfilename\fP \fIdest\fP +.TP +.PD +\fBmv\fP [ \fB\-fi\fP ] \fIfilename\fP \&.\&.\&. \fIdir\fP +Moves files\&. In the first form, the specified \fIfilename\fP is moved +to the specified \fIdest\fPination\&. In the second form, each of the +\fIfilename\fPs is +taken in turn, and moved to a pathname in the specified \fIdir\fPectory +that has the same last pathname component\&. +.RS +.PP +By default, the user will be queried before replacing any file +that the user cannot write to, but writable files will be silently +removed\&. +The \fB\-i\fP option causes the user to be queried about replacing +any existing files\&. The \fB\-f\fP option causes any existing files to be +silently deleted, without querying\&. \fB\-f\fP takes precedence\&. +.PP +Note that this \fBmv\fP will not move files across devices\&. +Historical versions of \fBmv\fP, when actual renaming is impossible, +fall back on copying and removing files; if this behaviour is desired, +use \fBcp\fP and \fBrm\fP manually\&. This may change in a future version\&. +.RE +.TP +\fBrm\fP [ \fB\-dfiRrs\fP ] \fIfilename\fP \&.\&.\&. +Removes files and directories specified\&. +.RS +.PP +Normally, \fBrm\fP will not remove directories (except with the \fB\-R\fP or \fB\-r\fP +options)\&. The \fB\-d\fP option causes \fBrm\fP to try removing directories +with \fBunlink\fP (see \fIunlink\fP(2)), the same method used for files\&. +Typically only the super\-user can actually succeed in unlinking +directories in this way\&. +\fB\-d\fP takes precedence over \fB\-R\fP and \fB\-r\fP\&. +.PP +By default, the user will be queried before removing any file +that the user cannot write to, but writable files will be silently +removed\&. +The \fB\-i\fP option causes the user to be queried about removing +any files\&. The \fB\-f\fP option causes files to be +silently deleted, without querying, and suppresses all error indications\&. +\fB\-f\fP takes precedence\&. +.PP +The \fB\-R\fP and \fB\-r\fP options cause \fBrm\fP to recursively descend into +directories, deleting all files in the directory before removing the directory +with the \fBrmdir\fP system call (see \fIrmdir\fP(2))\&. +.PP +The \fB\-s\fP option is a zsh extension to \fBrm\fP functionality\&. It enables +paranoid behaviour, intended to avoid common security problems involving +a root\-run \fBrm\fP being tricked into removing files other than the ones +intended\&. It will refuse to follow symbolic links, so that (for example) +``\fBrm /tmp/foo/passwd\fP\&'' can't accidentally remove \fB/etc/passwd\fP +if \fB/tmp/foo\fP happens to be a link to \fB/etc\fP\&. It will also check +where it is after leaving directories, so that a recursive removal of +a deep directory tree can\&'t end up recursively removing \fB/usr\fP as +a result of directories being moved up the tree\&. +.RE +.TP +\fBrmdir\fP \fIdir\fP \&.\&.\&. +Removes empty directories specified\&. +.TP +\fBsync\fP +Calls the system call of the same name (see \fIsync\fP(2)), which +flushes dirty buffers to disk\&. It might return before the I/O has +actually been completed\&. +.SH "THE ZSH/LANGINFO MODULE" +.\" Yodl file: Zsh/mod_langinfo.yo + +The \fBzsh/langinfo\fP module makes available one parameter: +.PP +.PD 0 +.TP +.PD +\fBlanginfo\fP +An associative array that maps langinfo elements to +their values\&. +.RS +.PP +Your implementation may support a number of the following keys: +.PP +\fBCODESET\fP, +\fBD_T_FMT\fP, +\fBD_FMT\fP, +\fBT_FMT\fP, +\fBRADIXCHAR\fP, +\fBTHOUSEP\fP, +\fBYESEXPR\fP, +\fBNOEXPR\fP, +\fBCRNCYSTR\fP, +\fBABDAY_{1\&.\&.7}\fP, +\fBDAY_{1\&.\&.7}\fP, +\fBABMON_{1\&.\&.12}\fP, +\fBMON_{1\&.\&.12}\fP, +\fBT_FMT_AMPM\fP, +\fBAM_STR\fP, +\fBPM_STR\fP, +\fBERA\fP, +\fBERA_D_FMT\fP, +\fBERA_D_T_FMT\fP, +\fBERA_T_FMT\fP, +\fBALT_DIGITS\fP +.PP +.RE +.SH "THE ZSH/MAPFILE MODULE" +.\" Yodl file: Zsh/mod_mapfile.yo + +The \fBzsh/mapfile\fP module provides one special associative array parameter of +the same name\&. +.PP +.PD 0 +.TP +.PD +\fBmapfile\fP +This associative array takes as keys the names of files; the resulting +value is the content of the file\&. The value is treated identically to any +other text coming from a parameter\&. The value may also be assigned to, in +which case the file in question is written (whether or not it originally +existed); or an element may be unset, which will delete the file in +question\&. For example, `\fBvared \&'mapfile[myfile]'\fP' works as expected, +editing the file `\fBmyfile\fP\&'\&. +.RS +.PP +When the array is accessed as a whole, the keys are the names of files in +the current directory, and the values are empty (to save a huge overhead in +memory)\&. Thus \fB${(k)mapfile}\fP has the same effect as the glob operator +\fB*(D)\fP, since files beginning with a dot are not special\&. Care must be +taken with expressions such as \fBrm ${(k)mapfile}\fP, which will delete +every file in the current directory without the usual `\fBrm *\fP\&' test\&. +.PP +The parameter \fBmapfile\fP may be made read\-only; in that case, files +referenced may not be written or deleted\&. +.PP +A file may conveniently be read into an array as one line per element +with the form +`\fIarray\fP\fB=("${(f@)mapfile[\fP\fIfilename\fP\fB]}")\fP\&'\&. +The double quotes and the `\fB@\fP\&' are necessary to prevent empty lines +from being removed\&. Note that if the file ends with a newline, +the shell will split on the final newline, generating an additional +empty field; this can be suppressed by using +`\fIarray\fP\fB=("${(f@)${mapfile[\fP\fIfilename\fP\fB]%$\&'\en'}}")\fP'\&. +.RE +.PP +.SS "Limitations" +.PP +Although reading and writing of the file in question is efficiently +handled, zsh\&'s internal memory management may be arbitrarily baroque; +however, \fBmapfile\fP is usually very much more efficient than +anything involving a loop\&. Note in particular that +the whole contents of the file will always reside physically in memory when +accessed (possibly multiple times, due to standard parameter substitution +operations)\&. In particular, this means handling of sufficiently long files +(greater than the machine\&'s swap space, or than the range of the pointer +type) will be incorrect\&. +.PP +No errors are printed or flagged for non\-existent, unreadable, or +unwritable files, as the parameter mechanism is too low in the shell +execution hierarchy to make this convenient\&. +.PP +It is unfortunate that the mechanism for loading modules does not yet allow +the user to specify the name of the shell parameter to be given the special +behaviour\&. +.SH "THE ZSH/MATHFUNC MODULE" +.\" Yodl file: Zsh/mod_mathfunc.yo + +The \fBzsh/mathfunc\fP module provides standard +mathematical functions for use when +evaluating mathematical formulae\&. The syntax agrees with normal C and +FORTRAN conventions, for example, +.PP +.RS +.nf +\fB(( f = sin(0\&.3) ))\fP +.fi +.RE +.PP +assigns the sine of 0\&.3 to the parameter f\&. +.PP +Most functions take floating point arguments and return a floating point +value\&. However, any necessary conversions from or to integer type will be +performed automatically by the shell\&. Apart from \fBatan\fP with a second +argument and the \fBabs\fP, \fBint\fP and \fBfloat\fP functions, all functions +behave as noted in the manual page for the corresponding C function, +except that any arguments out of range for the function in question will be +detected by the shell and an error reported\&. +.PP +The following functions take a single floating point argument: \fBacos\fP, +\fBacosh\fP, \fBasin\fP, \fBasinh\fP, \fBatan\fP, \fBatanh\fP, \fBcbrt\fP, \fBceil\fP, +\fBcos\fP, \fBcosh\fP, \fBerf\fP, \fBerfc\fP, \fBexp\fP, \fBexpm1\fP, \fBfabs\fP, +\fBfloor\fP, \fBgamma\fP, \fBj0\fP, \fBj1\fP, \fBlgamma\fP, \fBlog\fP, \fBlog10\fP, +\fBlog1p\fP, \fBlog2\fP, \fBlogb\fP, \fBsin\fP, \fBsinh\fP, \fBsqrt\fP, \fBtan\fP, +\fBtanh\fP, \fBy0\fP, \fBy1\fP\&. The \fBatan\fP function can optionally take a +second argument, in which case it behaves like the C function \fBatan2\fP\&. +The \fBilogb\fP function takes a single floating point argument, but +returns an integer\&. +.PP +The function \fBsigngam\fP takes no arguments, and returns an integer, which +is the C variable of the same name, as described in \fIgamma\fP(3)\&. Note +that it is therefore only useful immediately after a call to \fBgamma\fP or +\fBlgamma\fP\&. Note also that `\fBsigngam()\fP\&' and `\fBsigngam\fP' are +distinct expressions\&. +.PP +The functions \fBmin\fP, \fBmax\fP, and \fBsum\fP are defined not in this module +but in the \fBzmathfunc\fP autoloadable function, described in +the section `Mathematical Functions\&' in \fIzshcontrib\fP(1)\&. +.PP +The following functions take two floating point arguments: \fBcopysign\fP, +\fBfmod\fP, \fBhypot\fP, \fBnextafter\fP\&. +.PP +The following take an integer first argument and a floating point second +argument: \fBjn\fP, \fByn\fP\&. +.PP +The following take a floating point first argument and an integer second +argument: \fBldexp\fP, \fBscalb\fP\&. +.PP +The function \fBabs\fP does not convert the type of its single argument; it +returns the absolute value of either a floating point number or an +integer\&. The functions \fBfloat\fP and \fBint\fP convert their arguments into +a floating point or integer value (by truncation) respectively\&. +.PP +Note that the C \fBpow\fP function is available in ordinary math evaluation +as the `\fB**\fP\&' operator and is not provided here\&. +.PP +The function \fBrand48\fP is available if your system\&'s mathematical library +has the function \fBerand48(3)\fP\&. It returns a pseudo\-random floating point +number between 0 and 1\&. It takes a single string optional argument\&. +.PP +If the argument is not present, the random number seed is initialised by +three calls to the \fBrand(3)\fP function \-\-\- this produces the +same random +numbers as the next three values of \fB$RANDOM\fP\&. +.PP +If the argument is present, it gives the name of a scalar parameter where +the current random number seed will be stored\&. On the first call, the +value must contain at least twelve hexadecimal digits (the remainder of the +string is ignored), or the seed will be initialised in the same manner as +for a call to \fBrand48\fP with no argument\&. Subsequent calls to +\fBrand48\fP(\fIparam\fP) will then maintain the seed in the +parameter \fIparam\fP as a string of twelve hexadecimal digits, with no base +signifier\&. The random number sequences for different parameters are +completely independent, and are also independent from that used by calls to +\fBrand48\fP with no argument\&. +.PP +For example, consider +.PP +.RS +.nf +\fBprint $(( rand48(seed) )) +print $(( rand48() )) +print $(( rand48(seed) ))\fP +.fi +.RE +.PP +Assuming \fB$seed\fP does not exist, it will be initialised by the first +call\&. In the second call, the default seed is initialised; note, however, +that because of the properties of \fBrand()\fP there is a +correlation between +the seeds used for the two initialisations, so for more secure uses, you +should generate your own 12\-byte seed\&. The third call returns to the same +sequence of random numbers used in the first call, unaffected by the +intervening \fBrand48()\fP\&. +.SH "THE ZSH/NEARCOLOR MODULE" +.\" Yodl file: Zsh/mod_nearcolor.yo + +The \fBzsh/nearcolor\fP module replaces colours specified as hex triplets +with the nearest colour in the 88 or 256 colour palettes that are widely +used by terminal emulators\&. By default, 24\-bit true colour escape codes +are generated when colours are specified using hex triplets\&. These are +not supported by all terminals\&. The purpose of this module is to make +it easier to define colour preferences in a form that can work across a +range of terminal emulators\&. +.PP +Aside from the default colour, the ANSI standard for terminal escape +codes provides for eight colours\&. The bright attribute brings this to +sixteen\&. These basic colours are commonly used in terminal applications +due to being widely supported\&. Expanded 88 and 256 colour palettes are +also common and, while the first sixteen colours vary somewhat between +terminals and configurations, these add a generally consistent and +predictable set of colours\&. +.PP +In order to use the \fBzsh/nearcolor\fP module, it only needs to be +loaded\&. Thereafter, whenever a colour is specified using a hex triplet, +it will be compared against each of the available colours and the +closest will be selected\&. The first sixteen colours are never matched in +this process due to being unpredictable\&. +.PP +It isn\&'t possible to reliably detect support for true colour in the +terminal emulator\&. It is therefore recommended to be selective in +loading the \fBzsh/nearcolor\fP module\&. For example, the following +checks the \fBCOLORTERM\fP environment variable: +.PP +.RS +.nf +\fB[[ $COLORTERM = *(24bit|truecolor)* ]] || zmodload zsh/nearcolor\fP +.fi +.RE +.PP +Note that some terminals accept the true color escape codes but map +them internally to a more limited palette in a similar manner to the +\fBzsh/nearcolor\fP module\&. +.SH "THE ZSH/NEWUSER MODULE" +.\" Yodl file: Zsh/mod_newuser.yo + +The \fBzsh/newuser\fP module is loaded at boot if it is +available, the \fBRCS\fP option is set, and the \fBPRIVILEGED\fP option is not +set (all three are true by default)\&. This takes +place immediately after commands in the global \fBzshenv\fP file (typically +\fB/etc/zshenv\fP), if any, have been executed\&. If the module is not +available it is silently ignored by the shell; the module may safely be +removed from \fB$MODULE_PATH\fP by the administrator if it is not required\&. +.PP +On loading, the module tests if any of the start\-up files \fB\&.zshenv\fP, +\fB\&.zprofile\fP, \fB\&.zshrc\fP or \fB\&.zlogin\fP exist in the directory given by +the environment variable \fBZDOTDIR\fP, or the user\&'s home directory if that +is not set\&. The test is not performed and the module halts processing if +the shell was in an emulation mode (i\&.e\&. had been invoked as some other +shell than zsh)\&. +.PP +If none of the start\-up files were found, the module then looks for the +file \fBnewuser\fP first in a sitewide directory, usually the parent +directory of the \fBsite\-functions\fP directory, and if that is not found the +module searches in a version\-specific directory, usually the parent of the +\fBfunctions\fP directory containing version\-specific functions\&. (These +directories can be configured when zsh is built using the +\fB\-\-enable\-site\-scriptdir=\fP\fIdir\fP and \fB\-\-enable\-scriptdir=\fP\fIdir\fP +flags to \fBconfigure\fP, respectively; the defaults are +\fIprefix\fP\fB/share/zsh\fP and \fIprefix\fP\fB/share/zsh/$ZSH_VERSION\fP where +the default \fIprefix\fP is \fB/usr/local\fP\&.) +.PP +If the file \fBnewuser\fP is found, it is then sourced in the same manner as +a start\-up file\&. The file is expected to contain code to install start\-up +files for the user, however any valid shell code will be executed\&. +.PP +The \fBzsh/newuser\fP module is then unconditionally unloaded\&. +.PP +Note that it is possible to achieve exactly the same effect as the +\fBzsh/newuser\fP module by adding code to \fB/etc/zshenv\fP\&. The module +exists simply to allow the shell to make arrangements for new users without +the need for intervention by package maintainers and system administrators\&. +.PP +The script supplied with the module invokes the shell function +\fBzsh\-newuser\-install\fP\&. This may be invoked directly by the user +even if the \fBzsh/newuser\fP module is disabled\&. Note, however, that +if the module is not installed the function will not be installed either\&. +The function is documented in +the section `User Configuration Functions\&' in \fIzshcontrib\fP(1)\&. +.SH "THE ZSH/PARAMETER MODULE" +.\" Yodl file: Zsh/mod_parameter.yo + +The \fBzsh/parameter\fP module gives access to some of the internal hash +tables used by the shell by defining some special parameters\&. +.PP +.PD 0 +.TP +.PD +\fBoptions\fP +The keys for this associative array are the names of the options that +can be set and unset using the \fBsetopt\fP and \fBunsetopt\fP +builtins\&. The value of each key is either the string \fBon\fP if the +option is currently set, or the string \fBoff\fP if the option is unset\&. +Setting a key to one of these strings is like setting or unsetting +the option, respectively\&. Unsetting a key in this array is like +setting it to the value \fBoff\fP\&. +.TP +\fBcommands\fP +This array gives access to the command hash table\&. The keys are the +names of external commands, the values are the pathnames of the files +that would be executed when the command would be invoked\&. Setting a +key in this array defines a new entry in this table in the same way as +with the \fBhash\fP builtin\&. Unsetting a key as in `\fBunset +"commands[foo]"\fP\&' removes the entry for the given key from the command +hash table\&. +.TP +\fBfunctions\fP +This associative array maps names of enabled functions to their +definitions\&. Setting a key in it is like defining a function with the +name given by the key and the body given by the value\&. Unsetting a key +removes the definition for the function named by the key\&. +.TP +\fBdis_functions\fP +Like \fBfunctions\fP but for disabled functions\&. +.TP +\fBfunctions_source\fP +This readonly associative array maps names of enabled functions to the +name of the file containing the source of the function\&. +.RS +.PP +For an autoloaded function that has already been loaded, or marked for +autoload with an absolute path, or that has had its path resolved with +`\fBfunctions \-r\fP\&', this is the file found for autoloading, resolved +to an absolute path\&. +.PP +For a function defined within the body of a script or sourced file, +this is the name of that file\&. In this case, this is the exact path +originally used to that file, which may be a relative path\&. +.PP +For any other function, including any defined at an interactive prompt or +an autoload function whose path has not yet been resolved, this is +the empty string\&. However, the hash element is reported as defined +just so long as the function is present: the keys to this hash are +the same as those to \fB$functions\fP\&. +.RE +.TP +\fBdis_functions_source\fP +Like \fBfunctions_source\fP but for disabled functions\&. +.TP +\fBbuiltins\fP +This associative array gives information about the builtin commands +currently enabled\&. The keys are the names of the builtin commands and +the values are either `\fBundefined\fP\&' for builtin commands that will +automatically be loaded from a module if invoked or `\fBdefined\fP\&' for +builtin commands that are already loaded\&. +.TP +\fBdis_builtins\fP +Like \fBbuiltins\fP but for disabled builtin commands\&. +.TP +\fBreswords\fP +This array contains the enabled reserved words\&. +.TP +\fBdis_reswords\fP +Like \fBreswords\fP but for disabled reserved words\&. +.TP +\fBpatchars\fP +This array contains the enabled pattern characters\&. +.TP +\fBdis_patchars\fP +Like \fBpatchars\fP but for disabled pattern characters\&. +.TP +\fBaliases\fP +This maps the names of the regular aliases currently enabled to their +expansions\&. +.TP +\fBdis_aliases\fP +Like \fBaliases\fP but for disabled regular aliases\&. +.TP +\fBgaliases\fP +Like \fBaliases\fP, but for global aliases\&. +.TP +\fBdis_galiases\fP +Like \fBgaliases\fP but for disabled global aliases\&. +.TP +\fBsaliases\fP +Like \fBraliases\fP, but for suffix aliases\&. +.TP +\fBdis_saliases\fP +Like \fBsaliases\fP but for disabled suffix aliases\&. +.TP +\fBparameters\fP +The keys in this associative array are the names of the parameters +currently defined\&. The values are strings describing the type of the +parameter, in the same format used by the \fBt\fP parameter flag, see +\fIzshexpn\fP(1) +\&. +Setting or unsetting keys in this array is not possible\&. +.TP +\fBmodules\fP +An associative array giving information about modules\&. The keys are the names +of the modules loaded, registered to be autoloaded, or aliased\&. The +value says which state the named module is in and is one of the +strings `\fBloaded\fP\&', `\fBautoloaded\fP', or `\fBalias:\fP\fIname\fP', +where \fIname\fP is the name the module is aliased to\&. +.RS +.PP +Setting or unsetting keys in this array is not possible\&. +.RE +.TP +\fBdirstack\fP +A normal array holding the elements of the directory stack\&. Note that +the output of the \fBdirs\fP builtin command includes one more +directory, the current working directory\&. +.TP +\fBhistory\fP +This associative array maps history event numbers to the full history lines\&. +Although it is presented as an associative array, the array of all values +(\fB${history[@]}\fP) is guaranteed to be returned in order from most recent +to oldest history event, that is, by decreasing history event number\&. +.TP +\fBhistorywords\fP +A special array containing the words stored in the history\&. These also +appear in most to least recent order\&. +.TP +\fBjobdirs\fP +This associative array maps job numbers to the directories from which the +job was started (which may not be the current directory of the job)\&. +.RS +.PP +The keys of the associative arrays are usually valid job numbers, +and these are the values output with, for example, \fB${(k)jobdirs}\fP\&. +Non\-numeric job references may be used when looking up a value; +for example, \fB${jobdirs[%+]}\fP refers to the current job\&. +.PP +See the \fBjobs\fP builtin for how job information is provided in a subshell\&. +.RE +.TP +\fBjobtexts\fP +This associative array maps job numbers to the texts of the command lines +that were used to start the jobs\&. +.RS +.PP +Handling of the keys of the associative array is as described for +\fBjobdirs\fP above\&. +.PP +See the \fBjobs\fP builtin for how job information is provided in a subshell\&. +.RE +.TP +\fBjobstates\fP +This associative array gives information about the states of the jobs +currently known\&. The keys are the job numbers and the values are +strings of the form +`\fIjob\-state\fP\fB:\fP\fImark\fP\fB:\fP\fIpid\fP\fB=\fP\fIstate\fP\&.\&.\&.\&'\&. The +\fIjob\-state\fP gives the state the whole job is currently in, one of +`\fBrunning\fP\&', `\fBsuspended\fP', or `\fBdone\fP'\&. The \fImark\fP is +`\fB+\fP\&' for the current job, `\fB\-\fP' for the previous job and empty +otherwise\&. This is followed by one `\fB:\fP\fIpid\fP\fB=\fP\fIstate\fP\&' for every +process in the job\&. The \fIpid\fPs are, of course, the process IDs and +the \fIstate\fP describes the state of that process\&. +.RS +.PP +Handling of the keys of the associative array is as described for +\fBjobdirs\fP above\&. +.PP +See the \fBjobs\fP builtin for how job information is provided in a subshell\&. +.RE +.TP +\fBnameddirs\fP +This associative array maps the names of named directories to the pathnames +they stand for\&. +.TP +\fBuserdirs\fP +This associative array maps user names to the pathnames of their home +directories\&. +.TP +\fBusergroups\fP +This associative array maps names of system groups of which the current +user is a member to the corresponding group identifiers\&. The contents +are the same as the groups output by the \fBid\fP command\&. +.TP +\fBfuncfiletrace\fP +This array contains the absolute line numbers and corresponding file +names for the point where the current function, sourced file, or (if +\fBEVAL_LINENO\fP is set) \fBeval\fP command was +called\&. The array is of the same length as \fBfuncsourcetrace\fP and +\fBfunctrace\fP, but differs from \fBfuncsourcetrace\fP in that the line and +file are the point of call, not the point of definition, and differs +from \fBfunctrace\fP in that all values are absolute line numbers in +files, rather than relative to the start of a function, if any\&. +.TP +\fBfuncsourcetrace\fP +This array contains the file names and line numbers of the +points where the functions, sourced files, and (if \fBEVAL_LINENO\fP is set) +\fBeval\fP commands currently being executed were +defined\&. The line number is the line where the `\fBfunction\fP \fIname\fP\&' +or `\fIname\fP \fB()\fP\&' started\&. In the case of an autoloaded +function the line number is reported as zero\&. +The format of each element is \fIfilename\fP\fB:\fP\fIlineno\fP\&. +.RS +.PP +For functions autoloaded from a file in native zsh format, where only the +body of the function occurs in the file, or for files that have been +executed by the \fBsource\fP or `\fB\&.\fP\&' builtins, the trace information is +shown as \fIfilename\fP\fB:\fP\fI0\fP, since the entire file is the +definition\&. The source file name is resolved to an absolute path when +the function is loaded or the path to it otherwise resolved\&. +.PP +Most users will be interested in the information in the +\fBfuncfiletrace\fP array instead\&. +.RE +.TP +\fBfuncstack\fP +This array contains the names of the functions, sourced files, +and (if \fBEVAL_LINENO\fP is set) \fBeval\fP commands\&. currently being +executed\&. The first element is the name of the function using the +parameter\&. +.RS +.PP +The standard shell array \fBzsh_eval_context\fP can be used to +determine the type of shell construct being executed at each depth: +note, however, that is in the opposite order, with the most recent +item last, and it is more detailed, for example including an +entry for \fBtoplevel\fP, the main shell code being executed +either interactively or from a script, which is not present +in \fB$funcstack\fP\&. +.RE +.TP +\fBfunctrace\fP +This array contains the names and line numbers of the callers +corresponding to the functions currently being executed\&. +The format of each element is \fIname\fP\fB:\fP\fIlineno\fP\&. +Callers are also shown for sourced files; the caller is the point +where the \fBsource\fP or `\fB\&.\fP\&' command was executed\&. +.SH "THE ZSH/PCRE MODULE" +.\" Yodl file: Zsh/mod_pcre.yo + +The \fBzsh/pcre\fP module makes some commands available as builtins: +.PP +.PD 0 +.TP +.PD +\fBpcre_compile\fP [ \fB\-aimxs\fP ] \fIPCRE\fP +Compiles a perl\-compatible regular expression\&. +.RS +.PP +Option \fB\-a\fP will force the pattern to be anchored\&. +Option \fB\-i\fP will compile a case\-insensitive pattern\&. +Option \fB\-m\fP will compile a multi\-line pattern; that is, +\fB^\fP and \fB$\fP will match newlines within the pattern\&. +Option \fB\-x\fP will compile an extended pattern, wherein +whitespace and \fB#\fP comments are ignored\&. +Option \fB\-s\fP makes the dot metacharacter match all characters, +including those that indicate newline\&. +.RE +.TP +\fBpcre_study\fP +Studies the previously\-compiled PCRE which may result in faster +matching\&. +.TP +\fBpcre_match\fP [ \fB\-v\fP \fIvar\fP ] [ \fB\-a\fP \fIarr\fP ] [ \fB\-n\fP \fIoffset\fP ] [ \fB\-b\fP ] \fIstring\fP +Returns successfully if \fBstring\fP matches the previously\-compiled +PCRE\&. +.RS +.PP +Upon successful match, +if the expression captures substrings within parentheses, +\fBpcre_match\fP will set the array \fBmatch\fP to those +substrings, unless the \fB\-a\fP option is given, in which +case it will set the array \fIarr\fP\&. Similarly, the variable +\fBMATCH\fP will be set to the entire matched portion of the +string, unless the \fB\-v\fP option is given, in which case the variable +\fIvar\fP will be set\&. +No variables are altered if there is no successful match\&. +A \fB\-n\fP option starts searching for a match from the +byte \fIoffset\fP position in \fIstring\fP\&. If the \fB\-b\fP option is given, +the variable \fBZPCRE_OP\fP will be set to an offset pair string, +representing the byte offset positions of the entire matched portion +within the \fIstring\fP\&. For example, a \fBZPCRE_OP\fP set to "32 45" indicates +that the matched portion began on byte offset 32 and ended on byte offset 44\&. +Here, byte offset position 45 is the position directly after the matched +portion\&. Keep in mind that the byte position isn\&'t necessarily the same +as the character position when UTF\-8 characters are involved\&. +Consequently, the byte offset positions are only to be relied on in the +context of using them for subsequent searches on \fIstring\fP, using an offset +position as an argument to the \fB\-n\fP option\&. This is mostly +used to implement the "find all non\-overlapping matches" functionality\&. +.PP +A simple example of "find all non\-overlapping matches": +.PP +.RS +.nf +\fBstring="The following zip codes: 78884 90210 99513" +pcre_compile \-m "\ed{5}" +accum=() +pcre_match \-b \-\- $string +while [[ $? \-eq 0 ]] do + b=($=ZPCRE_OP) + accum+=$MATCH + pcre_match \-b \-n $b[2] \-\- $string +done +print \-l $accum\fP +.fi +.RE +.RE +.PP +The \fBzsh/pcre\fP module makes available the following test condition: +.PP +.PD 0 +.TP +.PD +\fIexpr\fP \fB\-pcre\-match\fP \fIpcre\fP +Matches a string against a perl\-compatible regular expression\&. +.RS +.PP +For example, +.PP +.RS +.nf +\fB[[ "$text" \-pcre\-match ^d+$ ]] && +print text variable contains only "d\&'s"\&.\fP +.fi +.RE +.PP +If the \fBREMATCH_PCRE\fP option is set, the \fB=~\fP operator is equivalent to +\fB\-pcre\-match\fP, and the \fBNO_CASE_MATCH\fP option may be used\&. Note that +\fBNO_CASE_MATCH\fP never applies to the \fBpcre_match\fP builtin, instead use +the \fB\-i\fP switch of \fBpcre_compile\fP\&. +.RE +.SH "THE ZSH/PARAM/PRIVATE MODULE" +.\" Yodl file: Zsh/mod_private.yo + +The \fBzsh/param/private\fP module is used to create parameters whose scope +is limited to the current function body, and \fInot\fP to other functions +called by the current function\&. +.PP +This module provides a single autoloaded builtin: + +.PD 0 +.TP +.PD +\fBprivate\fP [ {\fB+\fP|\fB\-\fP}\fBAHUahlmrtux\fP ] [ {\fB+\fP|\fB\-\fP}\fBEFLRZi\fP [ \fIn\fP ] ] [ \fIname\fP[\fB=\fP\fIvalue\fP] \&.\&.\&. ] +The \fBprivate\fP builtin accepts all the same options and arguments as \fBlocal\fP +(\fIzshbuiltins\fP(1)) except +for the `\fB\-\fP\fBT\fP\&' option\&. Tied parameters may not be made private\&. +.RS +.PP +The `\fB\-\fP\fBp\fP\&' option is presently a no\-op because the state of +private parameters cannot reliably be reloaded\&. This also applies +to printing private parameters with `\fBtypeset \-p\fP\&'\&. +.PP +If used at the top level (outside a function scope), \fBprivate\fP creates a +normal parameter in the same manner as \fBdeclare\fP or \fBtypeset\fP\&. A +warning about this is printed if \fBWARN_CREATE_GLOBAL\fP is set +(\fIzshoptions\fP(1))\&. Used inside a +function scope, \fBprivate\fP creates a local parameter similar to one +declared with \fBlocal\fP, except having special properties noted below\&. +.PP +Special parameters which expose or manipulate internal shell state, such +as \fBARGC\fP, \fBargv\fP, \fBCOLUMNS\fP, \fBLINES\fP, \fBUID\fP, \fBEUID\fP, \fBIFS\fP, +\fBPROMPT\fP, \fBRANDOM\fP, \fBSECONDS\fP, etc\&., cannot be made private unless +the `\fB\-\fP\fBh\fP\&' option is used to hide the special meaning of the +parameter\&. This may change in the future\&. +.RE +.PP +As with other \fBtypeset\fP equivalents, \fBprivate\fP is both a builtin and a +reserved word, so arrays may be assigned with parenthesized word list +\fIname\fP\fB=(\fP\fIvalue\fP\&.\&.\&.\fB)\fP syntax\&. However, the reserved +word `\fBprivate\fP\&' is not available until \fBzsh/param/private\fP is loaded, +so care must be taken with order of execution and parsing for function +definitions which use \fBprivate\fP\&. To compensate for this, the module +also adds the option `\fB\-P\fP\&' to the `\fBlocal\fP' builtin to declare private +parameters\&. +.PP +For example, this construction fails if \fBzsh/param/private\fP has not yet +been loaded when `\fBbad_declaration\fP\&' is defined: +.RS +.nf +\fBbad_declaration() { + zmodload zsh/param/private + private array=( one two three ) +}\fP +.fi +.RE +.PP +This construction works because \fBlocal\fP is already a keyword, and the +module is loaded before the statement is executed: +.RS +.nf +\fBgood_declaration() { + zmodload zsh/param/private + local \-P array=( one two three ) +}\fP +.fi +.RE +.PP +The following is usable in scripts but may have trouble with \fBautoload\fP: +.RS +.nf +\fBzmodload zsh/param/private +iffy_declaration() { + private array=( one two three ) +}\fP +.fi +.RE +.PP +The \fBprivate\fP builtin may always be used with scalar assignments and +for declarations without assignments\&. +.PP +Parameters declared with \fBprivate\fP have the following properties: + +.PD 0 +.TP +.PD +\(bu +Within the function body where it is declared, the parameter +behaves as a local, except as noted above for tied or special parameters\&. +.TP +\(bu +The type of a parameter declared private cannot be changed in the +scope where it was declared, even if the parameter is unset\&. Thus an +array cannot be assigned to a private scalar, etc\&. +.TP +\(bu +Within any other function called by the declaring function, the +private parameter does \fINOT\fP hide other parameters of the same name, so +for example a global parameter of the same name is visible and may be +assigned or unset\&. This includes calls to anonymous functions, although +that may also change in the future\&. However, the private name may not be +created outside the local scope when it was not previously declared\&. +.TP +\(bu +An exported private remains in the environment of inner scopes but +appears unset for the current shell in those scopes\&. Generally, exporting +private parameters should be avoided\&. +.PP +Note that this differs from the static scope defined by compiled languages +derived from C, in that the a new call to the same function creates a new +scope, i\&.e\&., the parameter is still associated with the call stack rather +than with the function definition\&. It differs from ksh `\fBtypeset \-S\fP\&' +because the syntax used to define the function has no bearing on whether +the parameter scope is respected\&. +.SH "THE ZSH/REGEX MODULE" +.\" Yodl file: Zsh/mod_regex.yo + +The \fBzsh/regex\fP module makes available the following test condition: +.PP +.PD 0 +.TP +.PD +\fIexpr\fP \fB\-regex\-match\fP \fIregex\fP +Matches a string against a POSIX extended regular expression\&. +On successful match, +matched portion of the string will normally be placed in the \fBMATCH\fP +variable\&. If there are any capturing parentheses within the regex, then +the \fBmatch\fP array variable will contain those\&. +If the match is not successful, then the variables will not be altered\&. +.RS +.PP +For example, +.PP +.RS +.nf +\fB[[ alphabetical \-regex\-match ^a([^a]+)a([^a]+)a ]] && +print \-l $MATCH X $match\fP +.fi +.RE +.PP +If the option \fBREMATCH_PCRE\fP is not set, then the \fB=~\fP operator will +automatically load this module as needed and will invoke the +\fB\-regex\-match\fP operator\&. +.PP +If \fBBASH_REMATCH\fP is set, then the array \fBBASH_REMATCH\fP will be set +instead of \fBMATCH\fP and \fBmatch\fP\&. +.PP +Note that the \fBzsh/regex\fP module logic relies on the host system\&. The +same \fIexpr\fP and \fIregex\fP pair could produce different results on different +platforms if a \fIregex\fP with non\-standard syntax is given\&. +.PP +For example, no syntax for matching a word boundary is defined in the POSIX +extended regular expression standard\&. GNU \fBlibc\fP and BSD \fBlibc\fP both provide +such syntaxes as extensions (\fB\eb\fP and \fB[[:<:]]\fP/\fB[[:>:]]\fP respectively), +but neither of these syntaxes is supported by both of these implementations\&. +.PP +Refer to the \fIregcomp\fP(3) and \fIre_format\fP(7) manual pages on your +system for locally\-supported syntax\&. +.RE +.SH "THE ZSH/SCHED MODULE" +.\" Yodl file: Zsh/mod_sched.yo + +The \fBzsh/sched\fP module makes available one builtin command and one +parameter\&. +.PP +.PD 0 +.TP +.PD 0 +\fBsched\fP [\fB\-o\fP] [\fB+\fP]\fIhh\fP\fB:\fP\fImm\fP[\fB:\fP\fIss\fP] \fIcommand\fP \&.\&.\&. +.TP +.PD 0 +\fBsched\fP [\fB\-o\fP] [\fB+\fP]\fIseconds\fP \fIcommand\fP \&.\&.\&. +.TP +.PD +\fBsched\fP [ \fB\-\fP\fIitem\fP ] +Make an entry in the scheduled list of commands to execute\&. +The time may be specified in either absolute or relative time, +and either as hours, minutes and (optionally) seconds separated by a +colon, or seconds alone\&. +An absolute number of seconds indicates the time since the epoch +(1970/01/01 00:00); this is useful in combination with the features in +the \fBzsh/datetime\fP module, see +the zsh/datetime module entry in \fIzshmodules\fP(1)\&. +.RS +.PP +With no arguments, prints the list of scheduled commands\&. If the +scheduled command has the \fB\-o\fP flag set, this is shown at the +start of the command\&. +.PP +With the argument `\fB\-\fP\fIitem\fP\&', removes the given item +from the list\&. The numbering of the list is continuous and entries are +in time order, so the numbering can change when entries are added or +deleted\&. +.PP +Commands are executed either immediately before a prompt, or while +the shell\&'s line editor is waiting for input\&. In the latter case +it is useful to be able to produce output that does not interfere +with the line being edited\&. Providing the option \fB\-o\fP causes +the shell to clear the command line before the event and redraw it +afterwards\&. This should be used with any scheduled event that produces +visible output to the terminal; it is not needed, for example, with +output that updates a terminal emulator\&'s title bar\&. +.PP +To effect changes to the editor buffer when an event executes, use the +`\fBzle\fP\&' command with no arguments to test whether the editor is active, +and if it is, then use `\fBzle \fP\fIwidget\fP\&' to access the editor via +the named \fIwidget\fP\&. +.PP +The \fBsched\fP builtin is not made available by default when the shell +starts in a mode emulating another shell\&. It can be made available +with the command `\fBzmodload \-F zsh/sched b:sched\fP\&'\&. +.RE +.PP +.PD 0 +.TP +.PD +\fBzsh_scheduled_events\fP +A readonly array corresponding to the events scheduled by the +\fBsched\fP builtin\&. The indices of the array correspond to the numbers +shown when \fBsched\fP is run with no arguments (provided that the +\fBKSH_ARRAYS\fP option is not set)\&. The value of the array +consists of the scheduled time in seconds since the epoch +(see the section `The zsh/datetime Module\&' for facilities for +using this number), followed by a colon, followed by any options +(which may be empty but will be preceded by a `\fB\-\fP\&' otherwise), +followed by a colon, followed by the command to be executed\&. +.RS +.PP +The \fBsched\fP builtin should be used for manipulating the events\&. Note +that this will have an immediate effect on the contents of the array, +so that indices may become invalid\&. +.RE +.SH "THE ZSH/NET/SOCKET MODULE" +.\" Yodl file: Zsh/mod_socket.yo + +The \fBzsh/net/socket\fP module makes available one builtin command: +.PP +.PD 0 +.TP +.PD +\fBzsocket\fP [ \fB\-altv\fP ] [ \fB\-d\fP \fIfd\fP ] [ \fIargs\fP ] +\fBzsocket\fP is implemented as a builtin to allow full use of shell +command line editing, file I/O, and job control mechanisms\&. +.PP +.SS "Outbound Connections" +.PP +.PD 0 +.TP +.PD +\fBzsocket\fP [ \fB\-v\fP ] [ \fB\-d\fP \fIfd\fP ] \fIfilename\fP +Open a new Unix domain connection to \fIfilename\fP\&. +The shell parameter \fBREPLY\fP will be set to the file descriptor +associated with that connection\&. Currently, only stream connections +are supported\&. +.RS +.PP +If \fB\-d\fP is specified, its argument +will be taken as the target file descriptor for the +connection\&. +.PP +In order to elicit more verbose output, use \fB\-v\fP\&. +.PP +File descriptors can be closed with normal shell syntax when no longer +needed, for example: +.PP +.RS +.nf +\fBexec {REPLY}>&\-\fP +.fi +.RE +.RE +.PP +.SS "Inbound Connections" +.PP +.PD 0 +.TP +.PD +\fBzsocket\fP \fB\-l\fP [ \fB\-v\fP ] [ \fB\-d\fP \fIfd\fP ] \fIfilename\fP +\fBzsocket \-l\fP will open a socket listening on \fIfilename\fP\&. +The shell parameter \fBREPLY\fP will be set to the file descriptor +associated with that listener\&. The file descriptor remains open in subshells +and forked external executables\&. +.RS +.PP +If \fB\-d\fP is specified, its argument +will be taken as the target file descriptor for +the connection\&. +.PP +In order to elicit more verbose output, use \fB\-v\fP\&. +.RE +.TP +\fBzsocket\fP \fB\-a\fP [ \fB\-tv\fP ] [ \fB\-d\fP \fItargetfd\fP ] \fIlistenfd\fP +\fBzsocket \-a\fP will accept an incoming connection +to the socket associated with \fIlistenfd\fP\&. +The shell parameter \fBREPLY\fP will +be set to the file descriptor associated with +the inbound connection\&. The file descriptor remains open in subshells +and forked external executables\&. +.RS +.PP +If \fB\-d\fP is specified, its argument +will be taken as the target file descriptor for the +connection\&. +.PP +If \fB\-t\fP is specified, \fBzsocket\fP will return +if no incoming connection is pending\&. Otherwise +it will wait for one\&. +.PP +In order to elicit more verbose output, use \fB\-v\fP\&. +.RE +.SH "THE ZSH/STAT MODULE" +.\" Yodl file: Zsh/mod_stat.yo + +The \fBzsh/stat\fP module makes available one builtin command under +two possible names: +.PP +.PD 0 + +.TP +.PD 0 +\fBzstat \fP[ \fB\-gnNolLtTrs\fP ] [ \fB\-f\fP \fIfd\fP ] [ \fB\-H\fP \fIhash\fP ] [ \fB\-A\fP \fIarray\fP ] [ \fB\-F\fP \fIfmt\fP ] +.TP +.PD 0 +\fB \fP[ \fB+\fP\fIelement\fP ] [ \fIfile\fP \&.\&.\&. ] +.TP +.PD +\fBstat\fP \fI\&.\&.\&.\fP +The command acts as a front end to the \fBstat\fP system call (see +\fIstat\fP(2))\&. The same command is provided with two names; as +the name \fBstat\fP is often used by an external command it is recommended +that only the \fBzstat\fP form of the command is used\&. This can be +arranged by loading the module with the command `\fBzmodload \-F zsh/stat +b:zstat\fP\&'\&. +.RS +.PP +If the \fBstat\fP call fails, the appropriate system error message +printed and status 1 is returned\&. +The fields of \fBstruct stat\fP give information about +the files provided as arguments to the command\&. In addition to those +available from the \fBstat\fP call, an extra element `\fBlink\fP\&' is provided\&. +These elements are: +.PP +.PD 0 +.TP +.PD +\fBdevice\fP +The number of the device on which the file resides\&. +.TP +\fBinode\fP +The unique number of the file on this device (`\fIinode\fP\&' number)\&. +.TP +\fBmode\fP +The mode of the file; that is, the file\&'s type and access permissions\&. +With the \fB\-s\fP option, this will +be returned as a string corresponding to the first column in the +display of the \fBls \-l\fP command\&. +.TP +\fBnlink\fP +The number of hard links to the file\&. +.TP +\fBuid\fP +The user ID of the owner of the file\&. With the \fB\-s\fP +option, this is displayed as a user name\&. +.TP +\fBgid\fP +The group ID of the file\&. With the \fB\-s\fP option, this +is displayed as a group name\&. +.TP +\fBrdev\fP +The raw device number\&. This is only useful for special devices\&. +.TP +\fBsize\fP +The size of the file in bytes\&. +.TP +.PD 0 +\fBatime\fP +.TP +.PD 0 +\fBmtime\fP +.TP +.PD +\fBctime\fP +The last access, modification and inode change times +of the file, respectively, as the number of seconds since +midnight GMT on 1st January, 1970\&. With the \fB\-s\fP option, +these are printed as strings for the local time zone; the format +can be altered with the \fB\-F\fP option, and with the \fB\-g\fP +option the times are in GMT\&. +.TP +\fBblksize\fP +The number of bytes in one allocation block on the +device on which the file resides\&. +.TP +\fBblock\fP +The number of disk blocks used by the file\&. +.TP +\fBlink\fP +If the file is a link and the \fB\-L\fP option is in +effect, this contains the name of the file linked to, otherwise +it is empty\&. Note that if this element is selected (``\fBzstat +link\fP\&'') +then the \fB\-L\fP option is automatically used\&. +.PP +A particular element may be selected by including its name +preceded by a `\fB+\fP\&' in the option list; only one element is allowed\&. +The element may be shortened to any unique set of leading +characters\&. Otherwise, all elements will be shown for all files\&. +.PP +Options: +.PP +.PD 0 +.TP +.PD +\fB\-A\fP \fIarray\fP +Instead of displaying the results on standard +output, assign them to an \fIarray\fP, one \fBstruct stat\fP element per array +element for each file in order\&. In this case neither the name +of the element nor the name of the files appears in \fIarray\fP unless the +\fB\-t\fP or \fB\-n\fP options were given, respectively\&. If \fB\-t\fP is given, +the element name appears as a prefix to the +appropriate array element; if \fB\-n\fP is given, the file name +appears as a separate array element preceding all the others\&. +Other formatting options are respected\&. +.TP +\fB\-H\fP \fIhash\fP +Similar to \fB\-A\fP, but instead assign the values to \fIhash\fP\&. The keys +are the elements listed above\&. If the \fB\-n\fP option is provided then the +name of the file is included in the hash with key \fBname\fP\&. +.TP +\fB\-f\fP \fIfd\fP +Use the file on file descriptor \fIfd\fP instead of +named files; no list of file names is allowed in this case\&. +.TP +\fB\-F\fP \fIfmt\fP +Supplies a \fBstrftime\fP (see \fIstrftime\fP(3)) string for the +formatting of the time elements\&. The format string supports all of the +zsh extensions described in +the section EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)\&. +In particular, \fB\-F %s\&.%N\fP can be used to show timestamps with nanosecond +precision if supported by the system\&. +The \fB\-s\fP option is implied\&. +.TP +\fB\-g\fP +Show the time elements in the GMT time zone\&. The +\fB\-s\fP option is implied\&. +.TP +\fB\-l\fP +List the names of the type elements (to standard +output or an array as appropriate) and return immediately; +arguments, and options other than \fB\-A\fP, are ignored\&. +.TP +\fB\-L\fP +Perform an \fBlstat\fP (see \fIlstat\fP(2)) rather than a \fBstat\fP +system call\&. In this case, if the file is a link, information +about the link itself rather than the target file is returned\&. +This option is required to make the \fBlink\fP element useful\&. +It\&'s important to note that this is the exact opposite from \fIls\fP(1), +etc\&. +.TP +\fB\-n\fP +Always show the names of files\&. Usually these are +only shown when output is to standard output and there is more +than one file in the list\&. +.TP +\fB\-N\fP +Never show the names of files\&. +.TP +\fB\-o\fP +If a raw file mode is printed, show it in octal, which is more useful for +human consumption than the default of decimal\&. A leading zero will be +printed in this case\&. Note that this does not affect whether a raw or +formatted file mode is shown, which is controlled by the \fB\-r\fP and \fB\-s\fP +options, nor whether a mode is shown at all\&. +.TP +\fB\-r\fP +Print raw data (the default format) alongside string +data (the \fB\-s\fP format); the string data appears in parentheses +after the raw data\&. +.TP +\fB\-s\fP +Print \fBmode\fP, \fBuid\fP, \fBgid\fP and the three time +elements as strings instead of numbers\&. In each case the format +is like that of \fBls \-l\fP\&. +.TP +\fB\-t\fP +Always show the type names for the elements of +\fBstruct stat\fP\&. Usually these are only shown when output is to +standard output and no individual element has been selected\&. +.TP +\fB\-T\fP +Never show the type names of the \fBstruct stat\fP elements\&. +.RE +.SH "THE ZSH/SYSTEM MODULE" +.\" Yodl file: Zsh/mod_system.yo + +The \fBzsh/system\fP module makes available various builtin commands and +parameters\&. +.PP +.SS "Builtins" +.PP +.PD 0 +.TP +.PD +\fBsyserror\fP [ \fB\-e\fP \fIerrvar\fP ] [ \fB\-p\fP \fIprefix\fP ] [ \fIerrno\fP | \fIerrname\fP ] +This command prints out the error message associated with \fIerrno\fP, a +system error number, followed by a newline to standard error\&. +.RS +.PP +Instead of the error number, a name \fIerrname\fP, for example +\fBENOENT\fP, may be used\&. The set of names is the same as the contents +of the array \fBerrnos\fP, see below\&. +.PP +If the string \fIprefix\fP is given, it is printed in front of the error +message, with no intervening space\&. +.PP +If \fIerrvar\fP is supplied, the entire message, without a newline, is +assigned to the parameter names \fIerrvar\fP and nothing is output\&. +.PP +A return status of 0 indicates the message was successfully printed +(although it may not be useful if the error number was out of the +system\&'s range), a return status of 1 indicates an error in the +parameters, and a return status of 2 indicates the error name was +not recognised (no message is printed for this)\&. +.RE + +.TP +.PD 0 +\fBsysopen\fP [ \fB\-arw\fP ] [ \fB\-m\fP \fIpermissions\fP ] [ \fB\-o\fP \fIoptions\fP ] +.TP +.PD +\fB \fP\fB\-u\fP \fIfd\fP \fIfile\fP +This command opens a file\&. The \fB\-r\fP, \fB\-w\fP and \fB\-a\fP flags indicate +whether the file should be opened for reading, writing and appending, +respectively\&. The \fB\-m\fP option allows the initial permissions to use when +creating a file to be specified in octal form\&. The file descriptor is +specified with \fB\-u\fP\&. Either an explicit file descriptor in the range 0 to 9 can +be specified or a variable name can be given to which the file descriptor +number will be assigned\&. +.RS +.PP +The \fB\-o\fP option allows various system specific options to be +specified as a comma\-separated list\&. The following is a list of possible +options\&. Note that, depending on the system, some may not be available\&. +.PD 0 +.TP +.PD +\fBcloexec\fP +mark file to be closed when other programs are executed (else +the file descriptor remains open in subshells and forked external +executables) +.TP +.PD 0 +\fBcreate\fP +.TP +.PD +\fBcreat\fP +create file if it does not exist +.TP +\fBexcl\fP +create file, error if it already exists +.TP +\fBnoatime\fP +suppress updating of the file atime +.TP +\fBnofollow\fP +fail if \fIfile\fP is a symbolic link +.TP +\fBnonblock\fP +the file is opened in nonblocking mode +.TP +\fBsync\fP +request that writes wait until data has been physically written +.TP +.PD 0 +\fBtruncate\fP +.TP +.PD +\fBtrunc\fP +truncate file to size 0 +.PP +To close the file, use one of the following: +.PP +.RS +.nf +\fB\fBexec {\fP\fIfd\fP\fB}<&\-\fP +\fBexec {\fP\fIfd\fP\fB}>&\-\fP\fP +.fi +.RE +.RE + +.TP +.PD 0 +\fBsysread \fP[ \fB\-c\fP \fIcountvar\fP ] [ \fB\-i\fP \fIinfd\fP ] [ \fB\-o\fP \fIoutfd\fP ] +.TP +.PD +\fB \fP[ \fB\-s\fP \fIbufsize\fP ] [ \fB\-t\fP \fItimeout\fP ] [ \fIparam\fP ] +Perform a single system read from file descriptor \fIinfd\fP, or zero if +that is not given\&. The result of the read is stored in \fIparam\fP or +\fBREPLY\fP if that is not given\&. If \fIcountvar\fP is given, the number +of bytes read is assigned to the parameter named by \fIcountvar\fP\&. +.RS +.PP +The maximum number of bytes read is \fIbufsize\fP or 8192 if that is not +given, however the command returns as soon as any number of bytes was +successfully read\&. +.PP +If \fItimeout\fP is given, it specifies a timeout in seconds, which may +be zero to poll the file descriptor\&. This is handled by the \fBpoll\fP +system call if available, otherwise the \fBselect\fP system call if +available\&. +.PP +If \fIoutfd\fP is given, an attempt is made to write all the bytes just +read to the file descriptor \fIoutfd\fP\&. If this fails, because of a +system error other than \fBEINTR\fP or because of an internal zsh error +during an interrupt, the bytes read but not written are stored in the +parameter named by \fIparam\fP if supplied (no default is used in this +case), and the number of bytes read but not written is stored in the +parameter named by \fIcountvar\fP if that is supplied\&. If it was +successful, \fIcountvar\fP contains the full number of bytes transferred, +as usual, and \fIparam\fP is not set\&. +.PP +The error \fBEINTR\fP (interrupted system call) is handled internally so +that shell interrupts are transparent to the caller\&. Any other error +causes a return\&. +.PP +The possible return statuses are +.PD 0 +.TP +.PD +0 +At least one byte of data was successfully read and, if appropriate, +written\&. +.TP +1 +There was an error in the parameters to the command\&. This is the only +error for which a message is printed to standard error\&. +.TP +2 +There was an error on the read, or on polling the input file descriptor +for a timeout\&. The parameter \fBERRNO\fP gives the error\&. +.TP +3 +Data were successfully read, but there was an error writing them +to \fIoutfd\fP\&. The parameter \fBERRNO\fP gives the error\&. +.TP +4 +The attempt to read timed out\&. Note this does not set \fBERRNO\fP as this +is not a system error\&. +.TP +5 +No system error occurred, but zero bytes were read\&. This usually +indicates end of file\&. The parameters are set according to the +usual rules; no write to \fIoutfd\fP is attempted\&. +.RE +.TP +\fBsysseek\fP [ \fB\-u\fP \fIfd\fP ] [ \fB\-w\fP \fBstart\fP|\fBend\fP|\fBcurrent\fP ] \fIoffset\fP +The current file position at which future reads and writes will take place is +adjusted to the specified byte offset\&. The \fIoffset\fP is evaluated as a math +expression\&. The \fB\-u\fP option allows the file descriptor to be specified\&. By +default the offset is specified relative to the start or the file but, with the +\fB\-w\fP option, it is possible to specify that the offset should be relative to +the current position or the end of the file\&. +.TP +\fBsyswrite\fP [ \fB\-c\fP \fIcountvar\fP ] [ \fB\-o\fP \fIoutfd\fP ] \fIdata\fP +The data (a single string of bytes) are written to the file descriptor +\fIoutfd\fP, or 1 if that is not given, using the \fBwrite\fP system call\&. +Multiple write operations may be used if the first does not write all +the data\&. +.RS +.PP +If \fIcountvar\fP is given, the number of byte written is stored in the +parameter named by \fIcountvar\fP; this may not be the full length of +\fIdata\fP if an error occurred\&. +.PP +The error \fBEINTR\fP (interrupted system call) is handled internally by +retrying; otherwise an error causes the command to return\&. For example, +if the file descriptor is set to non\-blocking output, an error +\fBEAGAIN\fP (on some systems, \fBEWOULDBLOCK\fP) may result in the command +returning early\&. +.PP +The return status may be 0 for success, 1 for an error in the parameters +to the command, or 2 for an error on the write; no error message is +printed in the last case, but the parameter \fBERRNO\fP will reflect +the error that occurred\&. +.RE +.TP +.PD 0 +\fBzsystem flock\fP [ \fB\-t\fP \fItimeout\fP ] [ \fB\-i\fP \fIinterval\fP ] [ \fB\-f\fP \fIvar\fP ] [\fB\-er\fP] \fIfile\fP +.TP +.PD +\fBzsystem flock \-u\fP \fIfd_expr\fP +The builtin \fBzsystem\fP\&'s subcommand \fBflock\fP performs advisory file +locking (via the \fIfcntl\fP(2) system call) over the entire contents +of the given file\&. This form of locking requires the processes +accessing the file to cooperate; its most obvious use is between two +instances of the shell itself\&. +.RS +.PP +In the first form the named \fIfile\fP, which must already exist, is +locked by opening a file descriptor to the file and applying a lock to +the file descriptor\&. The lock terminates when the shell process that +created the lock exits; it is therefore often convenient to create file +locks within subshells, since the lock is automatically released when +the subshell exits\&. Note that use of the \fBprint\fP builtin with the +\fB\-u\fP option will, as a side effect, release the lock, as will redirection +to the file in the shell holding the lock\&. To work around this use a +subshell, e\&.g\&. `\fB(print message) >> \fP\fIfile\fP\&'\&. Status 0 is +returned if the lock succeeds, else status 1\&. +.PP +In the second form the file descriptor given by the arithmetic +expression \fIfd_expr\fP is closed, releasing a lock\&. The file descriptor +can be queried by using the `\fB\-f\fP \fIvar\fP\&' form during the lock; +on a successful lock, the shell variable \fIvar\fP is set to the file +descriptor used for locking\&. The lock will be released if the +file descriptor is closed by any other means, for example using +`\fBexec {\fP\fIvar\fP\fB}>&\-\fP\&'; however, the form described here performs +a safety check that the file descriptor is in use for file locking\&. +.PP +By default the shell waits indefinitely for the lock to succeed\&. +The option \fB\-t\fP \fItimeout\fP specifies a timeout for the lock in +seconds; fractional seconds are allowed\&. During this period, the +shell will attempt to lock the file every \fIinterval\fP seconds +if the \fB\-i\fP \fIinterval\fP option is given, otherwise once a second\&. +(This \fIinterval\fP is shortened before the last attempt if needed, +so that the shell waits only until the \fItimeout\fP and not longer\&.) +If the attempt times out, status 2 is returned\&. +.PP +(Note: \fItimeout\fP is limited to 2^30\-1 seconds (about 34 years), and +\fIinterval\fP to 0\&.999 * LONG_MAX microseconds (only about 35 minutes +on 32\-bit systems)\&.) +.PP +If the option \fB\-e\fP is given, the file descriptor for the lock is +preserved when the shell uses \fBexec\fP to start a new process; +otherwise it is closed at that point and the lock released\&. +.PP +If the option \fB\-r\fP is given, the lock is only for reading, otherwise +it is for reading and writing\&. The file descriptor is opened +accordingly\&. +.RE +.TP +\fBzsystem supports\fP \fIsubcommand\fP +The builtin \fBzsystem\fP\&'s subcommand \fBsupports\fP tests whether a +given subcommand is supported\&. It returns status 0 if so, else +status 1\&. It operates silently unless there was a syntax error +(i\&.e\&. the wrong number of arguments), in which case status 255 +is returned\&. Status 1 can indicate one of two things: \fIsubcommand\fP +is known but not supported by the current operating system, or +\fIsubcommand\fP is not known (possibly because this is an older +version of the shell before it was implemented)\&. +.PP +.SS "Math Functions" +.PP +.PD 0 +.TP +.PD +\fBsystell(\fIfd\fP)\fP +The systell math function returns the current file position for the file +descriptor passed as an argument\&. +.PP +.SS "Parameters" +.PP +.PD 0 +.TP +.PD +\fBerrnos\fP +A readonly array of the names of errors defined on the system\&. These +are typically macros defined in C by including the system header file +\fBerrno\&.h\fP\&. The index of each name (assuming the option \fBKSH_ARRAYS\fP +is unset) corresponds to the error number\&. Error numbers \fInum\fP +before the last known error which have no name are given the name +\fBE\fP\fInum\fP in the array\&. +.RS +.PP +Note that aliases for errors are not handled; only the canonical name is +used\&. +.RE +.TP +\fBsysparams\fP +A readonly associative array\&. The keys are: +.RS +.PP +.PD 0 +.TP +.PD +\fBpid\fP +Returns the process ID of the current process, even in subshells\&. Compare +\fB$$\fP, which returns the process ID of the main shell process\&. +.TP +\fBppid\fP +Returns the current process ID of the parent of the current process, even +in subshells\&. Compare \fB$PPID\fP, which returns the process ID of the +initial parent of the main shell process\&. +.TP +\fBprocsubstpid\fP +Returns the process ID of the last process started for process +substitution, i\&.e\&. the \fB<(\fP\fI\&.\&.\&.\fP\fB)\fP and +\fB>(\fP\fI\&.\&.\&.\fP\fB)\fP expansions\&. +.RE +.SH "THE ZSH/NET/TCP MODULE" +.\" Yodl file: Zsh/mod_tcp.yo + +The \fBzsh/net/tcp\fP module makes available one builtin command: +.PP +.PD 0 +.TP +.PD +\fBztcp\fP [ \fB\-acflLtv\fP ] [ \fB\-d\fP \fIfd\fP ] [ \fIargs\fP ] +\fBztcp\fP is implemented as a builtin to allow full use of shell +command line editing, file I/O, and job control mechanisms\&. +.RS +.PP +If \fBztcp\fP is run with no options, it will output +the contents of its session table\&. +.PP +If it is run with only the option \fB\-L\fP, it will output the contents of +the session table in a format suitable for automatic parsing\&. The option +is ignored if given with a command to open or close a session\&. The output +consists of a set of lines, one per session, each containing the following +elements separated by spaces: +.PP +.PD 0 +.TP +.PD +File descriptor +The file descriptor in use for the connection\&. For normal inbound (\fBI\fP) +and outbound (\fBO\fP) connections this may be read and written by the usual +shell mechanisms\&. However, it should only be close with `\fBztcp \-c\fP\&'\&. +.TP +Connection type +A letter indicating how the session was created: +.RS +.PP +.PD 0 +.TP +.PD +\fBZ\fP +A session created with the \fBzftp\fP command\&. +.TP +\fBL\fP +A connection opened for listening with `\fBztcp \-l\fP\&'\&. +.TP +\fBI\fP +An inbound connection accepted with `\fBztcp \-a\fP\&'\&. +.TP +\fBO\fP +An outbound connection created with `\fBztcp\fP \fIhost\fP \fI\&.\&.\&.\fP\&'\&. +.PP +.RE +.TP +The local host +This is usually set to an all\-zero IP address as the address of the +localhost is irrelevant\&. +.TP +The local port +This is likely to be zero unless the connection is for listening\&. +.TP +The remote host +This is the fully qualified domain name of the peer, if available, else an +IP address\&. It is an all\-zero IP address for a session opened for +listening\&. +.TP +The remote port +This is zero for a connection opened for listening\&. +.RE +.PP +.SS "Outbound Connections" +.PP +.PD 0 +.TP +.PD +\fBztcp\fP [ \fB\-v\fP ] [ \fB\-d\fP \fIfd\fP ] \fIhost\fP [ \fIport\fP ] +Open a new TCP connection to \fIhost\fP\&. If the \fIport\fP is +omitted, it will default to port 23\&. The connection will +be added to the session table and the shell parameter +\fBREPLY\fP will be set to the file descriptor associated +with that connection\&. +.RS +.PP +If \fB\-d\fP is specified, its argument will be taken as the target file +descriptor for the connection\&. +.PP +In order to elicit more verbose output, use \fB\-v\fP\&. +.RE +.PP +.SS "Inbound Connections" +.PP +.PD 0 +.TP +.PD +\fBztcp\fP \fB\-l\fP [ \fB\-v\fP ] [ \fB\-d\fP \fIfd\fP ] \fIport\fP +\fBztcp \-l\fP will open a socket listening on TCP +\fIport\fP\&. The socket will be added to the +session table and the shell parameter \fBREPLY\fP +will be set to the file descriptor associated +with that listener\&. +.RS +.PP +If \fB\-d\fP is specified, its argument will be taken as the target file +descriptor for the connection\&. +.PP +In order to elicit more verbose output, use \fB\-v\fP\&. +.RE +.TP +\fBztcp\fP \fB\-a\fP [ \fB\-tv\fP ] [ \fB\-d\fP \fItargetfd\fP ] \fIlistenfd\fP +\fBztcp \-a\fP will accept an incoming connection +to the port associated with \fIlistenfd\fP\&. +The connection will be added to the session +table and the shell parameter \fBREPLY\fP will +be set to the file descriptor associated with +the inbound connection\&. +.RS +.PP +If \fB\-d\fP is specified, its argument +will be taken as the target file descriptor for the +connection\&. +.PP +If \fB\-t\fP is specified, \fBztcp\fP will return +if no incoming connection is pending\&. Otherwise +it will wait for one\&. +.PP +In order to elicit more verbose output, use \fB\-v\fP\&. +.RE +.PP +.SS "Closing Connections" +.PP +.PD 0 +.TP +.PD 0 +\fBztcp\fP \fB\-cf\fP [ \fB\-v\fP ] [ \fIfd\fP ] +.TP +.PD +\fBztcp\fP \fB\-c\fP [ \fB\-v\fP ] [ \fIfd\fP ] +\fBztcp \-c\fP will close the socket associated +with \fIfd\fP\&. The socket will be removed from the +session table\&. If \fIfd\fP is not specified, +\fBztcp\fP will close everything in the session table\&. +.RS +.PP +Normally, sockets registered by zftp (see +\fIzshmodules\fP(1) +) cannot be closed this way\&. In order +to force such a socket closed, use \fB\-f\fP\&. +.PP +In order to elicit more verbose output, use \fB\-v\fP\&. +.RE +.PP +.SS "Example" +Here is how to create a TCP connection between two instances of zsh\&. We +need to pick an unassigned port; here we use the randomly chosen 5123\&. +.PP +On \fBhost1\fP, +.RS +.nf +\fBzmodload zsh/net/tcp +ztcp \-l 5123 +listenfd=$REPLY +ztcp \-a $listenfd +fd=$REPLY\fP +.fi +.RE +The second from last command blocks until there is an incoming connection\&. +.PP +Now create a connection from \fBhost2\fP (which may, of course, be the same +machine): +.RS +.nf +\fBzmodload zsh/net/tcp +ztcp host1 5123 +fd=$REPLY\fP +.fi +.RE +.PP +Now on each host, \fB$fd\fP contains a file descriptor for talking to the +other\&. For example, on \fBhost1\fP: +.RS +.nf +\fBprint This is a message >&$fd\fP +.fi +.RE +and on \fBhost2\fP: +.RS +.nf +\fBread \-r line <&$fd; print \-r \- $line\fP +.fi +.RE +prints `\fBThis is a message\fP\&'\&. +.PP +To tidy up, on \fBhost1\fP: +.RS +.nf +\fBztcp \-c $listenfd +ztcp \-c $fd\fP +.fi +.RE +and on \fBhost2\fP +.RS +.nf +\fBztcp \-c $fd\fP +.fi +.RE +.SH "THE ZSH/TERMCAP MODULE" +.\" Yodl file: Zsh/mod_termcap.yo + +The \fBzsh/termcap\fP module makes available one builtin command: +.PP +.PD 0 +.TP +.PD +\fBechotc\fP \fIcap\fP [ \fIarg\fP \&.\&.\&. ] +Output the termcap value corresponding to the capability +\fIcap\fP, with optional arguments\&. +.PP +The \fBzsh/termcap\fP module makes available one parameter: +.PP +.PD 0 +.TP +.PD +\fBtermcap\fP +An associative array that maps termcap capability codes to +their values\&. +.SH "THE ZSH/TERMINFO MODULE" +.\" Yodl file: Zsh/mod_terminfo.yo + +The \fBzsh/terminfo\fP module makes available one builtin command: +.PP +.PD 0 +.TP +.PD +\fBechoti\fP \fIcap\fP [ \fIarg\fP ] +Output the terminfo value corresponding to the capability +\fIcap\fP, instantiated with \fIarg\fP if applicable\&. +.PP +The \fBzsh/terminfo\fP module makes available one parameter: +.PP +.PD 0 +.TP +.PD +\fBterminfo\fP +An associative array that maps terminfo capability names to +their values\&. +.SH "THE ZSH/WATCH MODULE" +.\" Yodl file: Zsh/mod_watch.yo + +The \fBzsh/watch\fP module can be used to report when specific users log in or +out\&. This is controlled via the following parameters\&. +.PP +.PD 0 +.TP +.PD +\fBLOGCHECK\fP +The interval in seconds between checks for login/logout activity +using the \fBwatch\fP parameter\&. +.TP +\fBwatch\fP <S> <Z> (\fBWATCH\fP <S>) +An array (colon\-separated list) of login/logout events to report\&. +.RS +.PP +If it contains the single word `\fBall\fP\&', then all login/logout events +are reported\&. If it contains the single word `\fBnotme\fP\&', then all +events are reported as with `\fBall\fP\&' except \fB$USERNAME\fP\&. +.PP +An entry in this list may consist of a username, +an `\fB@\fP\&' followed by a remote hostname, +and a `\fB%\fP\&' followed by a line (tty)\&. Any of these may +be a pattern (be sure to quote this during the assignment to +\fBwatch\fP so that it does not immediately perform file generation); +the setting of the \fBEXTENDED_GLOB\fP option is respected\&. +Any or all of these components may be present in an entry; +if a login/logout event matches all of them, +it is reported\&. +.PP +For example, with the \fBEXTENDED_GLOB\fP option set, the following: +.PP +.RS +.nf +\fBwatch=(\&'^(pws|barts)')\fP +.fi +.RE +.PP +causes reports for activity associated with any user other than \fBpws\fP +or \fBbarts\fP\&. +.RE +.TP +\fBWATCHFMT\fP +The format of login/logout reports if the \fBwatch\fP parameter is set\&. +Default is `\fB%n has %a %l from %m\fP\&'\&. +Recognizes the following escape sequences: +.RS +.PP +.PD 0 +.TP +.PD +\fB%n\fP +The name of the user that logged in/out\&. +.TP +\fB%a\fP +The observed action, i\&.e\&. "logged on" or "logged off"\&. +.TP +\fB%l\fP +The line (tty) the user is logged in on\&. +.TP +\fB%M\fP +The full hostname of the remote host\&. +.TP +\fB%m\fP +The hostname up to the first `\fB\&.\fP\&'\&. If only the +IP address is available or the utmp field contains +the name of an X\-windows display, the whole name is printed\&. +.RS +.PP +\fINOTE:\fP +The `\fB%m\fP\&' and `\fB%M\fP' escapes will work only if there is a host name +field in the utmp on your machine\&. Otherwise they are +treated as ordinary strings\&. +.RE +.TP +\fB%F{\fP\fIcolor\fP\fB}\fP (\fB%f\fP) +Start (stop) using a different foreground color\&. +.TP +\fB%K{\fP\fIcolor\fP\fB}\fP (\fB%k\fP) +Start (stop) using a different background color\&. +.TP +\fB%S\fP (\fB%s\fP) +Start (stop) standout mode\&. +.TP +\fB%U\fP (\fB%u\fP) +Start (stop) underline mode\&. +.TP +\fB%B\fP (\fB%b\fP) +Start (stop) boldface mode\&. +.TP +.PD 0 +\fB%t\fP +.TP +.PD +\fB%@\fP +The time, in 12\-hour, am/pm format\&. +.TP +\fB%T\fP +The time, in 24\-hour format\&. +.TP +\fB%w\fP +The date in `\fIday\fP\fB\-\fP\fIdd\fP\&' format\&. +.TP +\fB%W\fP +The date in `\fImm\fP\fB/\fP\fIdd\fP\fB/\fP\fIyy\fP\&' format\&. +.TP +\fB%D\fP +The date in `\fIyy\fP\fB\-\fP\fImm\fP\fB\-\fP\fIdd\fP\&' format\&. +.TP +\fB%D{\fP\fIstring\fP\fB}\fP +The date formatted as \fIstring\fP using the \fBstrftime\fP function, with +zsh extensions as described by +EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)\&. +.TP +\fB%(\fP\fIx\fP\fB:\fP\fItrue\-text\fP\fB:\fP\fIfalse\-text\fP\fB)\fP +Specifies a ternary expression\&. +The character following the \fIx\fP is +arbitrary; the same character is used to separate the text +for the "true" result from that for the "false" result\&. +Both the separator and the right parenthesis may be escaped +with a backslash\&. +Ternary expressions may be nested\&. +.RS +.PP +The test character \fIx\fP may be any one of `\fBl\fP\&', `\fBn\fP', `\fBm\fP' +or `\fBM\fP\&', which indicate a `true' result if the corresponding +escape sequence would return a non\-empty value; or it may be `\fBa\fP\&', +which indicates a `true\&' result if the watched user has logged in, +or `false\&' if he has logged out\&. +Other characters evaluate to neither true nor false; the entire +expression is omitted in this case\&. +.PP +If the result is `true\&', then the \fItrue\-text\fP +is formatted according to the rules above and printed, +and the \fIfalse\-text\fP is skipped\&. +If `false\&', the \fItrue\-text\fP is skipped and the \fIfalse\-text\fP +is formatted and printed\&. +Either or both of the branches may be empty, but +both separators must be present in any case\&. +.RE +.RE +.PP +Furthermore, the \fBzsh/watch\fP module makes available one builtin +command: +.PP +.PD 0 +.TP +.PD +\fBlog\fP +List all users currently logged in who are affected by +the current setting of the \fBwatch\fP parameter\&. +.SH "THE ZSH/ZFTP MODULE" +.\" Yodl file: Zsh/mod_zftp.yo + +The \fBzsh/zftp\fP module makes available one builtin command: +.PP +.PD 0 +.TP +.PD +\fBzftp\fP \fIsubcommand\fP [ \fIargs\fP ] +The \fBzsh/zftp\fP module is a client for FTP (file transfer protocol)\&. It +is implemented as a builtin to allow full use of shell command line +editing, file I/O, and job control mechanisms\&. Often, users will +access it via shell functions providing a more powerful interface; a set is +provided with the \fBzsh\fP distribution and is described in +\fIzshzftpsys\fP(1)\&. However, the \fBzftp\fP command is entirely usable in its +own right\&. +.RS +.PP +All commands consist of the command name \fBzftp\fP followed by the name +of a subcommand\&. These are listed below\&. The return status of each +subcommand is supposed to reflect the success or failure of the remote +operation\&. See a description of the variable \fBZFTP_VERBOSE\fP for +more information on how responses from the server may be printed\&. +.RE +.PP +.SS "Subcommands" +.PP +.PD 0 +.TP +.PD +\fBopen\fP \fIhost\fP[\fB:\fP\fIport\fP] [ \fIuser\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ] +Open a new FTP session to \fIhost\fP, which may be the name of a TCP/IP +connected host or an IP number in the standard dot notation\&. If the +argument is in the form \fIhost\fP\fB:\fP\fIport\fP, open a connection to +TCP port \fIport\fP instead of the standard FTP port 21\&. This may be +the name of a TCP service or a number: see the description of +\fBZFTP_PORT\fP below for more information\&. +.RS +.PP +If IPv6 addresses in colon format are used, the \fIhost\fP should be +surrounded by quoted square brackets to distinguish it from the \fIport\fP, +for example \fB\&'[fe80::203:baff:fe02:8b56]'\fP\&. For consistency this is +allowed with all forms of \fIhost\fP\&. +.PP +Remaining arguments are passed to the \fBlogin\fP subcommand\&. Note that +if no arguments beyond \fIhost\fP are supplied, \fBopen\fP will \fInot\fP +automatically call \fBlogin\fP\&. If no arguments at all are supplied, +\fBopen\fP will use the parameters set by the \fBparams\fP subcommand\&. +.PP +After a successful open, the shell variables \fBZFTP_HOST\fP, \fBZFTP_PORT\fP, +\fBZFTP_IP\fP and \fBZFTP_SYSTEM\fP are available; see `Variables\&' +below\&. +.RE +.TP +.PD 0 +\fBlogin\fP [ \fIname\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ] +.TP +.PD +\fBuser\fP [ \fIname\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ] +Login the user \fIname\fP with parameters \fIpassword\fP and \fIaccount\fP\&. +Any of the parameters can be omitted, and will be read from standard +input if needed (\fIname\fP is always needed)\&. If +standard input is a terminal, a prompt for each one will be printed on +standard error and \fIpassword\fP will not be echoed\&. If any of the +parameters are not used, a warning message is printed\&. +.RS +.PP +After a successful login, the shell variables \fBZFTP_USER\fP, +\fBZFTP_ACCOUNT\fP and \fBZFTP_PWD\fP are available; see `Variables\&' +below\&. +.PP +This command may be re\-issued when a user is already logged in, and +the server will first be reinitialized for a new user\&. +.RE +.TP +.PD 0 +\fBparams\fP [ \fIhost\fP [ \fIuser\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ] ] +.TP +.PD +\fBparams\fP \fB\-\fP +Store the given parameters for a later \fBopen\fP command with no +arguments\&. Only those given on the command line will be remembered\&. +If no arguments are given, the parameters currently set are printed, +although the password will appear as a line of stars; the return status is +one if no parameters were set, zero otherwise\&. +.RS +.PP +Any of the parameters may be specified as a `\fB?\fP\&', which +may need to be quoted to protect it from shell expansion\&. In this case, +the appropriate parameter will be read from stdin as with the +\fBlogin\fP subcommand, including special handling of \fIpassword\fP\&. If the +`\fB?\fP\&' is followed by a string, that is used as the prompt for reading the +parameter instead of the default message (any necessary punctuation and +whitespace should be included at the end of the prompt)\&. The first letter +of the parameter (only) may be quoted with a `\fB\e\fP\&'; hence an argument +\fB"\e\e$word"\fP guarantees that the string from the shell parameter \fB$word\fP +will be treated literally, whether or not it begins with a `\fB?\fP\&'\&. +.PP +If instead a single `\fB\-\fP\&' is given, the existing parameters, if any, +are deleted\&. In that case, calling \fBopen\fP with no arguments will +cause an error\&. +.PP +The list of parameters is not deleted after a \fBclose\fP, however it +will be deleted if the \fBzsh/zftp\fP module is unloaded\&. +.PP +For example, +.PP +.RS +.nf +\fBzftp params ftp\&.elsewhere\&.xx juser \&'?Password for juser: '\fP +.fi +.RE +.PP +will store the host \fBftp\&.elsewhere\&.xx\fP and the user \fBjuser\fP and +then prompt the user for the corresponding password with the given prompt\&. +.RE +.TP +\fBtest\fP +Test the connection; if the server has reported +that it has closed the connection (maybe due to a timeout), return +status 2; if no connection was open anyway, return status 1; else +return status 0\&. The \fBtest\fP subcommand is +silent, apart from messages printed by the \fB$ZFTP_VERBOSE\fP +mechanism, or error messages if the connection closes\&. There is no +network overhead for this test\&. +.RS +.PP +The test is only supported on systems with either the +\fBselect(2)\fP or +\fBpoll(2)\fP system calls; otherwise the message `\fBnot +supported on this system\fP\&' is printed instead\&. +.PP +The \fBtest\fP subcommand will automatically be called at the start of any +other subcommand for the current session when a connection is open\&. +.RE +.TP +\fBcd\fP \fIdirectory\fP +Change the remote directory to \fIdirectory\fP\&. Also alters the shell +variable \fBZFTP_PWD\fP\&. +.TP +\fBcdup\fP +Change the remote directory to the one higher in the directory tree\&. +Note that \fBcd \&.\&.\fP will also work correctly on non\-UNIX systems\&. +.TP +\fBdir\fP [ \fIarg\fP \&.\&.\&. ] +Give a (verbose) listing of the remote directory\&. The \fIarg\fPs are +passed directly to the server\&. The command\&'s behaviour is implementation +dependent, but a UNIX server will typically interpret \fIarg\fPs as +arguments to the \fBls\fP command and with no arguments return the +result of `\fBls \-l\fP\&'\&. The directory is listed to standard output\&. +.TP +\fBls\fP [ \fIarg\fP \&.\&.\&. ] +Give a (short) listing of the remote directory\&. With no \fIarg\fP, +produces a raw list of the files in the directory, one per line\&. +Otherwise, up to vagaries of the server implementation, behaves +similar to \fBdir\fP\&. +.TP +\fBtype\fP [ \fItype\fP ] +Change the type for the transfer to \fItype\fP, or print the current type +if \fItype\fP is absent\&. The allowed values are `\fBA\fP\&' (ASCII), +`\fBI\fP\&' (Image, i\&.e\&. binary), or `\fBB\fP' (a synonym for `\fBI\fP')\&. +.RS +.PP +The FTP default for a transfer is ASCII\&. However, if \fBzftp\fP finds +that the remote host is a UNIX machine with 8\-bit byes, it will +automatically switch to using binary for file transfers upon +\fBopen\fP\&. This can subsequently be overridden\&. +.PP +The transfer type is only passed to the remote host when a data +connection is established; this command involves no network overhead\&. +.RE +.TP +\fBascii\fP +The same as \fBtype A\fP\&. +.TP +\fBbinary\fP +The same as \fBtype I\fP\&. +.TP +\fBmode\fP [ \fBS\fP | \fBB\fP ] +Set the mode type to stream (\fBS\fP) or block (\fBB\fP)\&. Stream mode is +the default; block mode is not widely supported\&. +.TP +.PD 0 +\fBremote\fP \fIfile\fP \&.\&.\&. +.TP +.PD +\fBlocal\fP [ \fIfile\fP \&.\&.\&. ] +Print the size and last modification time of the remote or local +files\&. If there is more than one item on the list, the name of the +file is printed first\&. The first number is the file size, the second +is the last modification time of the file in the format +\fBCCYYMMDDhhmmSS\fP consisting of year, month, date, hour, minutes and +seconds in GMT\&. Note that this format, including the length, is +guaranteed, so that time strings can be directly compared via the +\fB[[\fP builtin\&'s \fB<\fP and \fB>\fP operators, even if they are too long +to be represented as integers\&. +.RS +.PP +Not all servers support the commands for retrieving this information\&. +In that case, the \fBremote\fP command will print nothing and return +status 2, compared with status 1 for a file not found\&. +.PP +The \fBlocal\fP command (but not \fBremote\fP) may be used with no +arguments, in which case the information comes from examining file +descriptor zero\&. This is the same file as seen by a \fBput\fP command +with no further redirection\&. +.RE +.TP +\fBget\fP \fIfile\fP \&.\&.\&. +Retrieve all \fIfile\fPs from the server, concatenating them +and sending them to standard output\&. +.TP +\fBput\fP \fIfile\fP \&.\&.\&. +For each \fIfile\fP, read a file from standard input and send that to +the remote host with the given name\&. +.TP +\fBappend\fP \fIfile\fP \&.\&.\&. +As \fBput\fP, but if the remote \fIfile\fP already exists, data is +appended to it instead of overwriting it\&. +.TP +.PD 0 +\fBgetat\fP \fIfile\fP \fIpoint\fP +.TP +.PD 0 +\fBputat\fP \fIfile\fP \fIpoint\fP +.TP +.PD +\fBappendat\fP \fIfile\fP \fIpoint\fP +Versions of \fBget\fP, \fBput\fP and \fBappend\fP which will start the +transfer at the given \fIpoint\fP in the remote \fIfile\fP\&. This is +useful for appending to an incomplete local file\&. However, note that +this ability is not universally supported by servers (and is not quite +the behaviour specified by the standard)\&. +.TP +\fBdelete\fP \fIfile\fP \&.\&.\&. +Delete the list of files on the server\&. +.TP +\fBmkdir\fP \fIdirectory\fP +Create a new directory \fIdirectory\fP on the server\&. +.TP +\fBrmdir\fP \fIdirectory\fP +Delete the directory \fIdirectory\fP on the server\&. +.TP +\fBrename\fP \fIold\-name\fP \fInew\-name\fP +Rename file \fIold\-name\fP to \fInew\-name\fP on the server\&. +.TP +\fBsite\fP \fIarg\fP \&.\&.\&. +Send a host\-specific command to the server\&. You will probably +only need this if instructed by the server to use it\&. +.TP +\fBquote\fP \fIarg\fP \&.\&.\&. +Send the raw FTP command sequence to the server\&. You should be +familiar with the FTP command set as defined in RFC959 before doing +this\&. Useful commands may include \fBSTAT\fP and \fBHELP\fP\&. Note also +the mechanism for returning messages as described for the variable +\fBZFTP_VERBOSE\fP below, in particular that all messages from the +control connection are sent to standard error\&. +.TP +.PD 0 +\fBclose\fP +.TP +.PD +\fBquit\fP +Close the current data connection\&. This unsets the shell parameters +\fBZFTP_HOST\fP, \fBZFTP_PORT\fP, \fBZFTP_IP\fP, \fBZFTP_SYSTEM\fP, \fBZFTP_USER\fP, +\fBZFTP_ACCOUNT\fP, \fBZFTP_PWD\fP, \fBZFTP_TYPE\fP and \fBZFTP_MODE\fP\&. +.TP +\fBsession\fP [ \fIsessname\fP ] +Allows multiple FTP sessions to be used at once\&. The name of the session +is an arbitrary string of characters; the default session is called +`\fBdefault\fP\&'\&. If this command is called without an argument, it will list +all the current sessions; with an argument, it will either switch to the +existing session called \fIsessname\fP, or create a new session of that name\&. +.RS +.PP +Each session remembers the status of the connection, the set of +connection\-specific shell parameters (the same set as are unset when a +connection closes, as given in the description of \fBclose\fP), and any user +parameters specified with the \fBparams\fP subcommand\&. Changing to a +previous session restores those values; changing to a new session +initialises them in the same way as if \fBzftp\fP had just been loaded\&. The +name of the current session is given by the parameter \fBZFTP_SESSION\fP\&. +.RE +.TP +\fBrmsession\fP [ \fIsessname\fP ] +Delete a session; if a name is not given, the current session is deleted\&. +If the current session is deleted, the earliest existing session becomes +the new current session, otherwise the current session is not changed\&. +If the session being deleted is the only one, a new session called +`\fBdefault\fP\&' is created and becomes the current session; note that this is +a new session even if the session being deleted is also called +`\fBdefault\fP\&'\&. It is recommended that sessions not be deleted while +background commands which use \fBzftp\fP are still active\&. +.PP +.SS "Parameters" +The following shell parameters are used by \fBzftp\fP\&. Currently none +of them are special\&. +.PP +.PD 0 +.TP +.PD +\fBZFTP_TMOUT\fP +Integer\&. The time in seconds to wait for a network operation to +complete before returning an error\&. If this is not set when the +module is loaded, it will be given the default value 60\&. A value of +zero turns off timeouts\&. If a timeout occurs on the control +connection it will be closed\&. Use a larger value if this occurs too +frequently\&. +.TP +\fBZFTP_IP\fP +Readonly\&. The IP address of the current connection in dot notation\&. +.TP +\fBZFTP_HOST\fP +Readonly\&. The hostname of the current remote server\&. If the host was +opened as an IP number, \fBZFTP_HOST\fP contains that instead; this +saves the overhead for a name lookup, as IP numbers are most commonly +used when a nameserver is unavailable\&. +.TP +\fBZFTP_PORT\fP +Readonly\&. The number of the remote TCP port to which the connection is +open (even if the port was originally specified as a named service)\&. +Usually this is the standard FTP port, 21\&. +.RS +.PP +In the unlikely event that your system does not have the appropriate +conversion functions, this appears in network byte order\&. If your +system is little\-endian, the port then consists of two swapped bytes and the +standard port will be reported as 5376\&. In that case, numeric ports passed +to \fBzftp open\fP will also need to be in this format\&. +.RE +.TP +\fBZFTP_SYSTEM\fP +Readonly\&. The system type string returned by the server in response +to an FTP \fBSYST\fP request\&. The most interesting case is a string +beginning \fB"UNIX Type: L8"\fP, which ensures maximum compatibility +with a local UNIX host\&. +.TP +\fBZFTP_TYPE\fP +Readonly\&. The type to be used for data transfers , either `\fBA\fP\&' or +`\fBI\fP\&'\&. Use the \fBtype\fP subcommand to change this\&. +.TP +\fBZFTP_USER\fP +Readonly\&. The username currently logged in, if any\&. +.TP +\fBZFTP_ACCOUNT\fP +Readonly\&. The account name of the current user, if any\&. Most servers +do not require an account name\&. +.TP +\fBZFTP_PWD\fP +Readonly\&. The current directory on the server\&. +.TP +\fBZFTP_CODE\fP +Readonly\&. The three digit code of the last FTP reply from the server +as a string\&. This can still be read after the connection is closed, and +is not changed when the current session changes\&. +.TP +\fBZFTP_REPLY\fP +Readonly\&. The last line of the last reply sent by the server\&. This +can still be read after the connection is closed, and is not changed when +the current session changes\&. +.TP +\fBZFTP_SESSION\fP +Readonly\&. The name of the current FTP session; see the description of the +\fBsession\fP subcommand\&. +.TP +\fBZFTP_PREFS\fP +A string of preferences for altering aspects of \fBzftp\fP\&'s behaviour\&. +Each preference is a single character\&. The following are defined: +.RS +.PP +.PD 0 +.TP +.PD +\fBP\fP +Passive: attempt to make the remote server initiate data transfers\&. +This is slightly more efficient than sendport mode\&. If the letter +\fBS\fP occurs later in the string, \fBzftp\fP will use sendport mode if +passive mode is not available\&. +.TP +\fBS\fP +Sendport: initiate transfers by the FTP \fBPORT\fP command\&. If this +occurs before any \fBP\fP in the string, passive mode will never be +attempted\&. +.TP +\fBD\fP +Dumb: use only the bare minimum of FTP commands\&. This prevents +the variables \fBZFTP_SYSTEM\fP and \fBZFTP_PWD\fP from being set, and +will mean all connections default to ASCII type\&. It may prevent +\fBZFTP_SIZE\fP from being set during a transfer if the server +does not send it anyway (many servers do)\&. +.PP +If \fBZFTP_PREFS\fP is not set when \fBzftp\fP is loaded, it will be set to a +default of `\fBPS\fP\&', i\&.e\&. use passive mode if available, otherwise +fall back to sendport mode\&. +.RE +.TP +\fBZFTP_VERBOSE\fP +A string of digits between 0 and 5 inclusive, specifying which +responses from the server should be printed\&. All responses go to +standard error\&. If any of the numbers 1 to 5 appear in the string, +raw responses from the server with reply codes beginning with that +digit will be printed to standard error\&. The first digit of the three +digit reply code is defined by RFC959 to correspond to: +.RS +.PP +.PD 0 +.TP +.PD +1\&. +A positive preliminary reply\&. +.TP +2\&. +A positive completion reply\&. +.TP +3\&. +A positive intermediate reply\&. +.TP +4\&. +A transient negative completion reply\&. +.TP +5\&. +A permanent negative completion reply\&. +.PP +It should be noted that, for unknown reasons, the reply `Service not +available\&', which forces termination of a connection, is classified as +421, i\&.e\&. `transient negative\&', an interesting interpretation of the word +`transient\&'\&. +.PP +The code 0 is special: it indicates that all but the last line of +multiline replies read from the server will be printed to standard +error in a processed format\&. By convention, servers use this +mechanism for sending information for the user to read\&. The +appropriate reply code, if it matches the same response, takes +priority\&. +.PP +If \fBZFTP_VERBOSE\fP is not set when \fBzftp\fP is loaded, it will be +set to the default value \fB450\fP, i\&.e\&., messages destined for the user +and all errors will be printed\&. A null string is valid and +specifies that no messages should be printed\&. +.RE +.PP +.SS "Functions" +.PP +.PD 0 +.TP +.PD +\fBzftp_chpwd\fP +If this function is set by the user, it is called every time the +directory changes on the server, including when a user is logged +in, or when a connection is closed\&. In the last case, \fB$ZFTP_PWD\fP +will be unset; otherwise it will reflect the new directory\&. +.TP +\fBzftp_progress\fP +If this function is set by the user, it will be called during +a \fBget\fP, \fBput\fP or \fBappend\fP operation each time sufficient data +has been received from the host\&. During a \fBget\fP, the data is sent +to standard output, so it is vital that this function should write +to standard error or directly to the terminal, \fInot\fP to standard +output\&. +.RS +.PP +When it is called with a transfer in progress, the following +additional shell parameters are set: +.PP +.PD 0 +.TP +.PD +\fBZFTP_FILE\fP +The name of the remote file being transferred from or to\&. +.TP +\fBZFTP_TRANSFER\fP +A \fBG\fP for a \fBget\fP operation and a \fBP\fP for a \fBput\fP operation\&. +.TP +\fBZFTP_SIZE\fP +The total size of the complete file being transferred: +the same as the first value provided by the +\fBremote\fP and \fBlocal\fP subcommands for a particular file\&. +If the server cannot supply this value for a remote file being +retrieved, it will not be set\&. If input is from a pipe the value may +be incorrect and correspond simply to a full pipe buffer\&. +.TP +\fBZFTP_COUNT\fP +The amount of data so far transferred; a number between zero and +\fB$ZFTP_SIZE\fP, if that is set\&. This number is always available\&. +.PP +The function is initially called with \fBZFTP_TRANSFER\fP set +appropriately and \fBZFTP_COUNT\fP set to zero\&. After the transfer is +finished, the function will be called one more time with +\fBZFTP_TRANSFER\fP set to \fBGF\fP or \fBPF\fP, in case it wishes to tidy +up\&. It is otherwise never called twice with the same value of +\fBZFTP_COUNT\fP\&. +.PP +Sometimes the progress meter may cause disruption\&. It is up to the +user to decide whether the function should be defined and to use +\fBunfunction\fP when necessary\&. +.RE +.PP +.SS "Problems" +.PP +A connection may not be opened in the left hand side of a pipe as this +occurs in a subshell and the file information is not updated in the main +shell\&. In the case of type or mode changes or closing the connection in a +subshell, the information is returned but variables are not updated until +the next call to \fBzftp\fP\&. Other status changes in subshells will not be +reflected by changes to the variables (but should be otherwise harmless)\&. +.PP +Deleting sessions while a \fBzftp\fP command is active in the background can +have unexpected effects, even if it does not use the session being deleted\&. +This is because all shell subprocesses share information on the state of +all connections, and deleting a session changes the ordering of that +information\&. +.PP +On some operating systems, the control connection is not valid after a +fork(), so that operations in subshells, on the left hand side +of a pipeline, or in the background are not possible, as they should be\&. +This is presumably a bug in the operating system\&. +.SH "THE ZSH/ZLE MODULE" +.\" Yodl file: Zsh/mod_zle.yo + +The \fBzsh/zle\fP module contains the Zsh Line Editor\&. See +\fIzshzle\fP(1)\&. +.SH "THE ZSH/ZLEPARAMETER MODULE" +.\" Yodl file: Zsh/mod_zleparameter.yo + +The \fBzsh/zleparameter\fP module defines two special parameters that can be +used to access internal information of the Zsh Line Editor (see +\fIzshzle\fP(1))\&. +.PP +.PD 0 +.TP +.PD +\fBkeymaps\fP +This array contains the names of the keymaps currently defined\&. +.TP +\fBwidgets\fP +This associative array contains one entry per widget\&. The name +of the widget is the key and the value gives information about the +widget\&. It is either + the string `\fBbuiltin\fP\&' for builtin widgets, + a string of the form `\fBuser:\fP\fIname\fP\&' for user\-defined widgets, + where \fIname\fP is the name of the shell function implementing the widget, + a string of the form `\fBcompletion:\fP\fItype\fP\fB:\fP\fIname\fP\&' + for completion widgets, + or a null value if the widget is not yet fully defined\&. +In the penultimate case, \fItype\fP is the name of the builtin widget the +completion widget imitates in its behavior and \fIname\fP is the name +of the shell function implementing the completion widget\&. +.SH "THE ZSH/ZPROF MODULE" +.\" Yodl file: Zsh/mod_zprof.yo + +When loaded, the \fBzsh/zprof\fP causes shell functions to be profiled\&. +The profiling results can be obtained with the \fBzprof\fP +builtin command made available by this module\&. There is no way to turn +profiling off other than unloading the module\&. +.PP +.PD 0 +.TP +.PD +\fBzprof\fP [ \fB\-c\fP ] +Without the \fB\-c\fP option, \fBzprof\fP lists profiling results to +standard output\&. The format is comparable to that of commands like +\fBgprof\fP\&. +.RS +.PP +At the top there is a summary listing all functions that were called +at least once\&. This summary is sorted in decreasing order of the +amount of time spent in each\&. The lines contain +the number of the function in order, which is used in +other parts of the list in suffixes of the form +`\fB[\fP\fInum\fP\fB]\fP\&', then the number of calls made to the function\&. +The next three columns list the time in +milliseconds spent in the function and its descendants, the average +time in milliseconds spent in the function and its descendants per +call and the percentage of time spent in all shell functions used in +this function and its descendants\&. The following three columns give +the same information, but counting only the time spent in the function +itself\&. The final column shows the name of the function\&. +.PP +After the summary, detailed information about every function that was +invoked is listed, sorted in decreasing order of the amount of time spent +in each function and its descendants\&. Each of these entries consists of +descriptions for the functions that called the function described, the +function itself, and the functions that were called from it\&. The +description for the function itself has the same format as in the summary +(and shows the same information)\&. The other lines don\&'t show the number of +the function at the beginning and have their function named indented to +make it easier to distinguish the line showing the function described in +the section from the surrounding lines\&. +.PP +The information shown in this case is almost the same as in the summary, +but only refers to the call hierarchy being displayed\&. For example, for a +calling function the column showing the total running time lists the time +spent in the described function and its descendants only for the times when +it was called from that particular calling function\&. Likewise, for a +called function, this columns lists the total time spent in the called +function and its descendants only for the times when it was called from the +function described\&. +.PP +Also in this case, the column showing the number of calls to a function +also shows a slash and then the total number of invocations made to the +called function\&. +.PP +As long as the \fBzsh/zprof\fP module is loaded, profiling will be done and +multiple invocations of the \fBzprof\fP builtin command will show the +times and numbers of calls since the module was loaded\&. With the +\fB\-c\fP option, the \fBzprof\fP builtin command will reset its internal +counters and will not show the listing\&. +.RE +.SH "THE ZSH/ZPTY MODULE" +.\" Yodl file: Zsh/mod_zpty.yo + +The \fBzsh/zpty\fP module offers one builtin: +.PP +.PD 0 +.TP +.PD +\fBzpty\fP [ \fB\-e\fP ] [ \fB\-b\fP ] \fIname\fP [ \fIarg\fP \&.\&.\&. ] +The arguments following \fIname\fP are concatenated with spaces between, +then executed as a command, as if passed to the \fBeval\fP builtin\&. The +command runs under a newly assigned pseudo\-terminal; this is useful for +running commands non\-interactively which expect an interactive +environment\&. The \fIname\fP is not part of the command, but is used to +refer to this command in later calls to \fBzpty\fP\&. +.RS +.PP +With the \fB\-e\fP option, the pseudo\-terminal is set up so that input +characters are echoed\&. +.PP +With the \fB\-b\fP option, input to and output from the pseudo\-terminal are +made non\-blocking\&. +.PP +The shell parameter \fBREPLY\fP is set to the file descriptor assigned to +the master side of the pseudo\-terminal\&. This allows the terminal to be +monitored with ZLE descriptor handlers (see \fIzshzle\fP(1)) or manipulated with \fBsysread\fP and +\fBsyswrite\fP (see THE ZSH/SYSTEM MODULE in \fIzshmodules\fP(1))\&. \fIWarning\fP: Use of \fBsysread\fP +and \fBsyswrite\fP is \fInot\fP recommended; use \fBzpty \-r\fP and \fBzpty \-w\fP +unless you know exactly what you are doing\&. +.RE +.TP +\fBzpty\fP \fB\-d\fP [ \fIname\fP \&.\&.\&. ] +The second form, with the \fB\-d\fP option, is used to delete commands +previously started, by supplying a list of their \fIname\fPs\&. If no +\fIname\fP is given, all commands are deleted\&. Deleting a command causes +the HUP signal to be sent to the corresponding process\&. +.TP +\fBzpty\fP \fB\-w\fP [ \fB\-n\fP ] \fIname\fP [ \fIstring\fP \&.\&.\&. ] +The \fB\-w\fP option can be used to send the to command \fIname\fP the given +\fIstring\fPs as input (separated by spaces)\&. If the \fB\-n\fP option is +\fInot\fP given, a newline is added at the end\&. +.RS +.PP +If no \fIstring\fP is provided, the standard input is copied to the +pseudo\-terminal; this may stop before copying the full input if the +pseudo\-terminal is non\-blocking\&. The exact input is always copied: +the \fB\-n\fP option is not applied\&. +.PP +Note that the command under the pseudo\-terminal sees this input as if it +were typed, so beware when sending special tty driver characters such as +word\-erase, line\-kill, and end\-of\-file\&. +.RE +.TP +\fBzpty\fP \fB\-r\fP [ \fB\-mt\fP ] \fIname\fP [ \fIparam\fP [ \fIpattern\fP ] ] +The \fB\-r\fP option can be used to read the output of the command \fIname\fP\&. +With only a \fIname\fP argument, the output read is copied to the standard +output\&. Unless the pseudo\-terminal is non\-blocking, copying continues +until the command under the pseudo\-terminal exits; when non\-blocking, only +as much output as is immediately available is copied\&. The return status is +zero if any output is copied\&. +.RS +.PP +When also given a \fIparam\fP argument, at most one line is read and stored +in the parameter named \fIparam\fP\&. Less than a full line may be read if +the pseudo\-terminal is non\-blocking\&. The return status is zero if at least +one character is stored in \fIparam\fP\&. +.PP +If a \fIpattern\fP is given as well, output is read until the whole string +read matches the \fIpattern\fP, even in the non\-blocking case\&. The return +status is zero if the string read matches the pattern, or if the command +has exited but at least one character could still be read\&. If the option +\fB\-m\fP is present, the return status is zero only if the pattern matches\&. +As of this writing, a maximum of one megabyte of output can be consumed +this way; if a full megabyte is read without matching the pattern, the +return status is non\-zero\&. +.PP +In all cases, the return status is non\-zero if nothing could be read, and +is \fB2\fP if this is because the command has finished\&. +.PP +If the \fB\-r\fP option is combined with the \fB\-t\fP option, \fBzpty\fP tests +whether output is available before trying to read\&. If no output is +available, \fBzpty\fP immediately returns the status \fB1\fP\&. When used +with a \fIpattern\fP, the behaviour on a failed poll is similar to +when the command has exited: the return value is zero if at least +one character could still be read even if the pattern failed to match\&. +.RE +.TP +\fBzpty\fP \fB\-t\fP \fIname\fP +The \fB\-t\fP option without the \fB\-r\fP option can be used to test +whether the command \fIname\fP is still running\&. It returns a zero +status if the command is running and a non\-zero value otherwise\&. +.TP +\fBzpty\fP [ \fB\-L\fP ] +The last form, without any arguments, is used to list the commands +currently defined\&. If the \fB\-L\fP option is given, this is done in the +form of calls to the \fBzpty\fP builtin\&. +.SH "THE ZSH/ZSELECT MODULE" +.\" Yodl file: Zsh/mod_zselect.yo + +The \fBzsh/zselect\fP module makes available one builtin command: +.PP +.PD 0 +.TP +.PD +\fBzselect\fP [ \fB\-rwe\fP ] [ \fB\-t\fP \fItimeout\fP ] [ \fB\-a\fP \fIarray\fP ] [ \fB\-A\fP \fIassoc\fP ] [ \fIfd\fP \&.\&.\&. ] +The \fBzselect\fP builtin is a front\-end to the `select\&' system call, which +blocks until a file descriptor is ready for reading or writing, or has an +error condition, with an optional timeout\&. If this is not available on +your system, the command prints an error message and returns status 2 +(normal errors return status 1)\&. For more information, see your system\&'s +documentation for \fIselect\fP(3)\&. Note there is no connection with the +shell builtin of the same name\&. +.RS +.PP +Arguments and options may be intermingled in any order\&. Non\-option +arguments are file descriptors, which must be decimal integers\&. By +default, file descriptors are to be tested for reading, i\&.e\&. \fBzselect\fP +will return when data is available to be read from the file descriptor, or +more precisely, when a read operation from the file descriptor will not +block\&. After a \fB\-r\fP, \fB\-w\fP and \fB\-e\fP, the given file descriptors are +to be tested for reading, writing, or error conditions\&. These options and +an arbitrary list of file descriptors may be given in any order\&. +.PP +(The presence of an `error condition\&' is not well defined in the +documentation for many implementations of the select system call\&. +According to recent versions of the POSIX specification, it is really an +\fIexception\fP condition, of which the only standard example is out\-of\-band +data received on a socket\&. So zsh users are unlikely to find the \fB\-e\fP +option useful\&.) +.PP +The option `\fB\-t\fP \fItimeout\fP\&' specifies a timeout in hundredths of a +second\&. This may be zero, in which case the file descriptors will simply +be polled and \fBzselect\fP will return immediately\&. It is possible to call +zselect with no file descriptors and a non\-zero timeout for use as a +finer\-grained replacement for `sleep\&'; note, however, the return status is +always 1 for a timeout\&. +.PP +The option `\fB\-a\fP \fIarray\fP\&' indicates that \fIarray\fP should be set to +indicate the file descriptor(s) which are ready\&. If the option +is not +given, the array \fBreply\fP will be used for this purpose\&. The array will +contain a string similar to the arguments for \fBzselect\fP\&. For example, +.PP +.RS +.nf +\fBzselect \-t 0 \-r 0 \-w 1\fP +.fi +.RE +.PP +might return immediately with status 0 and \fB$reply\fP containing `\fB\-r 0 \-w +1\fP\&' to show that both file descriptors are ready for the requested +operations\&. +.PP +The option `\fB\-A\fP \fIassoc\fP\&' indicates that the associative array +\fIassoc\fP should be set to indicate the file descriptor(s) +which are ready\&. This option overrides the option \fB\-a\fP, nor will +\fBreply\fP be modified\&. The keys of \fBassoc\fP are the file descriptors, and +the corresponding values are any of the characters `\fBrwe\fP\&' to indicate +the condition\&. +.PP +The command returns status 0 if some file descriptors are ready for +reading\&. If the operation timed out, or a timeout of 0 was given and no +file descriptors were ready, or there was an error, it returns status 1 and +the array will not be set (nor modified in any way)\&. If there was an error +in the select operation the appropriate error message is printed\&. +.RE +.SH "THE ZSH/ZUTIL MODULE" +.\" Yodl file: Zsh/mod_zutil.yo + +The \fBzsh/zutil\fP module only adds some builtins: +.PP +.PD 0 +.TP +.PD 0 +\fBzstyle\fP [ \fB\-L\fP [ \fImetapattern\fP [ \fIstyle\fP ] ] ] +.TP +.PD 0 +\fBzstyle\fP [ \fB\-e\fP | \fB\-\fP | \fB\-\fP\fB\-\fP ] \fIpattern\fP \fIstyle\fP \fIstring\fP \&.\&.\&. +.TP +.PD 0 +\fBzstyle \-d\fP [ \fIpattern\fP [ \fIstyle\fP \&.\&.\&. ] ] +.TP +.PD 0 +\fBzstyle \-g\fP \fIname\fP [ \fIpattern\fP [ \fIstyle\fP ] ] +.TP +.PD 0 +\fBzstyle \-\fP{\fBa\fP|\fBb\fP|\fBs\fP} \fIcontext\fP \fIstyle\fP \fIname\fP [ \fIsep\fP ] +.TP +.PD 0 +\fBzstyle \-\fP{\fBT\fP|\fBt\fP} \fIcontext\fP \fIstyle\fP [ \fIstring\fP \&.\&.\&. ] +.TP +.PD +\fBzstyle \-m\fP \fIcontext\fP \fIstyle\fP \fIpattern\fP +This builtin command is used to define and lookup styles\&. Styles are +pairs of names and values, where the values consist of any number of +strings\&. They are stored together with patterns and lookup is done by +giving a string, called the `\fIcontext\fP\&', which is matched against the +patterns\&. The definition stored for the most specific pattern that matches +will be returned\&. +.RS +.PP +A pattern is considered to be more specific +than another if it contains more components (substrings separated by +colons) or if the patterns for the components are more specific, where +simple strings are considered to be more specific than patterns and +complex patterns are considered to be more specific than the pattern +`\fB*\fP\&'\&. A `\fB*\fP' in the pattern will match zero or more characters +in the context; colons are not treated specially in this regard\&. +If two patterns are equally specific, the tie is broken in favour of +the pattern that was defined first\&. +.PP +\fIExample\fP +.PP +For example, a fictional `\fBweather\fP\&' plugin might state in its documentation +that it looks up the \fBpreferred\-precipitation\fP style under the +`\fB:weather:\fP\fIcontinent\fP\fB:\fP\fIday\-of\-the\-week\fP\fB:\fP\fIphase\-of\-the\-moon\fP\&' context\&. +According to this, you might set the following in your \fBzshrc\fP: +.PP +.RS +.nf +\fBzstyle \&':weather:europe:*' preferred\-precipitation rain +zstyle \&':weather:*:Sunday:*' preferred\-precipitation snow\fP +.fi +.RE +.PP +Then the plugin would run under the hood a command such as +.PP +.RS +.nf +\fBzstyle \-s ":weather:${continent}:${day_of_week}:${moon_phase}" preferred\-precipitation REPLY\fP +.fi +.RE +.PP +in order to retrieve your preference into the scalar variable \fB$REPLY\fP\&. +On Sundays \fB$REPLY\fP would be set to `\fBsnow\fP\&'; in Europe it would be set +to `\fBrain\fP\&'; and on Sundays in Europe it would be set to `\fBsnow\fP' again, +because the patterns `\fB:weather:europe:*\fP\&' and `\fB:weather:*:Sunday:*\fP' both +match the \fIcontext\fP argument to \fBzstyle \-s\fP, are equally specific, and the +latter is more specific (because it has more colon\-separated components)\&. +.PP +\fIUsage\fP +.PP +The forms that operate on patterns are the following\&. +.PP +.PD 0 +.TP +.PD +\fBzstyle\fP [ \fB\-L\fP [ \fImetapattern\fP [ \fIstyle\fP ] ] ] +Without arguments, lists style definitions\&. Styles +are shown in alphabetic order and patterns are shown in the order +\fBzstyle\fP will test them\&. +.RS +.PP +If the \fB\-L\fP option is given, listing is done in the form of calls to +\fBzstyle\fP\&. The optional first argument, \fImetapattern\fP, is a pattern which +will be matched against the string supplied as \fIpattern\fP when the style was +defined\&. Note: +this means, for example, `\fBzstyle \-L ":completion:*"\fP\&' will +match any supplied pattern beginning `\fB:completion:\fP\&', not +just \fB":completion:*"\fP: use \fB\&':completion:\e*'\fP to match that\&. +The optional second argument limits the output to a specific \fIstyle\fP (not a +pattern)\&. \fB\-L\fP is not compatible with any other options\&. +.RE +.TP +\fBzstyle\fP [ \fB\-\fP | \fB\-\fP\fB\-\fP | \fB\-e\fP ] \fIpattern\fP \fIstyle\fP \fIstring\fP \&.\&.\&. +Defines the given \fIstyle\fP for the \fIpattern\fP with the \fIstring\fPs as +the value\&. If the \fB\-e\fP option is given, the \fIstring\fPs will be +concatenated (separated by spaces) and the resulting string will be +evaluated (in the same way as it is done by the \fBeval\fP builtin +command) when the style is looked up\&. In this case the parameter +`\fBreply\fP\&' must be assigned to set the strings returned after the +evaluation\&. Before evaluating the value, \fBreply\fP is unset, and +if it is still unset after the evaluation, the style is treated as if +it were not set\&. +.TP +\fBzstyle \-d\fP [ \fIpattern\fP [ \fIstyle\fP \&.\&.\&. ] ] +Delete style definitions\&. Without arguments all definitions are deleted, +with a \fIpattern\fP all definitions for that pattern are deleted and if +any \fIstyle\fPs are given, then only those styles are deleted for the +\fIpattern\fP\&. +.TP +\fBzstyle \-g\fP \fIname\fP [ \fIpattern\fP [ \fIstyle\fP ] ] +Retrieve a style definition\&. The \fIname\fP is +used as the name of an array in which the results are stored\&. Without +any further arguments, all patterns defined are returned\&. With a +\fIpattern\fP the styles defined for that pattern are returned and with +both a \fIpattern\fP and a \fIstyle\fP, the value strings of that +combination is returned\&. +.PP +The other forms can be used to look up or test styles for a given context\&. +.PP +.PD 0 +.TP +.PD +\fBzstyle \-s\fP \fIcontext\fP \fIstyle\fP \fIname\fP [ \fIsep\fP ] +The parameter \fIname\fP is set to the value of the style interpreted as a +string\&. If the value contains several strings they are concatenated with +spaces (or with the \fIsep\fP string if that is given) between them\&. +.RS +.PP +Return \fB0\fP if the style is set, \fB1\fP otherwise\&. +.RE +.TP +\fBzstyle \-b\fP \fIcontext\fP \fIstyle\fP \fIname\fP +The value is stored in \fIname\fP as a boolean, i\&.e\&. as the string +`\fByes\fP\&' if the value has only one string and that string is equal to one +of `\fByes\fP\&', `\fBtrue\fP', `\fBon\fP', or `\fB1\fP'\&. If the value is any other +string or has more than one string, the parameter is set to `\fBno\fP\&'\&. +.RS +.PP +Return \fB0\fP if \fIname\fP is set to `\fByes\fP\&', \fB1\fP otherwise\&. +.RE +.TP +\fBzstyle \-a\fP \fIcontext\fP \fIstyle\fP \fIname\fP +The value is stored in \fIname\fP as an array\&. If \fIname\fP is declared +as an associative array, the first, third, etc\&. strings are used as the +keys and the other strings are used as the values\&. +.RS +.PP +Return \fB0\fP if the style is set, \fB1\fP otherwise\&. +.RE +.TP +.PD 0 +\fBzstyle \-t\fP \fIcontext\fP \fIstyle\fP [ \fIstring\fP \&.\&.\&. ] +.TP +.PD +\fBzstyle \-T\fP \fIcontext\fP \fIstyle\fP [ \fIstring\fP \&.\&.\&. ] +Test the value of a style, i\&.e\&. the \fB\-t\fP option only returns a status +(sets \fB$?\fP)\&. Without any \fIstring\fP the return status is zero if the +style is defined for at least one matching pattern, has only one string in +its value, and that is equal to one of `\fBtrue\fP\&', `\fByes\fP', `\fBon\fP' or +`\fB1\fP\&'\&. If any \fIstring\fPs are given the status is zero if and only if +at least one of the \fIstring\fPs is equal to at least one of the strings +in the value\&. If the style is defined but doesn\&'t match, the return status +is \fB1\fP\&. If the style is not defined, the status is \fB2\fP\&. +.RS +.PP +The \fB\-T\fP option tests the values of the style like \fB\-t\fP, but it +returns status zero (rather than \fB2\fP) if the style is not defined for any +matching pattern\&. +.RE +.TP +\fBzstyle \-m\fP \fIcontext\fP \fIstyle\fP \fIpattern\fP +Match a value\&. Returns status zero if the +\fIpattern\fP matches at least one of the strings in the value\&. +.RE +.TP +.PD 0 +\fBzformat \-f\fP \fIparam\fP \fIformat\fP \fIspec\fP \&.\&.\&. +.TP +.PD 0 +\fBzformat \-F\fP \fIparam\fP \fIformat\fP \fIspec\fP \&.\&.\&. +.TP +.PD +\fBzformat \-a\fP \fIarray\fP \fIsep\fP \fIspec\fP \&.\&.\&. +This builtin provides different forms of formatting\&. The first form +is selected with the \fB\-f\fP option\&. In this case the \fIformat\fP +string will be modified by replacing sequences starting with a percent +sign in it with strings from the \fIspec\fPs\&. Each \fIspec\fP should be +of the form `\fIchar\fP\fB:\fP\fIstring\fP\&' which will cause every +appearance of the sequence `\fB%\fP\fIchar\fP\&' in \fIformat\fP to be replaced +by the \fIstring\fP\&. The `\fB%\fP\&' sequence may also contain optional +minimum and maximum field width specifications between the `\fB%\fP\&' and +the `\fIchar\fP\&' in the form `\fB%\fP\fImin\fP\fB\&.\fP\fImax\fP\fBc\fP', +i\&.e\&. the minimum field width is given first and if the maximum field +width is used, it has to be preceded by a dot\&. Specifying a minimum field +width makes the result be padded with spaces to the right if the +\fIstring\fP is shorter than the requested width\&. Padding to the left +can be achieved by giving a negative minimum field width\&. If a maximum +field width is specified, the \fIstring\fP will be truncated after that +many characters\&. After all `\fB%\fP\&' sequences for the given \fIspec\fPs +have been processed, the resulting string is stored in the parameter +\fIparam\fP\&. +.RS +.PP +The \fB%\fP\-escapes also understand ternary expressions in the form used by +prompts\&. The \fB%\fP is followed by a `\fB(\fP\&' and then an ordinary +format specifier character as described above\&. There may be a set of +digits either before or after the `\fB(\fP\&'; these specify a test +number, which defaults to zero\&. Negative numbers are also allowed\&. An +arbitrary delimiter character follows the format specifier, which is +followed by a piece of `true\&' text, the delimiter character again, a piece +of `false\&' text, and a closing parenthesis\&. The complete expression +(without the digits) thus looks like +`\fB%(\fP\fIX\fP\fB\&.\fP\fItext1\fP\fB\&.\fP\fItext2\fP\fB)\fP\&', except that +the `\fB\&.\fP\&' character is arbitrary\&. The value given for the format +specifier in the \fIchar\fP\fB:\fP\fIstring\fP expressions is evaluated as a +mathematical expression, and compared with the test number\&. If they are +the same, \fItext1\fP is output, else \fItext2\fP is output\&. A parenthesis +may be escaped in \fItext2\fP as \fB%)\fP\&. Either of \fItext1\fP or +\fItext2\fP may contain nested \fB%\fP\-escapes\&. +.PP +For example: +.PP +.RS +.nf +\fBzformat \-f REPLY "The answer is \&'%3(c\&.yes\&.no)'\&." c:3\fP +.fi +.RE +.PP +outputs "The answer is \&'yes'\&." to \fBREPLY\fP since the value for the format +specifier \fBc\fP is 3, agreeing with the digit argument to the ternary +expression\&. +.PP +With \fB\-F\fP instead of \fB\-f\fP, ternary expressions choose between the +`true\&' or `false' text on the basis of whether the format specifier is +present and non\-empty\&. A test number indicates a minimum width for the +value given in the format specifier\&. Negative numbers reverse this, +so the test is for whether the value exceeds a maximum width\&. +.PP +The form, using the \fB\-a\fP option, can be used for aligning +strings\&. Here, the \fIspec\fPs are of the form +`\fIleft\fP\fB:\fP\fIright\fP\&' where `\fIleft\fP' and `\fIright\fP' are +arbitrary strings\&. These strings are modified by replacing the colons +by the \fIsep\fP string and padding the \fIleft\fP strings with spaces +to the right so that the \fIsep\fP strings in the result (and hence the +\fIright\fP strings after them) are all aligned if the strings are +printed below each other\&. All strings without a colon are left +unchanged and all strings with an empty \fIright\fP string have the +trailing colon removed\&. In both cases the lengths of the strings +are not used to determine how the other strings are to be aligned\&. +A colon in the \fIleft\fP string can be escaped with a backslash\&. +The resulting strings are stored in the \fIarray\fP\&. +.RE +.TP +\fBzregexparse\fP +This implements some internals of the \fB_regex_arguments\fP function\&. +.TP +\fBzparseopts\fP [ \fB\-D\fP \fB\-E\fP \fB\-F\fP \fB\-K\fP \fB\-M\fP ] [ \fB\-a\fP \fIarray\fP ] [ \fB\-A\fP \fIassoc\fP ] [ \fB\-\fP ] \fIspec\fP \&.\&.\&. +This builtin simplifies the parsing of options in positional parameters, +i\&.e\&. the set of arguments given by \fB$*\fP\&. Each \fIspec\fP describes one +option and must be of the form `\fIopt\fP[\fB=\fP\fIarray\fP]\&'\&. If an option +described by \fIopt\fP is found in the positional parameters it is copied +into the \fIarray\fP specified with the \fB\-a\fP option; if the optional +`\fB=\fP\fIarray\fP\&' is given, it is instead copied into that array, which +should be declared as a normal array and never as an associative array\&. +.RS +.PP +Note that it is an error to give any \fIspec\fP without an +`\fB=\fP\fIarray\fP\&' unless one of the \fB\-a\fP or \fB\-A\fP options is used\&. +.PP +Unless the \fB\-E\fP option is given, parsing stops at the first string +that isn\&'t described by one of the \fIspec\fPs\&. Even with \fB\-E\fP, +parsing always stops at a positional parameter equal to `\fB\-\fP\&' or +`\fB\-\fP\fB\-\fP\&'\&. See also \fB\-F\fP\&. +.PP +The \fIopt\fP description must be one of the following\&. Any of the special +characters can appear in the option name provided it is preceded by a +backslash\&. +.PP +.PD 0 +.TP +.PD 0 +\fIname\fP +.TP +.PD +\fIname\fP\fB+\fP +The \fIname\fP is the name of the option without the leading `\fB\-\fP\&'\&. To +specify a GNU\-style long option, one of the usual two leading `\fB\-\fP\&' must +be included in \fIname\fP; for example, a `\fB\-\fP\fB\-file\fP\&' option is +represented by a \fIname\fP of `\fB\-file\fP\&'\&. +.RS +.PP +If a `\fB+\fP\&' appears after \fIname\fP, the option is appended to \fIarray\fP +each time it is found in the positional parameters; without the `\fB+\fP\&' +only the \fIlast\fP occurrence of the option is preserved\&. +.PP +If one of these forms is used, the option takes no argument, so parsing +stops if the next positional parameter does not also begin with `\fB\-\fP\&' +(unless the \fB\-E\fP option is used)\&. +.RE +.TP +.PD 0 +\fIname\fP\fB:\fP +.TP +.PD 0 +\fIname\fP\fB:\-\fP +.TP +.PD +\fIname\fP\fB::\fP +If one or two colons are given, the option takes an argument; with one +colon, the argument is mandatory and with two colons it is optional\&. The +argument is appended to the \fIarray\fP after the option itself\&. +.RS +.PP +An optional argument is put into the same array element as the option name +(note that this makes empty strings as arguments indistinguishable)\&. A +mandatory argument is added as a separate element unless the `\fB:\-\fP\&' form +is used, in which case the argument is put into the same element\&. +.PP +A `\fB+\fP\&' as described above may appear between the \fIname\fP and the +first colon\&. +.RE +.PP +In all cases, option\-arguments must appear either immediately following the +option in the same positional parameter or in the next one\&. Even an optional +argument may appear in the next parameter, unless it begins with a `\fB\-\fP\&'\&. +There is no special handling of `\fB=\fP\&' as with GNU\-style argument parsers; +given the \fIspec\fP `\fB\-foo:\fP\&', the positional parameter `\fB\-\fP\fB\-foo=bar\fP' +is parsed as `\fB\-\fP\fB\-foo\fP\&' with an argument of `\fB=bar\fP'\&. +.PP +When the names of two options that take no arguments overlap, the longest one +wins, so that parsing for the \fIspec\fPs `\fB\-foo \-foobar\fP\&' (for example) is +unambiguous\&. However, due to the aforementioned handling of option\-arguments, +ambiguities may arise when at least one overlapping \fIspec\fP takes an +argument, as in `\fB\-foo: \-foobar\fP\&'\&. In that case, the last matching +\fIspec\fP wins\&. +.PP +The options of \fBzparseopts\fP itself cannot be stacked because, for +example, the stack `\fB\-DEK\fP\&' is indistinguishable from a \fIspec\fP for +the GNU\-style long option `\fB\-\fP\fB\-DEK\fP\&'\&. The options of \fBzparseopts\fP +itself are: +.PP +.PD 0 +.TP +.PD +\fB\-a\fP \fIarray\fP +As described above, this names the default array in which to store the +recognised options\&. +.TP +\fB\-A\fP \fIassoc\fP +If this is given, the options and their values are also put into an +associative array with the option names as keys and the arguments (if any) +as the values\&. +.TP +\fB\-D\fP +If this option is given, all options found are removed from the positional +parameters of the calling shell or shell function, up to but not including +any not described by the \fIspec\fPs\&. If the first such parameter is `\fB\-\fP\&' +or `\fB\-\fP\fB\-\fP\&', it is removed as well\&. This is similar to using the +\fBshift\fP builtin\&. +.TP +\fB\-E\fP +This changes the parsing rules to \fInot\fP stop at the first string +that isn\&'t described by one of the \fIspec\fPs\&. It can be used to test +for or (if used together with \fB\-D\fP) extract options and their +arguments, ignoring all other options and arguments that may be in the +positional parameters\&. As indicated above, parsing still stops at the +first `\fB\-\fP\&' or `\fB\-\fP\fB\-\fP' not described by a \fIspec\fP, but it is not +removed when used with \fB\-D\fP\&. +.TP +\fB\-F\fP +If this option is given, \fBzparseopts\fP immediately stops at the first +option\-like parameter not described by one of the \fIspec\fPs, prints an +error message, and returns status 1\&. Removal (\fB\-D\fP) and extraction +(\fB\-E\fP) are not performed, and option arrays are not updated\&. This +provides basic validation for the given options\&. +.RS +.PP +Note that the appearance in the positional parameters of an option without +its required argument always aborts parsing and returns an error as described +above regardless of whether this option is used\&. +.RE +.TP +\fB\-K\fP +With this option, the arrays specified with the \fB\-a\fP option and with the +`\fB=\fP\fIarray\fP\&' forms are kept unchanged when none of the \fIspec\fPs for +them is used\&. Otherwise the entire array is replaced when any of the +\fIspec\fPs is used\&. Individual elements of associative arrays specified +with the \fB\-A\fP option are preserved by \fB\-K\fP\&. This allows assignment of +default values to arrays before calling \fBzparseopts\fP\&. +.TP +\fB\-M\fP +This changes the assignment rules to implement a map among equivalent +option names\&. If any \fIspec\fP uses the `\fB=\fP\fIarray\fP\&' form, the +string \fIarray\fP is interpreted as the name of another \fIspec\fP, +which is used to choose where to store the values\&. If no other \fIspec\fP +is found, the values are stored as usual\&. This changes only the way the +values are stored, not the way \fB$*\fP is parsed, so results may be +unpredictable if the `\fIname\fP\fB+\fP\&' specifier is used inconsistently\&. +.PP +For example, +.PP +.RS +.nf +\fBset \-\- \-a \-bx \-c y \-cz baz \-cend +zparseopts a=foo b:=bar c+:=bar\fP +.fi +.RE +.PP +will have the effect of +.PP +.RS +.nf +\fBfoo=(\-a) +bar=(\-b x \-c y \-c z)\fP +.fi +.RE +.PP +The arguments from `\fBbaz\fP\&' on will not be used\&. +.PP +As an example for the \fB\-E\fP option, consider: +.PP +.RS +.nf +\fBset \-\- \-a x \-b y \-c z arg1 arg2 +zparseopts \-E \-D b:=bar\fP +.fi +.RE +.PP +will have the effect of +.PP +.RS +.nf +\fBbar=(\-b y) +set \-\- \-a x \-c z arg1 arg2\fP +.fi +.RE +.PP +I\&.e\&., the option \fB\-b\fP and its arguments are taken from the +positional parameters and put into the array \fBbar\fP\&. +.PP +The \fB\-M\fP option can be used like this: +.PP +.RS +.nf +\fBset \-\- \-a \-bx \-c y \-cz baz \-cend +zparseopts \-A bar \-M a=foo b+: c:=b\fP +.fi +.RE +.PP +to have the effect of +.PP +.RS +.nf +\fBfoo=(\-a) +bar=(\-a \&'' \-b xyz)\fP +.fi +.RE +.RE diff --git a/Doc/zshoptions.1 b/Doc/zshoptions.1 new file mode 100644 index 000000000..e37a1315c --- /dev/null +++ b/Doc/zshoptions.1 @@ -0,0 +1,2049 @@ +.TH "ZSHOPTIONS" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshoptions \- zsh options +.\" Yodl file: Zsh/options.yo +.SH "SPECIFYING OPTIONS" +Options are primarily referred to by name\&. +These names are case insensitive and underscores are ignored\&. +For example, `\fBallexport\fP\&' is equivalent to `\fBA__lleXP_ort\fP'\&. +.PP +The sense of an option name may be inverted by preceding it with +`\fBno\fP\&', so `\fBsetopt No_Beep\fP' is equivalent to `\fBunsetopt beep\fP'\&. +This inversion can only be done once, so `\fBnonobeep\fP\&' is \fInot\fP +a synonym for `\fBbeep\fP\&'\&. Similarly, `\fBtify\fP' is not a synonym for +`\fBnonotify\fP\&' (the inversion of `\fBnotify\fP')\&. +.PP +Some options also have one or more single letter names\&. +There are two sets of single letter options: one used by default, +and another used to emulate \fBsh\fP/\fBksh\fP (used when the +\fBSH_OPTION_LETTERS\fP option is set)\&. +The single letter options can be used on the shell command line, +or with the \fBset\fP, \fBsetopt\fP and \fBunsetopt\fP +builtins, as normal Unix options preceded by `\fB\-\fP\&'\&. +.PP +The sense of the single letter options may be inverted by using +`\fB+\fP\&' instead of `\fB\-\fP'\&. +Some of the single letter option names refer to an option being off, +in which case the inversion of that name refers to the option being on\&. +For example, `\fB+n\fP\&' is the short name of `\fBexec\fP', and +`\fB\-n\fP\&' is the short name of its inversion, `\fBnoexec\fP'\&. +.PP +In strings of single letter options supplied to the shell at startup, +trailing whitespace will be ignored; for example the string `\fB\-f \fP\&' +will be treated just as `\fB\-f\fP\&', but the string `\fB\-f i\fP' is an error\&. +This is because many systems which implement the `\fB#!\fP\&' mechanism for +calling scripts do not strip trailing whitespace\&. +.PP +It is possible for options to be set within a function scope\&. See the +description of the option \fBLOCAL_OPTIONS\fP below\&. +.PP +.SH "DESCRIPTION OF OPTIONS" +In the following list, options set by default in all emulations are marked +<D>; those set by default only in csh, ksh, sh, or zsh emulations are marked +<C>, <K>, <S>, <Z> as appropriate\&. When listing options (by `\fBsetopt\fP\&', +`\fBunsetopt\fP\&', `\fBset \-o\fP' or `\fBset +o\fP'), those turned on by default +appear in the list prefixed with `\fBno\fP\&'\&. Hence (unless +\fBKSH_OPTION_PRINT\fP is set), `\fBsetopt\fP\&' shows all options whose settings +are changed from the default\&. +.PP +.SS "Changing Directories" +.PD 0 +.TP +.PD +\fBAUTO_CD\fP (\fB\-J\fP) +If a command is issued that can\&'t be executed as a normal command, +and the command is the name of a directory, perform the \fBcd\fP +command to that directory\&. +This option is only applicable if the option \fBSHIN_STDIN\fP is set, +i\&.e\&. if commands are being read from standard input\&. The option +is designed for interactive use; it is recommended that \fBcd\fP +be used explicitly in scripts to avoid ambiguity\&. +.TP +\fBAUTO_PUSHD\fP (\fB\-N\fP) +Make \fBcd\fP push the old directory onto the directory stack\&. +.TP +\fBCDABLE_VARS\fP (\fB\-T\fP) +If the argument to a \fBcd\fP command (or an implied \fBcd\fP with the +\fBAUTO_CD\fP option set) is not a directory, and does not begin with a +slash, try to expand the expression as if it were preceded by a `\fB~\fP\&' (see +the section `Filename Expansion\&')\&. +.TP +\fBCD_SILENT\fP +Never print the working directory after a \fBcd\fP (whether explicit or +implied with the \fBAUTO_CD\fP option set)\&. \fBcd\fP normally prints the +working directory when the argument given to it was \fB\-\fP, a stack entry, or +the name of a directory found under \fBCDPATH\fP\&. Note that this is distinct +from \fBpushd\fP\&'s stack\-printing behaviour, which is controlled by +\fBPUSHD_SILENT\fP\&. This option overrides the printing\-related effects of +\fBPOSIX_CD\fP\&. +.TP +\fBCHASE_DOTS\fP +When changing to a directory containing a path segment `\fB\&.\&.\fP\&' which would +otherwise be treated as canceling the previous segment in the path (in +other words, `\fBfoo/\&.\&.\fP\&' would be removed from the path, or if `\fB\&.\&.\fP' is +the first part of the path, the last part of the current working directory +would be removed), instead resolve the path to the physical directory\&. +This option is overridden by \fBCHASE_LINKS\fP\&. +.RS +.PP +For example, suppose \fB/foo/bar\fP is a link to the directory \fB/alt/rod\fP\&. +Without this option set, `\fBcd /foo/bar/\&.\&.\fP\&' changes to \fB/foo\fP; with it +set, it changes to \fB/alt\fP\&. The same applies if the current directory +is \fB/foo/bar\fP and `\fBcd \&.\&.\fP\&' is used\&. Note that all other symbolic +links in the path will also be resolved\&. +.RE +.TP +\fBCHASE_LINKS\fP (\fB\-w\fP) +Resolve symbolic links to their true values when changing directory\&. +This also has the effect of \fBCHASE_DOTS\fP, i\&.e\&. a `\fB\&.\&.\fP\&' path segment +will be treated as referring to the physical parent, even if the preceding +path segment is a symbolic link\&. +.TP +\fBPOSIX_CD\fP <K> <S> +Modifies the behaviour of \fBcd\fP, \fBchdir\fP and \fBpushd\fP commands +to make them more compatible with the POSIX standard\&. The behaviour with +the option unset is described in the documentation for the \fBcd\fP +builtin in +\fIzshbuiltins\fP(1)\&. +If the option is set, the shell does not test for directories beneath +the local directory (`\fB\&.\fP\&') until after all directories in \fBcdpath\fP +have been tested, and the \fBcd\fP and \fBchdir\fP commands do not recognise +arguments of the form `{\fB+\fP|\fB\-\fP}\fIn\fP\&' as directory stack entries\&. +.RS +.PP +Also, if the option is set, the conditions under which the shell +prints the new directory after changing to it are modified\&. It is +no longer restricted to interactive shells (although printing of +the directory stack with \fBpushd\fP is still limited to interactive +shells); and any use of a component of \fBCDPATH\fP, including a `\fB\&.\fP\&' but +excluding an empty component that is otherwise treated as `\fB\&.\fP\&', causes +the directory to be printed\&. +.RE +.TP +\fBPUSHD_IGNORE_DUPS\fP +Don\&'t push multiple copies of the same directory onto the directory stack\&. +.TP +\fBPUSHD_MINUS\fP +Exchanges the meanings of `\fB+\fP\&' and `\fB\-\fP' +when used with a number to specify a directory in the stack\&. +.TP +\fBPUSHD_SILENT\fP (\fB\-E\fP) +Do not print the directory stack after \fBpushd\fP or \fBpopd\fP\&. +.TP +\fBPUSHD_TO_HOME\fP (\fB\-D\fP) +Have \fBpushd\fP with no arguments act like `\fBpushd $HOME\fP\&'\&. +.PP +.SS "Completion" +.PD 0 +.TP +.PD +\fBALWAYS_LAST_PROMPT\fP <D> +If unset, key functions that list completions try to return to the last +prompt if given a numeric argument\&. If set these functions try to +return to the last prompt if given \fIno\fP numeric argument\&. +.TP +\fBALWAYS_TO_END\fP +If a completion is performed with the cursor within a word, and a +full completion is inserted, the cursor is moved to the end of the +word\&. That is, the cursor is moved to the end of the word if either +a single match is inserted or menu completion is performed\&. +.TP +\fBAUTO_LIST\fP (\fB\-9\fP) <D> +Automatically list choices on an ambiguous completion\&. +.TP +\fBAUTO_MENU\fP <D> +Automatically use menu completion after the second consecutive request for +completion, for example by pressing the tab key repeatedly\&. This option +is overridden by \fBMENU_COMPLETE\fP\&. +.TP +\fBAUTO_NAME_DIRS\fP +Any parameter that is set to the absolute name of a directory +immediately becomes a name for that directory, that will be used +by the `\fB%~\fP\&' +and related prompt sequences, and will be available when completion +is performed on a word starting with `\fB~\fP\&'\&. +(Otherwise, the parameter must be used in the form `\fB~\fP\fIparam\fP\&' first\&.) +.TP +\fBAUTO_PARAM_KEYS\fP <D> +If a parameter name was completed and a following character +(normally a space) automatically +inserted, and the next character typed is one +of those that have to come directly after the name (like `\fB}\fP\&', `\fB:\fP', +etc\&.), the automatically added character is deleted, so that the character +typed comes immediately after the parameter name\&. +Completion in a brace expansion is affected similarly: the added character +is a `\fB,\fP\&', which will be removed if `\fB}\fP' is typed next\&. +.TP +\fBAUTO_PARAM_SLASH\fP <D> +If a parameter is completed whose content is the name of a directory, +then add a trailing slash instead of a space\&. +.TP +\fBAUTO_REMOVE_SLASH\fP <D> +When the last character resulting from a completion is a slash and the next +character typed is a word delimiter, a slash, or a character that ends +a command (such as a semicolon or an ampersand), remove the slash\&. +.TP +\fBBASH_AUTO_LIST\fP +On an ambiguous completion, automatically list choices when the +completion function is called twice in succession\&. This takes +precedence over \fBAUTO_LIST\fP\&. The setting of \fBLIST_AMBIGUOUS\fP is +respected\&. If \fBAUTO_MENU\fP is set, the menu behaviour will then start +with the third press\&. Note that this will not work with +\fBMENU_COMPLETE\fP, since repeated completion calls immediately cycle +through the list in that case\&. +.TP +\fBCOMPLETE_ALIASES\fP +Prevents aliases on the command line from being internally substituted +before completion is attempted\&. The effect is to make the alias a +distinct command for completion purposes\&. +.TP +\fBCOMPLETE_IN_WORD\fP +If unset, the cursor is set to the end of the word if completion is +started\&. Otherwise it stays there and completion is done from both ends\&. +.TP +\fBGLOB_COMPLETE\fP +When the current word has a glob pattern, do not insert all the words +resulting from the expansion but generate matches as for completion and +cycle through them like \fBMENU_COMPLETE\fP\&. The matches are generated as if +a `\fB*\fP\&' was added to the end of the word, or inserted at the cursor when +\fBCOMPLETE_IN_WORD\fP is set\&. This actually uses pattern matching, not +globbing, so it works not only for files but for any completion, such as +options, user names, etc\&. +.RS +.PP +Note that when the pattern matcher is used, matching control (for example, +case\-insensitive or anchored matching) cannot be used\&. This limitation +only applies when the current word contains a pattern; simply turning +on the \fBGLOB_COMPLETE\fP option does not have this effect\&. +.RE +.TP +\fBHASH_LIST_ALL\fP <D> +Whenever a command completion or spelling correction is attempted, make +sure the entire command path is hashed first\&. This makes the first +completion slower but avoids false reports of spelling errors\&. +.TP +\fBLIST_AMBIGUOUS\fP <D> +This option works when \fBAUTO_LIST\fP or \fBBASH_AUTO_LIST\fP is also +set\&. If there is an unambiguous prefix to insert on the command line, +that is done without a completion list being displayed; in other +words, auto\-listing behaviour only takes place when nothing would be +inserted\&. In the case of \fBBASH_AUTO_LIST\fP, this means that the list +will be delayed to the third call of the function\&. +.TP +\fBLIST_BEEP\fP <D> +Beep on an ambiguous completion\&. More accurately, this forces the +completion widgets to return status 1 on an ambiguous completion, which +causes the shell to beep if the option \fBBEEP\fP is also set; this may +be modified if completion is called from a user\-defined widget\&. +.TP +\fBLIST_PACKED\fP +Try to make the completion list smaller (occupying less lines) by +printing the matches in columns with different widths\&. +.TP +\fBLIST_ROWS_FIRST\fP +Lay out the matches in completion lists sorted horizontally, that is, +the second match is to the right of the first one, not under it as +usual\&. +.TP +\fBLIST_TYPES\fP (\fB\-X\fP) <D> +When listing files that are possible completions, show the +type of each file with a trailing identifying mark\&. +.TP +\fBMENU_COMPLETE\fP (\fB\-Y\fP) +On an ambiguous completion, instead of listing possibilities or beeping, +insert the first match immediately\&. Then when completion is requested +again, remove the first match and insert the second match, etc\&. +When there are no more matches, go back to the first one again\&. +\fBreverse\-menu\-complete\fP may be used to loop through the list +in the other direction\&. This option overrides \fBAUTO_MENU\fP\&. +.TP +\fBREC_EXACT\fP (\fB\-S\fP) +If the string on the command line exactly matches one of the possible +completions, it is accepted, even if there is another completion (i\&.e\&. that +string with something else added) that also matches\&. +.PP +.SS "Expansion and Globbing" +.PD 0 +.TP +.PD +\fBBAD_PATTERN\fP (\fB+2\fP) <C> <Z> +If a pattern for filename generation is badly formed, print an error message\&. +(If this option is unset, the pattern will be left unchanged\&.) +.TP +\fBBARE_GLOB_QUAL\fP <Z> +In a glob pattern, treat a trailing set of parentheses as a qualifier +list, if it contains no `\fB|\fP\&', `\fB(\fP' or (if special) `\fB~\fP' +characters\&. See the section `Filename Generation\&'\&. +.TP +\fBBRACE_CCL\fP +Expand expressions in braces which would not otherwise undergo brace +expansion to a lexically ordered list of all the characters\&. See +the section `Brace Expansion\&'\&. +.TP +\fBCASE_GLOB\fP <D> +Make globbing (filename generation) sensitive to case\&. Note that other +uses of patterns are always sensitive to case\&. If the option is unset, +the presence of any character which is special to filename generation +will cause case\-insensitive matching\&. For example, \fBcvs(/)\fP +can match the directory \fBCVS\fP owing to the presence of the globbing flag +(unless the option \fBBARE_GLOB_QUAL\fP is unset)\&. +.TP +\fBCASE_MATCH\fP <D> +Make regular expressions using the \fBzsh/regex\fP module (including +matches with \fB=~\fP) sensitive to case\&. +.TP +\fBCASE_PATHS\fP +If \fBCASE_PATHS\fP is not set (the default), \fBCASE_GLOB\fP affects the +interpretation of \fIevery\fP path component, whenever a special +character appears in \fIany\fP component\&. When \fBCASE_PATHS\fP is set, +file path components that do \fInot\fP contain special filename +generation characters are always sensitive to case, thus restricting +\fBNO_CASE_GLOB\fP to components that contain globbing characters\&. +.RS +.PP +Note that if the filesystem itself is not sensitive to case, then +\fBCASE_PATHS\fP has no effect\&. +.RE +.TP +\fBCSH_NULL_GLOB\fP <C> +If a pattern for filename generation has no matches, +delete the pattern from the argument list; +do not report an error unless all the patterns +in a command have no matches\&. +Overrides \fBNOMATCH\fP\&. +.TP +\fBEQUALS\fP <Z> +Perform \fB=\fP filename expansion\&. +(See the section `Filename Expansion\&'\&.) +.TP +\fBEXTENDED_GLOB\fP +Treat the `\fB#\fP\&', `\fB~\fP' and `\fB^\fP' characters as part of patterns +for filename generation, etc\&. (An initial unquoted `\fB~\fP\&' +always produces named directory expansion\&.) +.TP +\fBFORCE_FLOAT\fP +Constants in arithmetic evaluation will be treated as +floating point even without the use of a decimal point; the +values of integer variables will be converted to floating point when +used in arithmetic expressions\&. Integers in any base will be converted\&. +.TP +\fBGLOB\fP (\fB+F\fP, ksh: \fB+f\fP) <D> +Perform filename generation (globbing)\&. +(See the section `Filename Generation\&'\&.) +.TP +\fBGLOB_ASSIGN\fP <C> +If this option is set, filename generation (globbing) is +performed on the right hand side of scalar parameter assignments of +the form `\fIname\fP\fB=\fP\fIpattern\fP (e\&.g\&. `\fBfoo=*\fP\&')\&. +If the result has more than one word the parameter will become an array +with those words as arguments\&. This option is provided for backwards +compatibility only: globbing is always performed on the right hand side +of array assignments of the form `\fIname\fP\fB=(\fP\fIvalue\fP\fB)\fP\&' +(e\&.g\&. `\fBfoo=(*)\fP\&') and this form is recommended for clarity; +with this option set, it is not possible to predict whether the result +will be an array or a scalar\&. +.TP +\fBGLOB_DOTS\fP (\fB\-4\fP) +Do not require a leading `\fB\&.\fP\&' in a filename to be matched explicitly\&. +.TP +\fBGLOB_STAR_SHORT\fP +When this option is set and the default zsh\-style globbing is in +effect, the pattern `\fB**/*\fP\&' can be abbreviated to `\fB**\fP' and the +pattern `\fB***/*\fP\&' can be abbreviated to \fB***\fP\&. Hence `\fB**\&.c\fP' +finds a file ending in \fB\&.c\fP in any subdirectory, and `\fB***\&.c\fP\&' does +the same while also following symbolic links\&. A \fB/\fP immediately +after the `\fB**\fP\&' or `\fB***\fP' forces the pattern to be treated as the +unabbreviated form\&. +.TP +\fBGLOB_SUBST\fP <C> <K> <S> +Treat any characters resulting from parameter expansion as being +eligible for filename expansion and filename generation, and any +characters resulting from command substitution as being eligible for +filename generation\&. Braces (and commas in between) do not become eligible +for expansion\&. +.TP +\fBHIST_SUBST_PATTERN\fP +Substitutions using the \fB:s\fP and \fB:&\fP history modifiers are performed +with pattern matching instead of string matching\&. This occurs wherever +history modifiers are valid, including glob qualifiers and parameters\&. +See +the section `Modifiers\&' in \fIzshexpn\fP(1)\&. +.TP +\fBIGNORE_BRACES\fP (\fB\-I\fP) <S> +Do not perform brace expansion\&. For historical reasons this +also includes the effect of the \fBIGNORE_CLOSE_BRACES\fP option\&. +.TP +\fBIGNORE_CLOSE_BRACES\fP +When neither this option nor \fBIGNORE_BRACES\fP is set, a sole +close brace character `\fB}\fP\&' is syntactically significant at any +point on a command line\&. This has the effect that no semicolon +or newline is necessary before the brace terminating a function +or current shell construct\&. When either option is set, a closing brace +is syntactically significant only in command position\&. Unlike +\fBIGNORE_BRACES\fP, this option does not disable brace expansion\&. +.RS +.PP +For example, with both options unset a function may be defined +in the following fashion: +.PP +.RS +.nf +\fBargs() { echo $# }\fP +.fi +.RE +.PP +while if either option is set, this does not work and something +equivalent to the following is required: +.PP +.RS +.nf +\fBargs() { echo $#; }\fP +.fi +.RE +.PP +.RE +.TP +\fBKSH_GLOB\fP <K> +In pattern matching, the interpretation of parentheses is affected by +a preceding `\fB@\fP\&', `\fB*\fP', `\fB+\fP', `\fB?\fP' or `\fB!\fP'\&. +See the section `Filename Generation\&'\&. +.TP +\fBMAGIC_EQUAL_SUBST\fP +All unquoted arguments of the form `\fIanything\fP\fB=\fP\fIexpression\fP\&' +appearing after the command name have filename expansion (that is, +where \fIexpression\fP has a leading `\fB~\fP\&' or `\fB=\fP') performed on +\fIexpression\fP as if it were a parameter assignment\&. The argument is +not otherwise treated specially; it is passed to the command as a single +argument, and not used as an actual parameter assignment\&. For example, in +\fBecho foo=~/bar:~/rod\fP, both occurrences of \fB~\fP would be replaced\&. +Note that this happens anyway with \fBtypeset\fP and similar statements\&. +.RS +.PP +This option respects the setting of the \fBKSH_TYPESET\fP option\&. In other +words, if both options are in effect, arguments looking like +assignments will not undergo word splitting\&. +.RE +.TP +\fBMARK_DIRS\fP (\fB\-8\fP, ksh: \fB\-X\fP) +Append a trailing `\fB/\fP\&' to all directory +names resulting from filename generation (globbing)\&. +.TP +\fBMULTIBYTE\fP <D> +Respect multibyte characters when found in strings\&. +When this option is set, strings are examined using the +system library to determine how many bytes form a character, depending +on the current locale\&. This affects the way characters are counted in +pattern matching, parameter values and various delimiters\&. +.RS +.PP +The option is on by default if the shell was compiled with +\fBMULTIBYTE_SUPPORT\fP; otherwise it is off by default and has no effect +if turned on\&. +.PP +If the option is off a single byte is always treated as a single +character\&. This setting is designed purely for examining strings +known to contain raw bytes or other values that may not be characters +in the current locale\&. It is not necessary to unset the option merely +because the character set for the current locale does not contain multibyte +characters\&. +.PP +The option does not affect the shell\&'s editor, which always uses the +locale to determine multibyte characters\&. This is because +the character set displayed by the terminal emulator is independent of +shell settings\&. +.RE +.TP +\fBNOMATCH\fP (\fB+3\fP) <C> <Z> +If a pattern for filename generation has no matches, +print an error, instead of +leaving it unchanged in the argument list\&. +This also applies to file expansion +of an initial `\fB~\fP\&' or `\fB=\fP'\&. +.TP +\fBNULL_GLOB\fP (\fB\-G\fP) +If a pattern for filename generation has no matches, +delete the pattern from the argument list instead +of reporting an error\&. Overrides \fBNOMATCH\fP\&. +.TP +\fBNUMERIC_GLOB_SORT\fP +If numeric filenames are matched by a filename generation pattern, +sort the filenames numerically rather than lexicographically\&. +.TP +\fBRC_EXPAND_PARAM\fP (\fB\-P\fP) +Array expansions of the form +`\fIfoo\fP\fB${\fP\fIxx\fP\fB}\fP\fIbar\fP\&', where the parameter +\fIxx\fP is set to \fB(\fP\fIa b c\fP\fB)\fP, are substituted with +`\fIfooabar foobbar foocbar\fP\&' instead of the default +`\fIfooa b cbar\fP\&'\&. Note that an empty array will therefore cause +all arguments to be removed\&. +.TP +\fBREMATCH_PCRE\fP +If set, regular expression matching with the \fB=~\fP operator will use +Perl\-Compatible Regular Expressions from the PCRE library\&. +(The \fBzsh/pcre\fP module must be available\&.) +If not set, regular expressions will use the extended regexp syntax +provided by the system libraries\&. +.TP +\fBSH_GLOB\fP <K> <S> +Disables the special meaning of `\fB(\fP\&', `\fB|\fP', `\fB)\fP' +and \&'\fB<\fP' for globbing the result of parameter and command substitutions, +and in some other places where +the shell accepts patterns\&. If \fBSH_GLOB\fP is set but \fBKSH_GLOB\fP is +not, the shell allows the interpretation of +subshell expressions enclosed in parentheses in some cases where there +is no space before the opening parenthesis, e\&.g\&. \fB!(true)\fP +is interpreted as if there were a space after the \fB!\fP\&. This option is +set by default if zsh is invoked as \fBsh\fP or \fBksh\fP\&. +.TP +\fBUNSET\fP (\fB+u\fP, ksh: \fB+u\fP) <K> <S> <Z> +Treat unset parameters as if they were empty when substituting, and as if +they were zero when reading their values in arithmetic expansion and +arithmetic commands\&. +Otherwise they are treated as an error\&. +.TP +\fBWARN_CREATE_GLOBAL\fP +Print a warning message when a global parameter is created in a function +by an assignment or in math context\&. +This often indicates that a parameter has not been +declared local when it should have been\&. Parameters explicitly declared +global from within a function using \fBtypeset \-g\fP do not cause a warning\&. +Note that there is no warning when a local parameter is assigned to in +a nested function, which may also indicate an error\&. +.TP +\fBWARN_NESTED_VAR\fP +Print a warning message when an existing parameter from an +enclosing function scope, or global, is set in a function +by an assignment or in math context\&. Assignment to shell +special parameters does not cause a warning\&. This is the companion +to \fBWARN_CREATE_GLOBAL\fP as in this case the warning is only +printed when a parameter is \fInot\fP created\&. Where possible, +use of \fBtypeset \-g\fP to set the parameter suppresses the error, +but note that this needs to be used every time the parameter is set\&. +To restrict the effect of this option to a single function scope, +use `\fBfunctions \-W\fP\&'\&. +.RS +.PP +For example, the following code produces a warning for the assignment +inside the function \fBnested\fP as that overrides the value within +\fBtoplevel\fP +.PP +.RS +.nf +\fBtoplevel() { + local foo="in fn" + nested +} +nested() { + foo="in nested" +} +setopt warn_nested_var +toplevel\fP +.fi +.RE +.RE +.PP +.SS "History" +.PD 0 +.TP +.PD +\fBAPPEND_HISTORY\fP <D> +If this is set, zsh sessions will append their history list to +the history file, rather than replace it\&. Thus, multiple parallel +zsh sessions will all have the new entries from their history lists +added to the history file, in the order that they exit\&. +The file will still be periodically re\-written to trim it when the +number of lines grows 20% beyond the value specified by +\fB$SAVEHIST\fP (see also the \fBHIST_SAVE_BY_COPY\fP option)\&. +.TP +\fBBANG_HIST\fP (\fB+K\fP) <C> <Z> +Perform textual history expansion, \fBcsh\fP\-style, +treating the character `\fB!\fP\&' specially\&. +.TP +\fBEXTENDED_HISTORY\fP <C> +Save each command\&'s beginning timestamp (in seconds since the epoch) +and the duration (in seconds) to the history file\&. The format of +this prefixed data is: +.RS +.PP +`\fB: \fP\fI<beginning time>\fP\fB:\fP\fI<elapsed seconds>\fP\fB;\fP\fI<command>\fP\&'\&. +.RE +.TP +\fBHIST_ALLOW_CLOBBER\fP +Add `\fB|\fP\&' to output redirections in the history\&. This allows history +references to clobber files even when \fBCLOBBER\fP is unset\&. +.TP +\fBHIST_BEEP\fP <D> +Beep in ZLE when a widget attempts to access a history entry which +isn\&'t there\&. +.TP +\fBHIST_EXPIRE_DUPS_FIRST\fP +If the internal history needs to be trimmed to add the current command line, +setting this option will cause the oldest history event that has a duplicate +to be lost before losing a unique event from the list\&. +You should be sure to set the value of \fBHISTSIZE\fP to a larger number +than \fBSAVEHIST\fP in order to give you some room for the duplicated +events, otherwise this option will behave just like +\fBHIST_IGNORE_ALL_DUPS\fP once the history fills up with unique events\&. +.TP +\fBHIST_FCNTL_LOCK\fP +When writing out the history file, by default zsh uses ad\-hoc file locking +to avoid known problems with locking on some operating systems\&. With this +option locking is done by means of the system\&'s \fBfcntl\fP call, where +this method is available\&. On recent operating systems this may +provide better performance, in particular avoiding history corruption when +files are stored on NFS\&. +.TP +\fBHIST_FIND_NO_DUPS\fP +When searching for history entries in the line editor, do not display +duplicates of a line previously found, even if the duplicates are not +contiguous\&. +.TP +\fBHIST_IGNORE_ALL_DUPS\fP +If a new command line being added to the history list duplicates an +older one, the older command is removed from the list (even if it is +not the previous event)\&. +.TP +\fBHIST_IGNORE_DUPS\fP (\fB\-h\fP) +Do not enter command lines into the history list +if they are duplicates of the previous event\&. +.TP +\fBHIST_IGNORE_SPACE\fP (\fB\-g\fP) +Remove command lines from the history list when the first character on +the line is a space, or when one of the expanded aliases contains a +leading space\&. Only normal aliases (not global or suffix aliases) +have this behaviour\&. +Note that the command lingers in the internal history until the next +command is entered before it vanishes, allowing you to briefly reuse +or edit the line\&. If you want to make it vanish right away without +entering another command, type a space and press return\&. +.TP +\fBHIST_LEX_WORDS\fP +By default, shell history that is read in from files is split into +words on all white space\&. This means that arguments with quoted +whitespace are not correctly handled, with the consequence that +references to words in history lines that have been read from a file +may be inaccurate\&. When this option is set, words read in from a +history file are divided up in a similar fashion to normal shell +command line handling\&. Although this produces more accurately delimited +words, if the size of the history file is large this can be slow\&. Trial +and error is necessary to decide\&. +.TP +\fBHIST_NO_FUNCTIONS\fP +Remove function definitions from the history list\&. +Note that the function lingers in the internal history until the next +command is entered before it vanishes, allowing you to briefly reuse +or edit the definition\&. +.TP +\fBHIST_NO_STORE\fP +Remove the \fBhistory\fP (\fBfc \-l\fP) command from the history list +when invoked\&. +Note that the command lingers in the internal history until the next +command is entered before it vanishes, allowing you to briefly reuse +or edit the line\&. +.TP +\fBHIST_REDUCE_BLANKS\fP +Remove superfluous blanks from each command line +being added to the history list\&. +.TP +\fBHIST_SAVE_BY_COPY\fP <D> +When the history file is re\-written, we normally write out a copy of +the file named \fB$HISTFILE\&.new\fP and then rename it over the old one\&. +However, if this option is unset, we instead truncate the old +history file and write out the new version in\-place\&. If one of the +history\-appending options is enabled, this option only has an effect +when the enlarged history file needs to be re\-written to trim it +down to size\&. Disable this only if you have special needs, as doing +so makes it possible to lose history entries if zsh gets interrupted +during the save\&. +.RS +.PP +When writing out a copy of the history file, zsh preserves the old +file\&'s permissions and group information, but will refuse to write +out a new file if it would change the history file\&'s owner\&. +.RE +.TP +\fBHIST_SAVE_NO_DUPS\fP +When writing out the history file, older commands that duplicate +newer ones are omitted\&. +.TP +\fBHIST_VERIFY\fP +Whenever the user enters a line with history expansion, +don\&'t execute the line directly; instead, perform +history expansion and reload the line into the editing buffer\&. +.TP +\fBINC_APPEND_HISTORY\fP +This option works like \fBAPPEND_HISTORY\fP except that new history lines +are added to the \fB$HISTFILE\fP incrementally (as soon as they are +entered), rather than waiting until the shell exits\&. +The file will still be periodically re\-written to trim it when the +number of lines grows 20% beyond the value specified by +\fB$SAVEHIST\fP (see also the \fBHIST_SAVE_BY_COPY\fP option)\&. +.TP +\fBINC_APPEND_HISTORY_TIME\fP +This option is a variant of \fBINC_APPEND_HISTORY\fP in which, where +possible, the history entry is written out to the file after the +command is finished, so that the time taken by the command is recorded +correctly in the history file in \fBEXTENDED_HISTORY\fP format\&. This +means that the history entry will not be available immediately from +other instances of the shell that are using the same history file\&. +.RS +.PP +This option is only useful if \fBINC_APPEND_HISTORY\fP and +\fBSHARE_HISTORY\fP are turned off\&. The three options should be +considered mutually exclusive\&. +.RE +.TP +\fBSHARE_HISTORY\fP <K> +.RS +.PP +This option both imports new commands from the history file, and also +causes your typed commands to be appended to the history file (the +latter is like specifying \fBINC_APPEND_HISTORY\fP, which should be turned +off if this option is in effect)\&. The history lines are also output +with timestamps ala \fBEXTENDED_HISTORY\fP (which makes it easier to find +the spot where we left off reading the file after it gets re\-written)\&. +.PP +By default, history movement commands visit the imported lines as +well as the local lines, but you can toggle this on and off with the +set\-local\-history zle binding\&. It is also possible to create a zle +widget that will make some commands ignore imported commands, and +some include them\&. +.PP +If you find that you want more control over when commands +get imported, you may wish to turn \fBSHARE_HISTORY\fP off, +\fBINC_APPEND_HISTORY\fP or \fBINC_APPEND_HISTORY_TIME\fP (see above) on, +and then manually import commands whenever you need them using `\fBfc +\-RI\fP\&'\&. +.RE +.PP +.SS "Initialisation" +.PD 0 +.TP +.PD +\fBALL_EXPORT\fP (\fB\-a\fP, ksh: \fB\-a\fP) +All parameters subsequently defined are automatically exported\&. +.TP +\fBGLOBAL_EXPORT\fP <Z> +If this option is set, passing the \fB\-x\fP flag to the builtins \fBdeclare\fP, +\fBfloat\fP, \fBinteger\fP, \fBreadonly\fP and \fBtypeset\fP (but not \fBlocal\fP) +will also set the \fB\-g\fP flag; hence parameters exported to +the environment will not be made local to the enclosing function, unless +they were already or the flag \fB+g\fP is given explicitly\&. If the option is +unset, exported parameters will be made local in just the same way as any +other parameter\&. +.RS +.PP +This option is set by default for backward compatibility; it is not +recommended that its behaviour be relied upon\&. Note that the builtin +\fBexport\fP always sets both the \fB\-x\fP and \fB\-g\fP flags, and hence its +effect extends beyond the scope of the enclosing function; this is the +most portable way to achieve this behaviour\&. +.RE +.TP +\fBGLOBAL_RCS\fP (\fB+d\fP) <D> +If this option is unset, the startup files \fB/etc/zprofile\fP, +\fB/etc/zshrc\fP, \fB/etc/zlogin\fP and \fB/etc/zlogout\fP will not be run\&. It +can be disabled and re\-enabled at any time, including inside local startup +files (\fB\&.zshrc\fP, etc\&.)\&. +.TP +\fBRCS\fP (\fB+f\fP) <D> +After \fB/etc/zshenv\fP is sourced on startup, source the +\fB\&.zshenv\fP, \fB/etc/zprofile\fP, \fB\&.zprofile\fP, +\fB/etc/zshrc\fP, \fB\&.zshrc\fP, \fB/etc/zlogin\fP, \fB\&.zlogin\fP, and \fB\&.zlogout\fP +files, as described in the section `Files\&'\&. +If this option is unset, the \fB/etc/zshenv\fP file is still sourced, but any +of the others will not be; it can be set at any time to prevent the +remaining startup files after the currently executing one from +being sourced\&. +.PP +.SS "Input/Output" +.PD 0 +.TP +.PD +\fBALIASES\fP <D> +Expand aliases\&. +.TP +\fBCLOBBER\fP (\fB+C\fP, ksh: \fB+C\fP) <D> +Allows `\fB>\fP\&' redirection to truncate existing files\&. +Otherwise `\fB>!\fP\&' or `\fB>|\fP' must be used to truncate a file\&. +.RS +.PP +If the option is not set, and the option \fBAPPEND_CREATE\fP is also +not set, `\fB>>!\fP\&' or `\fB>>|\fP' must be used to create a file\&. +If either option is set, `\fB>>\fP\&' may be used\&. +.RE +.TP +\fBCLOBBER_EMPTY\fP +This option is only used if the option \fBCLOBBER\fP is not set: note that +it is set by default\&. +.RS +.PP +If this option is set, then regular files of zero length may be +ovewritten (`clobbered\&')\&. Note that it is possible another process +has written to the file between this test and use of the file by +the current process\&. This option should therefore not be used in +cases where files to be clobbered may be written to asynchronously\&. +.RE +.TP +\fBCORRECT\fP (\fB\-0\fP) +Try to correct the spelling of commands\&. +Note that, when the \fBHASH_LIST_ALL\fP option is not set or when some +directories in the path are not readable, this may falsely report spelling +errors the first time some commands are used\&. +.RS +.PP +The shell variable \fBCORRECT_IGNORE\fP may be set to a pattern to +match words that will never be offered as corrections\&. +.RE +.TP +\fBCORRECT_ALL\fP (\fB\-O\fP) +Try to correct the spelling of all arguments in a line\&. +.RS +.PP +The shell variable \fBCORRECT_IGNORE_FILE\fP may be set to a pattern to +match file names that will never be offered as corrections\&. +.RE +.TP +\fBDVORAK\fP +Use the Dvorak keyboard instead of the standard qwerty keyboard as a basis +for examining spelling mistakes for the \fBCORRECT\fP and \fBCORRECT_ALL\fP +options and the \fBspell\-word\fP editor command\&. +.TP +\fBFLOW_CONTROL\fP <D> +If this option is unset, +output flow control via start/stop characters (usually assigned to +^S/^Q) is disabled in the shell\&'s editor\&. +.TP +\fBIGNORE_EOF\fP (\fB\-7\fP) +Do not exit on end\-of\-file\&. Require the use +of \fBexit\fP or \fBlogout\fP instead\&. +However, ten consecutive EOFs will cause the shell to exit anyway, +to avoid the shell hanging if its tty goes away\&. +.RS +.PP +Also, if this option is set and the Zsh Line Editor is used, widgets +implemented by shell functions can be bound to EOF (normally +Control\-D) without printing the normal warning message\&. This works +only for normal widgets, not for completion widgets\&. +.RE +.TP +\fBINTERACTIVE_COMMENTS\fP (\fB\-k\fP) <K> <S> +Allow comments even in interactive shells\&. +.TP +\fBHASH_CMDS\fP <D> +Note the location of each command the first time it is executed\&. +Subsequent invocations of the same command will use the +saved location, avoiding a path search\&. +If this option is unset, no path hashing is done at all\&. +However, when \fBCORRECT\fP is set, commands whose names do not appear in +the functions or aliases hash tables are hashed in order to avoid +reporting them as spelling errors\&. +.TP +\fBHASH_DIRS\fP <D> +Whenever a command name is hashed, hash the directory containing it, +as well as all directories that occur earlier in the path\&. +Has no effect if neither \fBHASH_CMDS\fP nor \fBCORRECT\fP is set\&. +.TP +\fBHASH_EXECUTABLES_ONLY\fP +When hashing commands because of \fBHASH_CMDS\fP, check that the +file to be hashed is actually an executable\&. This option +is unset by default as if the path contains a large number of commands, +or consists of many remote files, the additional tests can take +a long time\&. Trial and error is needed to show if this option is +beneficial\&. +.TP +\fBMAIL_WARNING\fP (\fB\-U\fP) +Print a warning message if a mail file has been +accessed since the shell last checked\&. +.TP +\fBPATH_DIRS\fP (\fB\-Q\fP) +Perform a path search even on command names with slashes in them\&. +Thus if `\fB/usr/local/bin\fP\&' is in the user's path, and he or she types +`\fBX11/xinit\fP\&', the command `\fB/usr/local/bin/X11/xinit\fP' will be executed +(assuming it exists)\&. +Commands explicitly beginning with `\fB/\fP\&', `\fB\&./\fP' or `\fB\&.\&./\fP' +are not subject to the path search\&. +This also applies to the `\fB\&.\fP\&' and \fBsource\fP builtins\&. +.RS +.PP +Note that subdirectories of the current directory are always searched for +executables specified in this form\&. This takes place before any search +indicated by this option, and regardless of whether `\fB\&.\fP\&' or the current +directory appear in the command search path\&. +.RE +.TP +\fBPATH_SCRIPT\fP <K> <S> +If this option is not set, a script passed as the first non\-option argument +to the shell must contain the name of the file to open\&. If this +option is set, and the script does not specify a directory path, +the script is looked for first in the current directory, then in the +command path\&. See +the section INVOCATION in \fIzsh\fP(1)\&. +.TP +\fBPRINT_EIGHT_BIT\fP +Print eight bit characters literally in completion lists, etc\&. +This option is not necessary if your system correctly returns the +printability of eight bit characters (see \fIctype\fP(3))\&. +.TP +\fBPRINT_EXIT_VALUE\fP (\fB\-1\fP) +Print the exit value of programs with non\-zero exit status\&. +This is only available at the command line in interactive shells\&. +.TP +\fBRC_QUOTES\fP +Allow the character sequence `\fB\&''\fP' to signify a single quote +within singly quoted strings\&. Note this does not apply in quoted strings +using the format \fB$\&'\fP\fI\&.\&.\&.\fP\fB'\fP, where a backslashed single quote can +be used\&. +.TP +\fBRM_STAR_SILENT\fP (\fB\-H\fP) <K> <S> +Do not query the user before executing `\fBrm *\fP\&' or `\fBrm path/*\fP'\&. +.TP +\fBRM_STAR_WAIT\fP +If querying the user before executing `\fBrm *\fP\&' or `\fBrm path/*\fP', +first wait ten seconds and ignore anything typed in that time\&. +This avoids the problem of reflexively answering `yes\&' to the query +when one didn\&'t really mean it\&. The wait and query can always be +avoided by expanding the `\fB*\fP\&' in ZLE (with tab)\&. +.TP +\fBSHORT_LOOPS\fP <C> <Z> +Allow the short forms of \fBfor\fP, \fBrepeat\fP, \fBselect\fP, +\fBif\fP, and \fBfunction\fP constructs\&. +.TP +\fBSHORT_REPEAT\fP +Allow the short form \fBrepeat\fP as \fBSHORT_LOOPS\fP but without enabling +it for the other constructs\&. +.TP +\fBSUN_KEYBOARD_HACK\fP (\fB\-L\fP) +If a line ends with a backquote, and there are an odd number +of backquotes on the line, ignore the trailing backquote\&. +This is useful on some keyboards where the return key is +too small, and the backquote key lies annoyingly close to it\&. +As an alternative the variable \fBKEYBOARD_HACK\fP lets you choose the +character to be removed\&. +.PP +.SS "Job Control" +.PD 0 +.TP +.PD +\fBAUTO_CONTINUE\fP +With this option set, stopped jobs that are removed from the job table +with the \fBdisown\fP builtin command are automatically sent a \fBCONT\fP +signal to make them running\&. +.TP +\fBAUTO_RESUME\fP (\fB\-W\fP) +Treat single word simple commands without redirection +as candidates for resumption of an existing job\&. +.TP +\fBBG_NICE\fP (\fB\-6\fP) <C> <Z> +Run all background jobs at a lower priority\&. This option +is set by default\&. +.TP +\fBCHECK_JOBS\fP <Z> +Report the status of background and suspended jobs before exiting a shell +with job control; a second attempt to exit the shell will succeed\&. +\fBNO_CHECK_JOBS\fP is best used only in combination with \fBNO_HUP\fP, else +such jobs will be killed automatically\&. +.RS +.PP +The check is omitted if the commands run from the previous command line +included a `\fBjobs\fP\&' command, since it is assumed the user is aware that +there are background or suspended jobs\&. A `\fBjobs\fP\&' command run from one +of the hook functions defined in +the section SPECIAL FUNCTIONS in \fIzshmisc\fP(1) +is not counted for this purpose\&. +.RE +.TP +\fBCHECK_RUNNING_JOBS\fP <Z> +Check for both running and suspended jobs when \fBCHECK_JOBS\fP is enabled\&. +When this option is disabled, zsh checks only for suspended jobs, which +matches the default behavior of bash\&. +.RS +.PP +This option has no effect unless \fBCHECK_JOBS\fP is set\&. +.RE +.TP +\fBHUP\fP <Z> +Send the \fBHUP\fP signal to running jobs when the +shell exits\&. +.TP +\fBLONG_LIST_JOBS\fP (\fB\-R\fP) +Print job notifications in the long format by default\&. +.TP +\fBMONITOR\fP (\fB\-m\fP, ksh: \fB\-m\fP) +Allow job control\&. Set by default in interactive shells\&. +.TP +\fBNOTIFY\fP (\fB\-5\fP, ksh: \fB\-b\fP) <Z> +Report the status of background jobs immediately, rather than +waiting until just before printing a prompt\&. +.TP +\fBPOSIX_JOBS\fP <K> <S> +This option makes job control more compliant with the POSIX standard\&. +.RS +.PP +When the option is not set, the \fBMONITOR\fP option is unset on entry to +subshells, so that job control is no longer active\&. When the option is +set, the \fBMONITOR\fP option and job control remain active in the +subshell, but note that the subshell has no access to jobs in the parent +shell\&. +.PP +When the option is not set, jobs put in the background or foreground +with \fBbg\fP or \fBfg\fP are displayed with the same information that would +be reported by \fBjobs\fP\&. When the option is set, only the text is +printed\&. The output from \fBjobs\fP itself is not affected by the option\&. +.PP +When the option is not set, job information from the parent +shell is saved for output within a subshell (for example, within a +pipeline)\&. When the option is set, the output of \fBjobs\fP is empty +until a job is started within the subshell\&. +.PP +In previous versions of the shell, it was necessary to enable +\fBPOSIX_JOBS\fP in order for the builtin command \fBwait\fP to return the +status of background jobs that had already exited\&. This is no longer +the case\&. +.RE +.PP +.SS "Prompting" +.PD 0 +.TP +.PD +\fBPROMPT_BANG\fP <K> +If set, `\fB!\fP\&' is treated specially in prompt expansion\&. +See +EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)\&. +.TP +\fBPROMPT_CR\fP (\fB+V\fP) <D> +Print a carriage return just before printing +a prompt in the line editor\&. This is on by default as multi\-line editing +is only possible if the editor knows where the start of the line appears\&. +.TP +\fBPROMPT_SP\fP <D> +Attempt to preserve a partial line (i\&.e\&. a line that did not end with a +newline) that would otherwise be covered up by the command prompt due to +the \fBPROMPT_CR\fP option\&. This works by outputting some cursor\-control +characters, including a series of spaces, that should make the terminal +wrap to the next line when a partial line is present (note that this is +only successful if your terminal has automatic margins, which is typical)\&. +.RS +.PP +When a partial line is preserved, by default you will see an inverse+bold +character at the end of the partial line: a `\fB%\fP\&' for a normal user or +a `\fB#\fP\&' for root\&. If set, the shell parameter \fBPROMPT_EOL_MARK\fP can be +used to customize how the end of partial lines are shown\&. +.PP +NOTE: if the \fBPROMPT_CR\fP option is not set, enabling this option will +have no effect\&. This option is on by default\&. +.RE +.TP +\fBPROMPT_PERCENT\fP <C> <Z> +If set, `\fB%\fP\&' is treated specially in prompt expansion\&. +See +EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)\&. +.TP +\fBPROMPT_SUBST\fP <K> <S> +If set, \fIparameter expansion\fP, \fIcommand substitution\fP and +\fIarithmetic expansion\fP are performed in prompts\&. Substitutions +within prompts do not affect the command status\&. +.TP +\fBTRANSIENT_RPROMPT\fP +Remove any right prompt from display when accepting a command +line\&. This may be useful with terminals with other cut/paste methods\&. +.PP +.SS "Scripts and Functions" +.PD 0 +.TP +.PD +\fBALIAS_FUNC_DEF\fP <S> +By default, zsh does not allow the definition of functions using +the `\fIname\fP \fB()\fP\&' syntax if \fIname\fP was expanded as an +alias: this causes an error\&. This is usually the desired behaviour, as +otherwise the combination of an alias and a function based on the same +definition can easily cause problems\&. +.RS +.PP +When this option is set, aliases can be used for defining functions\&. +.PP +For example, consider the following definitions as they might +occur in a startup file\&. +.PP +.RS +.nf +\fBalias foo=bar +foo() { + print This probably does not do what you expect\&. +}\fP +.fi +.RE +.PP +Here, \fBfoo\fP is expanded as an alias to \fBbar\fP before the +\fB()\fP is encountered, so the function defined would be named +\fBbar\fP\&. By default this is instead an error in native mode\&. Note that +quoting any part of the function name, or using the keyword +\fBfunction\fP, avoids the problem, so is recommended when the function +name can also be an alias\&. +.RE +.TP +\fBC_BASES\fP +Output hexadecimal numbers in the standard C format, for example `\fB0xFF\fP\&' +instead of the usual `\fB16#FF\fP\&'\&. If the option \fBOCTAL_ZEROES\fP is also +set (it is not by default), octal numbers will be treated similarly and +hence appear as `\fB077\fP\&' instead of `\fB8#77\fP'\&. This option has no effect +on the choice of the output base, nor on the output of bases other than +hexadecimal and octal\&. Note that these formats will be understood on input +irrespective of the setting of \fBC_BASES\fP\&. +.TP +\fBC_PRECEDENCES\fP +This alters the precedence of arithmetic operators to be more +like C and other programming languages; +the section ARITHMETIC EVALUATION in \fIzshmisc\fP(1) +has an explicit list\&. +.TP +\fBDEBUG_BEFORE_CMD\fP <D> +Run the \fBDEBUG\fP trap before each command; otherwise it is run after +each command\&. Setting this option mimics the behaviour of ksh 93; with +the option unset the behaviour is that of ksh 88\&. +.TP +\fBERR_EXIT\fP (\fB\-e\fP, ksh: \fB\-e\fP) +If a command has a non\-zero exit status, execute the \fBZERR\fP +trap, if set, and exit\&. This is disabled while running initialization +scripts\&. +.RS +.PP +The behaviour is also disabled inside \fBDEBUG\fP traps\&. In this +case the option is handled specially: it is unset on entry to +the trap\&. If the option \fBDEBUG_BEFORE_CMD\fP is set, +as it is by default, and the option \fBERR_EXIT\fP is found to have been set +on exit, then the command for which the \fBDEBUG\fP trap is being executed is +skipped\&. The option is restored after the trap exits\&. +.PP +Non\-zero status in a command list containing \fB&&\fP or \fB||\fP is ignored +for commands not at the end of the list\&. Hence +.PP +.RS +.nf +\fBfalse && true\fP +.fi +.RE +.PP +does not trigger exit\&. +.PP +Exiting due to \fBERR_EXIT\fP has certain interactions with asynchronous +jobs noted in +the section JOBS in \fIzshmisc\fP(1)\&. +.RE +.TP +\fBERR_RETURN\fP +If a command has a non\-zero exit status, return immediately from the +enclosing function\&. The logic is similar to that for \fBERR_EXIT\fP, +except that an implicit \fBreturn\fP statement is executed instead of an +\fBexit\fP\&. This will trigger an exit at the outermost level of a +non\-interactive script\&. +.RS +.PP +Normally this option inherits the behaviour of \fBERR_EXIT\fP that +code followed by `\fB&&\fP\&' `\fB||\fP' does not trigger a return\&. Hence +in the following: +.PP +.RS +.nf +\fBsummit || true\fP +.fi +.RE +.PP +no return is forced as the combined effect always has a zero return +status\&. +.PP +Note\&. however, that if \fBsummit\fP in the above example is itself a +function, code inside it is considered separately: it may force a return +from \fBsummit\fP (assuming the option remains set within \fBsummit\fP), but +not from the enclosing context\&. This behaviour is different from +\fBERR_EXIT\fP which is unaffected by function scope\&. +.RE +.TP +\fBEVAL_LINENO\fP <Z> +If set, line numbers of expressions evaluated using the builtin \fBeval\fP +are tracked separately of the enclosing environment\&. This applies both +to the parameter \fBLINENO\fP and the line number output by the prompt +escape \fB%i\fP\&. If the option is set, the prompt escape \fB%N\fP will output +the string `\fB(eval)\fP\&' instead of the script or function name as an +indication\&. (The two prompt escapes are typically used in the parameter +\fBPS4\fP to be output when the option \fBXTRACE\fP is set\&.) If +\fBEVAL_LINENO\fP is unset, the line number of the surrounding script or +function is retained during the evaluation\&. +.TP +\fBEXEC\fP (\fB+n\fP, ksh: \fB+n\fP) <D> +Do execute commands\&. Without this option, commands are +read and checked for syntax errors, but not executed\&. +This option cannot be turned off in an interactive shell, +except when `\fB\-n\fP\&' is supplied to the shell at startup\&. +.TP +\fBFUNCTION_ARGZERO\fP <C> <Z> +When executing a shell function or sourcing a script, set \fB$0\fP +temporarily to the name of the function/script\&. Note that toggling +\fBFUNCTION_ARGZERO\fP from on to off (or off to on) does not change the +current value of \fB$0\fP\&. Only the state upon entry to the function or +script has an effect\&. Compare \fBPOSIX_ARGZERO\fP\&. +.TP +\fBLOCAL_LOOPS\fP +When this option is not set, the effect of \fBbreak\fP and \fBcontinue\fP +commands may propagate outside function scope, affecting loops in +calling functions\&. When the option is set in a calling function, a +\fBbreak\fP or a \fBcontinue\fP that is not caught within a called function +(regardless of the setting of the option within that function) +produces a warning and the effect is cancelled\&. +.TP +\fBLOCAL_OPTIONS\fP <K> +If this option is set at the point of return from a shell function, +most options (including this one) which were in force upon entry to +the function are restored; options that are not restored are +\fBPRIVILEGED\fP and \fBRESTRICTED\fP\&. Otherwise, only this option, +and the \fBLOCAL_LOOPS\fP, \fBXTRACE\fP and \fBPRINT_EXIT_VALUE\fP options are +restored\&. Hence if this is explicitly unset by a shell function the +other options in force at the point of return will remain so\&. +A shell function can also guarantee itself a known shell configuration +with a formulation like `\fBemulate \-L zsh\fP\&'; the \fB\-L\fP activates +\fBLOCAL_OPTIONS\fP\&. +.TP +\fBLOCAL_PATTERNS\fP +If this option is set at the point of return from a shell function, +the state of pattern disables, as set with the builtin command +`\fBdisable \-p\fP\&', is restored to what it was when the function was +entered\&. The behaviour of this option is similar to the effect +of \fBLOCAL_OPTIONS\fP on options; hence `\fBemulate \-L sh\fP\&' (or +indeed any other emulation with the \fB\-L\fP option) activates +\fBLOCAL_PATTERNS\fP\&. +.TP +\fBLOCAL_TRAPS\fP <K> +If this option is set when a signal trap is set inside a function, then the +previous status of the trap for that signal will be restored when the +function exits\&. Note that this option must be set \fIprior\fP to altering the +trap behaviour in a function; unlike \fBLOCAL_OPTIONS\fP, the value on exit +from the function is irrelevant\&. However, it does not need to be set +before any global trap for that to be correctly restored by a function\&. +For example, +.RS +.PP +.RS +.nf +\fBunsetopt localtraps +trap \- INT +fn() { setopt localtraps; trap \&'' INT; sleep 3; }\fP +.fi +.RE +.PP +will restore normal handling of \fBSIGINT\fP after the function exits\&. +.RE +.TP +\fBMULTI_FUNC_DEF\fP <Z> +Allow definitions of multiple functions at once in the form `\fBfn1 +fn2\fP\fI\&.\&.\&.\fP\fB()\fP\&'; if the option is not set, this causes +a parse error\&. Definition of multiple functions with the \fBfunction\fP +keyword is always allowed\&. Multiple function definitions are not often +used and can cause obscure errors\&. +.TP +\fBMULTIOS\fP <Z> +Perform implicit \fBtee\fPs or \fBcat\fPs when multiple +redirections are attempted (see the section `Redirection\&')\&. +.TP +\fBOCTAL_ZEROES\fP <S> +Interpret any integer constant beginning with a 0 as octal, per IEEE Std +1003\&.2\-1992 (ISO 9945\-2:1993)\&. This is not enabled by default as it +causes problems with parsing of, for example, date and time strings with +leading zeroes\&. +.RS +.PP +Sequences of digits indicating a numeric base such as the `\fB08\fP\&' +component in `\fB08#77\fP\&' are always interpreted as decimal, regardless +of leading zeroes\&. +.RE +.TP +\fBPIPE_FAIL\fP +By default, when a pipeline exits the exit status recorded by the shell +and returned by the shell variable \fB$?\fP reflects that of the +rightmost element of a pipeline\&. If this option is set, the exit status +instead reflects the status of the rightmost element of the pipeline +that was non\-zero, or zero if all elements exited with zero status\&. +.TP +\fBSOURCE_TRACE\fP +If set, zsh will print an informational message announcing the name of +each file it loads\&. The format of the output is similar to that +for the \fBXTRACE\fP option, with the message \fB<sourcetrace>\fP\&. +A file may be loaded by the shell itself when it +starts up and shuts down (\fBStartup/Shutdown Files\fP) or by the use of +the `\fBsource\fP\&' and `\fBdot\fP' builtin commands\&. +.TP +\fBTYPESET_SILENT\fP +If this is unset, executing any of the `\fBtypeset\fP\&' family of +commands with no options and a list of parameters that have no values +to be assigned but already exist will display the value of the parameter\&. +If the option is set, they will only be shown when parameters are selected +with the `\fB\-m\fP\&' option\&. The option `\fB\-p\fP' is available whether or not +the option is set\&. +.TP +\fBTYPESET_TO_UNSET\fP <K> <S> +When declaring a new parameter with any of the `\fBtypeset\fP\&' family of +related commands, the parameter remains unset unless and until a +value is explicity assigned to it, either in the `\fBtypeset\fP\&' command +itself or as a later assignment statement\&. +.TP +\fBVERBOSE\fP (\fB\-v\fP, ksh: \fB\-v\fP) +Print shell input lines as they are read\&. +.TP +\fBXTRACE\fP (\fB\-x\fP, ksh: \fB\-x\fP) +Print commands and their arguments as they are executed\&. The +output is preceded by the value of \fB$PS4\fP, formatted as described +in +the section EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)\&. +.PP +.SS "Shell Emulation" +.PD 0 +.TP +.PD +\fBAPPEND_CREATE\fP <K> <S> +This option only applies when \fBNO_CLOBBER\fP (\-\fBC\fP) is in effect\&. +.RS +.PP +If this option is not set, the shell will report an error when a +append redirection (\fB>>\fP) is used on a file that does not already +exists (the traditional zsh behaviour of \fBNO_CLOBBER\fP)\&. If the option +is set, no error is reported (POSIX behaviour)\&. +.RE +.TP +\fBBASH_REMATCH\fP +When set, matches performed with the \fB=~\fP operator will set the +\fBBASH_REMATCH\fP array variable, instead of the default \fBMATCH\fP and +\fBmatch\fP variables\&. The first element of the \fBBASH_REMATCH\fP array +will contain the entire matched text and subsequent elements will contain +extracted substrings\&. This option makes more sense when \fBKSH_ARRAYS\fP is +also set, so that the entire matched portion is stored at index 0 and the +first substring is at index 1\&. Without this option, the \fBMATCH\fP variable +contains the entire matched text and the \fBmatch\fP array variable contains +substrings\&. +.TP +\fBBSD_ECHO\fP <S> +Make the \fBecho\fP builtin compatible with the BSD \fIecho\fP(1) command\&. +This disables backslashed escape sequences in echo strings unless the +\fB\-e\fP option is specified\&. +.TP +\fBCONTINUE_ON_ERROR\fP +If a fatal error is encountered (see +the section ERRORS in \fIzshmisc\fP(1)), and the code is running +in a script, the shell will resume execution at the next statement +in the script at the top level, in other words outside all functions +or shell constructs such as loops and conditions\&. This mimics the +behaviour of interactive shells, where the shell returns to the +line editor to read a new command; it was the normal behaviour in versions +of zsh before 5\&.0\&.1\&. +.TP +\fBCSH_JUNKIE_HISTORY\fP <C> +A history reference without an event specifier will always refer to the +previous command\&. Without this option, such a history reference refers +to the same event as the previous history reference on the current +command line, defaulting to the previous command\&. +.TP +\fBCSH_JUNKIE_LOOPS\fP <C> +Allow loop bodies to take the form `\fIlist\fP\fB; end\fP\&' instead of +`\fBdo \fP\fIlist\fP\fB; done\fP\&'\&. +.TP +\fBCSH_JUNKIE_QUOTES\fP <C> +Changes the rules for single\- and double\-quoted text to match that of +\fBcsh\fP\&. These require that embedded newlines be preceded by a backslash; +unescaped newlines will cause an error message\&. +In double\-quoted strings, it is made impossible to escape `\fB$\fP\&', `\fB`\fP' +or `\fB"\fP\&' (and `\fB\e\fP' itself no longer needs escaping)\&. +Command substitutions are only expanded once, and cannot be nested\&. +.TP +\fBCSH_NULLCMD\fP <C> +Do not use the values of \fBNULLCMD\fP and \fBREADNULLCMD\fP +when running redirections with no command\&. This make +such redirections fail (see the section `Redirection\&')\&. +.TP +\fBKSH_ARRAYS\fP <K> <S> +Emulate \fBksh\fP array handling as closely as possible\&. If this option +is set, array elements are numbered from zero, an array parameter +without subscript refers to the first element instead of the whole array, +and braces are required to delimit a subscript (`\fB${path[2]}\fP\&' rather +than just `\fB$path[2]\fP\&') or to apply modifiers to any parameter +(`\fB${PWD:h}\fP\&' rather than `\fB$PWD:h\fP')\&. +.TP +\fBKSH_AUTOLOAD\fP <K> <S> +Emulate \fBksh\fP function autoloading\&. This means that when a function is +autoloaded, the corresponding file is merely executed, and must define +the function itself\&. (By default, the function is defined to the contents +of the file\&. However, the most common \fBksh\fP\-style case \- of the file +containing only a simple definition of the function \- is always handled +in the \fBksh\fP\-compatible manner\&.) +.TP +\fBKSH_OPTION_PRINT\fP <K> +Alters the way options settings are printed: instead of separate lists of +set and unset options, all options are shown, marked `on\&' if +they are in the non\-default state, `off\&' otherwise\&. +.TP +\fBKSH_TYPESET\fP +This option is now obsolete: a better appropximation to the behaviour of +other shells is obtained with the reserved word interface to +\fBdeclare\fP, \fBexport\fP, \fBfloat\fP, \fBinteger\fP, \fBlocal\fP, \fBreadonly\fP +and \fBtypeset\fP\&. Note that the option is only applied when the reserved +word interface is \fInot\fP in use\&. +.RS +.PP +Alters the way arguments to the \fBtypeset\fP family of commands, including +\fBdeclare\fP, \fBexport\fP, \fBfloat\fP, \fBinteger\fP, \fBlocal\fP and +\fBreadonly\fP, are processed\&. Without this option, zsh will perform normal +word splitting after command and parameter expansion in arguments of an +assignment; with it, word splitting does not take place in those cases\&. +.RE +.TP +\fBKSH_ZERO_SUBSCRIPT\fP +Treat use of a subscript of value zero in array or string expressions as a +reference to the first element, i\&.e\&. the element that usually has the +subscript 1\&. Ignored if \fBKSH_ARRAYS\fP is also set\&. +.RS +.PP +If neither this option nor \fBKSH_ARRAYS\fP is set, accesses to an element of +an array or string with subscript zero return an empty element or string, +while attempts to set element zero of an array or string are treated as an +error\&. However, attempts to set an otherwise valid subscript range that +includes zero will succeed\&. For example, if \fBKSH_ZERO_SUBSCRIPT\fP is not +set, +.PP +.RS +.nf +\fBarray[0]=(element)\fP +.fi +.RE +.PP +is an error, while +.PP +.RS +.nf +\fBarray[0,1]=(element)\fP +.fi +.RE +.PP +is not and will replace the first element of the array\&. +.PP +This option is for compatibility with older versions of the shell and +is not recommended in new code\&. +.RE +.TP +\fBPOSIX_ALIASES\fP <K> <S> +When this option is set, reserved words are not candidates for +alias expansion: it is still possible to declare any of them as an alias, +but the alias will never be expanded\&. Reserved words are described in +the section RESERVED WORDS in \fIzshmisc\fP(1)\&. +.RS +.PP +Alias expansion takes place while text is being read; hence when this +option is set it does not take effect until the end of any function or +other piece of shell code parsed as one unit\&. Note this may +cause differences from other shells even when the option is in +effect\&. For example, when running a command with `\fBzsh \-c\fP\&', +or even `\fBzsh \-o posixaliases \-c\fP\&', the entire command argument is parsed +as one unit, so aliases defined within the argument are not available even +in later lines\&. If in doubt, avoid use of aliases in non\-interactive +code\&. +.RE +.TP +\fBPOSIX_ARGZERO\fP +This option may be used to temporarily disable \fBFUNCTION_ARGZERO\fP and +thereby restore the value of \fB$0\fP to the name used to invoke the shell +(or as set by the \fB\-c\fP command line option)\&. For compatibility with +previous versions of the shell, emulations use \fBNO_FUNCTION_ARGZERO\fP +instead of \fBPOSIX_ARGZERO\fP, which may result in unexpected scoping of +\fB$0\fP if the emulation mode is changed inside a function or script\&. +To avoid this, explicitly enable \fBPOSIX_ARGZERO\fP in the \fBemulate\fP +command: +.RS +.PP +.RS +.nf +\fBemulate sh \-o POSIX_ARGZERO\fP +.fi +.RE +.PP +Note that \fBNO_POSIX_ARGZERO\fP has no effect unless \fBFUNCTION_ARGZERO\fP +was already enabled upon entry to the function or script\&. +.RE +.TP +\fBPOSIX_BUILTINS\fP <K> <S> +When this option is set the \fBcommand\fP builtin can be used to execute +shell builtin commands\&. Parameter assignments specified before shell +functions and special builtins are kept after the command completes unless +the special builtin is prefixed with the \fBcommand\fP builtin\&. Special +builtins are +\fB\&.\fP, +\fB:\fP, +\fBbreak\fP, +\fBcontinue\fP, +\fBdeclare\fP, +\fBeval\fP, +\fBexit\fP, +\fBexport\fP, +\fBinteger\fP, +\fBlocal\fP, +\fBreadonly\fP, +\fBreturn\fP, +\fBset\fP, +\fBshift\fP, +\fBsource\fP, +\fBtimes\fP, +\fBtrap\fP and +\fBunset\fP\&. +.RS +.PP +In addition, various error conditions associated with the above builtins +or \fBexec\fP cause a non\-interactive shell to exit and an interactive +shell to return to its top\-level processing\&. +.PP +Furthermore, functions and shell builtins are not executed after +an \fBexec\fP prefix; the command to be executed must be an external +command found in the path\&. +.PP +Furthermore, the \fBgetopts\fP builtin behaves in a POSIX\-compatible +fashion in that the associated variable \fBOPTIND\fP is not made +local to functions, and its value is calculated differently to match +other shells\&. +.PP +Moreover, the warning and special exit code from +\fB[[ \-o \fP\fInon_existent_option\fP\fB ]]\fP are suppressed\&. +.RE +.TP +\fBPOSIX_IDENTIFIERS\fP <K> <S> +When this option is set, only the ASCII characters \fBa\fP to \fBz\fP, \fBA\fP to +\fBZ\fP, \fB0\fP to \fB9\fP and \fB_\fP may be used in identifiers (names +of shell parameters and modules)\&. +.RS +.PP +In addition, setting this option limits the effect of parameter +substitution with no braces, so that the expression \fB$#\fP is treated as +the parameter \fB$#\fP even if followed by a valid parameter name\&. +When it is unset, zsh allows expressions of the form \fB$#\fP\fIname\fP +to refer to the length of \fB$\fP\fIname\fP, even for special variables, +for example in expressions such as \fB$#\-\fP and \fB$#*\fP\&. +.PP +Another difference is that with the option set assignment to an +unset variable in arithmetic context causes the variable to be created +as a scalar rather than a numeric type\&. So after `\fBunset t; (( t = 3 +))\fP\&'\&. without \fBPOSIX_IDENTIFIERS\fP set \fBt\fP has integer type, while with +it set it has scalar type\&. +.PP +When the option is unset and multibyte character support is enabled (i\&.e\&. it +is compiled in and the option \fBMULTIBYTE\fP is set), then additionally any +alphanumeric characters in the local character set may be used in +identifiers\&. Note that scripts and functions written with this feature are +not portable, and also that both options must be set before the script +or function is parsed; setting them during execution is not sufficient +as the syntax \fIvariable\fP\fB=\fP\fIvalue\fP has already been parsed as +a command rather than an assignment\&. +.PP +If multibyte character support is not compiled into the shell this option is +ignored; all octets with the top bit set may be used in identifiers\&. +This is non\-standard but is the traditional zsh behaviour\&. +.RE +.TP +\fBPOSIX_STRINGS\fP <K> <S> +This option affects processing of quoted strings\&. Currently it only +affects the behaviour of null characters, i\&.e\&. character 0 in the +portable character set corresponding to US ASCII\&. +.RS +.PP +When this option is not set, null characters embedded within strings +of the form \fB$\&'\fP\fI\&.\&.\&.\fP\fB'\fP are treated as ordinary characters\&. The +entire string is maintained within the shell and output to files where +necessary, although owing to restrictions of the library interface +the string is truncated at the null character in file names, environment +variables, or in arguments to external programs\&. +.PP +When this option is set, the \fB$\&'\fP\fI\&.\&.\&.\fP\fB'\fP expression is truncated at +the null character\&. Note that remaining parts of the same string +beyond the termination of the quotes are not truncated\&. +.PP +For example, the command line argument \fBa$\&'b\e0c'd\fP is treated with +the option off as the characters \fBa\fP, \fBb\fP, null, \fBc\fP, \fBd\fP, +and with the option on as the characters \fBa\fP, \fBb\fP, \fBd\fP\&. +.RE +.TP +\fBPOSIX_TRAPS\fP <K> <S> +When this option is set, the usual zsh behaviour of executing +traps for \fBEXIT\fP on exit from shell functions is suppressed\&. +In that case, manipulating \fBEXIT\fP traps always alters the global +trap for exiting the shell; the \fBLOCAL_TRAPS\fP option is +ignored for the \fBEXIT\fP trap\&. +.RS +.PP +Also, a \fBreturn\fP statement executed in a trap with no argument passes +back from the function the value from the surrounding context, not from +code executed within the trap\&. +.PP +Furthermore, if a trap is set to be ignored, this state persists when +a subshell is entered\&. Without the option, the trap would be reset to +its default state at this point\&. +.RE +.TP +\fBSH_FILE_EXPANSION\fP <K> <S> +Perform filename expansion (e\&.g\&., \fB~\fP expansion) \fIbefore\fP +parameter expansion, command substitution, arithmetic expansion +and brace expansion\&. +If this option is unset, it is performed \fIafter\fP +brace expansion, so things like `\fB~$USERNAME\fP\&' and +`\fB~{pfalstad,rc}\fP\&' will work\&. +.TP +\fBSH_NULLCMD\fP <K> <S> +Do not use the values of \fBNULLCMD\fP and \fBREADNULLCMD\fP +when doing redirections, use `\fB:\fP\&' instead (see the section `Redirection')\&. +.TP +\fBSH_OPTION_LETTERS\fP <K> <S> +If this option is set the shell tries to interpret single letter options +(which are used with \fBset\fP and \fBsetopt\fP) like \fBksh\fP does\&. +This also affects the value of the \fB\-\fP special parameter\&. +.TP +\fBSH_WORD_SPLIT\fP (\fB\-y\fP) <K> <S> +Causes field splitting to be performed on unquoted parameter expansions\&. +Note that this option has nothing to do with word splitting\&. +(See +\fIzshexpn\fP(1)\&.) +.TP +\fBTRAPS_ASYNC\fP +While waiting for a program to exit, handle signals and run traps +immediately\&. Otherwise the trap is run after a child process has exited\&. +Note this does not affect the point at which traps are run for any case +other than when the shell is waiting for a child process\&. +.PP +.SS "Shell State" +.PD 0 +.TP +.PD +\fBINTERACTIVE\fP (\fB\-i\fP, ksh: \fB\-i\fP) +This is an interactive shell\&. This option is set upon initialisation if +the standard input is a tty and commands are being read from standard input\&. +(See the discussion of \fBSHIN_STDIN\fP\&.) +This heuristic may be overridden by specifying a state for this option +on the command line\&. +The value of this option can only be changed via flags supplied at +invocation of the shell\&. +It cannot be changed once zsh is running\&. +.TP +\fBLOGIN\fP (\fB\-l\fP, ksh: \fB\-l\fP) +This is a login shell\&. +If this option is not explicitly set, the shell becomes a login shell if +the first character of the \fBargv[0]\fP passed to the shell is a `\fB\-\fP\&'\&. +.TP +\fBPRIVILEGED\fP (\fB\-p\fP, ksh: \fB\-p\fP) +Turn on privileged mode\&. Typically this is used when script is to be run +with elevated privileges\&. This should be done as follows directly with +the \fB\-p\fP option to zsh so that it takes effect during startup\&. +.RS +.PP +.RS +.nf +\fB#!/bin/zsh \-p\fP +.fi +.RE +.PP +The option is enabled automatically on startup if the effective user +(group) ID is not equal to the real user (group) ID\&. In this case, +turning the option off causes the effective user and group IDs to be set +to the real user and group IDs\&. Be aware that if that fails the shell may +be running with different IDs than was intended so a script should check +for failure and act accordingly, for example: +.PP +.RS +.nf +\fBunsetopt privileged || exit\fP +.fi +.RE +.PP +The \fBPRIVILEGED\fP option disables sourcing user startup files\&. +If zsh is invoked as `\fBsh\fP\&' or `\fBksh\fP' with this option set, +\fB/etc/suid_profile\fP is sourced (after \fB/etc/profile\fP on interactive +shells)\&. Sourcing \fB~/\&.profile\fP is disabled and the contents of the +\fBENV\fP variable is ignored\&. This option cannot be changed using the +\fB\-m\fP option of \fBsetopt\fP and \fBunsetopt\fP, and changing it inside a +function always changes it globally regardless of the \fBLOCAL_OPTIONS\fP +option\&. +.RE +.TP +\fBRESTRICTED\fP (\fB\-r\fP) +Enables restricted mode\&. This option cannot be changed using +\fBunsetopt\fP, and setting it inside a function always changes it +globally regardless of the \fBLOCAL_OPTIONS\fP option\&. See +the section `Restricted Shell\&'\&. +.TP +\fBSHIN_STDIN\fP (\fB\-s\fP, ksh: \fB\-s\fP) +Commands are being read from the standard input\&. +Commands are read from standard input if no command is specified with +\fB\-c\fP and no file of commands is specified\&. If \fBSHIN_STDIN\fP +is set explicitly on the command line, +any argument that would otherwise have been +taken as a file to run will instead be treated as a normal positional +parameter\&. +Note that setting or unsetting this option on the command line does not +necessarily affect the state the option will have while the shell is +running \- that is purely an indicator of whether or not commands are +\fIactually\fP being read from standard input\&. +The value of this option can only be changed via flags supplied at +invocation of the shell\&. +It cannot be changed once zsh is running\&. +.TP +\fBSINGLE_COMMAND\fP (\fB\-t\fP, ksh: \fB\-t\fP) +If the shell is reading from standard input, it exits after a single command +has been executed\&. This also makes the shell non\-interactive, unless the +\fBINTERACTIVE\fP option is explicitly set on the command line\&. +The value of this option can only be changed via flags supplied at +invocation of the shell\&. +It cannot be changed once zsh is running\&. +.PP +.SS "Zle" +.PD 0 +.TP +.PD +\fBBEEP\fP (\fB+B\fP) <D> +Beep on error in ZLE\&. +.TP +\fBCOMBINING_CHARS\fP +Assume that the terminal displays combining characters correctly\&. +Specifically, if a base alphanumeric character is followed by one or more +zero\-width punctuation characters, assume that the zero\-width characters +will be displayed as modifications to the base character within the +same width\&. Not all terminals handle this\&. If this option is not +set, zero\-width characters are displayed separately with special +mark\-up\&. +.RS +.PP +If this option is set, the pattern test \fB[[:WORD:]]\fP matches a +zero\-width punctuation character on the assumption that it will be +used as part of a word in combination with a word character\&. +Otherwise the base shell does not handle combining characters specially\&. +.RE +.TP +\fBEMACS\fP +If ZLE is loaded, turning on this option has the equivalent effect +of `\fBbindkey \-e\fP\&'\&. In addition, the VI option is unset\&. +Turning it off has no effect\&. The option setting is +not guaranteed to reflect the current keymap\&. This option is +provided for compatibility; \fBbindkey\fP is the recommended interface\&. +.TP +\fBOVERSTRIKE\fP +Start up the line editor in overstrike mode\&. +.TP +\fBSINGLE_LINE_ZLE\fP (\fB\-M\fP) <K> +Use single\-line command line editing instead of multi\-line\&. +.RS +.PP +Note that although this is on by default in ksh emulation it only +provides superficial compatibility with the ksh line editor and +reduces the effectiveness of the zsh line editor\&. As it has no +effect on shell syntax, many users may wish to disable this option +when using ksh emulation interactively\&. +.RE +.TP +\fBVI\fP +If ZLE is loaded, turning on this option has the equivalent effect +of `\fBbindkey \-v\fP\&'\&. In addition, the EMACS option is unset\&. +Turning it off has no effect\&. The option setting is +not guaranteed to reflect the current keymap\&. This option is +provided for compatibility; \fBbindkey\fP is the recommended interface\&. +.TP +\fBZLE\fP (\fB\-Z\fP) +Use the zsh line editor\&. Set by default in interactive shells connected to +a terminal\&. +.PP +.SH "OPTION ALIASES" +Some options have alternative names\&. These aliases are never used for +output, but can be used just like normal option names when specifying +options to the shell\&. +.PP +.PD 0 +.TP +.PD +\fBBRACE_EXPAND\fP +\fINO_\fP\fBIGNORE_BRACES\fP +(ksh and bash compatibility) +.TP +\fBDOT_GLOB\fP +\fBGLOB_DOTS\fP +(bash compatibility) +.TP +\fBHASH_ALL\fP +\fBHASH_CMDS\fP +(bash compatibility) +.TP +\fBHIST_APPEND\fP +\fBAPPEND_HISTORY\fP +(bash compatibility) +.TP +\fBHIST_EXPAND\fP +\fBBANG_HIST\fP +(bash compatibility) +.TP +\fBLOG\fP +\fINO_\fP\fBHIST_NO_FUNCTIONS\fP +(ksh compatibility) +.TP +\fBMAIL_WARN\fP +\fBMAIL_WARNING\fP +(bash compatibility) +.TP +\fBONE_CMD\fP +\fBSINGLE_COMMAND\fP +(bash compatibility) +.TP +\fBPHYSICAL\fP +\fBCHASE_LINKS\fP +(ksh and bash compatibility) +.TP +\fBPROMPT_VARS\fP +\fBPROMPT_SUBST\fP +(bash compatibility) +.TP +\fBSTDIN\fP +\fBSHIN_STDIN\fP +(ksh compatibility) +.TP +\fBTRACK_ALL\fP +\fBHASH_CMDS\fP +(ksh compatibility) +.SH "SINGLE LETTER OPTIONS" +.SS "Default set" +.PD 0 +.TP +\fB\-0\fP +CORRECT +.TP +\fB\-1\fP +PRINT_EXIT_VALUE +.TP +\fB\-2\fP +\fINO_\fPBAD_PATTERN +.TP +\fB\-3\fP +\fINO_\fPNOMATCH +.TP +\fB\-4\fP +GLOB_DOTS +.TP +\fB\-5\fP +NOTIFY +.TP +\fB\-6\fP +BG_NICE +.TP +\fB\-7\fP +IGNORE_EOF +.TP +\fB\-8\fP +MARK_DIRS +.TP +\fB\-9\fP +AUTO_LIST +.TP +\fB\-B\fP +\fINO_\fPBEEP +.TP +\fB\-C\fP +\fINO_\fPCLOBBER +.TP +\fB\-D\fP +PUSHD_TO_HOME +.TP +\fB\-E\fP +PUSHD_SILENT +.TP +\fB\-F\fP +\fINO_\fPGLOB +.TP +\fB\-G\fP +NULL_GLOB +.TP +\fB\-H\fP +RM_STAR_SILENT +.TP +\fB\-I\fP +IGNORE_BRACES +.TP +\fB\-J\fP +AUTO_CD +.TP +\fB\-K\fP +\fINO_\fPBANG_HIST +.TP +\fB\-L\fP +SUN_KEYBOARD_HACK +.TP +\fB\-M\fP +SINGLE_LINE_ZLE +.TP +\fB\-N\fP +AUTO_PUSHD +.TP +\fB\-O\fP +CORRECT_ALL +.TP +\fB\-P\fP +RC_EXPAND_PARAM +.TP +\fB\-Q\fP +PATH_DIRS +.TP +\fB\-R\fP +LONG_LIST_JOBS +.TP +\fB\-S\fP +REC_EXACT +.TP +\fB\-T\fP +CDABLE_VARS +.TP +\fB\-U\fP +MAIL_WARNING +.TP +\fB\-V\fP +\fINO_\fPPROMPT_CR +.TP +\fB\-W\fP +AUTO_RESUME +.TP +\fB\-X\fP +LIST_TYPES +.TP +\fB\-Y\fP +MENU_COMPLETE +.TP +\fB\-Z\fP +ZLE +.TP +\fB\-a\fP +ALL_EXPORT +.TP +\fB\-e\fP +ERR_EXIT +.TP +\fB\-f\fP +\fINO_\fPRCS +.TP +\fB\-g\fP +HIST_IGNORE_SPACE +.TP +\fB\-h\fP +HIST_IGNORE_DUPS +.TP +\fB\-i\fP +INTERACTIVE +.TP +\fB\-k\fP +INTERACTIVE_COMMENTS +.TP +\fB\-l\fP +LOGIN +.TP +\fB\-m\fP +MONITOR +.TP +\fB\-n\fP +\fINO_\fPEXEC +.TP +\fB\-p\fP +PRIVILEGED +.TP +\fB\-r\fP +RESTRICTED +.TP +\fB\-s\fP +SHIN_STDIN +.TP +\fB\-t\fP +SINGLE_COMMAND +.TP +\fB\-u\fP +\fINO_\fPUNSET +.TP +\fB\-v\fP +VERBOSE +.TP +\fB\-w\fP +CHASE_LINKS +.TP +\fB\-x\fP +XTRACE +.TP +\fB\-y\fP +SH_WORD_SPLIT +.PD +.SS "sh/ksh emulation set" +.PD 0 +.TP +\fB\-C\fP +\fINO_\fPCLOBBER +.TP +\fB\-T\fP +TRAPS_ASYNC +.TP +\fB\-X\fP +MARK_DIRS +.TP +\fB\-a\fP +ALL_EXPORT +.TP +\fB\-b\fP +NOTIFY +.TP +\fB\-e\fP +ERR_EXIT +.TP +\fB\-f\fP +\fINO_\fPGLOB +.TP +\fB\-i\fP +INTERACTIVE +.TP +\fB\-l\fP +LOGIN +.TP +\fB\-m\fP +MONITOR +.TP +\fB\-n\fP +\fINO_\fPEXEC +.TP +\fB\-p\fP +PRIVILEGED +.TP +\fB\-r\fP +RESTRICTED +.TP +\fB\-s\fP +SHIN_STDIN +.TP +\fB\-t\fP +SINGLE_COMMAND +.TP +\fB\-u\fP +\fINO_\fPUNSET +.TP +\fB\-v\fP +VERBOSE +.TP +\fB\-x\fP +XTRACE +.PD +.SS "Also note" +.PD 0 +.TP +\fB\-A\fP +Used by \fBset\fP for setting arrays +.TP +\fB\-b\fP +Used on the command line to specify end of option processing +.TP +\fB\-c\fP +Used on the command line to specify a single command +.TP +\fB\-m\fP +Used by \fBsetopt\fP for pattern\-matching option setting +.TP +\fB\-o\fP +Used in all places to allow use of long option names +.TP +\fB\-s\fP +Used by \fBset\fP to sort positional parameters +.PD diff --git a/Doc/zshparam.1 b/Doc/zshparam.1 new file mode 100644 index 000000000..fde15f575 --- /dev/null +++ b/Doc/zshparam.1 @@ -0,0 +1,1835 @@ +.TH "ZSHPARAM" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshparam \- zsh parameters +.\" Yodl file: Zsh/params.yo +.SH "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 +`\fB*\fP\&', `\fB@\fP', `\fB#\fP', `\fB?\fP', `\fB\-\fP', `\fB$\fP', or `\fB!\fP'\&. +A parameter whose name begins with an alphanumeric or underscore is also +referred to as a \fIvariable\fP\&. +.PP +The attributes of a parameter determine the \fItype\fP 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 \fIscalar\fP (a string, an integer, or a floating +point number), an array (indexed numerically), or an \fIassociative\fP +array (an unordered set of name\-value pairs, indexed by name, also +referred to as a \fIhash\fP)\&. +.PP +Named scalar parameters may have the \fIexported\fP, \fB\-x\fP, 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 +\fIenvironment variables\fP\&. The shell also \fIimports\fP 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\&. +.PP +Parameters may also be \fIspecial\fP, 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\&. +.PP +To declare the type of a parameter, or to assign a string or numeric value +to a scalar parameter, use the \fBtypeset\fP builtin\&. +.PP +The value of a scalar parameter may also be assigned by writing: + +.RS +.nf +\fIname\fP\fB=\fP\fIvalue\fP +.fi +.RE +.PP +In scalar assignment, \fIvalue\fP is expanded as a single string, in +which the elements of arrays are joined together; filename expansion is +not performed unless the option \fBGLOB_ASSIGN\fP is set\&. +.PP +When the integer attribute, \fB\-i\fP, or a floating point attribute, \fB\-E\fP +or \fB\-F\fP, is set for \fIname\fP, the \fIvalue\fP is subject to arithmetic +evaluation\&. Furthermore, by replacing `\fB=\fP\&' with `\fB+=\fP', a parameter +can be incremented or appended to\&. See the section `Array Parameters\&' and +\fIArithmetic Evaluation\fP (in \fIzshmisc\fP(1)) +for additional forms of assignment\&. +.PP +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 \fBGLOB_ASSIGN\fP assigning a +pattern to a variable may change its type to an array\&. +.PP +To reference the value of a parameter, write `\fB$\fP\fIname\fP\&' or +`\fB${\fP\fIname\fP\fB}\fP\&'\&. See +\fIParameter Expansion\fP in \fIzshexpn\fP(1) +for complete details\&. That section also explains the effect +of the difference between scalar and array assignment on parameter +expansion\&. +.SH "ARRAY PARAMETERS" +To assign an array value, write one of: + +.RS +.nf +\fBset \-A\fP \fIname\fP \fIvalue\fP \&.\&.\&. +.fi +.RE +.RS +.nf +\fIname\fP\fB=(\fP\fIvalue\fP \&.\&.\&.\fB)\fP +.fi +.RE +.RS +.nf +\fIname\fP\fB=(\fP\fB[\fP\fIkey\fP\fB]=\fP\fIvalue\fP \&.\&.\&.\fB)\fP +.fi +.RE +.PP +If no parameter \fIname\fP exists, an ordinary array parameter is created\&. +If the parameter \fIname\fP exists and is a scalar, it is replaced by a new +array\&. +.PP +In the third form, \fIkey\fP 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 \fIvalue\fP\&. 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: \fB[\fP and \fB]=\fP must +not be quoted, and \fIkey\fP may not consist of the unquoted string +\fB]=\fP, 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\&. +.PP +The syntaxes with and without the explicit key may be mixed\&. An implicit +\fIkey\fP 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\&. +.PP +For example, assuming the option \fBKSH_ARRAYS\fP is not set, the following: +.PP +.RS +.nf +\fBarray=(one [3]=three four)\fP +.fi +.RE +.PP +causes the array variable \fBarray\fP to contain four elements \fBone\fP, +an empty string, \fBthree\fP and \fBfour\fP, in that order\&. +.PP +In the forms where only \fIvalue\fP is specified, full command +line expansion is performed\&. +.PP +In the \fB[\fP\fIkey\fP\fB]=\fP\fIvalue\fP form, +both \fIkey\fP and \fIvalue\fP 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 +\fB(e)\fP as described in +\fIzshexpn\fP(1)\&. +Nested parentheses may surround \fIvalue\fP 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: + +.RS +.nf +\fIname\fP\fB=(\fP\fB[a\-z]\&'='*)\fP +.fi +.RE +.PP +To append to an array without changing the existing values, use +one of the following: + +.RS +.nf +\fIname\fP\fB+=(\fP\fIvalue\fP \&.\&.\&.\fB)\fP +.fi +.RE +.RS +.nf +\fIname\fP\fB+=(\fP\fB[\fP\fIkey\fP\fB]=\fP\fIvalue\fP \&.\&.\&.\fB)\fP +.fi +.RE +.PP +In the second form \fIkey\fP may specify an existing index as well as an +index off the end of the old array; any existing value is overwritten by +\fIvalue\fP\&. Also, it is possible to use \fB[\fP\fIkey\fP\fB]+=\fP\fIvalue\fP +to append to the existing value at that index\&. +.PP +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 \fIvalue\fPs\&. Any consecutive sequence of such +characters has the same effect\&. +.PP +Ordinary array parameters may also be explicitly declared with: + +.RS +.nf +\fBtypeset \-a\fP \fIname\fP +.fi +.RE +.PP +Associative arrays \fImust\fP be declared before assignment, by using: + +.RS +.nf +\fBtypeset \-A\fP \fIname\fP +.fi +.RE +.PP +When \fIname\fP refers to an associative array, the list in an assignment +is interpreted as alternating keys and values: + +.RS +.nf +\fBset \-A\fP \fIname\fP \fIkey\fP \fIvalue\fP \&.\&.\&. +.fi +.RE +.RS +.nf +\fIname\fP\fB=(\fP\fIkey\fP \fIvalue\fP \&.\&.\&.\fB)\fP +.fi +.RE +.RS +.nf +\fIname\fP\fB=(\fP\fB[\fP\fIkey\fP\fB]=\fP\fIvalue\fP \&.\&.\&.\fB)\fP +.fi +.RE +.PP +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\&. +.PP +Every \fIkey\fP must have a \fIvalue\fP 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: + +.RS +.nf +\fIname\fP\fB+=(\fP\fIkey\fP \fIvalue\fP \&.\&.\&.\fB)\fP +.fi +.RE +.RS +.nf +\fIname\fP\fB+=(\fP\fB[\fP\fIkey\fP\fB]=\fP\fIvalue\fP \&.\&.\&.\fB)\fP +.fi +.RE +.PP +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 \fB[\fP\fIkey\fP\fB]+=\fP\fIvalue\fP to +append to the existing value at that key\&. Expansion is performed +identically to the corresponding forms for normal arrays, as +described above\&. +.PP +To create an empty array (including associative arrays), use one of: + +.RS +.nf +\fBset \-A\fP \fIname\fP +.fi +.RE +.RS +.nf +\fIname\fP\fB=()\fP +.fi +.RE +.PP +.SS "Array Subscripts" +Individual elements of an array may be selected using a subscript\&. A +subscript of the form `\fB[\fP\fIexp\fP\fB]\fP\&' selects the single element +\fIexp\fP, where \fIexp\fP is an arithmetic expression which will be subject +to arithmetic expansion as if it were surrounded by +`\fB$((\fP\&.\&.\&.\fB))\fP\&'\&. The elements are numbered +beginning with 1, unless the \fBKSH_ARRAYS\fP option is set in which case +they are numbered from zero\&. +.PP +Subscripts may be used inside braces used to delimit a parameter name, thus +`\fB${foo[2]}\fP\&' is equivalent to `\fB$foo[2]\fP'\&. If the \fBKSH_ARRAYS\fP +option is set, the braced form is the only one that works, as bracketed +expressions otherwise are not treated as subscripts\&. +.PP +If the \fBKSH_ARRAYS\fP 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 \fBKSH_ZERO_SUBSCRIPT\fP +option can be set to cause subscript values 0 and 1 to be equivalent; see +the description of the option in \fIzshoptions\fP(1)\&. +.PP +The same subscripting syntax is used for associative arrays, except that +no arithmetic expansion is applied to \fIexp\fP\&. However, the parsing +rules for arithmetic expressions still apply, which affects the way that +certain special characters must be protected from interpretation\&. See +\fISubscript Parsing\fP below for details\&. +.PP +A subscript of the form `\fB[*]\fP\&' or `\fB[@]\fP' evaluates to all elements +of an array; there is no difference between the two except when they +appear within double quotes\&. +`\fB"$foo[*]"\fP\&' evaluates to `\fB"$foo[1] $foo[2] \fP\&.\&.\&.\fB"\fP', whereas +`\fB"$foo[@]"\fP\&' evaluates to `\fB"$foo[1]" "$foo[2]" \fP\&.\&.\&.'\&. For +associative arrays, `\fB[*]\fP\&' or `\fB[@]\fP' evaluate to all the values, +in no particular order\&. Note that this does not substitute +the keys; see the documentation for the `\fBk\fP\&' flag under +\fIParameter Expansion Flags\fP in \fIzshexpn\fP(1) +for complete details\&. +When an array parameter is referenced as `\fB$\fP\fIname\fP\&' (with no +subscript) it evaluates to `\fB$\fP\fIname\fP\fB[*]\fP\&', unless the \fBKSH_ARRAYS\fP +option is set in which case it evaluates to `\fB${\fP\fIname\fP\fB[0]}\fP\&' (for +an associative array, this means the value of the key `\fB0\fP\&', which may +not exist even if there are values for other keys)\&. +.PP +A subscript of the form `\fB[\fP\fIexp1\fP\fB,\fP\fIexp2\fP\fB]\fP\&' +selects all elements in the range \fIexp1\fP to \fIexp2\fP, +inclusive\&. (Associative arrays are unordered, and so do not support +ranges\&.) If one of the subscripts evaluates to a negative number, +say \fB\-\fP\fIn\fP, then the \fIn\fPth element from the end +of the array is used\&. Thus `\fB$foo[\-3]\fP\&' is the third element +from the end of the array \fBfoo\fP, and +`\fB$foo[1,\-1]\fP\&' is the same as `\fB$foo[*]\fP'\&. +.PP +Subscripting may also be performed on non\-array values, in which +case the subscripts specify a substring to be extracted\&. +For example, if \fBFOO\fP is set to `\fBfoobar\fP\&', then +`\fBecho $FOO[2,5]\fP\&' prints `\fBooba\fP'\&. 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, +.PP +.RS +.nf +\fBstring="abcdefghijklm" +print ${string[(r)d?,(r)h?]}\fP +.fi +.RE +.PP +prints `\fBdefghi\fP\&'\&. 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)\&. +.PP +Note that in substring operations the second subscript is handled +differently by the \fBr\fP and \fBR\fP subscript flags: the former takes the +shortest match as the length and the latter the longest match\&. Hence +in the former case a \fB*\fP 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\&. +.PP +.SS "Array Element Assignment" +.PP +A subscript may be used on the left side of an assignment like so: + +.RS +.nf +\fIname\fP\fB[\fP\fIexp\fP\fB]=\fP\fIvalue\fP +.fi +.RE +.PP +In this form of assignment the element or range specified by \fIexp\fP +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\&.) +.PP +This syntax also works as an argument to the \fBtypeset\fP command: + +.RS +.nf +\fBtypeset\fP \fB"\fP\fIname\fP\fB[\fP\fIexp\fP\fB]"=\fP\fIvalue\fP +.fi +.RE +.PP +The \fIvalue\fP may \fInot\fP be a parenthesized list in this case; only +single\-element assignments may be made with \fBtypeset\fP\&. Note that quotes +are necessary in this case to prevent the brackets from being interpreted +as filename generation operators\&. The \fBnoglob\fP precommand modifier +could be used instead\&. +.PP +To delete an element of an ordinary array, assign `\fB()\fP\&' to +that element\&. To delete an element of an associative array, use the +\fBunset\fP command: + +.RS +.nf +\fBunset\fP \fB"\fP\fIname\fP\fB[\fP\fIexp\fP\fB]"\fP +.fi +.RE +.PP +.SS "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 +`\fIname\fP\fB[(\fP\fIflags\fP\fB)\fP\fIexp\fP\fB]\fP\&'\&. +.PP +The flags \fBs\fP, \fBn\fP and \fBb\fP take an argument; the delimiter +is shown below as `\fB:\fP\&', but any character, or the matching pairs +`\fB(\fP\&.\&.\&.\fB)\fP\&', `\fB{\fP\&.\&.\&.\fB}\fP', `\fB[\fP\&.\&.\&.\fB]\fP', or +`\fB<\fP\&.\&.\&.\fB>\fP\&', may be used, but note that `\fB<\fP\&.\&.\&.\fB>\fP' 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\&. +.PP +The flags currently understood are: +.PP +.PD 0 +.TP +.PD +\fBw\fP +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 \fBi\fP or \fBI\fP 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\&. +.TP +\fBs:\fP\fIstring\fP\fB:\fP +This gives the \fIstring\fP that separates words (for use with the +\fBw\fP flag)\&. The delimiter character \fB:\fP is arbitrary; see above\&. +.TP +\fBp\fP +Recognize the same escape sequences as the \fBprint\fP builtin in +the string argument of a subsequent `\fBs\fP\&' flag\&. +.TP +\fBf\fP +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 `\fBpws:\en:\fP\&'\&. +.TP +\fBr\fP +Reverse subscripting: if this flag is given, the \fIexp\fP 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 `\fBw\fP\&' flag is given, respectively)\&. The subscript used +is the number of the matching element, so that pairs of subscripts such as +`\fB$foo[(r)??,3]\fP\&' and `\fB$foo[(r)??,(r)f*]\fP' 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\&. +.RS +.PP +If a search through an ordinary array failed, the search sets the +subscript to one past the end of the array, and hence +\fB${array[(r)\fP\fIpattern\fP\fB]}\fP will substitute the empty string\&. Thus the +success of a search can be tested by using the \fB(i)\fP flag, for +example (assuming the option \fBKSH_ARRAYS\fP is not in effect): +.PP +.RS +.nf +\fB[[ ${array[(i)pattern]} \-le ${#array} ]]\fP +.fi +.RE +.PP +If \fBKSH_ARRAYS\fP is in effect, the \fB\-le\fP should be replaced by \fB\-lt\fP\&. +.RE +.TP +\fBR\fP +Like `\fBr\fP\&', 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 \fBKSH_ARRAYS\fP or +\fBKSH_ZERO_SUBSCRIPT\fP is in effect\&. +.RS +.PP +Note that in subscripts with both `\fBr\fP\&' and `\fBR\fP' pattern characters +are active even if they were substituted for a parameter (regardless of the +setting of \fBGLOB_SUBST\fP which controls this feature in normal pattern +matching)\&. The flag `\fBe\fP\&' 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: +.PP +.RS +.nf +\fBkey2=\&'original key' +print ${array[(Re)$key2]}\fP +.fi +.RE +.RE +.TP +\fBi\fP +Like `\fBr\fP\&', 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 `\fBr\fP\&'\&. 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 `\fBr\fP\&', or the empty string for an +associative array\&. +.RS +.PP +Note: Although `\fBi\fP\&' may be applied to a scalar substitution to find +the offset of a substring, the results are likely to be misleading when +searching within substitutions that yield an empty string, or when +searching for the empty substring\&. +.RE +.TP +\fBI\fP +Like `\fBi\fP\&', 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\&. +.RS +.PP +Note: If the option \fBKSH_ARRAYS\fP is in effect and no match is found, the +result is indistinguishable from the case when the first element of the array +matches\&. +.RE +.TP +\fBk\fP +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 \fIexp\fP 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 `\fBr\fP\&'\&. +.TP +\fBK\fP +On an associative array this is like `\fBk\fP\&' but returns all values where +\fIexp\fP is matched by the keys\&. On other types of parameters this has +the same effect as `\fBR\fP\&'\&. +.TP +\fBn:\fP\fIexpr\fP\fB:\fP +If combined with `\fBr\fP\&', `\fBR\fP', `\fBi\fP' or `\fBI\fP', makes them give +the \fIn\fPth or \fIn\fPth last match (if \fIexpr\fP evaluates to +\fIn\fP)\&. This flag is ignored when the array is associative\&. +The delimiter character \fB:\fP is arbitrary; see above\&. +.TP +\fBb:\fP\fIexpr\fP\fB:\fP +If combined with `\fBr\fP\&', `\fBR\fP', `\fBi\fP' or `\fBI\fP', makes them begin +at the \fIn\fPth or \fIn\fPth last element, word, or character (if \fIexpr\fP +evaluates to \fIn\fP)\&. This flag is ignored when the array is associative\&. +The delimiter character \fB:\fP is arbitrary; see above\&. +.TP +\fBe\fP +This flag causes any pattern matching that would be performed on the +subscript to use plain string matching instead\&. Hence +`\fB${array[(re)*]}\fP\&' matches only the array element whose value is \fB*\fP\&. +Note that other forms of substitution such as parameter substitution are +not inhibited\&. +.RS +.PP +This flag can also be used to force \fB*\fP or \fB@\fP 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\&. +.RE +.PP +See \fIParameter Expansion Flags\fP (\fIzshexpn\fP(1)) for additional ways to manipulate the results of array subscripting\&. +.PP +.SS "Subscript Parsing" +.PP +This discussion applies mainly to associative array key strings and to +patterns used for reverse subscripting (the `\fBr\fP\&', `\fBR\fP', `\fBi\fP', +etc\&. flags), but it may also affect parameter substitutions that appear +as part of an arithmetic expression in an ordinary subscript\&. +.PP +To avoid subscript parsing limitations in assignments to associative array +elements, use the append syntax: +.PP +.RS +.nf +\fBaa+=(\&'key with "*strange*" characters' 'value string')\fP +.fi +.RE +.PP +The basic rule to remember when writing a subscript expression is that all +text between the opening `\fB[\fP\&' and the closing `\fB]\fP' is interpreted +\fIas if\fP it were in double quotes (see \fIzshmisc\fP(1))\&. 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\&. +.PP +The first difference is that brackets (`\fB[\fP\&' and `\fB]\fP') must appear as +balanced pairs in a subscript expression unless they are preceded by a +backslash (`\fB\e\fP\&')\&. Therefore, within a subscript expression (and unlike +true double\-quoting) the sequence `\fB\e[\fP\&' becomes `\fB[\fP', and similarly +`\fB\e]\fP\&' becomes `\fB]\fP'\&. This applies even in cases where a backslash is +not normally required; for example, the pattern `\fB[^[]\fP\&' (to match any +character other than an open bracket) should be written `\fB[^\e[]\fP\&' in a +reverse\-subscript pattern\&. However, note that `\fB\e[^\e[\e]\fP\&' and even +`\fB\e[^[]\fP\&' mean the \fIsame\fP thing, because backslashes are always +stripped when they appear before brackets! +.PP +The same rule applies to parentheses (`\fB(\fP\&' and `\fB)\fP') and +braces (`\fB{\fP\&' and `\fB}\fP'): 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\&. +.PP +The second difference is that a double\-quote (`\fB"\fP\&') may appear as part +of a subscript expression without being preceded by a backslash, and +therefore that the two characters `\fB\e"\fP\&' remain as two characters in the +subscript (in true double\-quoting, `\fB\e"\fP\&' becomes `\fB"\fP')\&. 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 `\fB\e"\fP\&' (rather than `\fB\e\e\e"\fP') for `\fB"\fP'\&. +.PP +To use an odd number of double quotes as a key in an assignment, use the +\fBtypeset\fP builtin and an enclosing pair of double quotes; to refer to +the value of that key, again use double quotes: +.PP +.RS +.nf +\fBtypeset \-A aa +typeset "aa[one\e"two\e"three\e"quotes]"=QQQ +print "$aa[one\e"two\e"three\e"quotes]"\fP +.fi +.RE +.PP +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\&. +.PP +A further complication arises from a way in which subscript parsing is +\fInot\fP different from double quote parsing\&. As in true double\-quoting, +the sequences `\fB\e*\fP\&', and `\fB\e@\fP' remain as two characters when they +appear in a subscript expression\&. To use a literal `\fB*\fP\&' or `\fB@\fP' as +an associative array key, the `\fBe\fP\&' flag must be used: +.PP +.RS +.nf +\fBtypeset \-A aa +aa[(e)*]=star +print $aa[(e)*]\fP +.fi +.RE +.PP +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 \fBGLOB_SUBST\fP 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 \fIfour\fP 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 `\fB${(q\fP\fB)\fP\fIname\fP\fB}\fP\&' (see \fIzshexpn\fP(1)) to quote the expanded value\&. +.PP +Note that the `\fBk\fP\&' and `\fBK\fP' flags are reverse subscripting for an +ordinary array, but are \fInot\fP 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\&.) +.PP +One final note, not directly related to subscripting: the numeric names +of positional parameters (described below) are parsed specially, so for example `\fB$2foo\fP\&' is equivalent to +`\fB${2}foo\fP\&'\&. Therefore, to use subscript syntax to extract a substring +from a positional parameter, the expansion must be surrounded by braces; +for example, `\fB${2[3,5]}\fP\&' evaluates to the third through fifth +characters of the second positional parameter, but `\fB$2[3,5]\fP\&' is the +entire second parameter concatenated with the filename generation pattern +`\fB[3,5]\fP\&'\&. +.PP +.SH "POSITIONAL PARAMETERS" +The positional parameters provide access to the command\-line arguments +of a shell function, shell script, or the shell itself; see +the section `Invocation\&', and also the section `Functions'\&. +The parameter \fIn\fP, where \fIn\fP is a number, +is the \fIn\fPth positional parameter\&. +The parameter `\fB$0\fP\&' is a special case, see +the section `Parameters Set By The Shell\&'\&. +.PP +The parameters \fB*\fP, \fB@\fP and \fBargv\fP are +arrays containing all the positional parameters; +thus `\fB$argv[\fP\fIn\fP\fB]\fP\&', etc\&., is equivalent to simply `\fB$\fP\fIn\fP'\&. +Note that the options \fBKSH_ARRAYS\fP or \fBKSH_ZERO_SUBSCRIPT\fP apply +to these arrays as well, so with either of those options set, +`\fB${argv[0]}\fP\&' is equivalent to `\fB$1\fP' and so on\&. +.PP +Positional parameters may be changed after the shell or function starts by +using the \fBset\fP builtin, by assigning to the \fBargv\fP array, or by direct +assignment of the form `\fIn\fP\fB=\fP\fIvalue\fP\&' where \fIn\fP is the number of +the positional parameter to be changed\&. This also creates (with empty +values) any of the positions from 1 to \fIn\fP that do not already have +values\&. Note that, because the positional parameters form an array, an +array assignment of the form `\fIn\fP\fB=(\fP\fIvalue\fP \&.\&.\&.\fB)\fP\&' is +allowed, and has the effect of shifting all the values at positions greater +than \fIn\fP by as many positions as necessary to accommodate the new values\&. +.PP +.SH "LOCAL PARAMETERS" +Shell function executions delimit scopes for shell parameters\&. +(Parameters are dynamically scoped\&.) The \fBtypeset\fP builtin, and its +alternative forms \fBdeclare\fP, \fBinteger\fP, \fBlocal\fP and \fBreadonly\fP +(but not \fBexport\fP), can be used to declare a parameter as being local +to the innermost scope\&. +.PP +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 \fBexport\fP, +causes it to be created in the \fIouter\fPmost scope\&. +.PP +Local parameters disappear when their scope ends\&. +\fBunset\fP can be used to delete a parameter while it is still in scope; +any outer parameter of the same name remains hidden\&. +.PP +Special parameters may also be made local; they retain their special +attributes unless either the existing or the newly\-created parameter +has the \fB\-h\fP (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: +.PP +.RS +.nf +\fBtypeset PATH=/new/directory:$PATH\fP +.fi +.RE +.PP +is valid for temporarily allowing the shell or programmes called from it to +find the programs in \fB/new/directory\fP inside a function\&. +.PP +Note that the restriction in older versions of zsh that local parameters +were never exported has been removed\&. +.PP +.SH "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 \fBsh\fP or \fBksh\fP emulation mode\&. +.PP +The parameters `\fB!\fP\&', `\fB#\fP', `\fB*\fP', `\fB\-\fP', `\fB?\fP', `\fB@\fP', +`\fB$\fP\&', `\fBARGC\fP', `\fBHISTCMD\fP', `\fBLINENO\fP', `\fBPPID\fP', +`\fBstatus\fP\&', `\fBTTYIDLE\fP', `\fBzsh_eval_context\fP', +`\fBZSH_EVAL_CONTEXT\fP\&', and `\fBZSH_SUBSHELL\fP' are read\-only and thus +cannot be restored by the user, so they are not output by +`\fBtypeset \-p\fP\&'\&. This also applies to many read\-only parameters loaded +from modules\&. +.PP +The following parameters are automatically set by the shell: +.PP +.PD 0 +.TP +.PD +\fB!\fP <S> +The process ID of the last command started in the background with \fB&\fP, +put into the background with the \fBbg\fP builtin, or spawned with \fBcoproc\fP\&. +.TP +\fB#\fP <S> +The number of positional parameters in decimal\&. Note that some confusion +may occur with the syntax \fB$#\fP\fIparam\fP which substitutes the length of +\fIparam\fP\&. Use \fB${#}\fP to resolve ambiguities\&. In particular, the +sequence `\fB$#\-\fP\fI\&.\&.\&.\fP\&' in an arithmetic expression is interpreted as +the length of the parameter \fB\-\fP, q\&.v\&. +.TP +\fBARGC\fP <S> <Z> +Same as \fB#\fP\&. +.TP +\fB$\fP <S> +The process ID of this shell, set when the shell initializes\&. Processes +forked from the shell without executing a new program, such as command +substitutions and commands grouped with \fB(\fP\fI\&.\&.\&.\fP\fB)\fP, +are subshells that duplicate the current shell, and thus substitute the +same value for \fB$$\fP as their parent shell\&. +.TP +\fB\-\fP <S> +Flags supplied to the shell on invocation or by the \fBset\fP +or \fBsetopt\fP commands\&. +.TP +\fB*\fP <S> +An array containing the positional parameters\&. +.TP +\fBargv\fP <S> <Z> +Same as \fB*\fP\&. Assigning to \fBargv\fP changes the local positional +parameters, but \fBargv\fP is \fInot\fP itself a local parameter\&. +Deleting \fBargv\fP with \fBunset\fP in any function deletes it everywhere, +although only the innermost positional parameter array is deleted (so +\fB*\fP and \fB@\fP in other scopes are not affected)\&. +.TP +\fB@\fP <S> +Same as \fBargv[@]\fP, even when \fBargv\fP is not set\&. +.TP +\fB?\fP <S> +The exit status returned by the last command\&. +.TP +\fB0\fP <S> +The name used to invoke the current shell, or as set by the \fB\-c\fP command +line option upon invocation\&. If the \fBFUNCTION_ARGZERO\fP option is set, +\fB$0\fP 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\&. +.TP +\fBstatus\fP <S> <Z> +Same as \fB?\fP\&. +.TP +\fBpipestatus\fP <S> <Z> +An array containing the exit statuses returned by all commands in the +last pipeline\&. +.TP +\fB_\fP <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\&. +.TP +\fBCPUTYPE\fP +The machine type (microprocessor class or machine model), +as determined at run time\&. +.TP +\fBEGID\fP <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 `\fB(EGID=\fP\fIgid\fP\fB; command)\fP\&' +.RS +.PP +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally\&. +.RE +.TP +\fBEUID\fP <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 `\fB(EUID=\fP\fIuid\fP\fB; command)\fP\&' +.RS +.PP +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally\&. +.RE +.TP +\fBERRNO\fP <S> +The value of \fBerrno\fP (see \fIerrno\fP(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 \fBzsh/system\fP module which +allows the number to be turned into a name or message\&. +.RS +.PP +To use this parameter, it must first be assigned a value (typically +0 (zero))\&. It is initially unset for scripting compatibility\&. +.RE +.TP +\fBFUNCNEST\fP <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\&. +.TP +\fBGID\fP <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 `\fB(GID=\fP\fIgid\fP\fB; command)\fP\&' +.RS +.PP +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally\&. +.RE +.TP +\fBHISTCMD\fP +The current history event number in an interactive shell, in other +words the event number for the command that caused \fB$HISTCMD\fP +to be read\&. If the current history event modifies the history, +\fBHISTCMD\fP changes to the new maximum history event number\&. +.TP +\fBHOST\fP +The current hostname\&. +.TP +\fBLINENO\fP <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 \fBfunctions\fP builtin\&. +.TP +\fBLOGNAME\fP +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 \fBtypeset\fP builtin\&. The value +is set to the string returned by the \fIgetlogin\fP(3) system call +if that is available\&. +.TP +\fBMACHTYPE\fP +The machine type (microprocessor class or machine model), +as determined at compile time\&. +.TP +\fBOLDPWD\fP +The previous working directory\&. This is set when the shell initializes +and whenever the directory changes\&. +.TP +\fBOPTARG\fP <S> +The value of the last option argument processed by the \fBgetopts\fP +command\&. +.TP +\fBOPTIND\fP <S> +The index of the last option argument processed by the \fBgetopts\fP +command\&. +.TP +\fBOSTYPE\fP +The operating system, as determined at compile time\&. +.TP +\fBPPID\fP <S> +The process ID of the parent of the shell, set when the shell initializes\&. +As with \fB$$\fP, the value does not change in subshells created as a +duplicate of the current shell\&. +.TP +\fBPWD\fP +The present working directory\&. This is set when the shell initializes +and whenever the directory changes\&. +.TP +\fBRANDOM\fP <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 \fBRANDOM\fP\&. +.RS +.PP +The values of \fBRANDOM\fP form an intentionally\-repeatable pseudo\-random +sequence; subshells that reference \fBRANDOM\fP will result +in identical pseudo\-random values unless the value of \fBRANDOM\fP is +referenced or seeded in the parent shell in between subshell invocations\&. +.RE +.TP +\fBSECONDS\fP <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\&. +.RS +.PP +Unlike other special parameters, the type of the \fBSECONDS\fP parameter can +be changed using the \fBtypeset\fP command\&. The type may be changed only +to one of the floating point types or back to integer\&. For example, +`\fBtypeset \-F SECONDS\fP\&' +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 \fBtypeset\fP\&. See +the documentation for the builtin \fBtypeset\fP in +\fIzshbuiltins\fP(1) for more details\&. +.RE +.TP +\fBSHLVL\fP <S> +Incremented by one each time a new shell is started\&. +.TP +\fBsignals\fP +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 +\fBHUP\fP is signal number 1, but is referred to as \fB$signals[2]\fP\&. This +is because of \fBEXIT\fP at position 1 in the array, which is used +internally by zsh but is not known to the operating system\&. +.TP +\fBTRY_BLOCK_ERROR\fP <S> +In an \fBalways\fP 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 +\fIComplex Commands\fP in \fIzshmisc\fP(1) +.TP +\fBTRY_BLOCK_INTERRUPT\fP <S> +This variable works in a similar way to \fBTRY_BLOCK_ERROR\fP, but +represents the status of an interrupt from the signal SIGINT, which +typically comes from the keyboard when the user types \fB^C\fP\&. If set to +0, any such interrupt will be reset; otherwise, the interrupt is +propagated after the \fBalways\fP block\&. +.RS +.PP +Note that it is possible that an interrupt arrives during the execution +of the \fBalways\fP block; this interrupt is also propagated\&. +.RE +.TP +\fBTTY\fP +The name of the tty associated with the shell, if any\&. +.TP +\fBTTYIDLE\fP <S> +The idle time of the tty associated with the shell in seconds or \-1 if there +is no such tty\&. +.TP +\fBUID\fP <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 `\fB(UID=\fP\fIuid\fP\fB; command)\fP\&' +.RS +.PP +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally\&. +.RE +.TP +\fBUSERNAME\fP <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 `\fB(USERNAME=\fP\fIusername\fP\fB; command)\fP\&' +.TP +\fBVENDOR\fP +The vendor, as determined at compile time\&. +.TP +\fBzsh_eval_context\fP <S> <Z> (\fBZSH_EVAL_CONTEXT\fP <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\&. +.RS +.PP +Note that the variable does not give information on syntactic context such +as pipelines or subshells\&. Use \fB$ZSH_SUBSHELL\fP to detect subshells\&. +.PP +The context is one of the following: +.PD 0 +.TP +.PD +\fBcmdarg\fP +Code specified by the \fB\-c\fP option to the command line that invoked +the shell\&. +.TP +\fBcmdsubst\fP +Command substitution using the \fB`\fP\fI\&.\&.\&.\fP\fB`\fP or +\fB$(\fP\fI\&.\&.\&.\fP\fB)\fP construct\&. +.TP +\fBequalsubst\fP +File substitution using the \fB=(\fP\fI\&.\&.\&.\fP\fB)\fP construct\&. +.TP +\fBeval\fP +Code executed by the \fBeval\fP builtin\&. +.TP +\fBevalautofunc\fP +Code executed with the \fBKSH_AUTOLOAD\fP mechanism in order to define +an autoloaded function\&. +.TP +\fBfc\fP +Code from the shell history executed by the \fB\-e\fP option to the \fBfc\fP +builtin\&. +.TP +\fBfile\fP +Lines of code being read directly from a file, for example by +the \fBsource\fP builtin\&. +.TP +\fBfilecode\fP +Lines of code being read from a \fB\&.zwc\fP file instead of directly +from the source file\&. +.TP +\fBglobqual\fP +Code executed by the \fBe\fP or \fB+\fP glob qualifier\&. +.TP +\fBglobsort\fP +Code executed to order files by the \fBo\fP glob qualifier\&. +.TP +\fBinsubst\fP +File substitution using the \fB<(\fP\fI\&.\&.\&.\fP\fB)\fP construct\&. +.TP +\fBloadautofunc\fP +Code read directly from a file to define an autoloaded function\&. +.TP +\fBoutsubst\fP +File substitution using the \fB>(\fP\fI\&.\&.\&.\fP\fB)\fP construct\&. +.TP +\fBsched\fP +Code executed by the \fBsched\fP builtin\&. +.TP +\fBshfunc\fP +A shell function\&. +.TP +\fBstty\fP +Code passed to \fBstty\fP by the \fBSTTY\fP environment variable\&. +Normally this is passed directly to the system\&'s \fBstty\fP command, +so this value is unlikely to be seen in practice\&. +.TP +\fBstyle\fP +Code executed as part of a style retrieved by the \fBzstyle\fP builtin +from the \fBzsh/zutil\fP module\&. +.TP +\fBtoplevel\fP +The highest execution level of a script or interactive shell\&. +.TP +\fBtrap\fP +Code executed as a trap defined by the \fBtrap\fP builtin\&. Traps +defined as functions have the context \fBshfunc\fP\&. As traps are +asynchronous they may have a different hierarchy from other +code\&. +.TP +\fBzpty\fP +Code executed by the \fBzpty\fP builtin from the \fBzsh/zpty\fP module\&. +.TP +\fBzregexparse\-guard\fP +Code executed as a guard by the \fBzregexparse\fP command from the +\fBzsh/zutil\fP module\&. +.TP +\fBzregexparse\-action\fP +Code executed as an action by the \fBzregexparse\fP command from the +\fBzsh/zutil\fP module\&. +.RE +.TP +\fBZSH_ARGZERO\fP +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 \fB$0\fP when the \fBPOSIX_ARGZERO\fP option is +set, but is always available\&. +.TP +\fBZSH_EXECUTION_STRING\fP +If the shell was started with the option \fB\-c\fP, this contains +the argument passed to the option\&. Otherwise it is not set\&. +.TP +\fBZSH_NAME\fP +Expands to the basename of the command used to invoke this instance +of zsh\&. +.TP +\fBZSH_PATCHLEVEL\fP +The output of `\fBgit describe \-\-tags \-\-long\fP\&' 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 +\fB$ZSH_VERSION\fP\&. +.TP +\fBzsh_scheduled_events\fP +See the section `The zsh/sched Module\&' in \fIzshmodules\fP(1)\&. +.TP +\fBZSH_SCRIPT\fP +If zsh was invoked to run a script, this is the name of the script, +otherwise it is unset\&. +.TP +\fBZSH_SUBSHELL\fP +Readonly integer\&. Initially zero, incremented each time the shell forks +to create a subshell for executing code\&. Hence `\fB(print $ZSH_SUBSHELL)\fP\&' +and `\fBprint $(print $ZSH_SUBSHELL)\fP\&' output 1, while +`\fB( (print $ZSH_SUBSHELL) )\fP\&' outputs 2\&. +.TP +\fBZSH_VERSION\fP +The version number of the release of zsh\&. +.SH "PARAMETERS USED BY THE SHELL" +The following parameters are used by the shell\&. Again, `<S>\&' indicates +that the parameter is special and `<Z>\&' indicates that the parameter does +not exist when the shell initializes in \fBsh\fP or \fBksh\fP emulation mode\&. +.PP +In cases where there are two parameters with an upper\- and lowercase +form of the same name, such as \fBpath\fP and \fBPATH\fP, the lowercase form +is an array and the uppercase form is a scalar with the elements of the +array joined together by colons\&. These are similar to tied parameters +created via `\fBtypeset \-T\fP\&'\&. The normal use for the colon\-separated +form is for exporting to the environment, while the array form is easier +to manipulate within the shell\&. Note that unsetting either of the pair +will unset the other; they retain their special properties when +recreated, and recreating one of the pair will recreate the other\&. +.PP +.PD 0 +.TP +.PD +\fBARGV0\fP +If exported, its value is used as the \fBargv[0]\fP of external commands\&. +Usually used in constructs like `\fBARGV0=emacs nethack\fP\&'\&. +.TP +\fBBAUD\fP +The rate in bits per second at which data reaches the terminal\&. +The line editor will use this value in order to compensate for a slow +terminal by delaying updates to the display until necessary\&. If the +parameter is unset or the value is zero the compensation mechanism is +turned off\&. The parameter is not set by default\&. +.RS +.PP +This parameter may be profitably set in some circumstances, e\&.g\&. +for slow modems dialing into a communications server, or on a slow wide +area network\&. It should be set to the baud +rate of the slowest part of the link for best performance\&. +.RE +.TP +\fBcdpath\fP <S> <Z> (\fBCDPATH\fP <S>) +An array (colon\-separated list) +of directories specifying the search path for the \fBcd\fP command\&. +.TP +\fBCOLUMNS\fP <S> +The number of columns for this terminal session\&. +Used for printing select lists and for the line editor\&. +.TP +\fBCORRECT_IGNORE\fP +If set, is treated as a pattern during spelling correction\&. Any +potential correction that matches the pattern is ignored\&. For example, +if the value is `\fB_*\fP\&' then completion functions (which, by +convention, have names beginning with `\fB_\fP\&') will never be offered +as spelling corrections\&. The pattern does not apply to the correction +of file names, as applied by the \fBCORRECT_ALL\fP option (so with the +example just given files beginning with `\fB_\fP\&' in the current +directory would still be completed)\&. +.TP +\fBCORRECT_IGNORE_FILE\fP +If set, is treated as a pattern during spelling correction of file names\&. +Any file name that matches the pattern is never offered as a correction\&. +For example, if the value is `\fB\&.*\fP\&' then dot file names will never be +offered as spelling corrections\&. This is useful with the +\fBCORRECT_ALL\fP option\&. +.TP +\fBDIRSTACKSIZE\fP +The maximum size of the directory stack, by default there is no limit\&. If the +stack gets larger than this, it will be truncated automatically\&. +This is useful with the \fBAUTO_PUSHD\fP option\&. +.TP +\fBENV\fP +If the \fBENV\fP environment variable is set when zsh is invoked as \fBsh\fP +or \fBksh\fP, \fB$ENV\fP is sourced after the profile scripts\&. The value of +\fBENV\fP is subjected to parameter expansion, command substitution, and +arithmetic expansion before being interpreted as a pathname\&. Note that +\fBENV\fP is \fInot\fP used unless the shell is interactive and zsh is +emulating \fBsh\fP or \fBksh\fP\&. +.TP +\fBFCEDIT\fP +The default editor for the \fBfc\fP builtin\&. If \fBFCEDIT\fP is not set, +the parameter \fBEDITOR\fP is used; if that is not set either, a builtin +default, usually \fBvi\fP, is used\&. +.TP +\fBfignore\fP <S> <Z> (\fBFIGNORE\fP <S>) +An array (colon separated list) +containing the suffixes of files to be ignored +during filename completion\&. However, if completion only generates files +with suffixes in this list, then these files are completed anyway\&. +.TP +\fBfpath\fP <S> <Z> (\fBFPATH\fP <S>) +An array (colon separated list) +of directories specifying the search path for +function definitions\&. This path is searched when a function +with the \fB\-u\fP attribute is referenced\&. If an executable +file is found, then it is read and executed in the current environment\&. +.TP +\fBhistchars\fP <S> +Three characters used by the shell\&'s history and lexical analysis +mechanism\&. The first character signals the start of a history +expansion (default `\fB!\fP\&')\&. The second character signals the +start of a quick history substitution (default `\fB^\fP\&')\&. The third +character is the comment character (default `\fB#\fP\&')\&. +.RS +.PP +The characters must be in the ASCII character set; any attempt to set +\fBhistchars\fP to characters with a locale\-dependent meaning will be +rejected with an error message\&. +.RE +.TP +\fBHISTCHARS\fP <S> <Z> +Same as \fBhistchars\fP\&. (Deprecated\&.) +.TP +\fBHISTFILE\fP +The file to save the history in when an interactive shell exits\&. +If unset, the history is not saved\&. +.TP +\fBHISTORY_IGNORE\fP +If set, is treated as a pattern at the time history files are written\&. +Any potential history entry that matches the pattern is skipped\&. For +example, if the value is `\fBfc *\fP\&' then commands that invoke the +interactive history editor are never written to the history file\&. +.RS +.PP +Note that \fBHISTORY_IGNORE\fP defines a single pattern: to +specify alternatives use the +`\fB(\fP\fIfirst\fP\fB|\fP\fIsecond\fP\fB|\fP\fI\&.\&.\&.\fP\fB)\fP\&' syntax\&. +.PP +Compare the \fBHIST_NO_STORE\fP option or the \fBzshaddhistory\fP hook, +either of which would prevent such commands from being added to the +interactive history at all\&. If you wish to use \fBHISTORY_IGNORE\fP to +stop history being added in the first place, you can define the +following hook: +.PP +.RS +.nf +\fBzshaddhistory() { + emulate \-L zsh + ## uncomment if HISTORY_IGNORE + ## should use EXTENDED_GLOB syntax + # setopt extendedglob + [[ $1 != ${~HISTORY_IGNORE} ]] +}\fP +.fi +.RE +.RE +.TP +\fBHISTSIZE\fP <S> +The maximum number of events stored in the internal history list\&. +If you use the \fBHIST_EXPIRE_DUPS_FIRST\fP option, setting this value +larger than the \fBSAVEHIST\fP size will give you the difference as a +cushion for saving duplicated history events\&. +.RS +.PP +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally\&. +.RE +.TP +\fBHOME\fP <S> +The default argument for the \fBcd\fP command\&. This is not set automatically +by the shell in \fBsh\fP, \fBksh\fP or \fBcsh\fP emulation, but it is typically +present in the environment anyway, and if it becomes set it has its usual +special behaviour\&. +.TP +\fBIFS\fP <S> +Internal field separators (by default space, tab, newline and NUL), that +are used to separate words which result from +command or parameter expansion and words read by +the \fBread\fP builtin\&. Any characters from the set space, tab and +newline that appear in the IFS are called \fIIFS white space\fP\&. +One or more IFS white space characters or one non\-IFS white space +character together with any adjacent IFS white space character delimit +a field\&. If an IFS white space character appears twice consecutively +in the IFS, this character is treated as if it were not an IFS white +space character\&. +.RS +.PP +If the parameter is unset, the default is used\&. Note this has +a different effect from setting the parameter to an empty string\&. +.RE +.TP +\fBKEYBOARD_HACK\fP +This variable defines a character to be removed from the end of the +command line before interpreting it (interactive shells only)\&. It is +intended to fix the problem with keys placed annoyingly close to return +and replaces the \fBSUNKEYBOARDHACK\fP option which did this for +backquotes only\&. Should the chosen character be one of singlequote, +doublequote or backquote, there must also be an odd number of them +on the command line for the last one to be removed\&. +.RS +.PP +For backward compatibility, if the \fBSUNKEYBOARDHACK\fP option is +explicitly set, the value of \fBKEYBOARD_HACK\fP reverts to backquote\&. +If the option is explicitly unset, this variable is set to empty\&. +.RE +.TP +\fBKEYTIMEOUT\fP +The time the shell waits, in hundredths of seconds, for another key to +be pressed when reading bound multi\-character sequences\&. +.TP +\fBLANG\fP <S> +This variable determines the locale category for any category not +specifically selected via a variable starting with `\fBLC_\fP\&'\&. +.TP +\fBLC_ALL\fP <S> +This variable overrides the value of the `\fBLANG\fP\&' variable and the value +of any of the other variables starting with `\fBLC_\fP\&'\&. +.TP +\fBLC_COLLATE\fP <S> +This variable determines the locale category for character collation +information within ranges in glob brackets and for sorting\&. +.TP +\fBLC_CTYPE\fP <S> +This variable determines the locale category for character handling +functions\&. If the \fBMULTIBYTE\fP option is in effect this variable or +\fBLANG\fP should contain a value that reflects the character set in +use, even if it is a single\-byte character set, unless only the +7\-bit subset (ASCII) is used\&. For example, if the character set +is ISO\-8859\-1, a suitable value might be \fBen_US\&.iso88591\fP (certain +Linux distributions) or \fBen_US\&.ISO8859\-1\fP (MacOS)\&. +.TP +\fBLC_MESSAGES\fP <S> +This variable determines the language in which messages should be +written\&. Note that zsh does not use message catalogs\&. +.TP +\fBLC_NUMERIC\fP <S> +This variable affects the decimal point character and thousands +separator character for the formatted input/output functions +and string conversion functions\&. Note that zsh ignores this +setting when parsing floating point mathematical expressions\&. +.TP +\fBLC_TIME\fP <S> +This variable determines the locale category for date and time +formatting in prompt escape sequences\&. +.TP +\fBLINES\fP <S> +The number of lines for this terminal session\&. +Used for printing select lists and for the line editor\&. +.TP +\fBLISTMAX\fP +In the line editor, the number of matches to list without asking +first\&. If the value is negative, the list will be shown if it spans at +most as many lines as given by the absolute value\&. +If set to zero, the shell asks only if the top of the listing would scroll +off the screen\&. +.TP +\fBMAIL\fP +If this parameter is set and \fBmailpath\fP is not set, +the shell looks for mail in the specified file\&. +.TP +\fBMAILCHECK\fP +The interval in seconds between checks for new mail\&. +.TP +\fBmailpath\fP <S> <Z> (\fBMAILPATH\fP <S>) +An array (colon\-separated list) of filenames to check for +new mail\&. Each filename can be followed by a `\fB?\fP\&' and a +message that will be printed\&. The message will undergo +parameter expansion, command substitution and arithmetic +expansion with the variable \fB$_\fP defined as the name +of the file that has changed\&. The default message is +`\fBYou have new mail\fP\&'\&. If an element is a directory +instead of a file the shell will recursively check every +file in every subdirectory of the element\&. +.TP +\fBmanpath\fP <S> <Z> (\fBMANPATH\fP <S> <Z>) +An array (colon\-separated list) +whose value is not used by the shell\&. The \fBmanpath\fP +array can be useful, however, since setting it also sets +\fBMANPATH\fP, and vice versa\&. +.TP +.PD 0 +\fBmatch\fP +.TP +.PD 0 +\fBmbegin\fP +.TP +.PD +\fBmend\fP +Arrays set by the shell when the \fBb\fP globbing flag is used in pattern +matches\&. See the subsection \fIGlobbing flags\fP in +the documentation for \fIFilename Generation\fP in \fIzshexpn\fP(1)\&. +.TP +.PD 0 +\fBMATCH\fP +.TP +.PD 0 +\fBMBEGIN\fP +.TP +.PD +\fBMEND\fP +Set by the shell when the \fBm\fP globbing flag is used in pattern +matches\&. See the subsection \fIGlobbing flags\fP in +the documentation for \fIFilename Generation\fP in \fIzshexpn\fP(1)\&. +.TP +\fBmodule_path\fP <S> <Z> (\fBMODULE_PATH\fP <S>) +An array (colon\-separated list) +of directories that \fBzmodload\fP +searches for dynamically loadable modules\&. +This is initialized to a standard pathname, +usually `\fB/usr/local/lib/zsh/$ZSH_VERSION\fP\&'\&. +(The `\fB/usr/local/lib\fP\&' part varies from installation to installation\&.) +For security reasons, any value set in the environment when the shell +is started will be ignored\&. +.RS +.PP +These parameters only exist if the installation supports dynamic +module loading\&. +.RE +.TP +\fBNULLCMD\fP <S> +The command name to assume if a redirection is specified +with no command\&. Defaults to \fBcat\fP\&. For \fBsh\fP/\fBksh\fP +behavior, change this to \fB:\fP\&. For \fBcsh\fP\-like +behavior, unset this parameter; the shell will print an +error message if null commands are entered\&. +.TP +\fBpath\fP <S> <Z> (\fBPATH\fP <S>) +An array (colon\-separated list) +of directories to search for commands\&. +When this parameter is set, each directory is scanned +and all files found are put in a hash table\&. +.TP +\fBPOSTEDIT\fP <S> +This string is output whenever the line editor exits\&. +It usually contains termcap strings to reset the terminal\&. +.TP +.PD 0 +\fBPROMPT\fP <S> <Z> +.TP +.PD 0 +\fBPROMPT2\fP <S> <Z> +.TP +.PD 0 +\fBPROMPT3\fP <S> <Z> +.TP +.PD +\fBPROMPT4\fP <S> <Z> +Same as \fBPS1\fP, \fBPS2\fP, \fBPS3\fP and \fBPS4\fP, +respectively\&. +.TP +\fBprompt\fP <S> <Z> +Same as \fBPS1\fP\&. +.TP +\fBPROMPT_EOL_MARK\fP +When the \fBPROMPT_CR\fP and \fBPROMPT_SP\fP options are set, the +\fBPROMPT_EOL_MARK\fP parameter can be used to customize how the end of +partial lines are shown\&. This parameter undergoes prompt expansion, with +the \fBPROMPT_PERCENT\fP option set\&. If not set, the default behavior is +equivalent to the value `\fB%B%S%#%s%b\fP\&'\&. +.TP +\fBPS1\fP <S> +The primary prompt string, printed before a command is read\&. +It undergoes a special form of expansion +before being displayed; see +EXPANSION OF PROMPT SEQUENCES in \fIzshmisc\fP(1)\&. The default is `\fB%m%# \fP\&'\&. +.TP +\fBPS2\fP <S> +The secondary prompt, printed when the shell needs more information +to complete a command\&. +It is expanded in the same way as \fBPS1\fP\&. +The default is `\fB%_> \fP\&', which displays any shell constructs or quotation +marks which are currently being processed\&. +.TP +\fBPS3\fP <S> +Selection prompt used within a \fBselect\fP loop\&. +It is expanded in the same way as \fBPS1\fP\&. +The default is `\fB?# \fP\&'\&. +.TP +\fBPS4\fP <S> +The execution trace prompt\&. Default is `\fB+%N:%i> \fP\&', which displays +the name of the current shell structure and the line number within it\&. +In sh or ksh emulation, the default is `\fB+ \fP\&'\&. +.TP +\fBpsvar\fP <S> <Z> (\fBPSVAR\fP <S>) +An array (colon\-separated list) whose elements can be used in +\fBPROMPT\fP strings\&. Setting \fBpsvar\fP also sets \fBPSVAR\fP, and +vice versa\&. +.TP +\fBREADNULLCMD\fP <S> +The command name to assume if a single input redirection +is specified with no command\&. Defaults to \fBmore\fP\&. +.TP +\fBREPORTMEMORY\fP +If nonnegative, commands whose maximum resident set size (roughly +speaking, main memory usage) in kilobytes is greater than this +value have timing statistics reported\&. The format used to output +statistics is the value of the \fBTIMEFMT\fP parameter, which is the same +as for the \fBREPORTTIME\fP variable and the \fBtime\fP builtin; note that +by default this does not output memory usage\&. Appending +\fB" max RSS %M"\fP to the value of \fBTIMEFMT\fP causes it to output the +value that triggered the report\&. If \fBREPORTTIME\fP is also in use, +at most a single report is printed for both triggers\&. This feature +requires the \fBgetrusage()\fP system call, commonly supported by +modern Unix\-like systems\&. +.TP +\fBREPORTTIME\fP +If nonnegative, commands whose combined user and system execution times +(measured in seconds) are greater than this value have timing +statistics printed for them\&. Output is suppressed for commands +executed within the line editor, including completion; commands +explicitly marked with the \fBtime\fP keyword still cause the summary +to be printed in this case\&. +.TP +\fBREPLY\fP +This parameter is reserved by convention to pass string values between +shell scripts and shell builtins in situations where a function call or +redirection are impossible or undesirable\&. The \fBread\fP builtin and the +\fBselect\fP complex command may set \fBREPLY\fP, and filename generation both +sets and examines its value when evaluating certain expressions\&. Some +modules also employ \fBREPLY\fP for similar purposes\&. +.TP +\fBreply\fP +As \fBREPLY\fP, but for array values rather than strings\&. +.TP +.PD 0 +\fBRPROMPT\fP <S> +.TP +.PD +\fBRPS1\fP <S> +This prompt is displayed on the right\-hand side of the screen +when the primary prompt is being displayed on the left\&. +This does not work if the \fBSINGLE_LINE_ZLE\fP option is set\&. +It is expanded in the same way as \fBPS1\fP\&. +.TP +.PD 0 +\fBRPROMPT2\fP <S> +.TP +.PD +\fBRPS2\fP <S> +This prompt is displayed on the right\-hand side of the screen +when the secondary prompt is being displayed on the left\&. +This does not work if the \fBSINGLE_LINE_ZLE\fP option is set\&. +It is expanded in the same way as \fBPS2\fP\&. +.TP +\fBSAVEHIST\fP +The maximum number of history events to save in the history file\&. +.RS +.PP +If this is made local, it is not implicitly set to 0, but may be +explicitly set locally\&. +.RE +.TP +\fBSPROMPT\fP <S> +The prompt used for spelling correction\&. The sequence +`\fB%R\fP\&' expands to the string which presumably needs spelling +correction, and `\fB%r\fP\&' expands to the proposed correction\&. +All other prompt escapes are also allowed\&. +.RS +.PP +The actions available at the prompt are \fB[nyae]\fP: +.PD 0 +.TP +\fBn\fP (`no\&') (default) +Discard the correction and run the command\&. +.TP +\fBy\fP (`yes\&') +Make the correction and run the command\&. +.TP +\fBa\fP (`abort\&') +Discard the entire command line without running it\&. +.TP +\fBe\fP (`edit\&') +Resume editing the command line\&. +.PD +.RE +.TP +\fBSTTY\fP +If this parameter is set in a command\&'s environment, the shell runs the +\fBstty\fP command with the value of this parameter as arguments in order to +set up the terminal before executing the command\&. The modes apply only to the +command, and are reset when it finishes or is suspended\&. If the command is +suspended and continued later with the \fBfg\fP or \fBwait\fP builtins it will +see the modes specified by \fBSTTY\fP, as if it were not suspended\&. This +(intentionally) does not apply if the command is continued via `\fBkill +\-CONT\fP\&'\&. \fBSTTY\fP is ignored if the command is run in the background, or +if it is in the environment of the shell but not explicitly assigned to in +the input line\&. This avoids running stty at every external command by +accidentally exporting it\&. Also note that \fBSTTY\fP should not be used for +window size specifications; these will not be local to the command\&. +.RS +.PP +If the parameter is set and empty, all of the above applies except +that \fBstty\fP is not run\&. This can be useful as a way to freeze the tty +around a single command, blocking its changes to tty settings, +similar to the \fBttyctl\fP builtin\&. +.RE +.TP +\fBTERM\fP <S> +The type of terminal in use\&. This is used when looking up termcap +sequences\&. An assignment to \fBTERM\fP causes zsh to re\-initialize the +terminal, even if the value does not change (e\&.g\&., `\fBTERM=$TERM\fP\&')\&. It +is necessary to make such an assignment upon any change to the terminal +definition database or terminal type in order for the new settings to +take effect\&. +.TP +\fBTERMINFO\fP <S> +A reference to your terminfo database, used by the `terminfo\&' library when the +system has it; see \fIterminfo\fP(5)\&. +If set, this causes the shell to reinitialise the terminal, making the +workaround `\fBTERM=$TERM\fP\&' unnecessary\&. +.TP +\fBTERMINFO_DIRS\fP <S> +A colon\-seprarated list of terminfo databases, used by the `terminfo\&' library +when the system has it; see \fIterminfo\fP(5)\&. This variable is only +used by certain terminal libraries, in particular ncurses; see +\fIterminfo\fP(5) to check support on your system\&. If set, this +causes the shell to reinitialise the terminal, making the workaround +`\fBTERM=$TERM\fP\&' unnecessary\&. Note that unlike other colon\-separated +arrays this is not tied to a zsh array\&. +.TP +\fBTIMEFMT\fP +The format of process time reports with the \fBtime\fP keyword\&. +The default is `\fB%J %U user %S system %P cpu %*E total\fP\&'\&. +Recognizes the following escape sequences, although not all +may be available on all systems, and some that are available +may not be useful: +.RS +.PP +.PD 0 +.TP +\fB%%\fP +A `\fB%\fP\&'\&. +.TP +\fB%U\fP +CPU seconds spent in user mode\&. +.TP +\fB%S\fP +CPU seconds spent in kernel mode\&. +.TP +\fB%E\fP +Elapsed time in seconds\&. +.TP +\fB%P\fP +The CPU percentage, computed as +100*(\fB%U\fP+\fB%S\fP)/\fB%E\fP\&. +.TP +\fB%W\fP +Number of times the process was swapped\&. +.TP +\fB%X\fP +The average amount in (shared) text space used in kilobytes\&. +.TP +\fB%D\fP +The average amount in (unshared) data/stack space used in +kilobytes\&. +.TP +\fB%K\fP +The total space used (\fB%X\fP+\fB%D\fP) in kilobytes\&. +.TP +\fB%M\fP +The maximum memory the process had in use at any time in +kilobytes\&. +.TP +\fB%F\fP +The number of major page faults (page needed to be brought +from disk)\&. +.TP +\fB%R\fP +The number of minor page faults\&. +.TP +\fB%I\fP +The number of input operations\&. +.TP +\fB%O\fP +The number of output operations\&. +.TP +\fB%r\fP +The number of socket messages received\&. +.TP +\fB%s\fP +The number of socket messages sent\&. +.TP +\fB%k\fP +The number of signals received\&. +.TP +\fB%w\fP +Number of voluntary context switches (waits)\&. +.TP +\fB%c\fP +Number of involuntary context switches\&. +.TP +\fB%J\fP +The name of this job\&. +.PD +.PP +A star may be inserted between the percent sign and flags printing time +(e\&.g\&., `\fB%*E\fP\&'); this causes the time to be printed in +`\fIhh\fP\fB:\fP\fImm\fP\fB:\fP\fIss\fP\fB\&.\fP\fIttt\fP\&' +format (hours and minutes are only printed if they are not zero)\&. +Alternatively, `\fBm\fP\&' or `\fBu\fP' may be used (e\&.g\&., `\fB%mE\fP') to produce +time output in milliseconds or microseconds, respectively\&. +.RE +.TP +\fBTMOUT\fP +If this parameter is nonzero, the shell will receive an \fBALRM\fP +signal if a command is not entered within the specified number of +seconds after issuing a prompt\&. If there is a trap on \fBSIGALRM\fP, it +will be executed and a new alarm is scheduled using the value of the +\fBTMOUT\fP parameter after executing the trap\&. If no trap is set, and +the idle time of the terminal is not less than the value of the +\fBTMOUT\fP parameter, zsh terminates\&. Otherwise a new alarm is +scheduled to \fBTMOUT\fP seconds after the last keypress\&. +.TP +\fBTMPPREFIX\fP +A pathname prefix which the shell will use for all temporary files\&. +Note that this should include an initial part for the file name as +well as any directory names\&. The default is `\fB/tmp/zsh\fP\&'\&. +.TP +\fBTMPSUFFIX\fP +A filename suffix which the shell will use for temporary files created +by process substitutions (e\&.g\&., `\fB=(\fIlist\fP)\fP\&')\&. +Note that the value should include a leading dot `\fB\&.\fP\&' if intended +to be interpreted as a file extension\&. The default is not to append +any suffix, thus this parameter should be assigned only when needed +and then unset again\&. +.TP +\fBWORDCHARS\fP <S> +A list of non\-alphanumeric characters considered part of a word +by the line editor\&. +.TP +\fBZBEEP\fP +If set, this gives a string of characters, which can use all the same codes +as the \fBbindkey\fP command as described in +the zsh/zle module entry in \fIzshmodules\fP(1), that will be output to the terminal +instead of beeping\&. This may have a visible instead of an audible effect; +for example, the string `\fB\ee[?5h\ee[?5l\fP\&' on a vt100 or xterm will have +the effect of flashing reverse video on and off (if you usually use reverse +video, you should use the string `\fB\ee[?5l\ee[?5h\fP\&' instead)\&. This takes +precedence over the \fBNOBEEP\fP option\&. +.TP +\fBZDOTDIR\fP +The directory to search for shell startup files (\&.zshrc, etc), +if not \fB$HOME\fP\&. +.TP +\fBzle_bracketed_paste\fP +Many terminal emulators have a feature that allows applications to +identify when text is pasted into the terminal rather than being typed +normally\&. For ZLE, this means that special characters such as tabs +and newlines can be inserted instead of invoking editor commands\&. +Furthermore, pasted text forms a single undo event and if the region is +active, pasted text will replace the region\&. +.RS +.PP +This two\-element array contains the terminal escape sequences for +enabling and disabling the feature\&. These escape sequences are used to +enable bracketed paste when ZLE is active and disable it at other times\&. +Unsetting the parameter has the effect of ensuring that bracketed paste +remains disabled\&. +.RE +.TP +\fBzle_highlight\fP +An array describing contexts in which ZLE should highlight the input text\&. +See \fICharacter Highlighting\fP in \fIzshzle\fP(1)\&. +.TP +\fBZLE_LINE_ABORTED\fP +This parameter is set by the line editor when an error occurs\&. It +contains the line that was being edited at the point of the error\&. +`\fBprint \-zr \-\- $ZLE_LINE_ABORTED\fP\&' can be used to recover the line\&. +Only the most recent line of this kind is remembered\&. +.TP +.PD 0 +\fBZLE_REMOVE_SUFFIX_CHARS\fP +.TP +.PD +\fBZLE_SPACE_SUFFIX_CHARS\fP +These parameters are used by the line editor\&. In certain circumstances +suffixes (typically space or slash) added by the completion system +will be removed automatically, either because the next editing command +was not an insertable character, or because the character was marked +as requiring the suffix to be removed\&. +.RS +.PP +These variables can contain the sets of characters that will cause the +suffix to be removed\&. If \fBZLE_REMOVE_SUFFIX_CHARS\fP is set, those +characters will cause the suffix to be removed; if +\fBZLE_SPACE_SUFFIX_CHARS\fP is set, those characters will cause the +suffix to be removed and replaced by a space\&. +.PP +If \fBZLE_REMOVE_SUFFIX_CHARS\fP is not set, the default behaviour is +equivalent to: +.PP +.RS +.nf +\fBZLE_REMOVE_SUFFIX_CHARS=$\&' \et\en;&|'\fP +.fi +.RE +.PP +If \fBZLE_REMOVE_SUFFIX_CHARS\fP is set but is empty, no characters have this +behaviour\&. \fBZLE_SPACE_SUFFIX_CHARS\fP takes precedence, so that the +following: +.PP +.RS +.nf +\fBZLE_SPACE_SUFFIX_CHARS=$\&'&|'\fP +.fi +.RE +.PP +causes the characters `\fB&\fP\&' and `\fB|\fP' to remove the suffix but to +replace it with a space\&. +.PP +To illustrate the difference, suppose that the option \fBAUTO_REMOVE_SLASH\fP +is in effect and the directory \fBDIR\fP has just been completed, with an +appended \fB/\fP, following which the user types `\fB&\fP\&'\&. The default result +is `\fBDIR&\fP\&'\&. With \fBZLE_REMOVE_SUFFIX_CHARS\fP set but without including +`\fB&\fP\&' the result is `\fBDIR/&\fP'\&. With \fBZLE_SPACE_SUFFIX_CHARS\fP set to +include `\fB&\fP\&' the result is `\fBDIR &\fP'\&. +.PP +Note that certain completions may provide their own suffix removal +or replacement behaviour which overrides the values described here\&. +See the completion system documentation in +\fIzshcompsys\fP(1)\&. +.RE +.TP +\fBZLE_RPROMPT_INDENT\fP <S> +If set, used to give the indentation between the right hand side of +the right prompt in the line editor as given by \fBRPS1\fP or \fBRPROMPT\fP +and the right hand side of the screen\&. If not set, the value 1 is used\&. +.RS +.PP +Typically this will be used to set the value to 0 so that the prompt +appears flush with the right hand side of the screen\&. This is not the +default as many terminals do not handle this correctly, in particular +when the prompt appears at the extreme bottom right of the screen\&. +Recent virtual terminals are more likely to handle this case correctly\&. +Some experimentation is necessary\&. +.RE diff --git a/Doc/zshroadmap.1 b/Doc/zshroadmap.1 new file mode 100644 index 000000000..fc04710a9 --- /dev/null +++ b/Doc/zshroadmap.1 @@ -0,0 +1,195 @@ +.TH "ZSHROADMAP" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshroadmap \- informal introduction to the zsh manual +.\" Yodl file: Zsh/roadmap.yo +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\&. +.PP +.SH "WHEN THE SHELL STARTS" +.PP +When it starts, the shell reads commands from various files\&. These can +be created or edited to customize the shell\&. See the section +Startup/Shutdown Files in \fIzsh\fP(1)\&. +.PP +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 \fBzsh/newuser\fP module\&. +The function is designed to be self\-explanatory\&. You can run it by hand +with `\fBautoload \-Uz zsh\-newuser\-install; zsh\-newuser\-install \-f\fP\&'\&. +See also +the section `User Configuration Functions\&' in \fIzshcontrib\fP(1)\&. +.PP +.SH "INTERACTIVE USE" +.PP +Interaction with the shell uses the builtin Zsh Line Editor, ZLE\&. This is +described in detail in \fIzshzle\fP(1)\&. +.PP +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 \fBbindkey \-e\fP\&. +.PP +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) \fBHISTFILE\fP, +\fBHISTSIZE\fP and \fBSAVEHIST\fP in \fIzshparam\fP(1)\&. 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\&. +.PP +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, +\fBhttps://www\&.zsh\&.org/FAQ/\fP\&. Note in particular that for combining +characters to be handled the option \fBCOMBINING_CHARS\fP 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 +\fBLANG\fP (to affect all aspects of the shell\&'s operation) or +\fBLC_CTYPE\fP (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 +\fBISO\-8859\-1\fP or \fBISO\-8859\-15\fP\&. See the description of \fBLC_CTYPE\fP +in +\fIzshparam\fP(1)\&. +.PP +.SS "Completion" +.PP +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 \fB~/\&.abook/addressbook\fP; +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\&. +.PP +Zsh has two completion systems, an old, so called \fBcompctl\fP completion +(named after the builtin command that serves as its complete and only +user interface), and a new one, referred to as \fBcompsys\fP, +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\&. +.PP +The completion system must be enabled explicitly when the shell starts\&. +For more information see +\fIzshcompsys\fP(1)\&. +.PP +.SS "Extending the line editor" +.PP +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: +.PP +.PD 0 +.TP +.PD +\fBinsert\-composed\-char\fP +composing characters not found on the keyboard +.TP +\fBmatch\-words\-by\-style\fP +configuring what the line editor considers a word when moving or +deleting by word +.TP +\fBhistory\-beginning\-search\-backward\-end\fP, etc\&. +alternative ways of searching the shell history +.TP +\fBreplace\-string\fP, \fBreplace\-pattern\fP +functions for replacing strings or patterns globally in the command line +.TP +\fBedit\-command\-line\fP +edit the command line with an external editor\&. +.PP +See the section `ZLE Functions\&' in \fIzshcontrib\fP(1) for descriptions of these\&. +.PP +.SH "OPTIONS" +.PP +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 +\fIzshoptions\fP(1)\&. +.PP +.SH "PATTERN MATCHING" +.PP +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 the section `Filename Generation\&' in \fIzshexpn\fP(1)\&. +.PP +Of particular interest are the following patterns that are not commonly +supported by other systems of pattern matching: +.PP +.PD 0 +.TP +.PD +\fB**\fP +for matching over multiple directories +.TP +\fB|\fP +for matching either of two alternatives +.TP +\fB~\fP, \fB^\fP +the ability to exclude patterns from matching when the \fBEXTENDED_GLOB\fP +option is set +.TP +\fB(\fP\fI\&.\&.\&.\fP\fB)\fP +glob qualifiers, included in parentheses at the end of the pattern, +which select files by type (such as directories) or attribute (such as +size)\&. +.PP +.SH "GENERAL COMMENTS ON SYNTAX" +.PP +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 the section `Shell Grammar\&' in +\fIzshmisc\fP(1)\&. +.PP +One commonly encountered difference is that variables substituted onto the +command line are not split into words\&. See the description of the shell option +\fBSH_WORD_SPLIT\fP in +the section `Parameter Expansion\&' in \fIzshexpn\fP(1)\&. +In zsh, you can either explicitly request the splitting (e\&.g\&. \fB${=foo}\fP) +or use an array when you want a variable to expand to more than one word\&. See +the section `Array Parameters\&' in \fIzshparam\fP(1)\&. +.PP +.SH "PROGRAMMING" +.PP +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 the section `Functions\&' in +\fIzshmisc\fP(1)\&. 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\&. +.PP +A few general functions, other than those for the line editor described +above, are provided with the shell and are described in +\fIzshcontrib\fP(1)\&. Features include: +.PP +.PD 0 +.TP +.PD +\fBpromptinit\fP +a prompt theme system for changing prompts easily, see the section +`Prompt Themes\&' + +.TP +\fBzsh\-mime\-setup\fP +a MIME\-handling system which dispatches commands according to the suffix of +a file as done by graphical file managers +.TP +\fBzcalc\fP +a calculator +.TP +\fBzargs\fP +a version of \fBxargs\fP that makes the \fBfind\fP command redundant +.TP +\fBzmv\fP +a command for renaming files by means of shell patterns\&. diff --git a/Doc/zshtcpsys.1 b/Doc/zshtcpsys.1 new file mode 100644 index 000000000..101f3fcd3 --- /dev/null +++ b/Doc/zshtcpsys.1 @@ -0,0 +1,845 @@ +.TH "ZSHTCPSYS" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshtcpsys \- zsh tcp system +.\" Yodl file: Zsh/tcpsys.yo +.SH "DESCRIPTION" +.PP +A module \fBzsh/net/tcp\fP is provided to provide network I/O over +TCP/IP from within the shell; see its description in +\fIzshmodules\fP(1)\&. This manual page describes a function suite based on the module\&. +If the module is installed, the functions are usually installed at the +same time, in which case they will be available for +autoloading in the default function search path\&. In addition to the +\fBzsh/net/tcp\fP module, the \fBzsh/zselect\fP module is used to implement +timeouts on read operations\&. For troubleshooting tips, consult the +corresponding advice for the \fBzftp\fP functions described in +\fIzshzftpsys\fP(1)\&. +.PP +There are functions corresponding to the basic I/O operations open, close, +read and send, named \fBtcp_open\fP etc\&., as well as a function +\fBtcp_expect\fP for pattern match analysis of data read as input\&. The +system makes it easy to receive data from and send data to multiple named +sessions at once\&. In addition, it can be linked with the shell\&'s line +editor in such a way that input data is automatically shown at the +terminal\&. Other facilities available including logging, filtering and +configurable output prompts\&. +.PP +To use the system where it is available, it should be enough to +`\fBautoload \-U tcp_open\fP\&' and run \fBtcp_open\fP as documented below to +start a session\&. The \fBtcp_open\fP function will autoload the remaining +functions\&. +.PP +.PP +.SH "TCP USER FUNCTIONS" +.PP +.SS "Basic I/O" +.PP +.PD 0 +.TP +.PD 0 +\fBtcp_open\fP [ \fB\-qz\fP ] \fIhost port\fP [ \fIsess\fP ] +.TP +.PD 0 +\fBtcp_open\fP [ \fB\-qz\fP ] [ \fB\-s\fP \fIsess\fP | \fB\-l\fP \fIsess\fP[\fB,\fP\&.\&.\&.] ] \&.\&.\&. +.TP +.PD +\fBtcp_open\fP [ \fB\-qz\fP ] [ \fB\-a\fP \fIfd\fP | \fB\-f\fP \fIfd\fP ] [ \fIsess\fP ] +Open a new session\&. In the first and simplest form, open a TCP connection +to host \fIhost\fP at port \fIport\fP; numeric and symbolic forms are +understood for both\&. +.RS +.PP +If \fIsess\fP is given, this becomes the name of the session which can be +used to refer to multiple different TCP connections\&. If \fIsess\fP is +not given, the function will invent a numeric name value (note this is +\fInot\fP the same as the file descriptor to which the session is attached)\&. +It is recommended that session names not include `funny\&' characters, where +funny characters are not well\-defined but certainly do not include +alphanumerics or underscores, and certainly do include whitespace\&. +.PP +In the second case, one or more sessions to be opened are given by name\&. +A single session name is given after \fB\-s\fP and a comma\-separated list +after \fB\-l\fP; both options may be repeated as many times as necessary\&. +A failure to open any session causes \fBtcp_open\fP to abort\&. +The host and port are read from the file \fB\&.ztcp_sessions\fP in the same +directory as the user\&'s zsh initialisation files, i\&.e\&. usually the home +directory, but \fB$ZDOTDIR\fP if that is set\&. The file consists of lines +each giving a session name and the corresponding host and port, in that +order (note the session name comes first, not last), separated by +whitespace\&. +.PP +The third form allows passive and fake TCP connections\&. If the option +\fB\-a\fP is used, its argument is a file descriptor open for listening for +connections\&. No function front\-end is provided to open such a file +descriptor, but a call to `\fBztcp \-l\fP \fIport\fP\&' will create one with the +file descriptor stored in the parameter \fB$REPLY\fP\&. The listening port can +be closed with `\fBztcp \-c\fP \fIfd\fP\&'\&. A call to `\fBtcp_open \-a\fP \fIfd\fP' +will block until a remote TCP connection is made to \fIport\fP on the local +machine\&. At this point, a session is created in the usual way and is +largely indistinguishable from an active connection created with one of the +first two forms\&. +.PP +If the option \fB\-f\fP is used, its argument is a file descriptor which is +used directly as if it were a TCP session\&. How well the remainder of the +TCP function system copes with this depends on what actually underlies this +file descriptor\&. A regular file is likely to be unusable; a FIFO (pipe) of +some sort will work better, but note that it is not a good idea for two +different sessions to attempt to read from the same FIFO at once\&. +.PP +If the option \fB\-q\fP is given with any of the three forms, \fBtcp_open\fP +will not print informational messages, although it will in any case exit +with an appropriate status\&. +.PP +If the line editor (zle) is in use, which is typically the case if the +shell is interactive, \fBtcp_open\fP installs a handler inside zle which +will check for new data at the same time as it checks for keyboard input\&. +This is convenient as the shell consumes no CPU time while waiting; the +test is performed by the operating system\&. Giving the option \fB\-z\fP to +any of the forms of \fBtcp_open\fP prevents the handler from being +installed, so data must be read explicitly\&. Note, however, this is not +necessary for executing complete sets of send and read commands from a +function, as zle is not active at this point\&. Generally speaking, the +handler is only active when the shell is waiting for input at a command +prompt or in the \fBvared\fP builtin\&. The option has no effect if zle is not +active; `\fB[[ \-o zle]]\fP\&' will test for this\&. +.PP +The first session to be opened becomes the current session and subsequent +calls to \fBtcp_open\fP do not change it\&. The current session is stored +in the parameter \fB$TCP_SESS\fP; see below for more detail about the +parameters used by the system\&. +.PP +The function \fBtcp_on_open\fP, if defined, is called when a session +is opened\&. See the description below\&. +.RE +.TP +\fBtcp_close\fP [ \fB\-qn\fP ] [ \fB\-a\fP | \fB\-l\fP \fIsess\fP[\fB,\fP\&.\&.\&.] | \fIsess\fP \&.\&.\&. ] +Close the named sessions, or the current session if none is given, +or all open sessions if \fB\-a\fP is given\&. The options \fB\-l\fP and \fB\-s\fP are +both handled for consistency with \fBtcp_open\fP, although the latter is +redundant\&. +.RS +.PP +If the session being closed is the current one, \fB$TCP_SESS\fP is unset, +leaving no current session, even if there are other sessions still open\&. +.PP +If the session was opened with \fBtcp_open \-f\fP, the file descriptor is +closed so long as it is in the range 0 to 9 accessible directly from the +command line\&. If the option \fB\-n\fP is given, no attempt will be made to +close file descriptors in this case\&. The \fB\-n\fP option is not used for +genuine \fBztcp\fP session; the file descriptors are always closed with the +session\&. +.PP +If the option \fB\-q\fP is given, no informational messages will be printed\&. +.RE + +.TP +.PD 0 +\fBtcp_read \fP[ \fB\-bdq\fP ] [ \fB\-t\fP \fITO\fP ] [ \fB\-T\fP \fITO\fP ] +.TP +.PD +\fB \fP[ \fB\-a\fP | \fB\-u\fP \fIfd\fP[\fB,\fP\&.\&.\&.] | \fB\-l\fP \fIsess\fP[\fB,\fP\&.\&.\&.] | \fB\-s\fP \fIsess\fP \&.\&.\&. ] +Perform a read operation on the current session, or on a list of +sessions if any are given with \fB\-u\fP, \fB\-l\fP or \fB\-s\fP, or all open +sessions if the option \fB\-a\fP is given\&. Any of the \fB\-u\fP, \fB\-l\fP or +\fB\-s\fP options may be repeated or mixed together\&. The \fB\-u\fP option +specifies a file descriptor directly (only those managed by this system +are useful), the other two specify sessions as described for +\fBtcp_open\fP above\&. +.RS +.PP +The function checks for new data available on all the sessions listed\&. +Unless the \fB\-b\fP option is given, it will not block waiting for new data\&. +Any one line of data from any of the available sessions will be read, +stored in the parameter \fB$TCP_LINE\fP, and displayed to standard output +unless \fB$TCP_SILENT\fP contains a non\-empty string\&. When printed to +standard output the string \fB$TCP_PROMPT\fP will be shown at the start of +the line; the default form for this includes the name of the session being +read\&. See below for more information on these parameters\&. In this mode, +\fBtcp_read\fP can be called repeatedly until it returns status 2 which +indicates all pending input from all specified sessions has been handled\&. +.PP +With the option \fB\-b\fP, equivalent to an infinite timeout, the function +will block until a line is available to read from one of the specified +sessions\&. However, only a single line is returned\&. +.PP +The option \fB\-d\fP indicates that all pending input should be drained\&. In +this case \fBtcp_read\fP may process multiple lines in the manner given +above; only the last is stored in \fB$TCP_LINE\fP, but the complete set is +stored in the array \fB$tcp_lines\fP\&. This is cleared at the start of each +call to \fBtcp_read\fP\&. +.PP +The options \fB\-t\fP and \fB\-T\fP specify a timeout in seconds, which may be a +floating point number for increased accuracy\&. With \fB\-t\fP the timeout is +applied before each line read\&. With \fB\-T\fP, the timeout applies to the +overall operation, possibly including multiple read operations if the +option \fB\-d\fP is present; without this option, there is no distinction +between \fB\-t\fP and \fB\-T\fP\&. +.PP +The function does not print informational messages, but if the option +\fB\-q\fP is given, no error message is printed for a non\-existent session\&. +.PP +A return status of 2 indicates a timeout or no data to read\&. Any other +non\-zero return status indicates some error condition\&. +.PP +See \fBtcp_log\fP for how to control where data is sent by \fBtcp_read\fP\&. +.RE +.TP +.PD 0 +\fBtcp_send\fP [ \fB\-cnq\fP ] [ \fB\-s\fP \fIsess\fP | \fB\-l\fP \fIsess\fP[\fB,\fP\&.\&.\&.] ] \fIdata\fP \&.\&.\&. +.TP +.PD +\fBtcp_send\fP [ \fB\-cnq\fP ] \fB\-a\fP \fIdata\fP \&.\&.\&. +Send the supplied data strings to all the specified sessions in turn\&. The +underlying operation differs little from a `\fBprint \-r\fP\&' to the session's +file descriptor, although it attempts to prevent the shell from dying owing +to a \fBSIGPIPE\fP caused by an attempt to write to a defunct session\&. +.RS +.PP +The option \fB\-c\fP causes \fBtcp_send\fP to behave like \fBcat\fP\&. It reads +lines from standard input until end of input and sends them in turn to the +specified session(s) exactly as if they were given as \fIdata\fP +arguments to individual \fBtcp_send\fP commands\&. +.PP +The option \fB\-n\fP prevents \fBtcp_send\fP from putting a newline at the end +of the data strings\&. +.PP +The remaining options all behave as for \fBtcp_read\fP\&. +.PP +The data arguments are not further processed once they have been passed to +\fBtcp_send\fP; they are simply passed down to \fBprint \-r\fP\&. +.PP +If the parameter \fB$TCP_OUTPUT\fP is a non\-empty string and logging is +enabled then the data sent to each session will be echoed to the log +file(s) with \fB$TCP_OUTPUT\fP in front where appropriate, much +in the manner of \fB$TCP_PROMPT\fP\&. +.RE +.PP +.SS "Session Management" +.PP +.PD 0 +.TP +.PD 0 +\fBtcp_alias\fP [ \fB\-q\fP ] \fIalias\fP\fB=\fP\fIsess\fP \&.\&.\&. +.TP +.PD 0 +\fBtcp_alias\fP [ \fB\-q\fP ] [ \fIalias\fP \&.\&.\&. ] +.TP +.PD +\fBtcp_alias\fP \fB\-d\fP [ \fB\-q\fP ] \fIalias\fP \&.\&.\&. +This function is not particularly well tested\&. +.RS +.PP +The first form creates an alias for a session name; \fIalias\fP can then be +used to refer to the existing session \fIsess\fP\&. As many aliases may be +listed as required\&. +.PP +The second form lists any aliases specified, or all aliases if none\&. +.PP +The third form deletes all the aliases listed\&. The underlying sessions are +not affected\&. +.PP +The option \fB\-q\fP suppresses an inconsistently chosen subset of error +messages\&. +.RE +.TP +\fBtcp_log\fP [ \fB\-asc\fP ] [ \fB\-n\fP | \fB\-N\fP ] [ \fIlogfile\fP ] +With an argument \fIlogfile\fP, all future input from \fBtcp_read\fP will be +logged to the named file\&. Unless \fB\-a\fP (append) is given, this file will +first be truncated or created empty\&. With no arguments, show the current +status of logging\&. +.RS +.PP +With the option \fB\-s\fP, per\-session logging is enabled\&. Input from +\fBtcp_read\fP is output to the file \fIlogfile\fP\fB\&.\fP\fIsess\fP\&. As the +session is automatically discriminated by the filename, the contents are +raw (no \fB$TCP_PROMPT\fP)\&. The option \fB\-a\fP applies as above\&. +Per\-session logging and logging of all data in one file are not mutually +exclusive\&. +.PP +The option \fB\-c\fP closes all logging, both complete and per\-session logs\&. +.PP +The options \fB\-n\fP and \fB\-N\fP respectively turn off or restore output of +data read by \fBtcp_read\fP to standard output; hence `\fBtcp_log \-cn\fP\&' turns +off all output by \fBtcp_read\fP\&. +.PP +The function is purely a convenient front end to setting the parameters +\fB$TCP_LOG\fP, \fB$TCP_LOG_SESS\fP, \fB$TCP_SILENT\fP, which are described below\&. +.RE +.TP +\fBtcp_rename\fP \fIold\fP \fInew\fP +Rename session \fIold\fP to session \fInew\fP\&. The old name becomes invalid\&. +.TP +\fBtcp_sess\fP [ \fIsess\fP [ \fIcommand\fP [ \fIarg\fP \&.\&.\&. ] ] ] +With no arguments, list all the open sessions and associated file +descriptors\&. The current session is marked with a star\&. For use in +functions, direct access to the parameters \fB$tcp_by_name\fP, \fB$tcp_by_fd\fP +and \fB$TCP_SESS\fP is probably more convenient; see below\&. +.RS +.PP +With a \fIsess\fP argument, set the current session to \fIsess\fP\&. +This is equivalent to changing \fB$TCP_SESS\fP directly\&. +.PP +With additional arguments, temporarily set the current session while +executing `\fIcommand\fP \fIarg\fP \&.\&.\&.\&'\&. \fIcommand\fP is re\-evaluated +so as to expand aliases etc\&., but the remaining \fIarg\fPs are passed +through as that appear to \fBtcp_sess\fP\&. The original session is restored +when \fBtcp_sess\fP exits\&. +.RE +.PP +.SS "Advanced I/O" +.PP +.PD 0 +.TP +.PD +\fBtcp_command\fP \fIsend\-option\fP \&.\&.\&. \fIsend\-argument\fP \&.\&.\&. +This is a convenient front\-end to \fBtcp_send\fP\&. All arguments are passed +to \fBtcp_send\fP, then the function pauses waiting for data\&. While data is +arriving at least every \fB$TCP_TIMEOUT\fP (default 0\&.3) seconds, data is +handled and printed out according to the current settings\&. Status 0 is +always returned\&. +.RS +.PP +This is generally only useful for interactive use, to prevent the display +becoming fragmented by output returned from the connection\&. Within a +programme or function it is generally better to handle reading data by a +more explicit method\&. +.RE + +.TP +.PD 0 +\fBtcp_expect \fP[ \fB\-q\fP ] [ \fB\-p\fP \fIvar\fP | \fB\-P\fP \fIvar\fP ] [ \fB\-t\fP \fITO\fP | \fB\-T\fP \fITO\fP ] +.TP +.PD +\fB \fP[ \fB\-a\fP | \fB\-s\fP \fIsess\fP | \fB\-l\fP \fIsess\fP[\fB,\fP\&.\&.\&.] ] \fIpattern\fP \&.\&.\&. +Wait for input matching any of the given \fIpattern\fPs from any of the +specified sessions\&. Input is ignored until an input line matches one of +the given patterns; at this point status zero is returned, the matching +line is stored in \fB$TCP_LINE\fP, and the full set of lines read during the +call to \fBtcp_expect\fP is stored in the array \fB$tcp_expect_lines\fP\&. +.RS +.PP +Sessions are specified in the same way as \fBtcp_read\fP: the default is to +use the current session, otherwise the sessions specified by \fB\-a\fP, +\fB\-s\fP, or \fB\-l\fP are used\&. +.PP +Each \fIpattern\fP is a standard zsh extended\-globbing pattern; note that it +needs to be quoted to avoid it being expanded immediately by filename +generation\&. It must match the full line, so to match a substring there +must be a `\fB*\fP\&' at the start and end\&. The line matched against includes +the \fB$TCP_PROMPT\fP added by \fBtcp_read\fP\&. It is possible to include the +globbing flags `\fB#b\fP\&' or `\fB#m\fP' in the patterns to make backreferences +available in the parameters \fB$MATCH\fP, \fB$match\fP, etc\&., as described in +the base zsh documentation on pattern matching\&. +.PP +Unlike \fBtcp_read\fP, the default behaviour of \fBtcp_expect\fP is to block +indefinitely until the required input is found\&. This can be modified by +specifying a timeout with \fB\-t\fP or \fB\-T\fP; these function as in +\fBtcp_read\fP, specifying a per\-read or overall timeout, respectively, in +seconds, as an integer or floating\-point number\&. As \fBtcp_read\fP, the +function returns status 2 if a timeout occurs\&. +.PP +The function returns as soon as any one of the patterns given match\&. If +the caller needs to know which of the patterns matched, the option \fB\-p\fP +\fIvar\fP can be used; on return, \fB$var\fP is set to the number of the +pattern using ordinary zsh indexing, i\&.e\&. the first is 1, and so on\&. Note +the absence of a `\fB$\fP\&' in front of \fIvar\fP\&. To avoid clashes, the +parameter cannot begin with `\fB_expect\fP\&'\&. The index \-1 is used if +there is a timeout and 0 if there is no match\&. +.PP +The option \fB\-P\fP \fIvar\fP works similarly to \fB\-p\fP, but instead of +numerical indexes the regular arguments must begin with a prefix +followed by a colon: that prefix is then used as a tag to which \fIvar\fP +is set when the argument matches\&. The tag \fBtimeout\fP is used if there +is a timeout and the empty string if there is no match\&. Note it is +acceptable for different arguments to start with the same prefix if the +matches do not need to be distinguished\&. +.PP +The option \fB\-q\fP is passed directly down to \fBtcp_read\fP\&. +.PP +As all input is done via \fBtcp_read\fP, all the usual rules about output of +lines read apply\&. One exception is that the parameter \fB$tcp_lines\fP will +only reflect the line actually matched by \fBtcp_expect\fP; use +\fB$tcp_expect_lines\fP for the full set of lines read during the function +call\&. +.RE +.TP +\fBtcp_proxy\fP +This is a simple\-minded function to accept a TCP connection and execute a +command with I/O redirected to the connection\&. Extreme caution should be +taken as there is no security whatsoever and this can leave your computer +open to the world\&. Ideally, it should only be used behind a firewall\&. +.RS +.PP +The first argument is a TCP port on which the function will listen\&. +.PP +The remaining arguments give a command and its arguments to execute with +standard input, standard output and standard error redirected to the +file descriptor on which the TCP session has been accepted\&. +If no command is given, a new zsh is started\&. This gives everyone on +your network direct access to your account, which in many cases will be a +bad thing\&. +.PP +The command is run in the background, so \fBtcp_proxy\fP can then accept new +connections\&. It continues to accept new connections until interrupted\&. +.RE +.TP +\fBtcp_spam\fP [ \fB\-ertv\fP ] [ \fB\-a\fP | \fB\-s\fP \fIsess\fP | \fB\-l\fP \fIsess\fP[\fB,\fP\&.\&.\&.] ] \fIcmd\fP [ \fIarg\fP \&.\&.\&. ] +Execute `\fIcmd\fP [ \fIarg\fP \&.\&.\&. ]\&' for each session in turn\&. Note this executes +the command and arguments; it does not send the command line as data +unless the \fB\-t\fP (transmit) option is given\&. +.RS +.PP +The sessions may be selected explicitly with the standard \fB\-a\fP, \fB\-s\fP or +\fB\-l\fP options, or may be chosen implicitly\&. If none of the three options +is given the rules are: first, if the array \fB$tcp_spam_list\fP is set, this +is taken as the list of sessions, otherwise all sessions are taken\&. +Second, any sessions given in the array \fB$tcp_no_spam_list\fP are removed +from the list of sessions\&. +.PP +Normally, any sessions added by the `\fB\-a\fP\&' flag or when all sessions are +chosen implicitly are spammed in alphabetic order; sessions given by the +\fB$tcp_spam_list\fP array or on the command line are spammed in the order +given\&. The \fB\-r\fP flag reverses the order however it was arrived it\&. +.PP +The \fB\-v\fP flag specifies that a \fB$TCP_PROMPT\fP will be output before each +session\&. This is output after any modification to \fBTCP_SESS\fP by the +user\-defined \fBtcp_on_spam\fP function described below\&. (Obviously that +function is able to generate its own output\&.) +.PP +If the option \fB\-e\fP is present, the line given as `\fIcmd\fP [ \fIarg\fP \&.\&.\&. ]\&' is executed +using \fBeval\fP, otherwise it is executed without any further processing\&. +.RE +.TP +\fBtcp_talk\fP +This is a fairly simple\-minded attempt to force input to the line editor to +go straight to the default \fBTCP_SESS\fP\&. +.RS +.PP +An escape string, \fB$TCP_TALK_ESCAPE\fP, default `\fB:\fP\&', is used to allow +access to normal shell operation\&. If it is on its own at the start of the +line, or followed only by whitespace, the line editor returns to normal +operation\&. Otherwise, the string and any following whitespace are skipped +and the remainder of the line executed as shell input without any change of +the line editor\&'s operating mode\&. +.PP +The current implementation is somewhat deficient in terms of use of the +command history\&. For this reason, many users will prefer to use some form +of alternative approach for sending data easily to the current session\&. +One simple approach is to alias some special character (such as `\fB%\fP\&') to +`\fBtcp_command \-\fP\fB\-\fP\&'\&. +.RE +.TP +\fBtcp_wait\fP +The sole argument is an integer or floating point number which gives the +seconds to delay\&. The shell will do nothing for that period except wait +for input on all TCP sessions by calling \fBtcp_read \-a\fP\&. This is similar +to the interactive behaviour at the command prompt when zle handlers are +installed\&. +.PP +.SS "`One\-shot\&' file transfer" +.PD 0 +.TP +.PD 0 +\fBtcp_point\fP \fIport\fP +.TP +.PD +\fBtcp_shoot\fP \fIhost\fP \fIport\fP +This pair of functions provide a simple way to transfer a file between +two hosts within the shell\&. Note, however, that bulk data transfer is +currently done using \fBcat\fP\&. \fBtcp_point\fP reads any data arriving at +\fIport\fP and sends it to standard output; \fBtcp_shoot\fP connects to +\fIport\fP on \fIhost\fP and sends its standard input\&. Any unused \fIport\fP +may be used; the standard mechanism for picking a port is to think of a +random four\-digit number above 1024 until one works\&. +.RS +.PP +To transfer a file from host \fBwoodcock\fP to host \fBspringes\fP, on +\fBspringes\fP: +.PP +.RS +.nf +\fBtcp_point 8091 >output_file\fP +.fi +.RE +.PP +and on \fBwoodcock\fP: +.PP +.RS +.nf +\fBtcp_shoot springes 8091 <input_file\fP +.fi +.RE +.PP +As these two functions do not require \fBtcp_open\fP to set up a TCP +connection first, they may need to be autoloaded separately\&. +.RE +.PP +.SH "TCP USER\-DEFINED FUNCTIONS" +.PP +Certain functions, if defined by the user, will be called by the function +system in certain contexts\&. This facility depends on the module +\fBzsh/parameter\fP, which is usually available in interactive shells as the +completion system depends on it\&. None of the functions need be defined; +they simply provide convenient hooks when necessary\&. +.PP +Typically, these are called after the requested action has been taken, so +that the various parameters will reflect the new state\&. +.PP +.PD 0 +.TP +.PD +\fBtcp_on_alias\fP \fIalias\fP \fIfd\fP +When an alias is defined, this function will be called with two arguments: +the name of the alias, and the file descriptor of the corresponding session\&. +.TP +\fBtcp_on_awol\fP \fIsess\fP \fIfd\fP +If the function \fBtcp_fd_handler\fP is handling input from the line +editor and detects that the file descriptor is no longer reusable, +by default it removes it from the list of file descriptors handled +by this method and prints a message\&. If the function \fBtcp_on_awol\fP +is defined it is called immediately before this point\&. It may +return status 100, which indicates that the normal handling should +still be performed; any other return status indicates that no further +action should be taken and the \fBtcp_fd_handler\fP should return +immediately with the given status\&. Typically the action of \fBtcp_on_awol\fP +will be to close the session\&. +.RS +.PP +The variable \fBTCP_INVALIDATE_ZLE\fP will be a non\-empty string if it is +necessary to invalidate the line editor display using `\fBzle \-I\fP\&' before +printing output from the function\&. +.PP +(`AWOL\&' is military jargon for `absent without leave' or some +variation\&. It has no pre\-existing technical meaning known to the author\&.) +.RE +.TP +\fBtcp_on_close\fP \fIsess\fP \fIfd\fP +This is called with the name of a session being closed and the file +descriptor which corresponded to that session\&. Both will be invalid by +the time the function is called\&. +.TP +\fBtcp_on_open\fP \fIsess\fP \fIfd\fP +This is called after a new session has been defined with the session name +and file descriptor as arguments\&. If it returns a non\-zero status, +opening the session is assumed to fail and the session is closed +again; however, \fBtcp_open\fP will continue to attempt to open any +remaining sessions given on the command line\&. +.TP +\fBtcp_on_rename\fP \fIoldsess\fP \fIfd\fP \fInewsess\fP +This is called after a session has been renamed with the three arguments +old session name, file descriptor, new session name\&. +.TP +\fBtcp_on_spam\fP \fIsess\fP \fIcommand \&.\&.\&.\fP +This is called once for each session spammed, just \fIbefore\fP a command is +executed for a session by \fBtcp_spam\fP\&. The arguments are the session name +followed by the command list to be executed\&. If \fBtcp_spam\fP was called +with the option \fB\-t\fP, the first command will be \fBtcp_send\fP\&. +.RS +.PP +This function is called after \fB$TCP_SESS\fP is set to reflect the session +to be spammed, but before any use of it is made\&. Hence it is possible to +alter the value of \fB$TCP_SESS\fP within this function\&. For example, the +session arguments to \fBtcp_spam\fP could include extra information to be +stripped off and processed in \fBtcp_on_spam\fP\&. +.PP +If the function sets the parameter \fB$REPLY\fP to `\fBdone\fP\&', the command +line is not executed; in addition, no prompt is printed for the \fB\-v\fP +option to \fBtcp_spam\fP\&. +.RE +.TP +\fBtcp_on_unalias\fP \fIalias\fP \fIfd\fP +This is called with the name of an alias and the corresponding session\&'s +file descriptor after an alias has been deleted\&. +.PP +.SH "TCP UTILITY FUNCTIONS" +.PP +The following functions are used by the TCP function system but will rarely +if ever need to be called directly\&. +.PP +.PD 0 +.TP +.PD +\fBtcp_fd_handler\fP +This is the function installed by \fBtcp_open\fP for handling input from +within the line editor, if that is required\&. It is in the format +documented for the builtin `\fBzle \-F\fP\&' in +\fIzshzle\fP(1) +\&. +.RS +.PP +While active, the function sets the parameter \fBTCP_HANDLER_ACTIVE\fP to 1\&. +This allows shell code called internally (for example, by setting +\fBtcp_on_read\fP) to tell if is being called when the shell is otherwise +idle at the editor prompt\&. +.RE +.TP +\fBtcp_output\fP [ \fB\-q\fP ] \fB\-P\fP \fIprompt\fP \fB\-F\fP \fIfd\fP \fB\-S\fP \fIsess\fP +This function is used for both logging and handling output to standard +output, from within \fBtcp_read\fP and (if \fB$TCP_OUTPUT\fP is set) +\fBtcp_send\fP\&. +.RS +.PP +The \fIprompt\fP to use is specified by \fB\-P\fP; the default is the empty +string\&. It can contain: +.PD 0 +.TP +.PD +\fB%c\fP +Expands to 1 if the session is the current session, otherwise 0\&. Used +with ternary expressions such as `\fB%(c\&.\-\&.+)\fP\&' to +output `\fB+\fP\&' for the current session and `\fB\-\fP' otherwise\&. +.TP +\fB%f\fP +Replaced by the session\&'s file descriptor\&. +.TP +\fB%s\fP +Replaced by the session name\&. +.TP +\fB%%\fP +Replaced by a single `\fB%\fP\&'\&. +.PP +The option \fB\-q\fP suppresses output to standard output, but not to any log +files which are configured\&. +.PP +The \fB\-S\fP and \fB\-F\fP options are used to pass in the session name and file +descriptor for possible replacement in the prompt\&. +.RE +.PP +.SH "TCP USER PARAMETERS" +.PP +Parameters follow the usual convention that uppercase is used for scalars +and integers, while lowercase is used for normal and associative array\&. +It is always safe for user code to read these parameters\&. Some parameters +may also be set; these are noted explicitly\&. Others are included in this +group as they are set by the function system for the user\&'s benefit, +i\&.e\&. setting them is typically not useful but is benign\&. +.PP +It is often also useful to make settable parameters local to a function\&. +For example, `\fBlocal TCP_SILENT=1\fP\&' specifies that data read during the +function call will not be printed to standard output, regardless of the +setting outside the function\&. Likewise, `\fBlocal TCP_SESS=\fP\fIsess\fP\&' +sets a session for the duration of a function, and `\fBlocal +TCP_PROMPT=\fP\&' specifies that no prompt is used for input during the +function\&. +.PP +.PD 0 +.TP +.PD +\fBtcp_expect_lines\fP +Array\&. The set of lines read during the last call to \fBtcp_expect\fP, +including the last (\fB$TCP_LINE\fP)\&. +.TP +\fBtcp_filter\fP +Array\&. May be set directly\&. A set of extended globbing patterns which, +if matched in \fBtcp_output\fP, will cause the line not to be printed to +standard output\&. The patterns should be defined as described for the +arguments to \fBtcp_expect\fP\&. Output of line to log files is not affected\&. +.TP +\fBTCP_HANDLER_ACTIVE\fP +Scalar\&. Set to 1 within \fBtcp_fd_handler\fP to indicate to functions +called recursively that they have been called during an editor session\&. +Otherwise unset\&. +.TP +\fBTCP_LINE\fP +The last line read by \fBtcp_read\fP, and hence also \fBtcp_expect\fP\&. +.TP +\fBTCP_LINE_FD\fP +The file descriptor from which \fB$TCP_LINE\fP was read\&. +\fB${tcp_by_fd[$TCP_LINE_FD]}\fP will give the corresponding session name\&. +.TP +\fBtcp_lines\fP +Array\&. The set of lines read during the last call to \fBtcp_read\fP, +including the last (\fB$TCP_LINE\fP)\&. +.TP +\fBTCP_LOG\fP +May be set directly, although it is also controlled by \fBtcp_log\fP\&. +The name of a file to which output from all sessions will be sent\&. +The output is proceeded by the usual \fB$TCP_PROMPT\fP\&. If it is not an +absolute path name, it will follow the user\&'s current directory\&. +.TP +\fBTCP_LOG_SESS\fP +May be set directly, although it is also controlled by \fBtcp_log\fP\&. +The prefix for a set of files to which output from each session separately +will be sent; the full filename is \fB${TCP_LOG_SESS}\&.\fP\fIsess\fP\&. +Output to each file is raw; no prompt is added\&. If it is not an absolute +path name, it will follow the user\&'s current directory\&. +.TP +\fBtcp_no_spam_list\fP +Array\&. May be set directly\&. See \fBtcp_spam\fP for how this is used\&. +.TP +\fBTCP_OUTPUT\fP +May be set directly\&. If a non\-empty string, any data sent to a session by +\fBtcp_send\fP will be logged\&. This parameter gives the prompt to be used +in a file specified by \fB$TCP_LOG\fP but not in a file generated from +\fB$TCP_LOG_SESS\fP\&. The prompt string has the same format as +\fBTCP_PROMPT\fP and the same rules for its use apply\&. +.TP +\fBTCP_PROMPT\fP +May be set directly\&. Used as the prefix for data read by \fBtcp_read\fP +which is printed to standard output or to the log file given by +\fB$TCP_LOG\fP, if any\&. Any `\fB%s\fP\&', `\fB%f\fP' or `\fB%%\fP' occurring in the +string will be replaced by the name of the session, the session\&'s +underlying file descriptor, or a single `\fB%\fP\&', respectively\&. The +expression `\fB%c\fP\&' expands to 1 if the session being read is the current +session, else 0; this is most useful in ternary expressions such as +`\fB%(c\&.\-\&.+)\fP\&' which outputs `\fB+\fP' if the session is +the current one, else `\fB\-\fP\&'\&. +.RS +.PP +If the prompt starts with \fB%P\fP, this is stripped and the complete +result of the previous stage is passed through standard prompt \fB%\fP\-style +formatting before being output\&. +.RE +.TP +\fBTCP_READ_DEBUG\fP +May be set directly\&. If this has non\-zero length, \fBtcp_read\fP will give +some limited diagnostics about data being read\&. +.TP +\fBTCP_SECONDS_START\fP +This value is created and initialised to zero by tcp_open\&. +.RS +.PP +The functions \fBtcp_read\fP and \fBtcp_expect\fP use the shell\&'s +\fBSECONDS\fP parameter for their own timing purposes\&. If that parameter +is not of floating point type on entry to one of the functions, it will +create a local parameter \fBSECONDS\fP which is floating point and set the +parameter \fBTCP_SECONDS_START\fP to the previous value of \fB$SECONDS\fP\&. +If the parameter is already floating point, it is used without a local +copy being created and \fBTCP_SECONDS_START\fP is not set\&. As the global +value is zero, the shell elapsed time is guaranteed to be the sum of +\fB$SECONDS\fP and \fB$TCP_SECONDS_START\fP\&. +.PP +This can be avoided by setting \fBSECONDS\fP globally to a floating point +value using `\fBtypeset \-F SECONDS\fP\&'; then the TCP functions will never +make a local copy and never set \fBTCP_SECONDS_START\fP to a non\-zero value\&. +.RE +.TP +\fBTCP_SESS\fP +May be set directly\&. The current session; must refer to one of the +sessions established by \fBtcp_open\fP\&. +.TP +\fBTCP_SILENT\fP +May be set directly, although it is also controlled by \fBtcp_log\fP\&. +If of non\-zero length, data read by \fBtcp_read\fP will not be written to +standard output, though may still be written to a log file\&. +.TP +\fBtcp_spam_list\fP +Array\&. May be set directly\&. See the description of the function +\fBtcp_spam\fP for how this is used\&. +.TP +\fBTCP_TALK_ESCAPE\fP +May be set directly\&. See the description of the function \fBtcp_talk\fP for +how this is used\&. +.TP +\fBTCP_TIMEOUT\fP +May be set directly\&. Currently this is only used by the function +\fBtcp_command\fP, see above\&. +.PP +.SH "TCP USER\-DEFINED PARAMETERS" +.PP +The following parameters are not set by the function system, but have +a special effect if set by the user\&. +.PP +.PD 0 +.TP +.PD +\fBtcp_on_read\fP +This should be an associative array; if it is not, the behaviour is +undefined\&. Each key is the name of a shell function or other command, +and the corresponding value is a shell pattern (using \fBEXTENDED_GLOB\fP)\&. +Every line read from a TCP session directly or indirectly using +\fBtcp_read\fP (which includes lines read by \fBtcp_expect\fP) is compared +against the pattern\&. If the line matches, the command given in the key is +called with two arguments: the name of the session from which the line was +read, and the line itself\&. +.RS +.PP +If any function called to handle a line returns a non\-zero status, the +line is not output\&. Thus a \fBtcp_on_read\fP handler containing only +the instruction `\fBreturn 1\fP\&' can be used to suppress output of +particular lines (see, however, \fBtcp_filter\fP above)\&. However, the line +is still stored in \fBTCP_LINE\fP and \fBtcp_lines\fP; this occurs after all +\fBtcp_on_read\fP processing\&. +.RE +.PP +.SH "TCP UTILITY PARAMETERS" +.PP +These parameters are controlled by the function system; they may be read +directly, but should not usually be set by user code\&. +.PP +.PD 0 +.TP +.PD +\fBtcp_aliases\fP +Associative array\&. The keys are the names of sessions established with +\fBtcp_open\fP; each value is a space\-separated list of aliases which refer +to that session\&. +.TP +\fBtcp_by_fd\fP +Associative array\&. The keys are session file descriptors; each +value is the name of that session\&. +.TP +\fBtcp_by_name\fP +Associative array\&. The keys are the names of sessions; each value is the +file descriptor associated with that session\&. +.PP +.SH "TCP EXAMPLES" +.PP +Here is a trivial example using a remote calculator\&. +.PP +To create a calculator server on port 7337 (see the \fBdc\fP manual page for +quite how infuriating the underlying command is): +.PP +.RS +.nf +\fBtcp_proxy 7337 dc\fP +.fi +.RE +.PP +To connect to this from the same host with a session also named `\fBdc\fP\&': +.PP +.RS +.nf +\fBtcp_open localhost 7337 dc\fP +.fi +.RE +.PP +To send a command to the remote session and wait a short while for output +(assuming \fBdc\fP is the current session): +.PP +.RS +.nf +\fBtcp_command 2 4 + p\fP +.fi +.RE +.PP +To close the session: +.PP +.RS +.nf +\fBtcp_close\fP +.fi +.RE +.PP +The \fBtcp_proxy\fP needs to be killed to be stopped\&. Note this will not +usually kill any connections which have already been accepted, and also +that the port is not immediately available for reuse\&. +.PP +The following chunk of code puts a list of sessions into an xterm header, +with the current session followed by a star\&. +.PP +.RS +.nf +\fBprint \-n "\e033]2;TCP:" ${(k)tcp_by_name:/$TCP_SESS/$TCP_SESS\e*} "\ea"\fP +.fi +.RE +.PP +.SH "TCP BUGS" +.PP +The function \fBtcp_read\fP uses the shell\&'s normal \fBread\fP builtin\&. As +this reads a complete line at once, data arriving without a terminating +newline can cause the function to block indefinitely\&. +.PP +Though the function suite works well for interactive use and for data +arriving in small amounts, the performance when large amounts of data are +being exchanged is likely to be extremely poor\&. diff --git a/Doc/zshzftpsys.1 b/Doc/zshzftpsys.1 new file mode 100644 index 000000000..782e4c0d7 --- /dev/null +++ b/Doc/zshzftpsys.1 @@ -0,0 +1,660 @@ +.TH "ZSHZFTPSYS" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshzftpsys \- zftp function front\-end +.\" Yodl file: Zsh/zftpsys.yo +.SH "DESCRIPTION" +.PP +This describes the set of shell functions supplied with the source +distribution as an interface to the \fBzftp\fP builtin command, allowing you +to perform FTP operations from the shell command line or within functions +or scripts\&. The interface is similar to a traditional FTP client (e\&.g\&. the +\fBftp\fP command itself, see \fIftp\fP(1)), but as it is entirely done +within the shell all the familiar completion, editing and globbing features, +and so on, are present, and macros are particularly simple to write as they +are just ordinary shell functions\&. +.PP +The prerequisite is that the \fBzftp\fP command, as described in +\fIzshmodules\fP(1) +, must be available in the +version of \fBzsh\fP installed at your site\&. If the shell is configured to +load new commands at run time, it probably is: typing `\fBzmodload zsh/zftp\fP\&' +will make sure (if that runs silently, it has worked)\&. If this is not the +case, it is possible \fBzftp\fP was linked into the shell anyway: to test +this, type `\fBwhich zftp\fP\&' and if \fBzftp\fP is available you will get the +message `\fBzftp: shell built\-in command\fP\&'\&. +.PP +Commands given directly with \fBzftp\fP builtin may be interspersed between +the functions in this suite; in a few cases, using \fBzftp\fP directly may +cause some of the status information stored in shell parameters to become +invalid\&. Note in particular the description of the variables +\fB$ZFTP_TMOUT\fP, \fB$ZFTP_PREFS\fP and \fB$ZFTP_VERBOSE\fP for \fBzftp\fP\&. +.PP +.PP +.SH "INSTALLATION" +.PP +You should make sure all the functions from the \fBFunctions/Zftp\fP +directory of the source distribution are available; they all begin with the +two letters `\fBzf\fP\&'\&. They may already have been installed on your system; +otherwise, you will need to find them and copy them\&. The directory should +appear as one of the elements of the \fB$fpath\fP array (this should already +be the case if they were installed), and at least the function \fBzfinit\fP +should be autoloaded; it will autoload the rest\&. Finally, to initialize +the use of the system you need to call the \fBzfinit\fP function\&. The +following code in your \fB\&.zshrc\fP will arrange for this; assume the +functions are stored in the directory \fB~/myfns\fP: +.PP +.RS +.nf +\fBfpath=(~/myfns $fpath) +autoload \-U zfinit +zfinit\fP +.fi +.RE +.PP +Note that \fBzfinit\fP assumes you are using the \fBzmodload\fP method to +load the \fBzftp\fP command\&. If it is already built into the shell, change +\fBzfinit\fP to \fBzfinit \-n\fP\&. It is helpful (though not essential) if the +call to \fBzfinit\fP appears after any code to initialize the new completion +system, else unnecessary \fBcompctl\fP commands will be given\&. +.PP +.SH "FUNCTIONS" +.PP +The sequence of operations in performing a file transfer is essentially the +same as that in a standard FTP client\&. Note that, due to a quirk of the +shell\&'s \fBgetopts\fP builtin, for those functions that handle options you +must use `\fB\-\fP\fB\-\fP\&' rather than `\fB\-\fP' to ensure the remaining arguments +are treated literally (a single `\fB\-\fP\&' is treated as an argument)\&. +.PP +.SS "Opening a connection" +.PD 0 +.TP +.PD +\fBzfparams\fP [ \fIhost\fP [ \fIuser\fP [ \fIpassword\fP \&.\&.\&. ] ] ] +Set or show the parameters for a future \fBzfopen\fP with no arguments\&. If +no arguments are given, the current parameters are displayed (the password +will be shown as a line of asterisks)\&. If a \fIhost\fP is given, and either the +\fIuser\fP or \fIpassword\fP is not, they will be prompted for; also, any +parameter given as `\fB?\fP\&' will be prompted for, and if the `\fB?\fP' is +followed by a string, that will be used as the prompt\&. As \fBzfopen\fP calls +\fBzfparams\fP to store the parameters, this usually need not be called +directly\&. +.RS +.PP +A single argument `\fB\-\fP\&' will delete the stored parameters\&. This will +also cause the memory of the last directory (and so on) on the other host +to be deleted\&. +.RE +.TP +\fBzfopen\fP [ \fB\-1\fP ] [ \fIhost\fP [ \fIuser\fP [ \fIpassword\fP [ \fIaccount\fP ] ] ] ] +If \fIhost\fP is present, open a connection to that host under username +\fIuser\fP with password \fIpassword\fP (and, on the rare occasions when it +is necessary, account \fIaccount\fP)\&. If a necessary parameter is missing or +given as `\fB?\fP\&' it will be prompted for\&. If \fIhost\fP is not present, use +a previously stored set of parameters\&. +.RS +.PP +If the command was successful, and the terminal is compatible with +\fBxterm\fP or is \fBsun\-cmd\fP, a summary will appear in the title bar, +giving the local \fBhost:directory\fP and the remote \fBhost:directory\fP; +this is handled by the function \fBzftp_chpwd\fP, described below\&. +.PP +Normally, the \fIhost\fP, \fIuser\fP and \fIpassword\fP are internally +recorded for later re\-opening, either by a \fBzfopen\fP with no arguments, or +automatically (see below)\&. With the option `\fB\-1\fP\&', no information is +stored\&. Also, if an open command with arguments failed, the parameters +will not be retained (and any previous parameters will also be deleted)\&. +A \fBzfopen\fP on its own, or a \fBzfopen \-1\fP, never alters the stored +parameters\&. +.PP +Both \fBzfopen\fP and \fBzfanon\fP (but not \fBzfparams\fP) understand URLs of +the form \fBftp://\fP\fIhost\fP/\fIpath\&.\&.\&.\fP as meaning to connect to the +\fIhost\fP, then change directory to \fIpath\fP (which must be a directory, +not a file)\&. The `\fBftp://\fP\&' can be omitted; the trailing `\fB/\fP' is enough +to trigger recognition of the \fIpath\fP\&. Note prefixes other than +`\fBftp:\fP\&' are not recognized, and that all characters after the first +slash beyond \fIhost\fP are significant in \fIpath\fP\&. +.RE +.TP +\fBzfanon\fP [ \fB\-1\fP ] \fIhost\fP +Open a connection \fIhost\fP for anonymous FTP\&. The username used is +`\fBanonymous\fP\&'\&. The password (which will be reported the first time) is +generated as \fIuser\fP\fB@\fP\fIhost\fP; this is then stored in the shell +parameter \fB$EMAIL_ADDR\fP which can alternatively be set manually to a +suitable string\&. +.PP +.SS "Directory management" +.PD 0 +.TP +.PD 0 +\fBzfcd\fP [ \fIdir\fP ] +.TP +.PD 0 +\fBzfcd \-\fP +.TP +.PD +\fBzfcd\fP \fIold\fP \fInew\fP +Change the current directory on the remote server: this is implemented to +have many of the features of the shell builtin \fBcd\fP\&. +.RS +.PP +In the first form with \fIdir\fP present, change to the directory \fIdir\fP\&. +The command `\fBzfcd \&.\&.\fP\&' is treated specially, so is guaranteed to work on +non\-UNIX servers (note this is handled internally by \fBzftp\fP)\&. If \fIdir\fP +is omitted, has the effect of `\fBzfcd ~\fP\&'\&. +.PP +The second form changes to the directory previously current\&. +.PP +The third form attempts to change the current directory by replacing the +first occurrence of the string \fIold\fP with the string \fInew\fP in the +current directory\&. +.PP +Note that in this command, and indeed anywhere a remote filename is +expected, the string which on the local host corresponds to `\fB~\fP\&' is +converted back to a `\fB~\fP\&' before being passed to the remote machine\&. +This is convenient because of the way expansion is performed on the command +line before \fBzfcd\fP receives a string\&. For example, suppose the command +is `\fBzfcd ~/foo\fP\&'\&. The shell will expand this to a full path such as +`\fBzfcd /home/user2/pws/foo\fP\&'\&. At this stage, \fBzfcd\fP recognises the +initial path as corresponding to `\fB~\fP\&' and will send the directory to +the remote host as \fB~/foo\fP, so that the `\fB~\fP\&' will be expanded by the +server to the correct remote host directory\&. Other named directories of +the form `\fB~name\fP\&' are not treated in this fashion\&. +.RE +.TP +\fBzfhere\fP +Change directory on the remote server to the one corresponding to the +current local directory, with special handling of `\fB~\fP\&' as in \fBzfcd\fP\&. +For example, if the current local directory is \fB~/foo/bar\fP, then +\fBzfhere\fP performs the effect of `\fBzfcd ~/foo/bar\fP\&'\&. +.TP +\fBzfdir\fP [ \fB\-rfd\fP ] [ \fB\-\fP ] [ \fIdir\-options\fP ] [ \fIdir\fP ] +Produce a long directory listing\&. The arguments \fIdir\-options\fP and +\fIdir\fP are passed directly to the server and their effect is +implementation dependent, but specifying a particular remote directory +\fIdir\fP is usually possible\&. The output is passed through a pager +given by the environment variable \fB$PAGER\fP, or `\fBmore\fP\&' if that is not +set\&. +.RS +.PP +The directory is usually cached for re\-use\&. In fact, two caches are +maintained\&. One is for use when there is no \fIdir\-options\fP or \fIdir\fP, +i\&.e\&. a full listing of the current remote directory; it is flushed +when the current remote directory changes\&. The other is +kept for repeated use of \fBzfdir\fP with the same arguments; for example, +repeated use of `\fBzfdir /pub/gnu\fP\&' will only require the directory to be +retrieved on the first call\&. Alternatively, this cache can be re\-viewed with +the \fB\-r\fP option\&. As relative directories will confuse +\fBzfdir\fP, the \fB\-f\fP option can be used to force the cache to be flushed +before the directory is listed\&. The option \fB\-d\fP will delete both +caches without showing a directory listing; it will also delete the cache +of file names in the current remote directory, if any\&. +.RE +.TP +\fBzfls\fP [ \fIls\-options\fP ] [ \fIdir\fP ] +List files on the remote server\&. With no arguments, this will produce a +simple list of file names for the current remote directory\&. Any arguments +are passed directly to the server\&. No pager and no caching is used\&. +.PP +.SS "Status commands" +.PD 0 +.TP +.PD +\fBzftype\fP [ \fItype\fP ] +With no arguments, show the type of data to be transferred, usually ASCII +or binary\&. With an argument, change the type: the types `\fBA\fP\&' or +`\fBASCII\fP\&' for ASCII data and `\fBB\fP' or `\fBBINARY\fP', `\fBI\fP' or +`\fBIMAGE\fP\&' for binary data are understood case\-insensitively\&. +.TP +\fBzfstat\fP [ \fB\-v\fP ] +Show the status of the current or last connection, as well as the status of +some of \fBzftp\fP\&'s status variables\&. With the \fB\-v\fP option, a more +verbose listing is produced by querying the server for its version of +events, too\&. +.PP +.SS "Retrieving files" +The commands for retrieving files all take at least two options\&. \fB\-G\fP +suppresses remote filename expansion which would otherwise be performed +(see below for a more detailed description of that)\&. \fB\-t\fP attempts +to set the modification time of the local file to that of the remote file: +see the description of the function \fBzfrtime\fP below for more information\&. +.PP +.PD 0 +.TP +.PD +\fBzfget\fP [ \fB\-Gtc\fP ] \fIfile1\fP \&.\&.\&. +Retrieve all the listed files \fIfile1\fP \&.\&.\&. one at a time from the remote +server\&. If a file contains a `\fB/\fP\&', the full name is passed to the +remote server, but the file is stored locally under the name given by the +part after the final `\fB/\fP\&'\&. The option \fB\-c\fP (cat) forces all files to +be sent as a single stream to standard output; in this case the \fB\-t\fP +option has no effect\&. +.TP +\fBzfuget\fP [ \fB\-Gvst\fP ] \fIfile1\fP \&.\&.\&. +As \fBzfget\fP, but only retrieve files where the version on the remote +server is newer (has a later modification time), or where the local file +does not exist\&. If the remote file is older but the files have different +sizes, or if the sizes are the same but the remote file is newer, the user +will usually be queried\&. With the option \fB\-s\fP, the command runs silently +and will always retrieve the file in either of those two cases\&. With the +option \fB\-v\fP, the command prints more information about the files while it +is working out whether or not to transfer them\&. +.TP +\fBzfcget\fP [ \fB\-Gt\fP ] \fIfile1\fP \&.\&.\&. +As \fBzfget\fP, but if any of the local files exists, and is shorter than +the corresponding remote file, the command assumes that it is the result of +a partially completed transfer and attempts to transfer the rest of the +file\&. This is useful on a poor connection which keeps failing\&. +.RS +.PP +Note that this requires a commonly implemented, but non\-standard, version +of the FTP protocol, so is not guaranteed to work on all servers\&. +.RE +.TP +.PD 0 +\fBzfgcp\fP [ \fB\-Gt\fP ] \fIremote\-file\fP \fIlocal\-file\fP +.TP +.PD +\fBzfgcp\fP [ \fB\-Gt\fP ] \fIrfile1\fP \&.\&.\&. \fIldir\fP +This retrieves files from the remote server with arguments behaving +similarly to the \fBcp\fP command\&. +.RS +.PP +In the first form, copy \fIremote\-file\fP from the server to the local file +\fIlocal\-file\fP\&. +.PP +In the second form, copy all the remote files \fIrfile1\fP \&.\&.\&. into the +local directory \fIldir\fP retaining the same basenames\&. This assumes UNIX +directory semantics\&. +.RE +.PP +.SS "Sending files" +.PD 0 +.TP +.PD +\fBzfput\fP [ \fB\-r\fP ] \fIfile1\fP \&.\&.\&. +Send all the \fIfile1\fP \&.\&.\&. given separately to the remote server\&. If a +filename contains a `\fB/\fP\&', the full filename is used locally to find the +file, but only the basename is used for the remote file name\&. +.RS +.PP +With the option \fB\-r\fP, if any of the \fIfiles\fP are directories they are +sent recursively with all their subdirectories, including files beginning +with `\fB\&.\fP\&'\&. This requires that the remote machine understand UNIX file +semantics, since `\fB/\fP\&' is used as a directory separator\&. +.RE +.TP +\fBzfuput\fP [ \fB\-vs\fP ] \fIfile1\fP \&.\&.\&. +As \fBzfput\fP, but only send files which are newer than their remote +equivalents, or if the remote file does not exist\&. The logic is the same +as for \fBzfuget\fP, but reversed between local and remote files\&. +.TP +\fBzfcput\fP \fIfile1\fP \&.\&.\&. +As \fBzfput\fP, but if any remote file already exists and is shorter than the +local equivalent, assume it is the result of an incomplete transfer and +send the rest of the file to append to the existing part\&. As the FTP +append command is part of the standard set, this is in principle more +likely to work than \fBzfcget\fP\&. +.TP +.PD 0 +\fBzfpcp\fP \fIlocal\-file\fP \fIremote\-file\fP +.TP +.PD +\fBzfpcp\fP \fIlfile1\fP \&.\&.\&. \fIrdir\fP +This sends files to the remote server with arguments behaving similarly to +the \fBcp\fP command\&. +.RS +.PP +With two arguments, copy \fIlocal\-file\fP to the server as +\fIremote\-file\fP\&. +.PP +With more than two arguments, copy all the local files \fIlfile1\fP \&.\&.\&. into +the existing remote directory \fIrdir\fP retaining the same basenames\&. This +assumes UNIX directory semantics\&. +.PP +A problem arises if you attempt to use \fBzfpcp\fP \fIlfile1\fP \fIrdir\fP, +i\&.e\&. the second form of copying but with two arguments, as the command has +no simple way of knowing if \fIrdir\fP corresponds to a directory or a +filename\&. It attempts to resolve this in various ways\&. First, if the +\fIrdir\fP argument is `\fB\&.\fP\&' or `\fB\&.\&.\fP' or ends in a slash, it is assumed +to be a directory\&. Secondly, if the operation of copying to a remote file +in the first form failed, and the remote server sends back the expected +failure code 553 and a reply including the string `\fBIs a directory\fP\&', +then \fBzfpcp\fP will retry using the second form\&. +.RE +.PP +.SS "Closing the connection" +.PD 0 +.TP +.PD +\fBzfclose\fP +Close the connection\&. +.PP +.SS "Session management" +.PD 0 +.TP +.PD +\fBzfsession\fP [ \fB\-lvod\fP ] [ \fIsessname\fP ] +Allows you to manage multiple FTP sessions at once\&. By default, +connections take place in a session called `\fBdefault\fP\&'; by giving the +command `\fBzfsession\fP \fIsessname\fP\&' you can change to a new or existing +session with a name of your choice\&. The new session remembers its own +connection, as well as associated shell parameters, and also the host/user +parameters set by \fBzfparams\fP\&. Hence you can have different sessions set +up to connect to different hosts, each remembering the appropriate host, +user and password\&. +.RS +.PP +With no arguments, \fBzfsession\fP prints the name of the current session; +with the option \fB\-l\fP it lists all sessions which currently exist, and +with the option \fB\-v\fP it gives a verbose list showing the host and +directory for each session, where the current session is marked with an +asterisk\&. With \fB\-o\fP, it will switch to the most recent previous session\&. +.PP +With \fB\-d\fP, the given session (or else the current one) is removed; +everything to do with it is completely forgotten\&. If it was the only +session, a new session called `\fBdefault\fP\&' is created and made current\&. +It is safest not to delete sessions while background commands using +\fBzftp\fP are active\&. +.RE +.TP +\fBzftransfer\fP \fIsess1\fP\fB:\fP\fIfile1\fP \fIsess2\fP\fB:\fP\fIfile2\fP +Transfer files between two sessions; no local copy is made\&. The file +is read from the session \fIsess1\fP as \fIfile1\fP and written to session +\fIsess2\fP as file \fIfile2\fP; \fIfile1\fP and \fIfile2\fP may be relative to +the current directories of the session\&. Either \fIsess1\fP or \fIsess2\fP +may be omitted (though the colon should be retained if there is a +possibility of a colon appearing in the file name) and defaults to the +current session; \fIfile2\fP may be omitted or may end with a slash, in +which case the basename of \fIfile1\fP will be added\&. The sessions +\fIsess1\fP and \fIsess2\fP must be distinct\&. +.RS +.PP +The operation is performed using pipes, so it is required that the +connections still be valid in a subshell, which is not the case under +versions of some operating systems, presumably due to a system bug\&. +.RE +.PP +.SS "Bookmarks" +The two functions \fBzfmark\fP and \fBzfgoto\fP allow you to `bookmark\&' the +present location (host, user and directory) of the current FTP connection +for later use\&. The file to be used for storing and retrieving bookmarks is +given by the parameter \fB$ZFTP_BMFILE\fP; if not set when one of the two +functions is called, it will be set to the file \fB\&.zfbkmarks\fP in the +directory where your zsh startup files live (usually \fB~\fP)\&. +.PP +.PD 0 +.TP +.PD +\fBzfmark\fP [ \fIbookmark\fP ] +If given an argument, mark the current host, user and directory under the +name \fIbookmark\fP for later use by \fBzfgoto\fP\&. If there is no connection +open, use the values for the last connection immediately before it was +closed; it is an error if there was none\&. Any existing bookmark +under the same name will be silently replaced\&. +.RS +.PP +If not given an argument, list the existing bookmarks and the points to +which they refer in the form \fIuser\fP\fB@\fP\fIhost\fP\fB:\fP\fIdirectory\fP; +this is the format in which they are stored, and the file may be edited +directly\&. +.RE +.TP +\fBzfgoto\fP [ \fB\-n\fP ] \fIbookmark\fP +Return to the location given by \fIbookmark\fP, as previously set by +\fBzfmark\fP\&. If the location has user `\fBftp\fP\&' or `\fBanonymous\fP', open +the connection with \fBzfanon\fP, so that no password is required\&. If the +user and host parameters match those stored for the current session, if +any, those will be used, and again no password is required\&. Otherwise a +password will be prompted for\&. +.RS +.PP +With the option \fB\-n\fP, the bookmark is taken to be a nickname stored by +the \fBncftp\fP program in its bookmark file, which is assumed to be +\fB~/\&.ncftp/bookmarks\fP\&. The function works identically in other ways\&. +Note that there is no mechanism for adding or modifying \fBncftp\fP bookmarks +from the zftp functions\&. +.RE +.PP +.SS "Other functions" +Mostly, these functions will not be called directly (apart from +\fBzfinit\fP), but are described here for completeness\&. You may wish to +alter \fBzftp_chpwd\fP and \fBzftp_progress\fP, in particular\&. +.PP +.PD 0 +.TP +.PD +\fBzfinit\fP [ \fB\-n\fP ] +As described above, this is used to initialize the zftp function system\&. +The \fB\-n\fP option should be used if the zftp command is already built into +the shell\&. +.TP +\fBzfautocheck\fP [ \fB\-dn\fP ] +This function is called to implement automatic reopening behaviour, as +described in more detail below\&. The options must appear in the first +argument; \fB\-n\fP prevents the command from changing to the old directory, +while \fB\-d\fP prevents it from setting the variable \fBdo_close\fP, which it +otherwise does as a flag for automatically closing the connection after a +transfer\&. The host and directory for the last session are stored in the +variable \fB$zflastsession\fP, but the internal host/user/password parameters +must also be correctly set\&. +.TP +\fBzfcd_match \fIprefix\fP \fIsuffix\fP\fP +This performs matching for completion of remote directory names\&. If the +remote server is UNIX, it will attempt to persuade the server to list the +remote directory with subdirectories marked, which usually works but is not +guaranteed\&. On other hosts it simply calls \fBzfget_match\fP and hence +completes all files, not just directories\&. On some systems, directories +may not even look like filenames\&. +.TP +\fBzfget_match \fIprefix\fP \fIsuffix\fP\fP +This performs matching for completion of remote filenames\&. It caches files +for the current directory (only) in the shell parameter \fB$zftp_fcache\fP\&. +It is in the form to be called by the \fB\-K\fP option of \fBcompctl\fP, but +also works when called from a widget\-style completion function with +\fIprefix\fP and \fIsuffix\fP set appropriately\&. +.TP +\fBzfrglob \fIvarname\fP\fP +Perform remote globbing, as describes in more detail below\&. \fIvarname\fP +is the name of a variable containing the pattern to be expanded; if there +were any matches, the same variable will be set to the expanded set of +filenames on return\&. +.TP +\fBzfrtime\fP \fIlfile\fP \fIrfile\fP [ \fItime\fP ] +Set the local file \fIlfile\fP to have the same modification time as the +remote file \fIrfile\fP, or the explicit time \fItime\fP in FTP format +\fBCCYYMMDDhhmmSS\fP for the GMT timezone\&. This uses the shell\&'s +\fBzsh/datetime\fP module to perform the conversion from +GMT to local time\&. +.TP +\fBzftp_chpwd\fP +This function is called every time a connection is opened, or closed, or +the remote directory changes\&. This version alters the title bar of an +\fBxterm\fP\-compatible or \fBsun\-cmd\fP terminal emulator to reflect the +local and remote hostnames and current directories\&. It works best when +combined with the function \fBchpwd\fP\&. In particular, a function of +the form +.RS +.PP +.RS +.nf +\fBchpwd() { + if [[ \-n $ZFTP_USER ]]; then + zftp_chpwd + else + # usual chpwd e\&.g put host:directory in title bar + fi +}\fP +.fi +.RE +.PP +fits in well\&. +.RE +.TP +\fBzftp_progress\fP +This function shows the status of the transfer\&. It will not write anything +unless the output is going to a terminal; however, if you transfer files in +the background, you should turn off progress reports by hand using +`\fBzstyle \&':zftp:*' progress none\fP'\&. Note also that if you alter it, any +output \fImust\fP be to standard error, as standard output may be a file +being received\&. The form of the progress meter, or whether it is used at +all, can be configured without altering the function, as described in the +next section\&. +.TP +\fBzffcache\fP +This is used to implement caching of files in the current directory for +each session separately\&. It is used by \fBzfget_match\fP and \fBzfrglob\fP\&. +.PP +.SH "MISCELLANEOUS FEATURES" +.PP +.SS "Configuration" +.PP +Various styles are available using the standard shell style mechanism, +described in +\fIzshmodules\fP(1)\&. Briefly, the +command `\fBzstyle \&':zftp:*'\fP \fIstyle\fP \fIvalue\fP \&.\&.\&.'\&. +defines the \fIstyle\fP to have value \fIvalue\fP; more than one value may be +given, although that is not useful in the cases described here\&. These +values will then be used throughout the zftp function system\&. For more +precise control, the first argument, which gives a pattern that matches \fIcontexts\fP in which the +style applies, can be modified to include a particular function, as for +example `\fB:zftp:zfget\fP\&': the style will then have the given value only +in the \fBzfget\fP function, and will override styles set under `\fB:zftp:*\fP\&'\&. +Note that only the top level function name, as called by +the user, is used; calling of lower level functions is transparent to the +user\&. Hence modifications to the title bar in \fBzftp_chpwd\fP use the +contexts \fB:zftp:zfopen\fP, \fB:zftp:zfcd\fP, etc\&., depending where it was +called from\&. The following styles are understood: +.PP +.PD 0 +.TP +.PD +\fBprogress\fP +Controls the way that \fBzftp_progress\fP reports on the progress of a +transfer\&. If empty, unset, or `\fBnone\fP\&', no progress report is made; if +`\fBbar\fP\&' a growing bar of inverse video is shown; if `\fBpercent\fP' (or any +other string, though this may change in future), the percentage of the file +transferred is shown\&. The bar meter requires that the width of the +terminal be available via the \fB$COLUMNS\fP parameter (normally this is set +automatically)\&. If the size of the file being transferred is not +available, \fBbar\fP and \fBpercent\fP meters will simply show the number of +bytes transferred so far\&. +.RS +.PP +When \fBzfinit\fP is run, if this style is not defined for the context +\fB:zftp:*\fP, it will be set to `bar\&'\&. +.RE +.TP +\fBupdate\fP +Specifies the minimum time interval between updates of the progress meter +in seconds\&. No update is made unless new data has been received, so the +actual time interval is limited only by \fB$ZFTP_TIMEOUT\fP\&. +.RS +.PP +As described for \fBprogress\fP, \fBzfinit\fP will force this to default to 1\&. +.RE +.TP +\fBremote\-glob\fP +If set to `\fB1\fP\&', `\fByes\fP' or `\fBtrue\fP', filename generation (globbing) is +performed on the remote machine instead of by zsh itself; see below\&. +.TP +\fBtitlebar\fP +If set to `\fB1\fP\&', `\fByes\fP' or `\fBtrue\fP', \fBzftp_chpwd\fP will put the remote host and +remote directory into the titlebar of terminal emulators such as xterm or +sun\-cmd that allow this\&. +.RS +.PP +As described for \fBprogress\fP, \fBzfinit\fP will force this to default to 1\&. +.RE +.TP +\fBchpwd\fP +If set to `\fB1\fP\&' `\fByes\fP' or `\fBtrue\fP', \fBzftp_chpwd\fP will call the function +\fBchpwd\fP when a connection is closed\&. This is useful if the remote host +details were put into the terminal title bar by \fBzftp_chpwd\fP and your +usual \fBchpwd\fP also modifies the title bar\&. +.RS +.PP +When \fBzfinit\fP is run, it will determine whether \fBchpwd\fP exists and if +so it will set the default value for the style to 1 if none exists +already\&. +.RE +.PP +Note that there is also an associative array \fBzfconfig\fP which contains +values used by the function system\&. This should not be modified or +overwritten\&. +.PP +.SS "Remote globbing" +.PP +The commands for retrieving files usually perform filename generation +(globbing) on their arguments; this can be turned off by passing the option +\fB\-G\fP to each of the commands\&. Normally this operates by retrieving a +complete list of files for the directory in question, then matching these +locally against the pattern supplied\&. This has the advantage that the full +range of zsh patterns (respecting the setting of the option +\fBEXTENDED_GLOB\fP) can be used\&. However, it means that the directory part +of a filename will not be expanded and must be given exactly\&. If the +remote server does not support the UNIX directory semantics, directory +handling is problematic and it is recommended that globbing only be used +within the current directory\&. The list of files in the current directory, +if retrieved, will be cached, so that subsequent globs in the same +directory without an intervening \fBzfcd\fP are much faster\&. +.PP +If the \fBremote\-glob\fP style (see above) is set, globbing is instead +performed on the remote host: the server is asked for a list of matching +files\&. This is highly dependent on how the server is implemented, though +typically UNIX servers will provide support for basic glob patterns\&. This +may in some cases be faster, as it avoids retrieving the entire list of +directory contents\&. +.PP +.SS "Automatic and temporary reopening" +.PP +As described for the \fBzfopen\fP command, a subsequent \fBzfopen\fP with no +parameters will reopen the connection to the last host (this includes +connections made with the \fBzfanon\fP command)\&. Opened in this fashion, the +connection starts in the default remote directory and will remain open +until explicitly closed\&. +.PP +Automatic re\-opening is also available\&. If a connection is not currently +open and a command requiring a connection is given, the last connection is +implicitly reopened\&. In this case the directory which was current when the +connection was closed again becomes the current directory (unless, of +course, the command given changes it)\&. Automatic reopening will also take +place if the connection was close by the remote server for whatever reason +(e\&.g\&. a timeout)\&. It is not available if the \fB\-1\fP option to \fBzfopen\fP +or \fBzfanon\fP was used\&. +.PP +Furthermore, if the command issued is a file transfer, the connection will +be closed after the transfer is finished, hence providing a one\-shot mode +for transfers\&. This does not apply to directory changing or listing +commands; for example a \fBzfdir\fP may reopen a connection but will leave it +open\&. Also, automatic closure will only ever happen in the same command as +automatic opening, i\&.e a \fBzfdir\fP directly followed by a \fBzfget\fP will +never close the connection automatically\&. +.PP +Information about the previous connection is given by the \fBzfstat\fP +function\&. So, for example, if that reports: +.PP +.RS +.nf +\fBSession: default +Not connected\&. +Last session: ftp\&.bar\&.com:/pub/textfiles\fP +.fi +.RE +.PP +then the command \fBzfget file\&.txt\fP will attempt to reopen a connection to +\fBftp\&.bar\&.com\fP, retrieve the file \fB/pub/textfiles/file\&.txt\fP, and +immediately close the connection again\&. On the other hand, \fBzfcd \&.\&.\fP +will open the connection in the directory \fB/pub\fP and leave it open\&. +.PP +Note that all the above is local to each session; if you return to a +previous session, the connection for that session is the one which will be +reopened\&. +.PP +.SS "Completion" +.PP +Completion of local and remote files, directories, sessions and bookmarks +is supported\&. The older, \fBcompctl\fP\-style completion is defined when +\fBzfinit\fP is called; support for the new widget\-based completion system is +provided in the function \fBCompletion/Zsh/Command/_zftp\fP, which should be +installed with the other functions of the completion system and hence +should automatically be available\&. diff --git a/Doc/zshzle.1 b/Doc/zshzle.1 new file mode 100644 index 000000000..f70a7d482 --- /dev/null +++ b/Doc/zshzle.1 @@ -0,0 +1,2841 @@ +.TH "ZSHZLE" "1" "May 1, 2022" "zsh 5\&.8\&.1\&.3-test" +.SH "NAME" +zshzle \- zsh command line editor +.\" Yodl file: Zsh/zle.yo +.SH "DESCRIPTION" +If the \fBZLE\fP option is set (which it is by default in interactive shells) +and the shell input is attached to the terminal, the user +is able to edit command lines\&. +.PP +There are two display modes\&. The first, multiline mode, is the +default\&. It only works if the \fBTERM\fP parameter is set to a valid +terminal type that can move the cursor up\&. The second, single line +mode, is used if \fBTERM\fP is invalid or incapable of moving the +cursor up, or if the \fBSINGLE_LINE_ZLE\fP option is set\&. +This mode +is similar to \fBksh\fP, and uses no termcap sequences\&. If \fBTERM\fP is +"emacs", the \fBZLE\fP option will be unset by default\&. +.PP +The parameters \fBBAUD\fP, \fBCOLUMNS\fP, and \fBLINES\fP are also used by the +line editor\&. See +\fIParameters Used By The Shell\fP in \fIzshparam\fP(1)\&. +.PP +The parameter \fBzle_highlight\fP is also used by the line editor; see +\fICharacter Highlighting\fP below\&. Highlighting +of special characters and the region between the cursor and the +mark (as set with \fBset\-mark\-command\fP in Emacs mode, or by \fBvisual\-mode\fP +in Vi mode) is enabled +by default; consult this reference for more information\&. Irascible +conservatives will wish to know that all highlighting may be disabled by +the following setting: +.PP +.RS +.nf +\fBzle_highlight=(none)\fP +.fi +.RE +.PP +In many places, references are made to the \fBnumeric argument\fP\&. This can +by default be entered in emacs mode by holding the alt key and typing +a number, or pressing escape before each digit, and in vi command mode +by typing the number before entering a command\&. Generally the numeric +argument causes the next command entered to be repeated the specified +number of times, unless otherwise noted below; this is implemented +by the \fBdigit\-argument\fP widget\&. See also +the \fIArguments\fP subsection of the \fIWidgets\fP section for some other ways the numeric argument can be modified\&. +.PP +.PP +.SH "KEYMAPS" +A keymap in ZLE contains a set of bindings between key sequences +and ZLE commands\&. The empty key sequence cannot be bound\&. +.PP +There can be any number of keymaps at any time, and each keymap has one +or more names\&. If all of a keymap\&'s names are deleted, it disappears\&. +\fBbindkey\fP can be used to manipulate keymap names\&. +.PP +Initially, there are eight keymaps: +.PP +.PD 0 +.TP +\fBemacs\fP +EMACS emulation +.TP +\fBviins\fP +vi emulation \- insert mode +.TP +\fBvicmd\fP +vi emulation \- command mode +.TP +\fBviopp\fP +vi emulation \- operator pending +.TP +\fBvisual\fP +vi emulation \- selection active +.TP +\fBisearch\fP +incremental search mode +.TP +\fBcommand\fP +read a command name +.TP +\fB\&.safe\fP +fallback keymap +.PD +.PP +The `\fB\&.safe\fP\&' keymap is special\&. It can never be altered, and the name +can never be removed\&. However, it can be linked to other names, which can +be removed\&. In the future other special keymaps may be added; users should +avoid using names beginning with `\fB\&.\fP\&' for their own keymaps\&. +.PP +In addition to these names, either `\fBemacs\fP\&' or `\fBviins\fP' is +also linked to the name `\fBmain\fP\&'\&. If one of the \fBVISUAL\fP or +\fBEDITOR\fP environment variables contain the string `\fBvi\fP\&' when the shell +starts up then it will be `\fBviins\fP\&', otherwise it will be `\fBemacs\fP'\&. +\fBbindkey\fP\&'s \fB\-e\fP and \fB\-v\fP +options provide a convenient way to override this default choice\&. +.PP +When the editor starts up, it will select the `\fBmain\fP\&' keymap\&. +If that keymap doesn\&'t exist, it will use `\fB\&.safe\fP' instead\&. +.PP +In the `\fB\&.safe\fP\&' keymap, each single key is bound to \fBself\-insert\fP, +except for ^J (line feed) and ^M (return) which are bound to \fBaccept\-line\fP\&. +This is deliberately not pleasant to use; if you are using it, it +means you deleted the main keymap, and you should put it back\&. +.PP +.SS "Reading Commands" +When ZLE is reading a command from the terminal, it may read a sequence +that is bound to some command and is also a prefix of a longer bound string\&. +In this case ZLE will wait a certain time to see if more characters +are typed, and if not (or they don\&'t match any longer string) it will +execute the binding\&. This timeout is defined by the \fBKEYTIMEOUT\fP parameter; +its default is 0\&.4 sec\&. There is no timeout if the prefix string is not +itself bound to a command\&. +.PP +The key timeout is also applied when ZLE is reading the bytes from a +multibyte character string when it is in the appropriate mode\&. (This +requires that the shell was compiled with multibyte mode enabled; typically +also the locale has characters with the UTF\-8 encoding, although any +multibyte encoding known to the operating system is supported\&.) If the +second or a subsequent byte is not read within the timeout period, the +shell acts as if \fB?\fP were typed and resets the input state\&. +.PP +As well as ZLE commands, key sequences can be bound to other strings, by using +`\fBbindkey \-s\fP\&'\&. +When such a sequence is read, the replacement string is pushed back as input, +and the command reading process starts again using these fake keystrokes\&. +This input can itself invoke further replacement strings, but in order to +detect loops the process will be stopped if there are twenty such replacements +without a real command being read\&. +.PP +A key sequence typed by the user can be turned into a command name for use +in user\-defined widgets with the \fBread\-command\fP widget, described in +the subsection `Miscellaneous\&' of the section `Standard Widgets' below\&. +.PP +.SS "Local Keymaps" +While for normal editing a single keymap is used exclusively, in many +modes a local keymap allows for some keys to be customised\&. For example, +in an incremental search mode, a binding in the \fBisearch\fP keymap will +override a binding in the \fBmain\fP keymap but all keys that are not +overridden can still be used\&. +.PP +If a key sequence is defined in a local keymap, it will hide a key +sequence in the global keymap that is a prefix of that sequence\&. An +example of this occurs with the binding of \fBiw\fP in \fBviopp\fP as this +hides the binding of \fBi\fP in \fBvicmd\fP\&. However, a longer sequence in +the global keymap that shares the same prefix can still apply so for +example the binding of \fB^Xa\fP in the global keymap will be unaffected +by the binding of \fB^Xb\fP in the local keymap\&. +.PP +.SH "ZLE BUILTINS" +The ZLE module contains three related builtin commands\&. The \fBbindkey\fP +command manipulates keymaps and key bindings; the \fBvared\fP command invokes +ZLE on the value of a shell parameter; and the \fBzle\fP command manipulates +editing widgets and allows command line access to ZLE commands from within +shell functions\&. +.PP +.PD 0 +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-l\fP [ \fB\-L\fP ] [ \fIkeymap\fP \&.\&.\&. ] +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-d\fP +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-D\fP \fIkeymap\fP \&.\&.\&. +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-A\fP \fIold\-keymap new\-keymap\fP +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-N\fP \fInew\-keymap\fP [ \fIold\-keymap\fP ] +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-m\fP +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-r\fP \fIin\-string\fP \&.\&.\&. +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fB\-s\fP \fIin\-string out\-string\fP \&.\&.\&. +.TP +.PD 0 +\fBbindkey\fP [ \fIoptions\fP ] \fIin\-string command\fP \&.\&.\&. +.TP +.PD +\fBbindkey\fP [ \fIoptions\fP ] [ \fIin\-string\fP ] +\fBbindkey\fP\&'s options can be divided into three categories: keymap +selection for the current command, operation selection, and others\&. The +keymap selection options are: +.RS +.PP +.PD 0 +.TP +.PD +\fB\-e\fP +Selects keymap `\fBemacs\fP\&' for any operations by the current command, +and also links `\fBemacs\fP\&' to `\fBmain\fP' so that it is selected by +default the next time the editor starts\&. +.TP +\fB\-v\fP +Selects keymap `\fBviins\fP\&' for any operations by the current command, +and also links `\fBviins\fP\&' to `\fBmain\fP' so that it is selected by default +the next time the editor starts\&. +.TP +\fB\-a\fP +Selects keymap `\fBvicmd\fP\&' for any operations by the current command\&. +.TP +\fB\-M\fP \fIkeymap\fP +The \fIkeymap\fP specifies a keymap name that is selected for any +operations by the current command\&. +.PP +If a keymap selection is required and none of the options above are used, the +`\fBmain\fP\&' keymap is used\&. Some operations do not permit a keymap to be +selected, namely: +.PP +.PD 0 +.TP +.PD +\fB\-l\fP +List all existing keymap names; if any arguments are given, list just +those keymaps\&. +.RS +.PP +If the \fB\-L\fP option is also used, list in the form of \fBbindkey\fP +commands to create or link the keymaps\&. `\fBbindkey \-lL +main\fP\&' shows which keymap is linked to `\fBmain\fP', if any, and hence if +the standard emacs or vi emulation is in effect\&. This option does +not show the \fB\&.safe\fP keymap because it cannot be created in that +fashion; however, neither is `\fBbindkey \-lL \&.safe\fP\&' reported as an +error, it simply outputs nothing\&. +.RE +.TP +\fB\-d\fP +Delete all existing keymaps and reset to the default state\&. +.TP +\fB\-D\fP \fIkeymap\fP \&.\&.\&. +Delete the named \fIkeymap\fPs\&. +.TP +\fB\-A\fP \fIold\-keymap new\-keymap\fP +Make the \fInew\-keymap\fP name an alias for \fIold\-keymap\fP, so that +both names refer to the same keymap\&. The names have equal standing; +if either is deleted, the other remains\&. If there is already a keymap +with the \fInew\-keymap\fP name, it is deleted\&. +.TP +\fB\-N\fP \fInew\-keymap\fP [ \fIold\-keymap\fP ] +Create a new keymap, named \fInew\-keymap\fP\&. If a keymap already has that +name, it is deleted\&. If an \fIold\-keymap\fP name is given, the new keymap +is initialized to be a duplicate of it, otherwise the new keymap will +be empty\&. +.PP +To use a newly created keymap, it should be linked to \fBmain\fP\&. Hence +the sequence of commands to create and use a new keymap `\fBmymap\fP\&' +initialized from the \fBemacs\fP keymap (which remains unchanged) is: +.PP +.RS +.nf +\fBbindkey \-N mymap emacs +bindkey \-A mymap main\fP +.fi +.RE +.PP +Note that while `\fBbindkey \-A\fP \fInewmap\fP \fBmain\fP\&' will work when +\fInewmap\fP is \fBemacs\fP or \fBviins\fP, it will not work for \fBvicmd\fP, as +switching from vi insert to command mode becomes impossible\&. +.PP +The following operations act on the `\fBmain\fP\&' keymap if no keymap +selection option was given: +.PP +.PD 0 +.TP +.PD +\fB\-m\fP +Add the built\-in set of meta\-key bindings to the selected keymap\&. +Only keys that are unbound or bound to \fBself\-insert\fP are affected\&. +.TP +\fB\-r\fP \fIin\-string\fP \&.\&.\&. +Unbind the specified \fIin\-string\fPs in the selected keymap\&. +This is exactly equivalent to binding the strings to \fBundefined\-key\fP\&. +.RS +.PP +When \fB\-R\fP is also used, interpret the \fIin\-string\fPs as ranges\&. +.PP +When \fB\-p\fP is also used, the \fIin\-string\fPs specify prefixes\&. Any +binding that has the given \fIin\-string\fP as a prefix, not including the +binding for the \fIin\-string\fP itself, if any, will be removed\&. For +example, +.PP +.RS +.nf +\fBbindkey \-rpM viins \&'^['\fP +.fi +.RE +.PP +will remove all bindings in the vi\-insert keymap beginning with an escape +character (probably cursor keys), but leave the binding for the escape +character itself (probably \fBvi\-cmd\-mode\fP)\&. This is incompatible with the +option \fB\-R\fP\&. +.RE +.TP +\fB\-s\fP \fIin\-string out\-string\fP \&.\&.\&. +Bind each \fIin\-string\fP to each \fIout\-string\fP\&. +When \fIin\-string\fP is typed, \fIout\-string\fP will be +pushed back and treated as input to the line editor\&. +When \fB\-R\fP is also used, interpret the \fIin\-string\fPs as ranges\&. +.RS +.PP +Note that both \fIin\-string\fP and \fIout\-string\fP are subject to the same +form of interpretation, as described below\&. +.RE +.TP +\fIin\-string command\fP \&.\&.\&. +Bind each \fIin\-string\fP to each \fIcommand\fP\&. +When \fB\-R\fP is used, interpret the \fIin\-string\fPs as ranges\&. +.TP +[ \fIin\-string\fP ] +List key bindings\&. If an \fIin\-string\fP is specified, the binding of +that string in the selected keymap is displayed\&. Otherwise, all key +bindings in the selected keymap are displayed\&. (As a special case, +if the \fB\-e\fP or \fB\-v\fP option is used alone, the keymap is \fInot\fP +displayed \- the implicit linking of keymaps is the only thing that +happens\&.) +.RS +.PP +When the option \fB\-p\fP is used, the \fIin\-string\fP must be present\&. +The listing shows all bindings which have the given key sequence as a +prefix, not including any bindings for the key sequence itself\&. +.PP +When the \fB\-L\fP option is used, the list is in the form of \fBbindkey\fP +commands to create the key bindings\&. +.RE +.PP +When the \fB\-R\fP option is used as noted above, a valid range consists of +two characters, with an optional `\fB\-\fP\&' between them\&. All characters +between the two specified, inclusive, are bound as specified\&. +.PP +For either \fIin\-string\fP or \fIout\-string\fP, the following +escape sequences are recognised: +.PP +.PD 0 +.TP +\fB\ea\fP +bell character +.TP +\fB\eb\fP +backspace +.TP +\fB\ee\fP, \fB\eE\fP +escape +.TP +\fB\ef\fP +form feed +.TP +\fB\en\fP +linefeed (newline) +.TP +\fB\er\fP +carriage return +.TP +\fB\et\fP +horizontal tab +.TP +\fB\ev\fP +vertical tab +.TP +\fB\e\fP\fINNN\fP +character code in octal +.TP +\fB\ex\fP\fINN\fP +character code in hexadecimal +.TP +\fB\eu\fP\fINNNN\fP +unicode character code in hexadecimal +.TP +\fB\eU\fP\fINNNNNNNN\fP +unicode character code in hexadecimal +.TP +\fB\eM\fP[\fB\-\fP]\fIX\fP +character with meta bit set +.TP +\fB\eC\fP[\fB\-\fP]\fIX\fP +control character +.TP +\fB^\fP\fIX\fP +control character +.PD +.PP +In all other cases, `\fB\e\fP\&' escapes the following character\&. Delete is +written as `\fB^?\fP\&'\&. Note that `\fB\eM^?\fP' and `\fB^\eM?\fP' are not the same, +and that (unlike emacs), the bindings `\fB\eM\-\fP\fIX\fP\&' and `\fB\ee\fP\fIX\fP' +are entirely distinct, although they are initialized to the same bindings +by `\fBbindkey \-m\fP\&'\&. +.RE + +.TP +.PD 0 +\fBvared \fP[ \fB\-Aacghe\fP ] [ \fB\-p\fP \fIprompt\fP ] [ \fB\-r\fP \fIrprompt\fP ] +.TP +.PD 0 +\fB \fP[ \fB\-M\fP \fImain\-keymap\fP ] [ \fB\-m\fP \fIvicmd\-keymap\fP ] +.TP +.PD 0 +\fB \fP[ \fB\-i\fP \fIinit\-widget\fP ] [ \fB\-f\fP \fIfinish\-widget\fP ] +.TP +.PD +\fB \fP[ \fB\-t\fP \fItty\fP ] \fIname\fP +The value of the parameter \fIname\fP is loaded into the edit +buffer, and the line editor is invoked\&. When the editor exits, +\fIname\fP is set to the string value returned by the editor\&. +When the \fB\-c\fP flag is given, the parameter is created if it doesn\&'t +already exist\&. The \fB\-a\fP flag may be given with \fB\-c\fP to create +an array parameter, or the \fB\-A\fP flag to create an associative array\&. +If the type of an existing parameter does not match the type to be +created, the parameter is unset and recreated\&. The \fB\-g\fP flag may +be given to suppress warnings from the \fBWARN_CREATE_GLOBAL\fP +and \fBWARN_NESTED_VAR\fP options\&. +.RS +.PP +If an array or array slice is being edited, separator characters as defined +in \fB$IFS\fP will be shown quoted with a backslash, as will backslashes +themselves\&. Conversely, when the edited text is split into an array, a +backslash quotes an immediately following separator character or backslash; +no other special handling of backslashes, or any handling of quotes, is +performed\&. +.PP +Individual elements of existing array or associative array parameters +may be edited by using subscript syntax on \fIname\fP\&. New elements are +created automatically, even without \fB\-c\fP\&. +.PP +If the \fB\-p\fP flag is given, the following string will be taken as +the prompt to display at the left\&. If the \fB\-r\fP flag is given, +the following string gives the prompt to display at the right\&. If the +\fB\-h\fP flag is specified, the history can be accessed from ZLE\&. If the +\fB\-e\fP flag is given, typing \fB^D\fP (Control\-D) on an empty line +causes \fBvared\fP to exit immediately with a non\-zero return value\&. +.PP +The \fB\-M\fP option gives a keymap to link to the \fBmain\fP keymap during +editing, and the \fB\-m\fP option gives a keymap to link to the \fBvicmd\fP +keymap during editing\&. For vi\-style editing, this allows a pair of keymaps +to override \fBviins\fP and \fBvicmd\fP\&. For emacs\-style editing, only \fB\-M\fP +is normally needed but the \fB\-m\fP option may still be used\&. On exit, the +previous keymaps will be restored\&. +.PP +\fBVared\fP calls the usual `\fBzle\-line\-init\fP\&' and `\fBzle\-line\-finish\fP' +hooks before and after it takes control\&. Using the \fB\-i\fP and \fB\-f\fP +options, it is possible to replace these with other custom widgets\&. +.PP +If `\fB\-t\fP \fItty\fP\&' is given, \fItty\fP is the name of a terminal device +to be used instead of the default \fB/dev/tty\fP\&. If \fItty\fP does not +refer to a terminal an error is reported\&. +.RE +.TP +.PD 0 +\fBzle\fP +.TP +.PD 0 +\fBzle\fP \fB\-l\fP [ \fB\-L\fP | \fB\-a\fP ] [ \fIstring\fP \&.\&.\&. ] +.TP +.PD 0 +\fBzle\fP \fB\-D\fP \fIwidget\fP \&.\&.\&. +.TP +.PD 0 +\fBzle\fP \fB\-A\fP \fIold\-widget\fP \fInew\-widget\fP +.TP +.PD 0 +\fBzle\fP \fB\-N\fP \fIwidget\fP [ \fIfunction\fP ] +.TP +.PD 0 +\fBzle\fP \fB\-f\fP \fIflag\fP [ \fIflag\fP\&.\&.\&. ] +.TP +.PD 0 +\fBzle\fP \fB\-C\fP \fIwidget\fP \fIcompletion\-widget\fP \fIfunction\fP +.TP +.PD 0 +\fBzle\fP \fB\-R\fP [ \fB\-c\fP ] [ \fIdisplay\-string\fP ] [ \fIstring\fP \&.\&.\&. ] +.TP +.PD 0 +\fBzle\fP \fB\-M\fP \fIstring\fP +.TP +.PD 0 +\fBzle\fP \fB\-U\fP \fIstring\fP +.TP +.PD 0 +\fBzle\fP \fB\-K\fP \fIkeymap\fP +.TP +.PD 0 +\fBzle\fP \fB\-F\fP [ \fB\-L\fP | \fB\-w\fP ] [ \fIfd\fP [ \fIhandler\fP ] ] +.TP +.PD 0 +\fBzle\fP \fB\-I\fP +.TP +.PD 0 +\fBzle\fP \fB\-T\fP [ \fBtc\fP \fIfunction\fP | \fB\-r\fP \fBtc\fP | \fB\-L\fP ] +.TP +.PD +\fBzle\fP \fIwidget\fP [ \fB\-n\fP \fInum\fP ] [ \fB\-f\fP \fIflag\fP ] [ \fB\-Nw\fP ] [ \fB\-K\fP \fIkeymap\fP ] \fIargs\fP \&.\&.\&. +The \fBzle\fP builtin performs a number of different actions concerning +ZLE\&. +.RS +.PP +With no options and no arguments, only the return status will be +set\&. It is zero if ZLE is currently active and widgets could be +invoked using this builtin command and non\-zero otherwise\&. +Note that even if non\-zero status is returned, zle may still be active as +part of the completion system; this does not allow direct calls to ZLE +widgets\&. +.PP +Otherwise, which operation it performs depends on its options: +.PP +.PD 0 +.TP +.PD +\fB\-l\fP [ \fB\-L\fP | \fB\-a\fP ] [ \fIstring\fP ] +List all existing user\-defined widgets\&. If the \fB\-L\fP +option is used, list in the form of \fBzle\fP +commands to create the widgets\&. +.RS +.PP +When combined with the \fB\-a\fP option, all widget names are listed, +including the builtin ones\&. In this case the \fB\-L\fP option is ignored\&. +.PP +If at least one \fIstring\fP is given, and \fB\-a\fP is present or \fB\-L\fP is +not used, nothing will be printed\&. The return status will be zero if +all \fIstring\fPs are names of existing widgets and non\-zero if at least one +\fIstring\fP is not a name of a defined widget\&. If \fB\-a\fP is also +present, all widget names are used for the comparison including builtin +widgets, else only user\-defined widgets are used\&. +.PP +If at least one \fIstring\fP is present and the \fB\-L\fP option is used, +user\-defined widgets matching any \fIstring\fP are listed in the form of +\fBzle\fP commands to create the widgets\&. +.RE +.TP +\fB\-D\fP \fIwidget\fP \&.\&.\&. +Delete the named \fIwidget\fPs\&. +.TP +\fB\-A\fP \fIold\-widget\fP \fInew\-widget\fP +Make the \fInew\-widget\fP name an alias for \fIold\-widget\fP, so that +both names refer to the same widget\&. The names have equal standing; +if either is deleted, the other remains\&. If there is already a widget +with the \fInew\-widget\fP name, it is deleted\&. +.TP +\fB\-N\fP \fIwidget\fP [ \fIfunction\fP ] +Create a user\-defined widget\&. If there is already a widget with the +specified name, it is overwritten\&. When the new +widget is invoked from within the editor, the specified shell \fIfunction\fP +is called\&. If no function name is specified, it defaults to +the same name as the widget\&. For further information, see +the section `Widgets\&' below\&. +.TP +\fB\-f\fP \fIflag\fP [ \fIflag\fP\&.\&.\&. ] +Set various flags on the running widget\&. Possible values for \fIflag\fP are: +.RS +.PP +\fByank\fP for indicating that the widget has yanked text into the buffer\&. +If the widget is wrapping an existing internal widget, no further +action is necessary, but if it has inserted the text manually, then it +should also take care to set \fBYANK_START\fP and \fBYANK_END\fP correctly\&. +\fByankbefore\fP does the same but is used when the yanked text appears +after the cursor\&. +.PP +\fBkill\fP for indicating that text has been killed into the cutbuffer\&. +When repeatedly invoking a kill widget, text is appended to the cutbuffer +instead of replacing it, but when wrapping such widgets, it is necessary +to call `\fBzle \-f kill\fP\&' to retain this effect\&. +.PP +\fBvichange\fP for indicating that the widget represents a vi change that +can be repeated as a whole with `\fBvi\-repeat\-change\fP\&'\&. The flag should be set +early in the function before inspecting the value of \fBNUMERIC\fP or invoking +other widgets\&. This has no effect for a widget invoked from insert mode\&. If +insert mode is active when the widget finishes, the change extends until next +returning to command mode\&. +.RE +.TP +\fB\-C\fP \fIwidget\fP \fIcompletion\-widget\fP \fIfunction\fP +Create a user\-defined completion widget named \fIwidget\fP\&. The +completion widget will behave like the built\-in completion\-widget +whose name is given as \fIcompletion\-widget\fP\&. To generate the +completions, the shell function \fIfunction\fP will be called\&. +For further information, see +\fIzshcompwid\fP(1)\&. +.TP +\fB\-R\fP [ \fB\-c\fP ] [ \fIdisplay\-string\fP ] [ \fIstring\fP \&.\&.\&. ] +Redisplay the command line\&. If a \fIdisplay\-string\fP is +given and not empty, this is shown in the status line (immediately +below the line being edited)\&. +.RS +.PP +If the optional \fIstring\fPs are given they are listed below the +prompt in the same way as completion lists are printed\&. If no +\fIstring\fPs are given but the \fB\-c\fP option is used such a list is +cleared\&. +.PP +Note that immediately after returning from running widgets, the command line +will be redisplayed and the strings displayed will be erased\&. Therefore, this +option is only useful for widgets that do not exit immediately after using it\&. +.PP +This command can safely be called outside user defined widgets; if zle is +active, the display will be refreshed, while if zle is not active, the +command has no effect\&. In this case there will usually be no other +arguments\&. +.PP +The status is zero if zle was active, else one\&. +.RE +.TP +\fB\-M\fP \fIstring\fP +As with the \fB\-R\fP option, the \fIstring\fP will be displayed below the +command line; unlike the \fB\-R\fP option, the string will not be put into +the status line but will instead be printed normally below the +prompt\&. This means that the \fIstring\fP will still be displayed after +the widget returns (until it is overwritten by subsequent commands)\&. +.TP +\fB\-U\fP \fIstring\fP +This pushes the characters in the \fIstring\fP onto the input stack of +ZLE\&. After the widget currently executed finishes ZLE will behave as +if the characters in the \fIstring\fP were typed by the user\&. +.RS +.PP +As ZLE uses a stack, if this option is used repeatedly +the last string pushed onto the stack will be processed first\&. However, +the characters in each \fIstring\fP will be processed in the order in which +they appear in the string\&. +.RE +.TP +\fB\-K\fP \fIkeymap\fP +Selects the keymap named \fIkeymap\fP\&. An error message will be displayed if +there is no such keymap\&. +.RS +.PP +This keymap selection affects the interpretation of following keystrokes +within this invocation of ZLE\&. Any following invocation (e\&.g\&., the next +command line) will start as usual with the `\fBmain\fP\&' keymap selected\&. +.RE +.TP +\fB\-F\fP [ \fB\-L\fP | \fB\-w\fP ] [ \fIfd\fP [ \fIhandler\fP ] ] +Only available if your system supports one of the `poll\&' or `select' system +calls; most modern systems do\&. +.RS +.PP +Installs \fIhandler\fP (the name of a shell function) to handle input from +file descriptor \fIfd\fP\&. Installing a handler for an \fIfd\fP which is +already handled causes the existing handler to be replaced\&. Any number of +handlers for any number of readable file descriptors may be installed\&. +Note that zle makes no attempt to check whether this \fIfd\fP is actually +readable when installing the handler\&. The user must make their own +arrangements for handling the file descriptor when zle is not active\&. +.PP +When zle is attempting to read data, it will examine both the terminal and +the list of handled \fIfd\fP\&'s\&. If data becomes available on a handled +\fIfd\fP, zle calls \fIhandler\fP with the fd which is ready for reading +as the first argument\&. Under normal circumstances this is the only +argument, but if an error was detected, a second argument provides +details: `\fBhup\fP\&' for a disconnect, `\fBnval\fP' for a closed or otherwise +invalid descriptor, or `\fBerr\fP\&' for any other condition\&. Systems that +support only the `select\&' system call always use `\fBerr\fP'\&. +.PP +If the option \fB\-w\fP is also given, the \fIhandler\fP is instead a line +editor widget, typically a shell function made into a widget using +`\fBzle \-N\fP\&'\&. In that case \fIhandler\fP can use all the facilities of zle +to update the current editing line\&. Note, however, that as handling \fIfd\fP +takes place at a low level changes to the display will not automatically +appear; the widget should call `\fBzle \-R\fP\&' to force redisplay\&. As of this +writing, widget handlers only support a single argument and thus are never +passed a string for error state, so widgets must be prepared to test the +descriptor themselves\&. +.PP +If either type of handler produces output to the terminal, it should call +`\fBzle \-I\fP\&' before doing so (see below)\&. Handlers should not attempt to +read from the terminal\&. +.PP +If no \fIhandler\fP is given, but an \fIfd\fP is present, any handler for +that \fIfd\fP is removed\&. If there is none, an error message is printed +and status 1 is returned\&. +.PP +If no arguments are given, or the \fB\-L\fP option is supplied, a list of +handlers is printed in a form which can be stored for later execution\&. +.PP +An \fIfd\fP (but not a \fIhandler\fP) may optionally be given with the \fB\-L\fP +option; in this case, the function will list the handler if any, else +silently return status 1\&. +.PP +Note that this feature should be used with care\&. Activity on one of the +\fIfd\fP\&'s which is not properly handled can cause the terminal to become +unusable\&. Removing an \fIfd\fP handler from within a signal trap may cause +unpredictable behavior\&. +.PP +Here is a simple example of using this feature\&. A connection to a remote +TCP port is created using the ztcp command; see +the description of the \fBzsh/net/tcp\fP module in \fIzshmodules\fP(1)\&. Then a handler is installed +which simply prints out any data which arrives on this connection\&. Note +that `select\&' will indicate that the file descriptor needs handling +if the remote side has closed the connection; we handle that by testing +for a failed read\&. +.PP +.RS +.nf +\fBif ztcp pwspc 2811; then + tcpfd=$REPLY + handler() { + zle \-I + local line + if ! read \-r line <&$1; then + # select marks this fd if we reach EOF, + # so handle this specially\&. + print "[Read on fd $1 failed, removing\&.]" >&2 + zle \-F $1 + return 1 + fi + print \-r \- $line + } + zle \-F $tcpfd handler +fi\fP +.fi +.RE +.RE +.TP +\fB\-I\fP +Unusually, this option is most useful outside ordinary widget functions, +though it may be used within if normal output to the terminal is required\&. +It invalidates the current zle display in preparation for output; typically +this will be from a trap function\&. It has no effect if zle is not +active\&. When a trap exits, the shell checks to see if the display needs +restoring, hence the following will print output in such a way as not to +disturb the line being edited: +.RS +.PP +.RS +.nf +\fBTRAPUSR1() { + # Invalidate zle display + [[ \-o zle ]] && zle \-I + # Show output + print Hello +}\fP +.fi +.RE +.PP +In general, the trap function may need to test whether zle is active before +using this method (as shown in the example), since the \fBzsh/zle\fP module +may not even be loaded; if it is not, the command can be skipped\&. +.PP +It is possible to call `\fBzle \-I\fP\&' several times before control is +returned to the editor; the display will only be invalidated the first time +to minimise disruption\&. +.PP +Note that there are normally better ways of manipulating the display from +within zle widgets; see, for example, `\fBzle \-R\fP\&' above\&. +.PP +The returned status is zero if zle was invalidated, even though +this may have been by a previous call to `\fBzle \-I\fP\&' or by a system +notification\&. To test if a zle widget may be called at this point, execute +\fBzle\fP with no arguments and examine the return status\&. +.RE +.TP +\fB\-T\fP +This is used to add, list or remove internal transformations on the +processing performed by the line editor\&. It is typically used only for +debugging or testing and is therefore of little interest to the general +user\&. +.RS +.PP +`\fBzle \-T\fP \fItransformation\fP \fIfunc\fP\&' specifies that the +given \fItransformation\fP (see below) is effected by shell function +\fIfunc\fP\&. +.PP +`\fBzle \-Tr\fP \fItransformation\fP\&' removes the given \fItransformation\fP +if it was present (it is not an error if none was)\&. +.PP +`\fBzle \-TL\fP\&' can be used to list all transformations currently in +operation\&. +.PP +Currently the only transformation is \fBtc\fP\&. This is used instead +of outputting termcap codes to the terminal\&. When the transformation is +in operation the shell function is passed the termcap code that would be +output as its first argument; if the operation required a numeric +argument, that is passed as a second argument\&. The function should set +the shell variable \fBREPLY\fP to the transformed termcap code\&. Typically +this is used to produce some simply formatted version of the code and +optional argument for debugging or testing\&. Note that this +transformation is not applied to other non\-printing characters such as +carriage returns and newlines\&. +.RE +.TP +\fIwidget\fP [ \fB\-n\fP \fInum\fP ] [ \fB\-f\fP \fIflag\fP ] [ \fB\-Nw\fP ] [ \fB\-K\fP \fIkeymap\fP ] \fIargs\fP \&.\&.\&. +Invoke the specified \fIwidget\fP\&. This can only be done when ZLE is +active; normally this will be within a user\-defined widget\&. +.RS +.PP +With the options \fB\-n\fP and \fB\-N\fP, the current numeric argument will be +saved and then restored after the call to \fIwidget\fP; `\fB\-n\fP \fInum\fP\&' +sets the numeric argument temporarily to \fInum\fP, while `\fB\-N\fP\&' sets it +to the default, i\&.e\&. as if there were none\&. +.PP +With the option \fB\-K\fP, \fIkeymap\fP will be used as the current keymap +during the execution of the widget\&. The previous keymap will be +restored when the widget exits\&. +.PP +Normally, calling a widget in this way does not set the special +parameter \fBWIDGET\fP and related parameters, so that the environment +appears as if the top\-level widget called by the user were still +active\&. With the option \fB\-w\fP, \fBWIDGET\fP and related parameters are set +to reflect the widget being executed by the \fBzle\fP call\&. +.PP +Normally, when \fIwidget\fP returns the special parameter \fBLASTWIDGET\fP will +point to it\&. This can be inhibited by passing the option \fB\-f nolast\fP\&. +.PP +Any further arguments will be passed to the widget; note that as +standard argument handling is performed, any general argument list +should be preceded by \fB\-\fP\fB\-\fP\&. If it is a shell +function, these are passed down as positional parameters; for builtin +widgets it is up to the widget in question what it does with them\&. +Currently arguments are only handled by the incremental\-search commands, +the \fBhistory\-search\-forward\fP and \fB\-backward\fP and the corresponding +functions prefixed by \fBvi\-\fP, and by \fBuniversal\-argument\fP\&. No error is +flagged if the command does not use the arguments, or only uses some of +them\&. +.PP +The return status reflects the success or failure of the operation carried +out by the widget, or if it is a user\-defined widget the return status of +the shell function\&. +.PP +A non\-zero return status causes the shell to beep when the widget exits, +unless the \fBBEEP\fP options was unset or the widget was called via the +\fBzle\fP command\&. Thus if a user defined widget requires an immediate beep, +it should call the \fBbeep\fP widget directly\&. +.RE +.RE +.PP +.SH "ZLE WIDGETS" +All actions in the editor are performed by `widgets\&'\&. A widget's job is +simply to perform some small action\&. The ZLE commands that key sequences +in keymaps are bound to are in fact widgets\&. Widgets can be user\-defined +or built in\&. +.PP +The standard widgets built into ZLE are listed in +the section `Standard Widgets\&' below\&. +Other built\-in widgets can be defined by other modules (see +\fIzshmodules\fP(1))\&. Each built\-in widget has two names: its normal canonical name, and the +same name preceded by a `\fB\&.\fP\&'\&. The `\fB\&.\fP' name is special: it can't be +rebound to a different widget\&. This makes the widget available even when +its usual name has been redefined\&. +.PP +User\-defined widgets are defined using `\fBzle \-N\fP\&', and implemented +as shell functions\&. When the widget is executed, the corresponding +shell function is executed, and can perform editing (or other) actions\&. +It is recommended that user\-defined widgets should not have names +starting with `\fB\&.\fP\&'\&. +.PP +.SH "USER\-DEFINED WIDGETS" +User\-defined widgets, being implemented as shell functions, +can execute any normal shell command\&. They can also run other widgets +(whether built\-in or user\-defined) using the \fBzle\fP builtin command\&. The +standard input of the function is redirected from /dev/null to prevent +external commands from unintentionally blocking ZLE by reading from the +terminal, but \fBread \-k\fP or \fBread \-q\fP can be used to read characters\&. +Finally, they can examine and edit the ZLE buffer being edited by reading +and setting the special parameters described below\&. +.PP +These special parameters are always available in widget functions, but +are not in any way special outside ZLE\&. If they have some normal value +outside ZLE, that value is temporarily inaccessible, but will return +when the widget function exits\&. These special parameters in fact have +local scope, like parameters created in a function using \fBlocal\fP\&. +.PP +Inside completion widgets and traps called while ZLE is active, these +parameters are available read\-only\&. +.PP +Note that the parameters appear as local to any ZLE widget in +which they appear\&. Hence if it is desired to override them this needs +to be done within a nested function: +.PP +.RS +.nf +\fBwidget\-function() { + # $WIDGET here refers to the special variable + # that is local inside widget\-function + () { + # This anonymous nested function allows WIDGET + # to be used as a local variable\&. The \-h + # removes the special status of the variable\&. + local \-h WIDGET + } +}\fP +.fi +.RE +.PP +.PD 0 +.TP +.PD +\fBBUFFER\fP (scalar) +The entire contents of the edit buffer\&. If it is written to, the +cursor remains at the same offset, unless that would put it outside the +buffer\&. +.TP +\fBBUFFERLINES\fP (integer) +The number of screen lines needed for the edit buffer currently +displayed on screen (i\&.e\&. without any changes to the preceding +parameters done after the last redisplay); read\-only\&. +.TP +\fBCONTEXT\fP (scalar) +The context in which zle was called to read a line; read\-only\&. One of +the values: +.RS +.PP +.PD 0 +.TP +.PD +\fBstart\fP +The start of a command line (at prompt \fBPS1\fP)\&. +.TP +\fBcont\fP +A continuation to a command line (at prompt \fBPS2\fP)\&. +.TP +\fBselect\fP +In a \fBselect\fP loop (at prompt \fBPS3\fP)\&. +.TP +\fBvared\fP +Editing a variable in \fBvared\fP\&. +.RE +.TP +\fBCURSOR\fP (integer) +The offset of the cursor, within the edit buffer\&. This is in the range +0 to \fB$#BUFFER\fP, and is by definition equal to \fB$#LBUFFER\fP\&. +Attempts to move the cursor outside the buffer will result in the +cursor being moved to the appropriate end of the buffer\&. +.TP +\fBCUTBUFFER\fP (scalar) +The last item cut using one of the `\fBkill\-\fP\&' commands; the string +which the next yank would insert in the line\&. Later entries in +the kill ring are in the array \fBkillring\fP\&. Note that the +command `\fBzle copy\-region\-as\-kill\fP \fIstring\fP\&' can be used to +set the text of the cut buffer from a shell function and cycle the kill +ring in the same way as interactively killing text\&. +.TP +\fBHISTNO\fP (integer) +The current history number\&. Setting this has the same effect as +moving up or down in the history to the corresponding history line\&. +An attempt to set it is ignored if the line is not stored in the +history\&. Note this is not the same as the parameter \fBHISTCMD\fP, +which always gives the number of the history line being added to the main +shell\&'s history\&. \fBHISTNO\fP refers to the line being retrieved within +zle\&. +.TP +.PD 0 +\fBISEARCHMATCH_ACTIVE\fP (integer) +.TP +.PD 0 +\fBISEARCHMATCH_START\fP (integer) +.TP +.PD +\fBISEARCHMATCH_END\fP (integer) +\fBISEARCHMATCH_ACTIVE\fP indicates whether a part of the \fBBUFFER\fP is +currently matched by an incremental search pattern\&. \fBISEARCHMATCH_START\fP +and \fBISEARCHMATCH_END\fP give the location of the matched part and are +in the same units as \fBCURSOR\fP\&. They are only valid for reading +when \fBISEARCHMATCH_ACTIVE\fP is non\-zero\&. +.RS +.PP +All parameters are read\-only\&. +.RE +.TP +\fBKEYMAP\fP (scalar) +The name of the currently selected keymap; read\-only\&. +.TP +\fBKEYS\fP (scalar) +The keys typed to invoke this widget, as a literal string; read\-only\&. +.TP +\fBKEYS_QUEUED_COUNT\fP (integer) +The number of bytes pushed back to the input queue and therefore +available for reading immediately before any I/O is done; read\-only\&. +See also \fBPENDING\fP; the two values are distinct\&. +.TP +\fBkillring\fP (array) +The array of previously killed items, with the most recently killed first\&. +This gives the items that would be retrieved by a \fByank\-pop\fP in the +same order\&. Note, however, that the most recently killed item is in +\fB$CUTBUFFER\fP; \fB$killring\fP shows the array of previous entries\&. +.RS +.PP +The default size for the kill ring is eight, however the length may be +changed by normal array operations\&. Any empty string in the kill ring is +ignored by the \fByank\-pop\fP command, hence the size of the array +effectively sets the maximum length of the kill ring, while the number of +non\-zero strings gives the current length, both as seen by the user at the +command line\&. +.RE +.TP +\fBLASTABORTEDSEARCH\fP (scalar) +The last search string used by an interactive search that was +aborted by the user (status 3 returned by the search widget)\&. +.TP +\fBLASTSEARCH\fP (scalar) +The last search string used by an interactive search; read\-only\&. +This is set even if the search failed (status 0, 1 or 2 returned +by the search widget), but not if it was aborted by the user\&. +.TP +\fBLASTWIDGET\fP (scalar) +The name of the last widget that was executed; read\-only\&. +.TP +\fBLBUFFER\fP (scalar) +The part of the buffer that lies to the left of the cursor position\&. +If it is assigned to, only that part of the buffer is replaced, and the +cursor remains between the new \fB$LBUFFER\fP and the old \fB$RBUFFER\fP\&. +.TP +\fBMARK\fP (integer) +Like \fBCURSOR\fP, but for the mark\&. With vi\-mode operators that wait for +a movement command to select a region of text, setting \fBMARK\fP allows +the selection to extend in both directions from the initial cursor +position\&. +.TP +\fBNUMERIC\fP (integer) +The numeric argument\&. If no numeric argument was given, this parameter +is unset\&. When this is set inside a widget function, builtin widgets +called with the \fBzle\fP builtin command will use the value +assigned\&. If it is unset inside a widget function, builtin widgets +called behave as if no numeric argument was given\&. +.TP +\fBPENDING\fP (integer) +The number of bytes pending for input, i\&.e\&. the number of bytes which have +already been typed and can immediately be read\&. On systems where the shell +is not able to get this information, this parameter will always have a +value of zero\&. Read\-only\&. See also \fBKEYS_QUEUED_COUNT\fP; the two +values are distinct\&. +.TP +\fBPREBUFFER\fP (scalar) +In a multi\-line input at the secondary prompt, this read\-only parameter +contains the contents of the lines before the one the cursor is +currently in\&. +.TP +\fBPREDISPLAY\fP (scalar) +Text to be displayed before the start of the editable text buffer\&. This +does not have to be a complete line; to display a complete line, a newline +must be appended explicitly\&. The text is reset on each new invocation +(but not recursive invocation) of zle\&. +.TP +\fBPOSTDISPLAY\fP (scalar) +Text to be displayed after the end of the editable text buffer\&. This +does not have to be a complete line; to display a complete line, a newline +must be prepended explicitly\&. The text is reset on each new invocation +(but not recursive invocation) of zle\&. +.TP +\fBRBUFFER\fP (scalar) +The part of the buffer that lies to the right of the cursor position\&. +If it is assigned to, only that part of the buffer is replaced, and the +cursor remains between the old \fB$LBUFFER\fP and the new \fB$RBUFFER\fP\&. +.TP +\fBREGION_ACTIVE\fP (integer) +Indicates if the region is currently active\&. It can be assigned 0 or 1 +to deactivate and activate the region respectively\&. A value of 2 +activates the region in line\-wise mode with the highlighted text +extending for whole lines only; see +\fICharacter Highlighting\fP below\&. +.TP +\fBregion_highlight\fP (array) +Each element of this array may be set to a string that describes +highlighting for an arbitrary region of the command line that will +take effect the next time the command line is redisplayed\&. Highlighting +of the non\-editable parts of the command line in \fBPREDISPLAY\fP +and \fBPOSTDISPLAY\fP are possible, but note that the \fBP\fP flag +is needed for character indexing to include \fBPREDISPLAY\fP\&. +.RS +.PP +Each string consists of the following whitespace\-separated parts: +.PP +.PD 0 +.TP +.PD +\(bu +Optionally, a `\fBP\fP\&' to signify that the start and end offset that +follow include any string set by the \fBPREDISPLAY\fP special parameter; +this is needed if the predisplay string itself is to be highlighted\&. +Whitespace between the `\fBP\fP\&' and the start offset is optional\&. +.TP +\(bu +A start offset in the same units as \fBCURSOR\fP\&. +.TP +\(bu +An end offset in the same units as \fBCURSOR\fP\&. +.TP +\(bu +A highlight specification in the same format as +used for contexts in the parameter \fBzle_highlight\fP, see +the section `Character Highlighting\&' below; +for example, \fBstandout\fP or \fBfg=red,bold\fP\&. +.TP +\(bu +Optionally, a string of the form `\fBmemo=\fP\fItoken\fP\&'\&. +The \fItoken\fP consists of everything between the `\fB=\fP\&' and the next +whitespace, comma, NUL, or the end of the string\&. +The \fItoken\fP is preserved verbatim but not parsed in any way\&. +.RS +.PP +Plugins may use this to identify array elements they have added: for example, +a plugin might set \fItoken\fP to its (the plugin\&'s) name and then use +`\fBregion_highlight=( ${region_highlight:#*memo=\fP\fItoken\fP\fB} )\fP\&' +in order to remove array elements it have added\&. +.PP +(This example uses the `\fB${\fP\fIname\fP\fB:#\fP\fIpattern\fP\fB}\fP\&' array\-grepping +syntax described in +the section `Parameter Expansion\&' in \fIzshexpn\fP(1)\&.) +.RE +.PP +For example, +.PP +.RS +.nf +\fBregion_highlight=("P0 20 bold memo=foobar")\fP +.fi +.RE +.PP +specifies that the first twenty characters of the text including +any predisplay string should be highlighted in bold\&. +.PP +Note that the effect of \fBregion_highlight\fP is not saved and disappears +as soon as the line is accepted\&. +.PP +Note that zsh 5\&.8 and older do not support the `\fBmemo=\fP\fItoken\fP\&' field +and may misparse the third (highlight specification) field when a memo +is given\&. + +.PP +The final highlighting on the command line depends on both \fBregion_highlight\fP +and \fBzle_highlight\fP; see +the section CHARACTER HIGHLIGHTING below for details\&. +.RE +.TP +\fBregisters\fP (associative array) +The contents of each of the vi register buffers\&. These are +typically set using \fBvi\-set\-buffer\fP followed by a delete, change or +yank command\&. +.TP +.PD 0 +\fBSUFFIX_ACTIVE\fP (integer) +.TP +.PD 0 +\fBSUFFIX_START\fP (integer) +.TP +.PD +\fBSUFFIX_END\fP (integer) +\fBSUFFIX_ACTIVE\fP indicates whether an auto\-removable completion suffix +is currently active\&. \fBSUFFIX_START\fP and \fBSUFFIX_END\fP give the +location of the suffix and are in the same units as \fBCURSOR\fP\&. They are +only valid for reading when \fBSUFFIX_ACTIVE\fP is non\-zero\&. +.RS +.PP +All parameters are read\-only\&. +.RE +.TP +\fBUNDO_CHANGE_NO\fP (integer) +A number representing the state of the undo history\&. The only use +of this is passing as an argument to the \fBundo\fP widget in order to +undo back to the recorded point\&. Read\-only\&. +.TP +\fBUNDO_LIMIT_NO\fP (integer) +A number corresponding to an existing change in the undo history; +compare \fBUNDO_CHANGE_NO\fP\&. If this is set to a value greater +than zero, the \fBundo\fP command will not allow the line to +be undone beyond the given change number\&. It is still possible +to use `\fBzle undo\fP \fIchange\fP\&' in a widget to undo beyond +that point; in that case, it will not be possible to undo at +all until \fBUNDO_LIMIT_NO\fP is reduced\&. Set to 0 to disable the limit\&. +.RS +.PP +A typical use of this variable in a widget function is as follows (note +the additional function scope is required): +.PP +.RS +.nf +\fB() { + local UNDO_LIMIT_NO=$UNDO_CHANGE_NO + # Perform some form of recursive edit\&. +}\fP +.fi +.RE +.RE +.TP +\fBWIDGET\fP (scalar) +The name of the widget currently being executed; read\-only\&. +.TP +\fBWIDGETFUNC\fP (scalar) +The name of the shell function that implements a widget defined with +either \fBzle \-N\fP or \fBzle \-C\fP\&. In the former case, this is the second +argument to the \fBzle \-N\fP command that defined the widget, or +the first argument if there was no second argument\&. In the latter case +this is the third argument to the \fBzle \-C\fP command that defined the +widget\&. Read\-only\&. +.TP +\fBWIDGETSTYLE\fP (scalar) +Describes the implementation behind the completion widget currently being +executed; the second argument that followed \fBzle \-C\fP when the widget was +defined\&. This is the name of a builtin completion widget\&. For widgets +defined with \fBzle \-N\fP this is set to the empty string\&. Read\-only\&. +.TP +.PD 0 +\fBYANK_ACTIVE\fP (integer) +.TP +.PD 0 +\fBYANK_START\fP (integer) +.TP +.PD +\fBYANK_END\fP (integer) +\fBYANK_ACTIVE\fP indicates whether text has just been yanked (pasted) +into the buffer\&. \fBYANK_START\fP and \fBYANK_END\fP give the location of +the pasted text and are in the same units as \fBCURSOR\fP\&. They are only +valid for reading when \fBYANK_ACTIVE\fP is non\-zero\&. They can also be +assigned by widgets that insert text in a yank\-like fashion, for example +wrappers of \fBbracketed\-paste\fP\&. See also \fBzle \-f\fP\&. +.RS +.PP +\fBYANK_ACTIVE\fP is read\-only\&. +.RE +.TP +\fBZLE_RECURSIVE\fP (integer) +Usually zero, but incremented inside any instance of +\fBrecursive\-edit\fP\&. Hence indicates the current recursion level\&. +.RS +.PP +\fBZLE_RECURSIVE\fP is read\-only\&. +.RE +.TP +\fBZLE_STATE\fP (scalar) +Contains a set of space\-separated words that describe the current \fBzle\fP +state\&. +.RS +.PP +Currently, the states shown are the insert mode as set by the +\fBoverwrite\-mode\fP or \fBvi\-replace\fP widgets and whether history commands +will visit imported entries as controlled by the set\-local\-history widget\&. +The string contains `\fBinsert\fP\&' if characters to be inserted on the +command line move existing characters to the right or `\fBoverwrite\fP\&' +if characters to be inserted overwrite existing characters\&. It contains +`\fBlocalhistory\fP\&' if only local history commands will be visited or +`\fBglobalhistory\fP\&' if imported history commands will also be visited\&. +.PP +The substrings are sorted in alphabetical order so that if you want to +test for two specific substrings in a future\-proof way, you can do match +by doing: +.PP +.RS +.nf +\fBif [[ $ZLE_STATE == *globalhistory*insert* ]]; then \&.\&.\&.; fi\fP +.fi +.RE +.RE +.PP +.SS "Special Widgets" +.PP +There are a few user\-defined widgets which are special to the shell\&. +If they do not exist, no special action is taken\&. The environment +provided is identical to that for any other editing widget\&. +.PP +.PD 0 +.TP +.PD +\fBzle\-isearch\-exit\fP +Executed at the end of incremental search at the point where the isearch +prompt is removed from the display\&. See \fBzle\-isearch\-update\fP for +an example\&. +.TP +\fBzle\-isearch\-update\fP +Executed within incremental search when the display is about to be +redrawn\&. Additional output below the incremental search prompt can be +generated by using `\fBzle \-M\fP\&' within the widget\&. For example, +.RS +.PP +.RS +.nf +\fBzle\-isearch\-update() { zle \-M "Line $HISTNO"; } +zle \-N zle\-isearch\-update\fP +.fi +.RE +.PP +Note the line output by `\fBzle \-M\fP\&' is not deleted on exit from +incremental search\&. This can be done from a \fBzle\-isearch\-exit\fP +widget: +.PP +.RS +.nf +\fBzle\-isearch\-exit() { zle \-M ""; } +zle \-N zle\-isearch\-exit\fP +.fi +.RE +.RE +.TP +\fBzle\-line\-pre\-redraw\fP +Executed whenever the input line is about to be redrawn, providing an +opportunity to update the region_highlight array\&. +.TP +\fBzle\-line\-init\fP +Executed every time the line editor is started to read a new line +of input\&. The following example puts the line editor into vi command +mode when it starts up\&. +.RS +.PP +.RS +.nf +\fBzle\-line\-init() { zle \-K vicmd; } +zle \-N zle\-line\-init\fP +.fi +.RE +.PP +(The command inside the function sets the keymap directly; it is +equivalent to \fBzle vi\-cmd\-mode\fP\&.) +.RE +.TP +\fBzle\-line\-finish\fP +This is similar to \fBzle\-line\-init\fP but is executed every time the +line editor has finished reading a line of input\&. +.TP +\fBzle\-history\-line\-set\fP +Executed when the history line changes\&. +.TP +\fBzle\-keymap\-select\fP +Executed every time the keymap changes, i\&.e\&. the special parameter +\fBKEYMAP\fP is set to a different value, while the line editor is active\&. +Initialising the keymap when the line editor starts does not cause the +widget to be called\&. +.RS +.PP +The value \fB$KEYMAP\fP within the function reflects the new keymap\&. The +old keymap is passed as the sole argument\&. +.PP +This can be used for detecting switches between the vi command +(\fBvicmd\fP) and insert (usually \fBmain\fP) keymaps\&. +.RE +.PP +.SH "STANDARD WIDGETS" +The following is a list of all the standard widgets, +and their default bindings in emacs mode, +vi command mode and vi insert mode +(the `\fBemacs\fP\&', `\fBvicmd\fP' and `\fBviins\fP' keymaps, respectively)\&. +.PP +Note that cursor keys are bound to movement keys in all three keymaps; +the shell assumes that the cursor keys send the key sequences reported +by the terminal\-handling library (termcap or terminfo)\&. The key sequences +shown in the list are those based on the VT100, common on many modern +terminals, but in fact these are not necessarily bound\&. In the case of the +\fBviins\fP keymap, the initial escape character of the sequences serves also +to return to the \fBvicmd\fP keymap: whether this happens is determined by +the \fBKEYTIMEOUT\fP parameter, see \fIzshparam\fP(1)\&. +.SS "Movement" +.PD 0 +.TP +.PD +\fBvi\-backward\-blank\-word\fP (unbound) (\fBB\fP) (unbound) +Move backward one word, where a word is defined as a series of +non\-blank characters\&. +.TP +\fBvi\-backward\-blank\-word\-end\fP (unbound) (\fBgE\fP) (unbound) +Move to the end of the previous word, where a word is defined as a +series of non\-blank characters\&. +.TP +\fBbackward\-char\fP (\fB^B ESC\-[D\fP) (unbound) (unbound) +Move backward one character\&. +.TP +\fBvi\-backward\-char\fP (unbound) (\fB^H h ^?\fP) (\fBESC\-[D\fP) +Move backward one character, without changing lines\&. +.TP +\fBbackward\-word\fP (\fBESC\-B ESC\-b\fP) (unbound) (unbound) +Move to the beginning of the previous word\&. +.TP +\fBemacs\-backward\-word\fP +Move to the beginning of the previous word\&. +.TP +\fBvi\-backward\-word\fP (unbound) (\fBb\fP) (unbound) +Move to the beginning of the previous word, vi\-style\&. +.TP +\fBvi\-backward\-word\-end\fP (unbound) (\fBge\fP) (unbound) +Move to the end of the previous word, vi\-style\&. +.TP +\fBbeginning\-of\-line\fP (\fB^A\fP) (unbound) (unbound) +Move to the beginning of the line\&. If already at the beginning +of the line, move to the beginning of the previous line, if any\&. +.TP +\fBvi\-beginning\-of\-line\fP +Move to the beginning of the line, without changing lines\&. +.TP +\fBdown\-line\fP (unbound) (unbound) (unbound) +Move down a line in the buffer\&. +.TP +\fBend\-of\-line\fP (\fB^E\fP) (unbound) (unbound) +Move to the end of the line\&. If already at the end +of the line, move to the end of the next line, if any\&. +.TP +\fBvi\-end\-of\-line\fP (unbound) (\fB$\fP) (unbound) +Move to the end of the line\&. +If an argument is given to this command, the cursor will be moved to +the end of the line (argument \- 1) lines down\&. +.TP +\fBvi\-forward\-blank\-word\fP (unbound) (\fBW\fP) (unbound) +Move forward one word, where a word is defined as a series of +non\-blank characters\&. +.TP +\fBvi\-forward\-blank\-word\-end\fP (unbound) (\fBE\fP) (unbound) +Move to the end of the current word, or, if at the end of the current word, +to the end of the next word, +where a word is defined as a series of non\-blank characters\&. +.TP +\fBforward\-char\fP (\fB^F ESC\-[C\fP) (unbound) (unbound) +Move forward one character\&. +.TP +\fBvi\-forward\-char\fP (unbound) (\fBspace l\fP) (\fBESC\-[C\fP) +Move forward one character\&. +.TP +\fBvi\-find\-next\-char\fP (\fB^X^F\fP) (\fBf\fP) (unbound) +Read a character from the keyboard, and move to +the next occurrence of it in the line\&. +.TP +\fBvi\-find\-next\-char\-skip\fP (unbound) (\fBt\fP) (unbound) +Read a character from the keyboard, and move to +the position just before the next occurrence of it in the line\&. +.TP +\fBvi\-find\-prev\-char\fP (unbound) (\fBF\fP) (unbound) +Read a character from the keyboard, and move to +the previous occurrence of it in the line\&. +.TP +\fBvi\-find\-prev\-char\-skip\fP (unbound) (\fBT\fP) (unbound) +Read a character from the keyboard, and move to +the position just after the previous occurrence of it in the line\&. +.TP +\fBvi\-first\-non\-blank\fP (unbound) (\fB^\fP) (unbound) +Move to the first non\-blank character in the line\&. +.TP +\fBvi\-forward\-word\fP (unbound) (\fBw\fP) (unbound) +Move forward one word, vi\-style\&. +.TP +\fBforward\-word\fP (\fBESC\-F ESC\-f\fP) (unbound) (unbound) +Move to the beginning of the next word\&. +The editor\&'s idea of a word is specified with the \fBWORDCHARS\fP +parameter\&. +.TP +\fBemacs\-forward\-word\fP +Move to the end of the next word\&. +.TP +\fBvi\-forward\-word\-end\fP (unbound) (\fBe\fP) (unbound) +Move to the end of the next word\&. +.TP +\fBvi\-goto\-column\fP (\fBESC\-|\fP) (\fB|\fP) (unbound) +Move to the column specified by the numeric argument\&. +.TP +\fBvi\-goto\-mark\fP (unbound) (\fB`\fP) (unbound) +Move to the specified mark\&. +.TP +\fBvi\-goto\-mark\-line\fP (unbound) (\fB\&'\fP) (unbound) +Move to beginning of the line containing the specified mark\&. +.TP +\fBvi\-repeat\-find\fP (unbound) (\fB;\fP) (unbound) +Repeat the last \fBvi\-find\fP command\&. +.TP +\fBvi\-rev\-repeat\-find\fP (unbound) (\fB,\fP) (unbound) +Repeat the last \fBvi\-find\fP command in the opposite direction\&. +.TP +\fBup\-line\fP (unbound) (unbound) (unbound) +Move up a line in the buffer\&. +.SS "History Control" +.PD 0 +.TP +.PD +\fBbeginning\-of\-buffer\-or\-history\fP (\fBESC\-<\fP) (\fBgg\fP) (unbound) +Move to the beginning of the buffer, or if already there, +move to the first event in the history list\&. +.TP +\fBbeginning\-of\-line\-hist\fP +Move to the beginning of the line\&. If already at the +beginning of the buffer, move to the previous history line\&. +.TP +\fBbeginning\-of\-history\fP +Move to the first event in the history list\&. +.TP +\fBdown\-line\-or\-history\fP (\fB^N ESC\-[B\fP) (\fBj\fP) (\fBESC\-[B\fP) +Move down a line in the buffer, or if already at the bottom line, +move to the next event in the history list\&. +.TP +\fBvi\-down\-line\-or\-history\fP (unbound) (\fB+\fP) (unbound) +Move down a line in the buffer, or if already at the bottom line, +move to the next event in the history list\&. +Then move to the first non\-blank character on the line\&. +.TP +\fBdown\-line\-or\-search\fP +Move down a line in the buffer, or if already at the bottom line, +search forward in the history for a line beginning with the first +word in the buffer\&. +.RS +.PP +If called from a function by the \fBzle\fP command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer\&. +.RE +.TP +\fBdown\-history\fP (unbound) (\fB^N\fP) (unbound) +Move to the next event in the history list\&. +.TP +\fBhistory\-beginning\-search\-backward\fP +Search backward in the history for a line beginning with the current +line up to the cursor\&. +This leaves the cursor in its original position\&. +.TP +\fBend\-of\-buffer\-or\-history\fP (\fBESC\->\fP) (unbound) (unbound) +Move to the end of the buffer, or if already there, +move to the last event in the history list\&. +.TP +\fBend\-of\-line\-hist\fP +Move to the end of the line\&. If already at the end of +the buffer, move to the next history line\&. +.TP +\fBend\-of\-history\fP +Move to the last event in the history list\&. +.TP +\fBvi\-fetch\-history\fP (unbound) (\fBG\fP) (unbound) +Fetch the history line specified by the numeric argument\&. +This defaults to the current history line +(i\&.e\&. the one that isn\&'t history yet)\&. +.TP +\fBhistory\-incremental\-search\-backward\fP (\fB^R ^Xr\fP) (unbound) (unbound) +Search backward incrementally for a specified string\&. The search is +case\-insensitive if the search string does not have uppercase letters and no +numeric argument was given\&. The string may begin with `\fB^\fP\&' to anchor the +search to the beginning of the line\&. When called from a user\-defined +function returns the following statuses: 0, if the search succeeded; +1, if the search failed; 2, if the search term was a bad pattern; +3, if the search was aborted by the \fBsend\-break\fP command\&. +.RS +.PP +A restricted set of editing functions +is available in the mini\-buffer\&. Keys are looked up in the special +\fBisearch\fP keymap, and if not found there in the main keymap (note +that by default the \fBisearch\fP keymap is empty)\&. +An interrupt signal, as defined by the stty +setting, will stop the search and go back to the original line\&. An undefined +key will have the same effect\&. Note that the following always +perform the same task within incremental searches and cannot be +replaced by user defined widgets, nor can the set of functions +be extended\&. The supported functions are: +.PP +.PD 0 +.TP +.PD 0 +\fBaccept\-and\-hold\fP +.TP +.PD 0 +\fBaccept\-and\-infer\-next\-history\fP +.TP +.PD 0 +\fBaccept\-line\fP +.TP +.PD +\fBaccept\-line\-and\-down\-history\fP +Perform the usual function after exiting incremental search\&. +The command line displayed is executed\&. +.TP +.PD 0 +\fBbackward\-delete\-char\fP +.TP +.PD +\fBvi\-backward\-delete\-char\fP +Back up one place in the search history\&. If the search has been +repeated this does not immediately erase a character in the +minibuffer\&. +.TP +\fBaccept\-search\fP +Exit incremental search, retaining the command line but performing no +further action\&. Note that this function is not bound by default +and has no effect outside incremental search\&. +.TP +.PD 0 +\fBbackward\-delete\-word\fP +.TP +.PD 0 +\fBbackward\-kill\-word\fP +.TP +.PD +\fBvi\-backward\-kill\-word\fP +Back up one character in the minibuffer; if multiple searches +have been performed since the character was inserted the search +history is rewound to the point just before the character was +entered\&. Hence this has the effect of repeating +\fBbackward\-delete\-char\fP\&. +.TP +\fBclear\-screen\fP +Clear the screen, remaining in incremental search mode\&. +.TP +\fBhistory\-incremental\-search\-backward\fP +Find the next occurrence of the contents of the mini\-buffer\&. If the +mini\-buffer is empty, the most recent previously used search string is +reinstated\&. +.TP +\fBhistory\-incremental\-search\-forward\fP +Invert the sense of the search\&. +.TP +\fBmagic\-space\fP +Inserts a non\-magical space\&. +.TP +.PD 0 +\fBquoted\-insert\fP +.TP +.PD +\fBvi\-quoted\-insert\fP +Quote the character to insert into the minibuffer\&. +.TP +\fBredisplay\fP +Redisplay the command line, remaining in incremental search mode\&. +.TP +\fBvi\-cmd\-mode\fP +Select the `\fBvicmd\fP\&' keymap; +the `\fBmain\fP\&' keymap (insert mode) will be selected initially\&. +.RS +.PP +In addition, the modifications that were made while in vi insert mode are +merged to form a single undo event\&. +.RE +.TP +.PD 0 +\fBvi\-repeat\-search\fP +.TP +.PD +\fBvi\-rev\-repeat\-search\fP +Repeat the search\&. The direction of the search is indicated in the +mini\-buffer\&. +.PP +Any character that is not bound to one of the above functions, or +\fBself\-insert\fP or \fBself\-insert\-unmeta\fP, will cause the mode to be +exited\&. The character is then looked up and executed in the keymap in +effect at that point\&. +.PP +When called from a widget function by the \fBzle\fP command, the incremental +search commands can take a string argument\&. This will be treated as a +string of keys, as for arguments to the \fBbindkey\fP command, and used as +initial input for the command\&. Any characters in the string which are +unused by the incremental search will be silently ignored\&. For example, +.PP +.RS +.nf +\fBzle history\-incremental\-search\-backward forceps\fP +.fi +.RE +.PP +will search backwards for \fBforceps\fP, leaving the minibuffer containing +the string `\fBforceps\fP\&'\&. +.RE +.TP +\fBhistory\-incremental\-search\-forward\fP (\fB^S ^Xs\fP) (unbound) (unbound) +Search forward incrementally for a specified string\&. The search is +case\-insensitive if the search string does not have uppercase letters and no +numeric argument was given\&. The string may begin with `\fB^\fP\&' to anchor the +search to the beginning of the line\&. The functions available in the +mini\-buffer are the same as for \fBhistory\-incremental\-search\-backward\fP\&. +.TP +.PD 0 +\fBhistory\-incremental\-pattern\-search\-backward\fP +.TP +.PD +\fBhistory\-incremental\-pattern\-search\-forward\fP +These widgets behave similarly to the corresponding widgets with +no \fB\-pattern\fP, but the search string typed by the user is treated +as a pattern, respecting the current settings of the various options +affecting pattern matching\&. See +FILENAME GENERATION in \fIzshexpn\fP(1) for a description of patterns\&. +If no numeric argument was given lowercase letters in the search +string may match uppercase letters in the history\&. The string may begin +with `\fB^\fP\&' to anchor the search to the beginning of the line\&. +.RS +.PP +The prompt changes to indicate an invalid pattern; this may simply +indicate the pattern is not yet complete\&. +.PP +Note that only non\-overlapping matches are reported, so an expression +with wildcards may return fewer matches on a line than are visible +by inspection\&. +.RE +.TP +\fBhistory\-search\-backward\fP (\fBESC\-P ESC\-p\fP) (unbound) (unbound) +Search backward in the history for a line beginning with the first +word in the buffer\&. +.RS +.PP +If called from a function by the \fBzle\fP command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer\&. +.RE +.TP +\fBvi\-history\-search\-backward\fP (unbound) (\fB/\fP) (unbound) +Search backward in the history for a specified string\&. +The string may begin with `\fB^\fP\&' to anchor the search to the +beginning of the line\&. +.RS +.PP +A restricted set of editing functions is available in +the mini\-buffer\&. An interrupt signal, as defined by the stty setting, will +stop the search\&. +The functions available in the mini\-buffer are: +\fBaccept\-line\fP, +\fBbackward\-delete\-char\fP, +\fBvi\-backward\-delete\-char\fP, +\fBbackward\-kill\-word\fP, +\fBvi\-backward\-kill\-word\fP, +\fBclear\-screen\fP, +\fBredisplay\fP, +\fBquoted\-insert\fP +and +\fBvi\-quoted\-insert\fP\&. +.PP +\fBvi\-cmd\-mode\fP is treated the same as accept\-line, and +\fBmagic\-space\fP is treated as a space\&. +Any other character that is not bound to self\-insert or +self\-insert\-unmeta will beep and be ignored\&. If the function is called from vi +command mode, the bindings of the current insert mode will be used\&. +.PP +If called from a function by the \fBzle\fP command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer\&. +.RE +.TP +\fBhistory\-search\-forward\fP (\fBESC\-N ESC\-n\fP) (unbound) (unbound) +Search forward in the history for a line beginning with the first +word in the buffer\&. +.RS +.PP +If called from a function by the \fBzle\fP command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer\&. +.RE +.TP +\fBvi\-history\-search\-forward\fP (unbound) (\fB?\fP) (unbound) +Search forward in the history for a specified string\&. +The string may begin with `\fB^\fP\&' to anchor the search to the +beginning of the line\&. The functions available in the mini\-buffer are the same +as for \fBvi\-history\-search\-backward\fP\&. Argument handling is also the same +as for that command\&. +.TP +\fBinfer\-next\-history\fP (\fB^X^N\fP) (unbound) (unbound) +Search in the history list for a line matching the current one and +fetch the event following it\&. +.TP +\fBinsert\-last\-word\fP (\fBESC\-_ ESC\-\&.\fP) (unbound) (unbound) +Insert the last word from the previous history event at the +cursor position\&. If a positive numeric argument is given, +insert that word from the end of the previous history event\&. +If the argument is zero or negative insert that word from the +left (zero inserts the previous command word)\&. Repeating this command +replaces the word just inserted with the last word from the +history event prior to the one just used; numeric arguments can be used in +the same way to pick a word from that event\&. +.RS +.PP +When called from a shell function invoked from a user\-defined widget, the +command can take one to three arguments\&. The first argument specifies a +history offset which applies to successive calls to this widget: if it is \-1, +the default behaviour is used, while if it is 1, successive calls will move +forwards through the history\&. The value 0 can be used to indicate that the +history line examined by the previous execution of the command will be +reexamined\&. Note that negative numbers should be preceded by a +`\fB\-\fP\fB\-\fP\&' argument to avoid confusing them with options\&. +.PP +If two arguments are given, the second specifies the word on the command +line in normal array index notation (as a more natural alternative to the +numeric argument)\&. Hence 1 is the first word, and \-1 (the default) is the +last word\&. +.PP +If a third argument is given, its value is ignored, but it is used to +signify that the history offset is relative to the current history line, +rather than the one remembered after the previous invocations of +\fBinsert\-last\-word\fP\&. +.PP +For example, the default behaviour of the command corresponds to +.PP +.RS +.nf +\fBzle insert\-last\-word \-\- \-1 \-1\fP +.fi +.RE +.PP +while the command +.PP +.RS +.nf +\fBzle insert\-last\-word \-\- \-1 1 \-\fP +.fi +.RE +.PP +always copies the first word of the line in the history immediately before +the line being edited\&. This has the side effect that later invocations of +the widget will be relative to that line\&. +.RE +.TP +\fBvi\-repeat\-search\fP (unbound) (\fBn\fP) (unbound) +Repeat the last vi history search\&. +.TP +\fBvi\-rev\-repeat\-search\fP (unbound) (\fBN\fP) (unbound) +Repeat the last vi history search, but in reverse\&. +.TP +\fBup\-line\-or\-history\fP (\fB^P ESC\-[A\fP) (\fBk\fP) (\fBESC\-[A\fP) +Move up a line in the buffer, or if already at the top line, +move to the previous event in the history list\&. +.TP +\fBvi\-up\-line\-or\-history\fP (unbound) (\fB\-\fP) (unbound) +Move up a line in the buffer, or if already at the top line, +move to the previous event in the history list\&. +Then move to the first non\-blank character on the line\&. +.TP +\fBup\-line\-or\-search\fP +Move up a line in the buffer, or if already at the top line, +search backward in the history for a line beginning with the +first word in the buffer\&. +.RS +.PP +If called from a function by the \fBzle\fP command with arguments, the first +argument is taken as the string for which to search, rather than the +first word in the buffer\&. +.RE +.TP +\fBup\-history\fP (unbound) (\fB^P\fP) (unbound) +Move to the previous event in the history list\&. +.TP +\fBhistory\-beginning\-search\-forward\fP +Search forward in the history for a line beginning with the current +line up to the cursor\&. +This leaves the cursor in its original position\&. +.TP +\fBset\-local\-history\fP +By default, history movement commands visit the imported lines as well as +the local lines\&. This widget lets you toggle this on and off, or set it with +the numeric argument\&. Zero for both local and imported lines and nonzero for +only local lines\&. +.SS "Modifying Text" +.PD 0 +.TP +.PD +\fBvi\-add\-eol\fP (unbound) (\fBA\fP) (unbound) +Move to the end of the line and enter insert mode\&. +.TP +\fBvi\-add\-next\fP (unbound) (\fBa\fP) (unbound) +Enter insert mode after the current cursor position, without changing lines\&. +.TP +\fBbackward\-delete\-char\fP (\fB^H ^?\fP) (unbound) (unbound) +Delete the character behind the cursor\&. +.TP +\fBvi\-backward\-delete\-char\fP (unbound) (\fBX\fP) (\fB^H\fP) +Delete the character behind the cursor, without changing lines\&. +If in insert mode, this won\&'t delete past the point where insert mode was +last entered\&. +.TP +\fBbackward\-delete\-word\fP +Delete the word behind the cursor\&. +.TP +\fBbackward\-kill\-line\fP +Kill from the beginning of the line to the cursor position\&. +.TP +\fBbackward\-kill\-word\fP (\fB^W ESC\-^H ESC\-^?\fP) (unbound) (unbound) +Kill the word behind the cursor\&. +.TP +\fBvi\-backward\-kill\-word\fP (unbound) (unbound) (\fB^W\fP) +Kill the word behind the cursor, without going past the point where insert +mode was last entered\&. +.TP +\fBcapitalize\-word\fP (\fBESC\-C ESC\-c\fP) (unbound) (unbound) +Capitalize the current word and move past it\&. +.TP +\fBvi\-change\fP (unbound) (\fBc\fP) (unbound) +Read a movement command from the keyboard, and kill +from the cursor position to the endpoint of the movement\&. +Then enter insert mode\&. +If the command is \fBvi\-change\fP, change the current line\&. +.RS +.PP +For compatibility with vi, if the command is \fBvi\-forward\-word\fP +or \fBvi\-forward\-blank\-word\fP, the whitespace after the word is not +included\&. If you prefer the more consistent behaviour with the +whitespace included use the following key binding: +.PP +.RS +.nf +\fBbindkey \-a \-s cw dwi\fP +.fi +.RE +.RE +.TP +\fBvi\-change\-eol\fP (unbound) (\fBC\fP) (unbound) +Kill to the end of the line and enter insert mode\&. +.TP +\fBvi\-change\-whole\-line\fP (unbound) (\fBS\fP) (unbound) +Kill the current line and enter insert mode\&. +.TP +\fBcopy\-region\-as\-kill\fP (\fBESC\-W ESC\-w\fP) (unbound) (unbound) +Copy the area from the cursor to the mark to the kill buffer\&. +.RS +.PP +If called from a ZLE widget function in the form `\fBzle +copy\-region\-as\-kill\fP \fIstring\fP\&' then \fIstring\fP will be taken as the +text to copy to the kill buffer\&. The cursor, the mark and the text on the +command line are not used in this case\&. +.RE +.TP +\fBcopy\-prev\-word\fP (\fBESC\-^_\fP) (unbound) (unbound) +Duplicate the word to the left of the cursor\&. +.TP +\fBcopy\-prev\-shell\-word\fP +Like \fBcopy\-prev\-word\fP, but the word is found by using shell parsing, +whereas \fBcopy\-prev\-word\fP looks for blanks\&. This makes a difference +when the word is quoted and contains spaces\&. +.TP +\fBvi\-delete\fP (unbound) (\fBd\fP) (unbound) +Read a movement command from the keyboard, and kill +from the cursor position to the endpoint of the movement\&. +If the command is \fBvi\-delete\fP, kill the current line\&. +.TP +\fBdelete\-char\fP +Delete the character under the cursor\&. +.TP +\fBvi\-delete\-char\fP (unbound) (\fBx\fP) (unbound) +Delete the character under the cursor, +without going past the end of the line\&. +.TP +\fBdelete\-word\fP +Delete the current word\&. +.TP +\fBdown\-case\-word\fP (\fBESC\-L ESC\-l\fP) (unbound) (unbound) +Convert the current word to all lowercase and move past it\&. +.TP +\fBvi\-down\-case\fP (unbound) (\fBgu\fP) (unbound) +Read a movement command from the keyboard, and convert all characters +from the cursor position to the endpoint of the movement to lowercase\&. +If the movement command is \fBvi\-down\-case\fP, swap the case of all +characters on the current line\&. +.TP +\fBkill\-word\fP (\fBESC\-D ESC\-d\fP) (unbound) (unbound) +Kill the current word\&. +.TP +\fBgosmacs\-transpose\-chars\fP +Exchange the two characters behind the cursor\&. +.TP +\fBvi\-indent\fP (unbound) (\fB>\fP) (unbound) +Indent a number of lines\&. +.TP +\fBvi\-insert\fP (unbound) (\fBi\fP) (unbound) +Enter insert mode\&. +.TP +\fBvi\-insert\-bol\fP (unbound) (\fBI\fP) (unbound) +Move to the first non\-blank character on the line and enter insert mode\&. +.TP +\fBvi\-join\fP (\fB^X^J\fP) (\fBJ\fP) (unbound) +Join the current line with the next one\&. +.TP +\fBkill\-line\fP (\fB^K\fP) (unbound) (unbound) +Kill from the cursor to the end of the line\&. +If already on the end of the line, kill the newline character\&. +.TP +\fBvi\-kill\-line\fP (unbound) (unbound) (\fB^U\fP) +Kill from the cursor back to wherever insert mode was last entered\&. +.TP +\fBvi\-kill\-eol\fP (unbound) (\fBD\fP) (unbound) +Kill from the cursor to the end of the line\&. +.TP +\fBkill\-region\fP +Kill from the cursor to the mark\&. +.TP +\fBkill\-buffer\fP (\fB^X^K\fP) (unbound) (unbound) +Kill the entire buffer\&. +.TP +\fBkill\-whole\-line\fP (\fB^U\fP) (unbound) (unbound) +Kill the current line\&. +.TP +\fBvi\-match\-bracket\fP (\fB^X^B\fP) (\fB%\fP) (unbound) +Move to the bracket character (one of \fB{}\fP, \fB()\fP or \fB[]\fP) that +matches the one under the cursor\&. +If the cursor is not on a bracket character, move forward without going +past the end of the line to find one, and then go to the matching bracket\&. +.TP +\fBvi\-open\-line\-above\fP (unbound) (\fBO\fP) (unbound) +Open a line above the cursor and enter insert mode\&. +.TP +\fBvi\-open\-line\-below\fP (unbound) (\fBo\fP) (unbound) +Open a line below the cursor and enter insert mode\&. +.TP +\fBvi\-oper\-swap\-case\fP (unbound) (\fBg~\fP) (unbound) +Read a movement command from the keyboard, and swap +the case of all characters +from the cursor position to the endpoint of the movement\&. +If the movement command is \fBvi\-oper\-swap\-case\fP, +swap the case of all characters on the current line\&. +.TP +\fBoverwrite\-mode\fP (\fB^X^O\fP) (unbound) (unbound) +Toggle between overwrite mode and insert mode\&. +.TP +\fBvi\-put\-before\fP (unbound) (\fBP\fP) (unbound) +Insert the contents of the kill buffer before the cursor\&. +If the kill buffer contains a sequence of lines (as opposed to characters), +paste it above the current line\&. +.TP +\fBvi\-put\-after\fP (unbound) (\fBp\fP) (unbound) +Insert the contents of the kill buffer after the cursor\&. +If the kill buffer contains a sequence of lines (as opposed to characters), +paste it below the current line\&. +.TP +\fBput\-replace\-selection\fP (unbound) (unbound) (unbound) +Replace the contents of the current region or selection with the +contents of the kill buffer\&. If the kill buffer contains a sequence of +lines (as opposed to characters), the current line will be split by the +pasted lines\&. +.TP +\fBquoted\-insert\fP (\fB^V\fP) (unbound) (unbound) +Insert the next character typed into the buffer literally\&. +An interrupt character will not be inserted\&. +.TP +\fBvi\-quoted\-insert\fP (unbound) (unbound) (\fB^Q ^V\fP) +Display a `\fB^\fP\&' at the cursor position, and +insert the next character typed into the buffer literally\&. +An interrupt character will not be inserted\&. +.TP +\fBquote\-line\fP (\fBESC\-\&'\fP) (unbound) (unbound) +Quote the current line; that is, put a `\fB\&'\fP' character at the +beginning and the end, and convert all `\fB\&'\fP' characters +to `\fB\&'\e''\fP'\&. +.TP +\fBquote\-region\fP (\fBESC\-"\fP) (unbound) (unbound) +Quote the region from the cursor to the mark\&. +.TP +\fBvi\-replace\fP (unbound) (\fBR\fP) (unbound) +Enter overwrite mode\&. +.TP +\fBvi\-repeat\-change\fP (unbound) (\fB\&.\fP) (unbound) +Repeat the last vi mode text modification\&. +If a count was used with the modification, it is remembered\&. +If a count is given to this command, it overrides the remembered count, +and is remembered for future uses of this command\&. +The cut buffer specification is similarly remembered\&. +.TP +\fBvi\-replace\-chars\fP (unbound) (\fBr\fP) (unbound) +Replace the character under the cursor with a character +read from the keyboard\&. +.TP +\fBself\-insert\fP (printable characters) (unbound) (printable characters and some control characters) +Insert a character into the buffer at the cursor position\&. +.TP +\fBself\-insert\-unmeta\fP (\fBESC\-^I ESC\-^J ESC\-^M\fP) (unbound) (unbound) +Insert a character into the buffer after stripping the meta bit +and converting ^M to ^J\&. +.TP +\fBvi\-substitute\fP (unbound) (\fBs\fP) (unbound) +Substitute the next character(s)\&. +.TP +\fBvi\-swap\-case\fP (unbound) (\fB~\fP) (unbound) +Swap the case of the character under the cursor and move past it\&. +.TP +\fBtranspose\-chars\fP (\fB^T\fP) (unbound) (unbound) +Exchange the two characters to the left of the +cursor if at end of line, else exchange the +character under the cursor with the character +to the left\&. +.TP +\fBtranspose\-words\fP (\fBESC\-T ESC\-t\fP) (unbound) (unbound) +Exchange the current word with the one before it\&. +.RS +.PP +With a positive numeric argument \fIN\fP, the word around the cursor, or +following it if the cursor is between words, is transposed with the +preceding \fIN\fP words\&. The cursor is put at the end of the resulting +group of words\&. +.PP +With a negative numeric argument \fI\-N\fP, the effect is the same as using +a positive argument \fIN\fP except that the original cursor position is +retained, regardless of how the words are rearranged\&. +.RE +.TP +\fBvi\-unindent\fP (unbound) (\fB<\fP) (unbound) +Unindent a number of lines\&. +.TP +\fBvi\-up\-case\fP (unbound) (\fBgU\fP) (unbound) +Read a movement command from the keyboard, and convert all characters +from the cursor position to the endpoint of the movement to lowercase\&. +If the movement command is \fBvi\-up\-case\fP, swap the case of all +characters on the current line\&. +.TP +\fBup\-case\-word\fP (\fBESC\-U ESC\-u\fP) (unbound) (unbound) +Convert the current word to all caps and move past it\&. +.TP +\fByank\fP (\fB^Y\fP) (unbound) (unbound) +Insert the contents of the kill buffer at the cursor position\&. +.TP +\fByank\-pop\fP (\fBESC\-y\fP) (unbound) (unbound) +Remove the text just yanked, rotate the kill\-ring (the history of +previously killed text) and yank the new top\&. Only works following +\fByank\fP, \fBvi\-put\-before\fP, \fBvi\-put\-after\fP or \fByank\-pop\fP\&. +.TP +\fBvi\-yank\fP (unbound) (\fBy\fP) (unbound) +Read a movement command from the keyboard, and copy the region +from the cursor position to the endpoint of the movement +into the kill buffer\&. +If the command is \fBvi\-yank\fP, copy the current line\&. +.TP +\fBvi\-yank\-whole\-line\fP (unbound) (\fBY\fP) (unbound) +Copy the current line into the kill buffer\&. +.TP +\fBvi\-yank\-eol\fP +Copy the region from the cursor position to the end of the line +into the kill buffer\&. +Arguably, this is what Y should do in vi, but it isn\&'t what it actually does\&. +.SS "Arguments" +.PD 0 +.TP +.PD +\fBdigit\-argument\fP (\fBESC\-0\fP\&.\&.\fBESC\-9\fP) (\fB1\fP\-\fB9\fP) (unbound) +Start a new numeric argument, or add to the current one\&. +See also \fBvi\-digit\-or\-beginning\-of\-line\fP\&. This only works if bound to a +key sequence ending in a decimal digit\&. +.RS +.PP +Inside a widget function, a call to this function treats the last key of +the key sequence which called the widget as the digit\&. +.RE +.TP +\fBneg\-argument\fP (\fBESC\-\fP\fB\-\fP) (unbound) (unbound) +Changes the sign of the following argument\&. +.TP +\fBuniversal\-argument\fP +Multiply the argument of the next command by 4\&. Alternatively, if +this command is followed by an integer (positive or negative), use +that as the argument for the next command\&. Thus digits cannot be +repeated using this command\&. For example, if this command occurs +twice, followed immediately by \fBforward\-char\fP, move forward sixteen +spaces; if instead it is followed by \fB\-2\fP, then \fBforward\-char\fP, +move backward two spaces\&. +.RS +.PP +Inside a widget function, if passed an argument, i\&.e\&. `\fBzle +universal\-argument\fP \fInum\fP\&', the numeric argument will be set to +\fInum\fP; this is equivalent to `\fBNUMERIC=\fP\fInum\fP\&'\&. +.RE +.TP +\fBargument\-base\fP +Use the existing numeric argument as a numeric base, which must be in the +range 2 to 36 inclusive\&. Subsequent use of \fBdigit\-argument\fP and +\fBuniversal\-argument\fP will input a new numeric argument in the given base\&. +The usual hexadecimal convention is used: the letter \fBa\fP or \fBA\fP +corresponds to 10, and so on\&. Arguments in bases requiring digits from 10 +upwards are more conveniently input with \fBuniversal\-argument\fP, since +\fBESC\-a\fP etc\&. are not usually bound to \fBdigit\-argument\fP\&. +.RS +.PP +The function can be used with a command argument inside a user\-defined +widget\&. The following code sets the base to 16 and lets the user input a +hexadecimal argument until a key out of the digit range is typed: +.PP +.RS +.nf +\fBzle argument\-base 16 +zle universal\-argument\fP +.fi +.RE +.RE +.SS "Completion" +.PD 0 +.TP +.PD +\fBaccept\-and\-menu\-complete\fP +In a menu completion, insert the current completion into the buffer, +and advance to the next possible completion\&. +.TP +\fBcomplete\-word\fP +Attempt completion on the current word\&. +.TP +\fBdelete\-char\-or\-list\fP (\fB^D\fP) (unbound) (unbound) +Delete the character under the cursor\&. If the cursor +is at the end of the line, list possible completions for the +current word\&. +.TP +\fBexpand\-cmd\-path\fP +Expand the current command to its full pathname\&. +.TP +\fBexpand\-or\-complete\fP (\fBTAB\fP) (unbound) (\fBTAB\fP) +Attempt shell expansion on the current word\&. +If that fails, +attempt completion\&. +.TP +\fBexpand\-or\-complete\-prefix\fP +Attempt shell expansion on the current word up to cursor\&. +.TP +\fBexpand\-history\fP (\fBESC\-space ESC\-!\fP) (unbound) (unbound) +Perform history expansion on the edit buffer\&. +.TP +\fBexpand\-word\fP (\fB^X*\fP) (unbound) (unbound) +Attempt shell expansion on the current word\&. +.TP +\fBlist\-choices\fP (\fBESC\-^D\fP) (\fB^D =\fP) (\fB^D\fP) +List possible completions for the current word\&. +.TP +\fBlist\-expand\fP (\fB^Xg ^XG\fP) (\fB^G\fP) (\fB^G\fP) +List the expansion of the current word\&. +.TP +\fBmagic\-space\fP +Perform history expansion and insert a space into the +buffer\&. This is intended to be bound to space\&. +.TP +\fBmenu\-complete\fP +Like \fBcomplete\-word\fP, except that menu completion is used\&. +See the \fBMENU_COMPLETE\fP option\&. +.TP +\fBmenu\-expand\-or\-complete\fP +Like \fBexpand\-or\-complete\fP, except that menu completion is used\&. +.TP +\fBreverse\-menu\-complete\fP +Perform menu completion, like \fBmenu\-complete\fP, except that if +a menu completion is already in progress, move to the \fIprevious\fP +completion rather than the next\&. +.TP +\fBend\-of\-list\fP +When a previous completion displayed a list below the prompt, this +widget can be used to move the prompt below the list\&. +.SS "Miscellaneous" +.PD 0 +.TP +.PD +\fBaccept\-and\-hold\fP (\fBESC\-A ESC\-a\fP) (unbound) (unbound) +Push the contents of the buffer on the buffer stack +and execute it\&. +.TP +\fBaccept\-and\-infer\-next\-history\fP +Execute the contents of the buffer\&. +Then search the history list for a line matching the current one +and push the event following onto the buffer stack\&. +.TP +\fBaccept\-line\fP (\fB^J ^M\fP) (\fB^J ^M\fP) (\fB^J ^M\fP) +Finish editing the buffer\&. Normally this causes the buffer to be +executed as a shell command\&. +.TP +\fBaccept\-line\-and\-down\-history\fP (\fB^O\fP) (unbound) (unbound) +Execute the current line, and push the next history +event on the buffer stack\&. +.TP +\fBauto\-suffix\-remove\fP +If the previous action added a suffix (space, slash, etc\&.) to the word on +the command line, remove it\&. Otherwise do nothing\&. Removing the suffix +ends any active menu completion or menu selection\&. +.RS +.PP +This widget is intended to be called from user\-defined widgets to enforce +a desired suffix\-removal behavior\&. +.RE +.TP +\fBauto\-suffix\-retain\fP +If the previous action added a suffix (space, slash, etc\&.) to the word on +the command line, force it to be preserved\&. Otherwise do nothing\&. +Retaining the suffix ends any active menu completion or menu selection\&. +.RS +.PP +This widget is intended to be called from user\-defined widgets to enforce +a desired suffix\-preservation behavior\&. +.RE +.TP +\fBbeep\fP +Beep, unless the \fBBEEP\fP option is unset\&. +.TP +\fBbracketed\-paste\fP (\fB^[[200~\fP) (\fB^[[200~\fP) (\fB^[[200~\fP) +This widget is invoked when text is pasted to the terminal emulator\&. It +is not intended to be bound to actual keys but instead to the special +sequence generated by the terminal emulator when text is pasted\&. +.RS +.PP +When invoked interactively, the pasted text is inserted to the buffer +and placed in the cutbuffer\&. +If a numeric argument is given, shell quoting will be applied to the +pasted text before it is inserted\&. +.PP +When a named buffer is specified with \fBvi\-set\-buffer\fP (\fB"x\fP), +the pasted text is stored in that named buffer but not inserted\&. +.PP +When called from a widget function as `\fBbracketed\-paste\fP \fIname\fP`, the +pasted text is assigned to the variable \fIname\fP and no other processing is +done\&. +.PP +See also the \fBzle_bracketed_paste\fP parameter\&. +.RE +.TP +\fBvi\-cmd\-mode\fP (\fB^X^V\fP) (unbound) (\fB^[\fP) +Enter command mode; that is, select the `\fBvicmd\fP\&' keymap\&. +Yes, this is bound by default in emacs mode\&. +.TP +\fBvi\-caps\-lock\-panic\fP +Hang until any lowercase key is pressed\&. +This is for vi users without the mental capacity to keep +track of their caps lock key (like the author)\&. +.TP +\fBclear\-screen\fP (\fB^L ESC\-^L\fP) (\fB^L\fP) (\fB^L\fP) +Clear the screen and redraw the prompt\&. +.TP +\fBdeactivate\-region\fP +Make the current region inactive\&. This disables vim\-style visual +selection mode if it is active\&. +.TP +\fBdescribe\-key\-briefly\fP +Reads a key sequence, then prints the function bound to that sequence\&. +.TP +\fBexchange\-point\-and\-mark\fP (\fB^X^X\fP) (unbound) (unbound) +Exchange the cursor position (point) with the position of the mark\&. +Unless a negative numeric argument is given, the region between +point and mark is activated so that it can be highlighted\&. +If a zero numeric argument is given, the region is activated but +point and mark are not swapped\&. +.TP +\fBexecute\-named\-cmd\fP (\fBESC\-x\fP) (\fB:\fP) (unbound) +Read the name of an editor command and execute it\&. Aliasing this +widget with `\fBzle \-A\fP\&' or replacing it with `\fBzle \-N\fP' has no +effect when interpreting key bindings, but `\fBzle execute\-named\-cmd\fP\&' +will invoke such an alias or replacement\&. +.RS +.PP +A restricted set of editing functions is available in the +mini\-buffer\&. Keys are looked up in the special +\fBcommand\fP keymap, and if not found there in the main keymap\&. +An interrupt signal, as defined by the stty setting, will +abort the function\&. Note that the following always +perform the same task within the \fBexecuted\-named\-cmd\fP environment and +cannot be replaced by user defined widgets, nor can the set of functions +be extended\&. The allowed functions are: +\fBbackward\-delete\-char\fP, +\fBvi\-backward\-delete\-char\fP, +\fBclear\-screen\fP, +\fBredisplay\fP, +\fBquoted\-insert\fP, +\fBvi\-quoted\-insert\fP, +\fBbackward\-kill\-word\fP, +\fBvi\-backward\-kill\-word\fP, +\fBkill\-whole\-line\fP, +\fBvi\-kill\-line\fP, +\fBbackward\-kill\-line\fP, +\fBlist\-choices\fP, +\fBdelete\-char\-or\-list\fP, +\fBcomplete\-word\fP, +\fBaccept\-line\fP, +\fBexpand\-or\-complete\fP and +\fBexpand\-or\-complete\-prefix\fP\&. +.PP +\fBkill\-region\fP kills the last word, +and vi\-cmd\-mode is treated the same as accept\-line\&. +The space and tab characters, if not bound to one of +these functions, will complete the name and then list the +possibilities if the \fBAUTO_LIST\fP option is set\&. +Any other character that is not bound to \fBself\-insert\fP or +\fBself\-insert\-unmeta\fP will beep and be ignored\&. +The bindings of the current insert mode will be used\&. +.PP +Currently this command may not be redefined or called by name\&. +.RE +.TP +\fBexecute\-last\-named\-cmd\fP (\fBESC\-z\fP) (unbound) (unbound) +Redo the last function executed with \fBexecute\-named\-cmd\fP\&. +.RS +.PP +Like \fBexecute\-named\-cmd\fP, this command may not be redefined, +but it may be called by name\&. +.RE +.TP +\fBget\-line\fP (\fBESC\-G ESC\-g\fP) (unbound) (unbound) +Pop the top line off the buffer stack and insert it at the +cursor position\&. +.TP +\fBpound\-insert\fP (unbound) (\fB#\fP) (unbound) +If there is no # character at the beginning of the buffer, +add one to the beginning of each line\&. +If there is one, remove a # from each line that has one\&. +In either case, accept the current line\&. +The \fBINTERACTIVE_COMMENTS\fP option must be set +for this to have any usefulness\&. +.TP +\fBvi\-pound\-insert\fP +If there is no # character at the beginning of the current line, +add one\&. If there is one, remove it\&. +The \fBINTERACTIVE_COMMENTS\fP option must be set +for this to have any usefulness\&. +.TP +\fBpush\-input\fP +Push the entire current multiline construct onto the buffer stack and +return to the top\-level (\fBPS1\fP) prompt\&. +If the current parser construct is only a single line, this is exactly +like \fBpush\-line\fP\&. +Next time the editor starts up or is popped with \fBget\-line\fP, the +construct will be popped off the top of the buffer stack and loaded +into the editing buffer\&. +.TP +\fBpush\-line\fP (\fB^Q ESC\-Q ESC\-q\fP) (unbound) (unbound) +Push the current buffer onto the buffer stack and clear +the buffer\&. +Next time the editor starts up, the buffer will be popped +off the top of the buffer stack and loaded into the editing +buffer\&. +.TP +\fBpush\-line\-or\-edit\fP +At the top\-level (\fBPS1\fP) prompt, equivalent to \fBpush\-line\fP\&. +At a secondary (\fBPS2\fP) prompt, move the entire current multiline +construct into the editor buffer\&. +The latter is equivalent to \fBpush\-input\fP followed by \fBget\-line\fP\&. +.TP +\fBread\-command\fP +Only useful from a user\-defined widget\&. A keystroke is read just as in +normal operation, but instead of the command being executed the name +of the command that would be executed is stored in the shell parameter +\fBREPLY\fP\&. This can be used as the argument of a future \fBzle\fP +command\&. If the key sequence is not bound, status 1 is returned; +typically, however, \fBREPLY\fP is set to \fBundefined\-key\fP to indicate +a useless key sequence\&. +.TP +\fBrecursive\-edit\fP +Only useful from a user\-defined widget\&. At this point in the function, +the editor regains control until one of the standard widgets which would +normally cause zle to exit (typically an \fBaccept\-line\fP caused by +hitting the return key) is executed\&. Instead, control returns to the +user\-defined widget\&. The status returned is non\-zero if the return was +caused by an error, but the function still continues executing and hence +may tidy up\&. This makes it safe for the user\-defined widget to alter +the command line or key bindings temporarily\&. +.RS +.PP +The following widget, \fBcaps\-lock\fP, serves as an example\&. +.PP +.RS +.nf +\fBself\-insert\-ucase() { + LBUFFER+=${(U)KEYS[\-1]} +} + +integer stat + +zle \-N self\-insert self\-insert\-ucase +zle \-A caps\-lock save\-caps\-lock +zle \-A accept\-line caps\-lock + +zle recursive\-edit +stat=$? + +zle \-A \&.self\-insert self\-insert +zle \-A save\-caps\-lock caps\-lock +zle \-D save\-caps\-lock + +(( stat )) && zle send\-break + +return $stat\fP +.fi +.RE +.PP +This causes typed letters to be inserted capitalised until either +\fBaccept\-line\fP (i\&.e\&. typically the return key) is typed or the +\fBcaps\-lock\fP widget is invoked again; the later is handled by saving +the old definition of \fBcaps\-lock\fP as \fBsave\-caps\-lock\fP and then +rebinding it to invoke \fBaccept\-line\fP\&. Note that an error from the +recursive edit is detected as a non\-zero return status and propagated by +using the \fBsend\-break\fP widget\&. +.RE +.TP +\fBredisplay\fP (unbound) (\fB^R\fP) (\fB^R\fP) +Redisplays the edit buffer\&. +.TP +\fBreset\-prompt\fP (unbound) (unbound) (unbound) +Force the prompts on both the left and right of the screen to be +re\-expanded, then redisplay the edit buffer\&. This +reflects changes both to the prompt variables themselves and changes +in the expansion of the values (for example, changes in time or +directory, or changes to the value of variables referred to by the +prompt)\&. +.RS +.PP +Otherwise, the prompt is only expanded each time zle starts, and +when the display has been interrupted by output from another part of the +shell (such as a job notification) which causes the command line to be +reprinted\&. +.PP +\fBreset\-prompt\fP doesn\&'t alter the special parameter \fBLASTWIDGET\fP\&. +.PP +.RE +.TP +\fBsend\-break\fP (\fB^G ESC\-^G\fP) (unbound) (unbound) +Abort the current editor function, e\&.g\&. \fBexecute\-named\-command\fP, or the +editor itself, e\&.g\&. if you are in \fBvared\fP\&. Otherwise abort the parsing of +the current line; in this case the aborted line is available in the shell +variable \fBZLE_LINE_ABORTED\fP\&. If the editor is aborted from within +\fBvared\fP, the variable \fBZLE_VARED_ABORTED\fP is set\&. +.TP +\fBrun\-help\fP (\fBESC\-H ESC\-h\fP) (unbound) (unbound) +Push the buffer onto the buffer stack, and execute the +command `\fBrun\-help\fP \fIcmd\fP\&', where \fIcmd\fP is the current +command\&. \fBrun\-help\fP is normally aliased to \fBman\fP\&. +.TP +\fBvi\-set\-buffer\fP (unbound) (\fB"\fP) (unbound) +Specify a buffer to be used in the following command\&. +There are 37 buffers that can be specified: +the 26 `named\&' buffers \fB"a\fP to \fB"z\fP, the `yank' buffer \fB"0\fP, +the nine `queued\&' buffers \fB"1\fP to \fB"9\fP and the `black hole' buffer +\fB"_\fP\&. The named buffers can also be specified as \fB"A\fP to \fB"Z\fP\&. +.RS +.PP +When a buffer is specified for a cut, change or yank command, the text +concerned replaces the previous contents of the specified buffer\&. If +a named buffer is specified using a capital, the newly cut text is +appended to the buffer instead of overwriting it\&. When using the \fB"_\fP +buffer, nothing happens\&. This can be useful for deleting text without +affecting any buffers\&. +.PP +If no buffer is specified for a cut or change command, \fB"1\fP is used, and +the contents of \fB"1\fP to \fB"8\fP are each shifted along one buffer; +the contents of \fB"9\fP is lost\&. If no buffer is specified for a yank +command, \fB"0\fP is used\&. Finally, a paste command without a specified +buffer will paste the text from the most recent command regardless of any +buffer that might have been used with that command\&. +.PP +When called from a widget function by the \fBzle\fP command, the buffer +can optionally be specified with an argument\&. For example, +.PP +.RS +.nf +\fBzle vi\-set\-buffer A\fP +.fi +.RE +.RE +.TP +\fBvi\-set\-mark\fP (unbound) (\fBm\fP) (unbound) +Set the specified mark at the cursor position\&. +.TP +\fBset\-mark\-command\fP (\fB^@\fP) (unbound) (unbound) +Set the mark at the cursor position\&. If called with a negative +numeric argument, do not set the mark but deactivate the region so that +it is no longer highlighted (it is still usable for other purposes)\&. +Otherwise the region is marked as active\&. +.TP +\fBspell\-word\fP (\fBESC\-$ ESC\-S ESC\-s\fP) (unbound) (unbound) +Attempt spelling correction on the current word\&. +.TP +\fBsplit\-undo\fP +Breaks the undo sequence at the current change\&. This is useful in vi mode as +changes made in insert mode are coalesced on entering command mode\&. Similarly, +\fBundo\fP will normally revert as one all the changes made by a user\-defined +widget\&. +.TP +\fBundefined\-key\fP +This command is executed when a key sequence that is not bound to any +command is typed\&. By default it beeps\&. +.TP +\fBundo\fP (\fB^_ ^Xu ^X^U\fP) (\fBu\fP) (unbound) +Incrementally undo the last text modification\&. When called from a +user\-defined widget, takes an optional argument indicating a previous state +of the undo history as returned by the \fBUNDO_CHANGE_NO\fP variable; +modifications are undone until that state is reached, subject to +any limit imposed by the \fBUNDO_LIMIT_NO\fP variable\&. +.RS +.PP +Note that when invoked from vi command mode, the full prior change made in +insert mode is reverted, the changes having been merged when command mode was +selected\&. +.RE +.TP +\fBredo\fP (unbound) (\fB^R\fP) (unbound) +Incrementally redo undone text modifications\&. +.TP +\fBvi\-undo\-change\fP (unbound) (unbound) (unbound) +Undo the last text modification\&. +If repeated, redo the modification\&. +.TP +\fBvisual\-mode\fP (unbound) (\fBv\fP) (unbound) +Toggle vim\-style visual selection mode\&. If line\-wise visual mode is +currently enabled then it is changed to being character\-wise\&. If used +following an operator, it forces the subsequent movement command to be +treated as a character\-wise movement\&. +.TP +\fBvisual\-line\-mode\fP (unbound) (\fBV\fP) (unbound) +Toggle vim\-style line\-wise visual selection mode\&. If character\-wise +visual mode is currently enabled then it is changed to being line\-wise\&. If used +following an operator, it forces the subsequent movement command to be +treated as a line\-wise movement\&. +.TP +\fBwhat\-cursor\-position\fP (\fB^X=\fP) (\fBga\fP) (unbound) +Print the character under the cursor, its code as an octal, decimal and +hexadecimal number, the current cursor position within the buffer and the +column of the cursor in the current line\&. +.TP +\fBwhere\-is\fP +Read the name of an editor command and print the listing of key +sequences that invoke the specified command\&. +A restricted set of editing functions is available in the +mini\-buffer\&. Keys are looked up in the special +\fBcommand\fP keymap, and if not found there in the main keymap\&. +.TP +\fBwhich\-command\fP (\fBESC\-?\fP) (unbound) (unbound) +Push the buffer onto the buffer stack, and execute the +command `\fBwhich\-command\fP \fIcmd\fP\&'\&. where \fIcmd\fP is the current +command\&. \fBwhich\-command\fP is normally aliased to \fBwhence\fP\&. +.TP +\fBvi\-digit\-or\-beginning\-of\-line\fP (unbound) (\fB0\fP) (unbound) +If the last command executed was a digit as part of an argument, +continue the argument\&. Otherwise, execute vi\-beginning\-of\-line\&. +.SS "Text Objects" +Text objects are commands that can be used to select a block of text +according to some criteria\&. They are a feature of the vim text editor +and so are primarily intended for use with vi operators or from visual +selection mode\&. However, they can also be used from vi\-insert or emacs +mode\&. Key bindings listed below apply to the \fBviopp\fP and \fBvisual\fP +keymaps\&. +.PP +.PD 0 +.TP +.PD +\fBselect\-a\-blank\-word\fP (\fBaW\fP) +Select a word including adjacent blanks, where a word is defined as a +series of non\-blank characters\&. With a numeric argument, multiple words +will be selected\&. +.TP +\fBselect\-a\-shell\-word\fP (\fBaa\fP) +Select the current command argument applying the normal rules for +quoting\&. +.TP +\fBselect\-a\-word\fP (\fBaw\fP) +Select a word including adjacent blanks, using the normal vi\-style word +definition\&. With a numeric argument, multiple words will be selected\&. +.TP +\fBselect\-in\-blank\-word\fP (\fBiW\fP) +Select a word, where a word is defined as a series of non\-blank +characters\&. With a numeric argument, multiple words will be selected\&. +.TP +\fBselect\-in\-shell\-word\fP (\fBia\fP) +Select the current command argument applying the normal rules for +quoting\&. If the argument begins and ends with matching quote characters, +these are not included in the selection\&. +.TP +\fBselect\-in\-word\fP (\fBiw\fP) +Select a word, using the normal vi\-style word definition\&. With a numeric +argument, multiple words will be selected\&. +.PP +.SH "CHARACTER HIGHLIGHTING" +.PP +The line editor has the ability to highlight characters or regions +of the line that have a particular significance\&. This is controlled +by the array parameter \fBzle_highlight\fP, if it has been set by the user\&. +.PP +If the parameter contains the single entry \fBnone\fP all highlighting +is turned off\&. Note the parameter is still expected to be an array\&. +.PP +Otherwise each entry of the array should consist of a word indicating a +context for highlighting, then a colon, then a comma\-separated list of +the types of highlighting to apply in that context\&. +.PP +The contexts available for highlighting are the following: +.PP +.PD 0 +.TP +.PD +\fBdefault\fP +Any text within the command line not affected by any other highlighting\&. +Text outside the editable area of the command line is not affected\&. +.TP +\fBisearch\fP +When one of the incremental history search widgets is active, the +area of the command line matched by the search string or pattern\&. +.TP +\fBregion\fP +The currently selected text\&. In emacs terminology, this is referred to as +the region and is bounded by the cursor (point) and the mark\&. The region +is only highlighted if it is active, which is the case after the mark +is modified with \fBset\-mark\-command\fP or \fBexchange\-point\-and\-mark\fP\&. +Note that whether or not the region is active has no effect on its +use within emacs style widgets, it simply determines whether it is +highlighted\&. In vi mode, the region corresponds to selected text in +visual mode\&. +.TP +\fBspecial\fP +Individual characters that have no direct printable +representation but are shown in a special manner by the line editor\&. +These characters are described below\&. +.TP +\fBsuffix\fP +This context is used in completion for characters that are +marked as suffixes that will be removed if the completion ends +at that point, the most obvious example being a slash (\fB/\fP) after +a directory name\&. Note that suffix removal is configurable; the +circumstances under which the suffix will be removed may differ +for different completions\&. +.TP +\fBpaste\fP +Following a command to paste text, the characters that were inserted\&. +.PP +When \fBregion_highlight\fP is set, the contexts that describe a region \-\- +\fBisearch\fP, \fBregion\fP, \fBsuffix\fP, and \fBpaste\fP \-\- +are applied first, then \fBregion_highlight\fP is applied, then the remaining +\fBzle_highlight\fP contexts are applied\&. If a particular character is +affected by multiple specifications, the last specification wins\&. +.PP +\fBzle_highlight\fP may contain additional fields for controlling how +terminal sequences to change colours are output\&. Each of the following is +followed by a colon and a string in the same form as for key bindings\&. +This will not be necessary for the vast majority of terminals as the +defaults shown in parentheses are widely used\&. +.PP +.PD 0 +.TP +.PD +\fBfg_start_code\fP (\fB\ee[3\fP) +The start of the escape sequence for the foreground colour\&. +This is followed by one to three ASCII digits representing the colour\&. +Only used for palette colors, i\&.e\&. not 24\-bit colors specified via a +color triplet\&. +.TP +\fBfg_default_code\fP (\fB9\fP) +The number to use instead of the colour to reset the default foreground +colour\&. +.TP +\fBfg_end_code\fP (\fBm\fP) +The end of the escape sequence for the foreground colour\&. +.TP +\fBbg_start_code\fP (\fB\ee[4\fP) +The start of the escape sequence for the background colour\&. +See \fBfg_start_code\fP above\&. +.TP +\fBbg_default_code\fP (\fB9\fP) +The number to use instead of the colour to reset the default +background colour\&. +.TP +\fBbg_end_code\fP (\fBm\fP) +The end of the escape sequence for the background colour\&. +.PP +The available types of highlighting are the following\&. Note that +not all types of highlighting are available on all terminals: +.PP +.PD 0 +.TP +.PD +\fBnone\fP +No highlighting is applied to the given context\&. It is not useful for +this to appear with other types of highlighting; it is used to override +a default\&. +.TP +\fBfg=\fP\fIcolour\fP +The foreground colour should be set to \fIcolour\fP, a decimal integer, +the name of one of the eight most widely\-supported colours or as a +`\fB#\fP\&' followed by an RGB triplet in hexadecimal format\&. +.RS +.PP +Not all terminals support this and, of those that do, not all provide +facilities to test the support, hence the user should decide based on the +terminal type\&. Most terminals support the colours \fBblack\fP, \fBred\fP, +\fBgreen\fP, \fByellow\fP, \fBblue\fP, \fBmagenta\fP, \fBcyan\fP and \fBwhite\fP, +which can be set by name\&. In addition\&. \fBdefault\fP may be used to +set the terminal\&'s default foreground colour\&. Abbreviations are allowed; +\fBb\fP or \fBbl\fP selects black\&. Some terminals may generate additional +colours if the \fBbold\fP attribute is also present\&. +.PP +On recent terminals and on systems with an up\-to\-date terminal database the +number of colours supported may be tested by the command `\fBechotc +Co\fP\&'; if this succeeds, it indicates a limit on the number of colours which +will be enforced by the line editor\&. The number of colours is in any case +limited to 256 (i\&.e\&. the range 0 to 255)\&. +.PP +Some modern terminal emulators have support for 24\-bit true colour (16 +million colours)\&. In this case, the hex triplet format can be used\&. This +consists of a `\fB#\fP\&' followed by either a three or six digit hexadecimal +number describing the red, green and blue components of the colour\&. Hex +triplets can also be used with 88 and 256 colour terminals via the +\fBzsh/nearcolor\fP module (see \fIzshmodules\fP(1))\&. +.PP +Colour is also known as color\&. +.RE +.TP +\fBbg=\fP\fIcolour\fP +The background colour should be set to \fIcolour\fP\&. +This works similarly to the foreground colour, except the background is +not usually affected by the bold attribute\&. +.TP +\fBbold\fP +The characters in the given context are shown in a bold font\&. +Not all terminals distinguish bold fonts\&. +.TP +\fBstandout\fP +The characters in the given context are shown in the terminal\&'s standout +mode\&. The actual effect is specific to the terminal; on many terminals it +is inverse video\&. On some such terminals, where the cursor does not blink +it appears with standout mode negated, making it less than clear where +the cursor actually is\&. On such terminals one of the other effects +may be preferable for highlighting the region and matched search string\&. +.TP +\fBunderline\fP +The characters in the given context are shown underlined\&. Some +terminals show the foreground in a different colour instead; in this +case whitespace will not be highlighted\&. +.PP +The characters described above as `special\&' are as follows\&. The +formatting described here is used irrespective of whether the characters +are highlighted: +.PP +.PD 0 +.TP +.PD +ASCII control characters +Control characters in the ASCII range are shown as +`\fB^\fP\&' followed by the base character\&. +.TP +Unprintable multibyte characters +This item applies to control characters not in the ASCII range, +plus other characters as follows\&. If the \fBMULTIBYTE\fP option is in +effect, multibyte characters not in the ASCII character set that are +reported as having zero width are treated as combining characters when the +option \fBCOMBINING_CHARS\fP is on\&. If the option is off, or if a character +appears where a combining character is not valid, the character +is treated as unprintable\&. +.RS +.PP +Unprintable multibyte characters are shown as a hexadecimal number between +angle brackets\&. The number is the code point of the character in the wide +character set; this may or may not be Unicode, depending on the operating +system\&. +.RE +.TP +Invalid multibyte characters +If the \fBMULTIBYTE\fP option is in effect, any sequence of one or more +bytes that does not form a valid character in the current character +set is treated as a series of bytes each shown as a special character\&. +This case can be distinguished from other unprintable characters +as the bytes are represented as two hexadecimal digits between angle +brackets, as distinct from the four or eight digits that are used for +unprintable characters that are nonetheless valid in the current +character set\&. +.RS +.PP +Not all systems support this: for it to work, the system\&'s representation of +wide characters must be code values from the Universal Character Set, +as defined by IS0 10646 (also known as Unicode)\&. +.RE +.TP +Wrapped double\-width characters +When a double\-width character appears in the final column of a line, it +is instead shown on the next line\&. The empty space left in the original +position is highlighted as a special character\&. +.PP +If \fBzle_highlight\fP is not set or no value applies to a particular +context, the defaults applied are equivalent to +.PP +.RS +.nf +\fBzle_highlight=(region:standout special:standout +suffix:bold isearch:underline paste:standout)\fP +.fi +.RE +.PP +i\&.e\&. both the region and special characters are shown in standout mode\&. +.PP +Within widgets, arbitrary regions may be highlighted by setting the +special array parameter \fBregion_highlight\fP; see +above\&. +.PP diff --git a/Etc/FAQ b/Etc/FAQ new file mode 100644 index 000000000..5382bd1ee --- /dev/null +++ b/Etc/FAQ @@ -0,0 +1,2713 @@ +Archive-Name: unix-faq/shell/zsh +Last-Modified: 2020/08/08 +Submitted-By: coordinator@zsh.org (Peter Stephenson) <coordinator@zsh.org (Peter Stephenson)> +Posting-Frequency: Monthly +Copyright: (C) P.W. Stephenson, 1995--2020 (see end of document) + + +This document contains a list of frequently-asked (or otherwise +significant) questions concerning the Z-shell, a command interpreter +for many UNIX systems which is freely available to anyone with FTP +access. Zsh is among the most powerful freely available Bourne-like +shells for interactive use. + +If you have never heard of `sh', `csh' or `ksh', then you are +probably better off to start by reading a general introduction to UNIX +rather than this document. + +If you just want to know how to get your hands on the latest version, +skip to question 1.6; if you want to know what to do with +insoluble problems, go to 6.2. + +Notation: Quotes `like this' are ordinary textual quotation +marks. Other uses of quotation marks are input to the shell. + + +Contents: +Chapter 1: Introducing zsh and how to install it +1.1. Sources of information +1.2. What is it? +1.3. What is it good at? +1.4. On what machines will it run? (Plus important compilation notes) +1.5. What's the latest version? +1.6. Where do I get it? +1.7. I don't have root access: how do I make zsh my login shell? + +Chapter 2: How does zsh differ from...? +2.1. sh and ksh? +2.2. csh? +2.3. Why do my csh aliases not work? (Plus other alias pitfalls.) +2.4. tcsh? +2.5. bash? +2.6. Shouldn't zsh be more/less like ksh/(t)csh? +2.7. What is zsh's support for Unicode/UTF-8? +2.8. Why does my bash script report an error when I run it under zsh? + +Chapter 3: How to get various things to work +3.1. Why does `$var' where `var="foo bar"' not do what I expect? +3.2. In which startup file do I put...? +3.3. What is the difference between `export' and the ALL_EXPORT option? +3.4. How do I turn off spelling correction/globbing for a single command? +3.5. How do I get the Meta key to work on my xterm? +3.6. How do I automatically display the directory in my xterm title bar? +3.7. How do I make the completion list use eight bit characters? +3.8. Why do the cursor (arrow) keys not work? (And other terminal oddities.) +3.9. Why does my terminal act funny in some way? +3.10. Why does zsh not work in an Emacs shell mode any more? +3.11. Why do my autoloaded functions not autoload [the first time]? +3.12. How does base arithmetic work? +3.13. How do I get a newline in my prompt? +3.14. Why does `bindkey ^a command-name' or 'stty intr ^-' do something funny? +3.15. Why can't I bind \C-s and \C-q any more? +3.16. How do I execute command `foo' within function `foo'? +3.17. Why do history substitutions with single bangs do something funny? +3.18. Why does zsh kill off all my background jobs when I logout? +3.19. How do I list all my history entries? +3.20. How does the alternative loop syntax, e.g. `while {...} {...}' work? +3.21. Why is my history not being saved? +3.22. How do I get a variable's value to be evaluated as another variable? +3.23. How do I prevent the prompt overwriting output when there is no newline? +3.24. What's wrong with cut and paste on my xterm? +3.25. How do I get coloured prompts on my colour xterm? +3.26. Why is my output duplicated with `foo 2>&1 >foo.out | bar'? +3.27. What are these `^' and `~' pattern characters, anyway? +3.28. How do I edit the input buffer in $EDITOR? +3.29. Why does `which' output for missing commands go to stdout? +3.30. Why doesn't the expansion `*.{tex,aux,pdf}' do what I expect? + +Chapter 4: The mysteries of completion +4.1. What is completion? +4.2. What sorts of things can be completed? +4.3. How does zsh deal with ambiguous completions? +4.4. How do I complete in the middle of words / just what's before the cursor? +4.5. How do I get started with programmable completion? +4.6. Suppose I want to complete all files during a special completion? + +Chapter 5: Multibyte input and output + +5.1. What is multibyte input? +5.2. How does zsh handle multibyte input and output? +5.3. How do I ensure multibyte input and output work on my system? +5.4. How can I input characters that aren't on my keyboard? + +Chapter 6: The future of zsh +6.1. What bugs are currently known and unfixed? (Plus recent important changes) +6.2. Where do I report bugs, get more info / who's working on zsh? +6.3. What's on the wish-list? +6.4. Did zsh have problems in the year 2000? +6.5. When reporting a bug, how do I reduce my `.zshrc' into a minimal reproduction recipe? + +Acknowledgments + +Copyright +--- End of Contents --- + + +Chapter 1: Introducing zsh and how to install it + + + +1.1: Sources of information + + + +Information on zsh is available via the World Wide Web. The URL + is https://zsh.sourceforge.io/ . + The server provides this FAQ and much else and is + now maintained by the zsh workers (email zsh-workers@zsh.org <zsh-workers@zsh.org>). + The FAQ is at https://zsh.sourceforge.io/FAQ/ . + The site also contains some contributed zsh scripts and functions; + we are delighted to add more, or simply links to your own collection. + +This document was originally written in YODL, allowing it to be converted + easily into various other formats. The master source file lives at + https://zsh.sourceforge.io/FAQ/zshfaq.yo and the plain text version + can be found at https://zsh.sourceforge.io/FAQ/zshfaq.txt . + +Another useful source of information is the collection of FAQ articles + posted frequently to the Usenet news groups comp.unix.questions, + comp.unix.shells and comp.answers with answers to general questions + about UNIX. The fifth of the seven articles deals with shells, + including zsh, with a brief description of differences. There is + also a separate FAQ on shell differences and how to change your + shell. Usenet FAQs are available via FTP from rtfm.mit.edu and + mirrors and also on the World Wide Web; see + + USA http://www.cis.ohio-state.edu/hypertext/faq/usenet/top.html + UK http://www.lib.ox.ac.uk/internet/news/faq/comp.unix.shell.html + Netherlands http://www.cs.uu.nl/wais/html/na-dir/unix-faq/shell/.html + + +You can also get it via email by emailing mail-server@rtfm.mit.edu <mail-server@rtfm.mit.edu> + with, in the body of the message, `send faqs/unix-faq/shell/zsh'. + +The latest version of this FAQ is also available directly from any + of the zsh archive sites listed in question 1.6. + +I have put together a user guide to complement the manual by + explaining the most useful features of zsh in a more easy to read way. + This can be found at the zsh web site: + https://zsh.sourceforge.io/Guide/ + +(As a method of reading the following in Emacs, you can type \M-2 + \C-x $ to make all the indented text vanish, then \M-0 \C-x $ + when you are on the title you want.) + +For any more eclectic information, you should contact the mailing + list: see question 6.2. + + +1.2: What is it? + + +Zsh is a UNIX command interpreter (shell) which of the standard + shells most resembles the Korn shell (ksh); its compatibility with + the 1988 Korn shell has been gradually increasing. It includes + enhancements of many types, notably in the command-line editor, + options for customising its behaviour, filename globbing, features + to make C-shell (csh) users feel more at home and extra features + drawn from tcsh (another `custom' shell). + +It was written by Paul Falstad when a student at Princeton; however, + Paul doesn't maintain it any more and enquiries should be sent to + the mailing list (see question 6.2). Zsh is distributed under a + standard Berkeley style copyright. + +For more information, the files Doc/intro.txt or Doc/intro.troff + included with the source distribution are highly recommended. A list + of features is given in FEATURES, also with the source. + + +1.3: What is it good at? + + +Here are some things that zsh is particularly good at. No claim of + exclusivity is made, especially as shells copy one another, though + in the areas of command line editing and globbing zsh is well ahead + of the competition. I am not aware of a major interactive feature + in any other freely-available shell which zsh does not also have + (except smallness). + + + o Command line editing: + + o programmable completion: incorporates the ability to use the + full power of zsh's globbing and shell programming features, + o multi-line commands editable as a single buffer (even files!), + o variable editing (vared), + o command buffer stack, + o print text straight into the buffer for immediate editing (print -z), + o execution of unbound commands, + o menu completion in two flavours, + o variable, editing function and option name completion, + o inline expansion of variables and history commands. + + o Globbing --- extremely powerful, including: + + o recursive globbing (cf. find), + o file attribute qualifiers (size, type, etc. also cf. find), + o full alternation and negation of patterns. + + o Handling of multiple redirections (simpler than tee). + o Large number of options for tailoring. + o Path expansion (=foo -> /usr/bin/foo). + o Adaptable messages for spelling, watch, time as well as prompt + (including conditional expressions). + o Named directories. + o Comprehensive integer and floating point arithmetic. + o Manipulation of arrays (including reverse subscripting). + o Associative arrays (key-to-value hashes) + o Spelling correction. + + + +1.4: On what machines will it run? + + +From version 3.0, zsh uses GNU autoconf as the installation + mechanism. This considerably increases flexibility over the old + `buildzsh' mechanism. Consequently, zsh should compile and run on + any modern version of UNIX, and a great many not-so-modern versions + too. The file MACHINES in the distribution has more details. + +There used to be separate ports for Windows and OS/2, but these + are rather out of date and hard to get; however, zsh exists for + the Cygwin environment. See further notes below. + +If you need to change something to support a new machine, it would be + appreciated if you could add any necessary preprocessor code and + alter configure.in and acconfig.h to configure zsh automatically, + then send the required unified diffs to the list (see question + 6.2). Please make sure you have the latest version first. + +To get it to work, retrieve the source distribution (see question + 1.6), un-gzip it, un-tar it and read the INSTALL file in the top + directory. Also read the MACHINES file for up-to-date + information on compilation on certain architectures. + +*Note for users of nawk* (The following information comes from Zoltan + Hidvegi): On some systems nawk is broken and produces an incorrect + signames.h file. This makes the signals code unusable. This often happens + on Ultrix, HP-UX, IRIX (?). Install gawk if you experience such problems. + + +1.5: What's the latest version? + + +Zsh 5.9 is the latest production version. For details of all the + changes, see the NEWS file in the source distribution. + +A beta of the next version is sometimes available. Development of zsh is + patch by patch, with each intermediate version publicly available. Note + that this `open' development system does mean bugs are sometimes + introduced into the most recent archived version. These are usually + fixed quickly. If you are really interested in getting the latest + improvements, and less worried about providing a stable environment, + development versions are uploaded quite frequently to the archive in the + development subdirectory. + +Note also that as the shell changes, it may become incompatible with + older versions; see the end of question 6.1 for a partial list. + Changes of this kind are almost always forced by an awkward or + unnecessary feature in the original design (as perceived by current + users), or to enhance compatibility with other Bourne shell + derivatives, or (mostly in the 3.0 series) to provide POSIX compliance. + + +1.6: Where do I get it? + + + +The coordinator of development is currently me; the alias + coordinator@zsh.org <coordinator@zsh.org> can be used to contact whoever is in the hot + seat. https://www.zsh.org/ is the official + archive site. Test versions are kept in the + `testing' subdirectory: such up-to-the-minute development versions should + only be retrieved if you actually plan to help test the latest version of + the shell. + +A Windows port was created by Amol Deshpandem based on 3.0.5 (which + is now rather old). This has now been restored and can be found at + http://zsh-nt.sourceforge.net/. + +All recent releases of zsh compile under Cygwin, a freely available + UNIX-style environment for the Win32 API, and a pre-compiled version of + zsh can be downloaded by the Cygwin installer. You can find information + about this at http://www.cygwin.com/. + Please email zsh-workers@zsh.org <zsh-workers@zsh.org> if you have information about + other ports. + +Starting from mid-October 1997, there is an archive of patches sent + to the maintainers' mailing list. Note that these may not all be + added to the shell, and some may already have been; you simply have + to search for something you might want which is not in the version + you have. Also, there may be some prerequisites earlier in the + archive. It can be found on the zsh WWW pages (as described in + 1.1) at: + + + https://zsh.sourceforge.io/Patches/ + + + +1.7: I don't have root access: how do I make zsh my login shell? + + +Unfortunately, on many machines you can't use `chsh' to change your + shell unless the name of the shell is contained in /etc/shells, so if + you have your own copy of zsh you need some sleight-of-hand to use it + when you log on. (Simply typing `zsh' is not really a solution since + you still have your original login shell waiting for when you exit.) + +The basic idea is to use `exec <zsh-path>' to replace the current + shell with zsh. Often you can do this in a login file such as .profile + (if your shell is sh or ksh) or .login (if it's csh). Make sure you + have some way of altering the file (e.g. via FTP) before you try this as + `exec' is often rather unforgiving. + +If you have zsh in a subdirectory `bin' of your home directory, + put this in .profile: + + [ -f $HOME/bin/zsh ] && exec $HOME/bin/zsh -l + + or if your login shell is csh or tcsh, put this in .login: + + if ( -f ~/bin/zsh ) exec ~/bin/zsh -l + + (in each case the `-l' tells zsh it is a login shell). + +If you want to check this works before committing yourself to it, + you can make the login shell ask whether to exec zsh. The following + work for Bourne-like shells: + + [ -f $HOME/bin/zsh ] && { + echo "Type Y to run zsh: \c" + read line + [ "$line" = Y ] && exec $HOME/bin/zsh -l + } + + and for C-shell-like shells: + + if ( -f ~/bin/zsh ) then + echo -n "Type Y to run zsh: " + if ( "$<" == Y ) exec ~/bin/zsh -l + endif + + +It's not a good idea to put this (even without the -l) into .cshrc, + at least without some tests on what the csh is supposed to be doing, + as that will cause _every_ instance of csh to turn into a zsh and + will cause csh scripts (yes, unfortunately some people write these) + which do not call `csh -f' to fail. If you want to tell xterm to + run zsh, change the SHELL environment variable to the full path of + zsh at the same time as you exec zsh (in fact, this is sensible for + consistency even if you aren't using xterm). If you have to exec + zsh from your .cshrc, a minimum safety check is `if ($?prompt) exec + zsh'. + +If you like your login shell to appear in the process list as `-zsh', + you can link `zsh' to `-zsh' (e.g. by `ln -s ~/bin/zsh + ~/bin/-zsh') and change the exec to `exec -zsh'. (Make sure + `-zsh' is in your path.) This has the same effect as the `-l' + option. + +Footnote: if you DO have root access, make sure zsh goes in + /etc/shells on all appropriate machines, including NIS clients, or you + may have problems with FTP to that machine. + + +Chapter 2: How does zsh differ from...? + + +As has already been mentioned, zsh is most similar to ksh, while many +of the additions are to please csh users. Here are some more detailed +notes. See also the article `UNIX shell differences and how to change +your shell' posted frequently to the USENET group comp.unix.shell. + + +2.1: Differences from sh and ksh + + + +Most features of ksh (and hence also of sh) are implemented in zsh; + problems can arise because the implementation is slightly different. + Note also that not all ksh's are the same either. I have based this + on the 11/16/88f version of ksh; differences from ksh93 will be more + substantial. + +As a summary of the status: + + 1. ) because of all the options it is not safe to assume a general + zsh run by a user will behave as if sh or ksh compatible; + 2. ) invoking zsh as sh or ksh (or if either is a symbolic link to + zsh) sets appropriate options and improves compatibility (from + within zsh itself, calling `ARGV0=sh zsh' will also work); + 3. ) from version 3.0 onward the degree of compatibility with sh + under these circumstances is very high: zsh can now be used + with GNU configure or perl's Configure, for example; + 4. ) the degree of compatibility with ksh is also high, but a few + things are missing: for example the more sophisticated + pattern-matching expressions are different for versions before + 3.1.3 --- see the detailed list below; + 5. ) also from 3.0, the command `emulate' is available: `emulate + ksh' and `emulate sh' set various options as well as changing the + effect of single-letter option flags as if the shell had been + invoked with the appropriate name. Including the command + `emulate sh; setopt localoptions' in a shell function will + turn on sh emulation for that function only. In version 4 (and in + 3.0.6 through 8), this can be abbreviated as `emulate -L sh'. + + +The classic difference is word splitting, discussed in question 3.1; + this catches out very many beginning zsh users. As explained there, + this is actually a bug in every other shell. The answer is to set + SH_WORD_SPLIT for backward compatibility. The next most classic + difference is that unmatched glob patterns cause the command to abort; + set NO_NOMATCH for those. + +Here is a list of various options which will increase ksh + compatibility, though maybe decrease zsh's abilities: see the manual + entries for GLOB_SUBST, IGNORE_BRACES (though brace expansion occurs + in some versions of ksh), KSH_ARRAYS, KSH_GLOB, KSH_OPTION_PRINT, + LOCAL_OPTIONS, NO_BAD_PATTERN, NO_BANG_HIST, NO_EQUALS, NO_HUP, + NO_NOMATCH, NO_RCS, NO_SHORT_LOOPS, PROMPT_SUBST, RM_STAR_SILENT, + POSIX_ALIASES, POSIX_BUILTINS, POSIX_IDENTIFIERS, + SH_FILE_EXPANSION, SH_GLOB, SH_OPTION_LETTERS, + SH_WORD_SPLIT (see question 3.1) and SINGLE_LINE_ZLE. + Note that you can also disable any built-in commands which get in + your way. If invoked as `ksh', the shell will try to set suitable + options. + +Here are some differences from ksh which might prove significant for + ksh programmers, some of which may be interpreted as bugs; there + must be more. Note that this list is deliberately rather full and + that most of the items are fairly minor. Those marked `*' perform + in a ksh-like manner if the shell is invoked with the name `ksh', or + if `emulate ksh' is in effect. Capitalised words with underlines + refer to shell options. + + + o Syntax: + + o * Shell word splitting: see question 3.1. + o * Arrays are (by default) more csh-like than ksh-like: + subscripts start at 1, not 0; array[0] refers to array[1]; + `$array' refers to the whole array, not $array[0]; + braces are unnecessary: $a[1] == ${a[1]}, etc. + Set the KSH_ARRAYS option for compatibility. + o Furthermore, individual elements of arrays in zsh are always + strings, not separate parameters. This means, for example, you + can't `unset' an array element in zsh as you can in ksh; you + can only set it to the empty string, or shorten the array. + (You can unset elements of associative arrays in zsh because + those are a completely different type of object.) + o Coprocesses are established by `coproc'; `|&' behaves like + csh. Handling of coprocess file descriptors is also different. + o In `cmd1 && cmd2 &', only `cmd2' instead of the whole + expression is run in the background in zsh. The manual implies + this is a bug. Use `{ cmd1 && cmd2 } &' as a workaround. + + o Command line substitutions, globbing etc.: + + o * Failure to match a globbing pattern causes an error (use + NO_NOMATCH). + o * The results of parameter substitutions are treated as plain text: + `foo="*"; print $foo' prints all files in ksh but `*' in zsh + (use GLOB_SUBST). + o * $PSn do not do parameter substitution by default (use PROMPT_SUBST). + o * Standard globbing does not allow ksh-style `pattern-lists'. + Equivalents: + +---------------------------------------------------------------------- + ksh zsh Meaning + ------ ------ --------- + !(foo) ^foo Anything but foo. + or foo1~foo2 Anything matching foo1 but foo2[1]. +@(foo1|foo2|...) (foo1|foo2|...) One of foo1 or foo2 or ... + ?(foo) (foo|) Zero or one occurrences of foo. + *(foo) (foo)# Zero or more occurrences of foo. + +(foo) (foo)## One or more occurrences of foo. +---------------------------------------------------------------------- + + The `^', `~' and `#' (but not `|')forms require EXTENDED_GLOB. + From version 3.1.3, the ksh forms are fully supported when the + option KSH_GLOB is in effect; for previous versions you + must use the table above. + +[1] See question 3.27 for more on the mysteries of + `~' and `^'. + o Unquoted assignments do file expansion after `:'s (intended for + PATHs). + o * `typeset' and `integer' have special behaviour for + assignments in ksh, but not in zsh. For example, this doesn't + work in zsh: + + integer k=$(wc -l ~/.zshrc) + + because the return value from wc includes leading + whitespace which causes wordsplitting. Ksh handles the + assignment specially as a single word. + + o Command execution: + + o * There is no $ENV variable (use /etc/zshrc, ~/.zshrc; + note also $ZDOTDIR). + o * $PATH is not searched for commands specified + at invocation without -c. + + o Aliases and functions: + + o The order in which aliases and functions are defined is significant: + function definitions with () expand aliases -- see question 2.3. + o Aliases and functions cannot be exported. + o There are no tracked aliases: command hashing replaces these. + o The use of aliases for key bindings is replaced by `bindkey'. + o * Options are not local to functions (use LOCAL_OPTIONS; note this + may always be unset locally to propagate options settings from a + function to the calling level). + o Functions defined with `function funcname { body }' behave the + same way as those defined with `funcname () { body }'. In ksh, + the former behave as if the body were read from a file with `.', + and only the latter behave as true functions. + + o Traps and signals: + + o * Traps are not local to functions. The option LOCAL_TRAPS is + available from 3.1.6. + o TRAPERR has become TRAPZERR (this was forced by UNICOS which + has SIGERR). + + o Editing: + + o The options gmacs, viraw are not supported. + Use bindkey to change the editing behaviour: `set -o {emacs,vi}' + becomes `bindkey -{e,v}', although `set -o emacs' and `set -o vi' + are supported for compatibility; for gmacs, go to emacs mode and + use `bindkey \^t gosmacs-transpose-characters'. + o The `keyword' option does not exist and `-k' is instead + interactivecomments. (`keyword' is not in recent versions + of ksh either.) + o * Management of histories in multiple shells is different: + the history list is not saved and restored after each command. + The option SHARE_HISTORY appeared in 3.1.6 and is set in ksh + compatibility mode to remedy this. + o `\' does not escape editing chars (use `^V'). + o Not all ksh bindings are set (e.g. `<ESC>#'; try `<ESC>q'). + o * `#' in an interactive shell is not treated as a comment by + default. + o In vi command mode the keys "k" and "j" move the cursor to the + end of the line. To move the cursor to the start instead, use + + bindkey -M vicmd 'k' vi-up-line-or-history + bindkey -M vicmd 'j' vi-down-line-or-history + + + o Built-in commands: + + o Some built-ins (r, autoload, history, integer ...) + were aliases in ksh. + o There is no built-in command newgrp: use e.g. `alias + newgrp="exec newgrp"' + o `jobs' has no `-n' flag. + + o Other idiosyncrasies: + + o `select' always redisplays the list of selections on each loop. + + + + +2.2: Similarities with csh + + +Although certain features aim to ease the withdrawal symptoms of csh + (ab)users, the syntax is in general rather different and you should + certainly not try to run scripts without modification. The c2z script + is provided with the source (in Misc/c2z) to help convert .cshrc + and .login files; see also the next question concerning aliases, + particularly those with arguments. + +Csh-compatibility additions include: + + o logout, rehash, source, (un)limit built-in commands. + o *rc file for interactive shells. + o Directory stacks. + o cshjunkie*, ignoreeof options. + o The CSH_NULL_GLOB option. + o >&, |& etc. redirection. + (Note that `>file 2>&1' is the standard Bourne shell command for + csh's `>&file'.) + o foreach ... loops; alternative syntax for other loops. + o Alternative syntax `if ( ... ) ...', though this still doesn't + work like csh: it expects a command in the parentheses. Also + `for', `which'. + o $PROMPT as well as $PS1, $status as well as $?, + $#argv as well as $#, .... + o Escape sequences via % for prompts. + o Special array variables $PATH etc. are colon-separated, $path + are arrays. + o !-type history (which may be turned off via `setopt + nobanghist'). + o Arrays have csh-like features (see under 2.1). + + + +2.3: Why do my csh aliases not work? (Plus other alias pitfalls.) + + + +First of all, check you are using the syntax + + alias newcmd='list of commands' + + and not + + alias newcmd 'list of commands' + + which won't work. (It tells you if `newcmd' and `list of commands' are + already defined as aliases.) + +Otherwise, your aliases probably contain references to the command + line of the form `\!*', etc. Zsh does not handle this behaviour as it + has shell functions which provide a way of solving this problem more + consistent with other forms of argument handling. For example, the + csh alias + + alias cd 'cd \!*; echo $cwd' + + can be replaced by the zsh function, + + cd() { builtin cd "$@"; echo $PWD; } + + (the `builtin' tells zsh to use its own `cd', avoiding an infinite loop) + or, perhaps better, + + cd() { builtin cd "$@"; print -D $PWD; } + + (which converts your home directory to a ~). In fact, this problem is + better solved by defining the special function chpwd() (see + the manual). Note also that the `;' at the end of the function is + optional in zsh, but not in ksh or sh (for sh's where it exists). + +Here is Bart Schaefer's guide to converting csh aliases for zsh. + + + 1. ) If the csh alias references "parameters" (\!:1, \!* etc.), + then in zsh you need a function (referencing $1, $* etc.). + In recent versions of zsh this can be done by defining an anonymous + function within the alias. Otherwise, a simple zsh alias suffices. + +2. ) If you use a zsh function, you need to refer _at_least_ to + $* in the body (inside the { }). Parameters don't magically + appear inside the { } the way they get appended to an alias. + +3. ) If the csh alias references its own name (alias rm "rm -i"), + then in a zsh function you need the "command" or "builtin" keyword + (function rm() { command rm -i "$@" }), but in a zsh alias + you don't (alias rm="rm -i"). + +4. ) If you have aliases that refer to each other (alias ls "ls -C"; + alias lf "ls -F" ==> lf == ls -C -F) then you must either: + + o convert all of them to zsh functions; or + o after converting, be sure your .zshrc defines all of your + aliases before it defines any of your functions. + + +Those first four are all you really need, but here are four more for + heavy csh alias junkies: + +5. ) Mapping from csh alias "parameter referencing" into zsh function + (assuming SH_WORD_SPLIT and KSH_ARRAYS are NOT set in zsh): + + csh zsh + ===== ========== + \!* $* (or $argv) + \!^ $1 (or $argv[1]) + \!:1 $1 + \!:2 $2 (or $argv[2], etc.) + \!$ $*[$#] (or $argv[$#], or $*[-1]) + \!:1-4 $*[1,4] + \!:1- $*[1,$#-1] (or $*[1,-2]) + \!^- $*[1,$#-1] + \!*:q "$@" + \!*:x $=* ($*:x doesn't work (yet)) + + +6. ) Remember that it is NOT a syntax error in a zsh function to + refer to a position ($1, $2, etc.) greater than the number of + parameters. (E.g., in a csh alias, a reference to \!:5 will + cause an error if 4 or fewer arguments are given; in a zsh + function, $5 is the empty string if there are 4 or fewer + parameters. Force an error in this example by using ${5?}.) + +7. ) To begin a zsh alias with a - (dash, hyphen) character, use + `alias --': + + csh zsh + =============== ================== + alias - "fg %-" alias -- -="fg %-" + + +8. ) Stay away from `alias -g' in zsh until you REALLY know what + you're doing. + + +There is one other serious problem with aliases: consider + + alias l='/bin/ls -F' + l() { /bin/ls -la "$@" | more } + + `l' in the function definition is in command position and is expanded + as an alias, defining `/bin/ls' and `-F' as functions which call + `/bin/ls', which gets a bit recursive. Recent versions of zsh treat + this as an error, but older versions silently create the functions. + +One workaround for this is to use the "function" keyword instead: + + alias l='/bin/ls -F' + function l { /bin/ls -la "$@" | more } + + The `l' after `function' is not expanded. Note you don't need + the `()' in this case, although it's harmless. + +You need to be careful if you are defining a function with multiple + names; most people don't need to do this, so it's an unusual problem, + but in case you do you should be aware that in versions of the shell + before 5.1 names after the first were expanded: + + function a b c { ... } + + Here, `b' and `c', but not `a', have aliases expanded. + This oddity was fixed in version 5.1. + +The rest of this item assumes you use the (more common, + but equivalent) `()' definitions. + +Bart Schaefer's rule is: Define first those aliases you expect to + use in the body of a function, but define the function first if the + alias has the same name as the function. + +If you aware of the problem, you can always escape part or all of the + name of the function: + + 'l'() { /bin/ls -la "$@" | more } + + Adding the quotes has no effect on the function definition, but + suppresses alias expansion for the function name. Hence this is + guaranteed to be safe---unless you are in the habit of defining + aliases for expressions such as 'l', which is valid, but probably + confusing. + + +2.4: Similarities with tcsh + + +(The sections on csh apply too, of course.) Certain features have + been borrowed from tcsh, including $watch, run-help, $savehist, + periodic commands etc., extended prompts, sched and which built-ins. + Programmable completion was inspired by, but is entirely different to, + tcsh's `complete'. (There is a perl script called lete2ctl in the + Misc directory of the source distribution to convert `complete' to `compctl' + statements.) This list is not definitive: some features have gone in + the other direction. + +If you're missing the editor function run-fg-editor, try something + with `bindkey -s' (which binds a string to a keystroke), e.g. + + bindkey -s '^z' '\eqfg %$EDITOR:t\n' + + which pushes the current line onto the stack and tries to bring a job + with the basename of your editor into the foreground. `bindkey -s' + allows limitless possibilities along these lines. You can execute + any command in the middle of editing a line in the same way, + corresponding to tcsh's `-c' option: + + bindkey -s '^p' '\eqpwd\n' + + In both these examples, the `\eq' saves the current input line to + be restored after the command runs; a better effect with multiline + buffers is achieved if you also have + + bindkey '\eq' push-input + + to save the entire buffer. In version 4 and recent versions of zsh 3.1, + you have the following more sophisticated option, + + run-fg-editor() { + zle push-input + BUFFER="fg %$EDITOR:t" + zle accept-line + } + zle -N run-fg-editor + + and can now bind run-fg-editor just like any other editor function. + + +2.5: Similarities with bash + + + +The Bourne-Again Shell, bash, is another enhanced Bourne-like shell; + the most obvious difference from zsh is that it does not attempt to + emulate the Korn shell. Since both shells are under active + development it is probably not sensible to be too specific here. + Broadly, bash has paid more attention to standards compliance + (i.e. POSIX) for longer, and has so far avoided the more abstruse + interactive features (programmable completion, etc.) that zsh has. + +In recent years there has been a certain amount of crossover in the + extensions, however. Zsh (as of 3.1.6) has bash's `${var/old/new}' + feature for replacing the text old with the text new in the + parameter $var. Note one difference here: while both shells + implement the syntax `${var/#old/new}' and `${var/%old/new}' for + anchoring the match of old to the start or end of the parameter text, + respectively, in zsh you can't put the `#' or `%' inside a + parameter: in other words `{var/$old/new}' where old begins with + a `#' treats that as an ordinary character in zsh, unlike bash. To + do this sort of thing in zsh you can use (from 3.1.7) the new syntax + for anchors in any pattern, `(#s)' to match the start of a string, + and `(#e)' to match the end. These require the option + EXTENDED_GLOB to be set. + + +2.6: Shouldn't zsh be more/less like ksh/(t)csh? + + +People often ask why zsh has all these `unnecessary' csh-like features, + or alternatively why zsh doesn't understand more csh syntax. This is + far from a definitive answer and the debate will no doubt continue. + +Paul's object in writing zsh was to produce a ksh-like shell which + would have features familiar to csh users. For a long time, csh was + the preferred interactive shell and there is a strong resistance to + changing to something unfamiliar, hence the additional syntax and + CSH_JUNKIE options. This argument still holds. On the other hand, + the arguments for having what is close to a plug-in replacement for ksh + are, if anything, even more powerful: the deficiencies of csh as a + programming language are well known (look in any Usenet FAQ archive, e.g. + http://www.cis.ohio-state.edu/hypertext/faq/usenet/unix-faq/\ + shell/csh-whynot/faq.html + if you are in any doubt) and zsh is able to run many standard + scripts such as /etc/rc. + +Of course, this makes zsh rather large and feature-ridden so that it + seems to appeal mainly to hackers. The only answer, perhaps not + entirely satisfactory, is that you have to ignore the bits you don't + want. The introduction of loadable in modules in version 3.1 should + help. + + +2.7: What is zsh's support for Unicode/UTF-8? + + +`Unicode', or UCS for Universal Character Set, is the modern way + of specifying character sets. It replaces a large number of ad hoc + ways of supporting character sets beyond ASCII. `UTF-8' is an + encoding of Unicode that is particularly natural on Unix-like systems. + +The production branch of zsh, 4.2, has very limited support: + the built-in printf command supports "\u" and "\U" escapes + to output arbitrary Unicode characters; ZLE (the Zsh Line Editor) has + no concept of character encodings, and is confused by multi-octet + encodings. + +However, the 4.3 branch has much better support, and furthermore this + is now fairly stable. (Only a few minor areas need fixing before + this becomes a production release.) This is discussed more + fully below, see `Multibyte input and output'. + + +2.8: Why does my bash script report an error when I run it under zsh? + + + +tl;dr: bash is not the reference implementation of zsh, and zsh is not + a bug-for-bug compatible reimplementation of bash. + +bash and zsh are different programming languages. They are not + interchangeable; programs written for either of these languages will, + in general, not run under the other. (The situation is similar with + many other pairs of closely-related languages, such as Python 2 and + Python 3; C and C++; and even C89 and C11.) + +When bash and zsh behave differently on the same input, whether zsh's + behaviour is a bug does not depend on what bash does on the same + input; rather, it depends on what zsh's user manual specifies. + (By way of comparison, it's not a bug in Emacs that `:q!' doesn't + cause it to exit.) + +That being said, the bash and zsh languages do have a common subset, and it is + feasible to write non-trivial pieces of code that would run under either of + them, if one is sufficiently familiar with both of them. However, + a difference between bash's behaviour and zsh's does not imply that + zsh has a bug. The difference might be a bug in zsh, a bug in bash, or + a bug in neither shell + (see 3.1 for an example). + +The recommended way to deal with these differences depends on what kind + of piece of code is in question: a _script_ or a _plugin_. + +For scripts -- external commands that + are located in $PATH, or located elsewhere and are executed by + giving their path explicitly (as in `ls', `/etc/rc.d/sshd', + and `./configure') -- the answer is simple: + +Don't run bash scripts under zsh. If the scripts were written for + bash, run them in bash. There's absolutely no problem with having + `#!/usr/bin/env bash' scripts even if `zsh' is your shell for + interactive sessions. + +In fact, if you've recently changed to zsh, we _recommend_ that + you keep your scripts as `#!/usr/bin/env bash', at least for + a while: this would make the change more gradual and flatten your + learning curve. Once you're used to zsh, you can decide for each + script whether to port it to zsh or keep it as-is. + +For _plugins_ -- pieces of code + executed within the shell itself, loaded via the `.', + `source', or `autoload' builtins, added to `.zshrc', or + pasted interactively at the shell prompt -- one may consider it + worthwhile to invest the effort to make them runnable under either shell. + However, as mentioned above, doing so requires one to be familiar with both + shells, and either steer clear of their differences or handle them explicitly + with conditional code (such as `if test -n "$ZSH_VERSION"'). + +In summary, + if you'd like to run a bash script or plugin under zsh, you must port the script or plugin + properly, reviewing it line by line for differences between the two + languages and adjusting it accordingly, just like you would + when translating a book from American English to British English. + + +Chapter 3: How to get various things to work + + + +3.1: Why does `$var' where `var="foo bar"' not do what I expect? + + + +In most Bourne-shell derivatives, multiple-word variables such as + + var="foo bar" + + are split into words when passed to a command or used in a `for foo in + $var' loop. By default, zsh does not have that behaviour: the + variable remains intact. (This is not a bug! See below.) The option + SH_WORD_SPLIT exists to provide compatibility. + +For example, defining the function args to show the number of its + arguments: + + args() { echo $#; } + + and with our definition of `var', + + args $var + + produces the output `1'. After + + setopt shwordsplit + + the same function produces the output `2', as with sh and ksh. + +Unless you need strict sh/ksh compatibility, you should ask yourself + whether you really want this behaviour, as it can produce unexpected + effects for variables with entirely innocuous embedded spaces. This + can cause horrendous quoting problems when invoking scripts written + for other shells (see 2.8). The natural way to produce + word-splitting behaviour in zsh is via arrays. For example, + + set -A array one two three twenty + + (or + + array=(one two three twenty) + + if you prefer), followed by + + args $array + + produces the output `4', regardless of the setting of SH_WORD_SPLIT. + Arrays are also much more versatile than single strings. Probably + if this mechanism had always been available there would never have + been automatic word splitting in scalars, which is a sort of + uncontrollable poor man's array. + +Note that word splitting happens regardless of the value of the internal field + separator, $IFS; in other words, with `IFS=:; foo=a:b; args $foo' + you get the answer 1. + +Other ways of causing word splitting include a judicious use of + `eval': + + sentence="Longtemps, je me suis couch\e de bonne heure." + eval "words=($sentence)" + + after which $words is an array with the words of $sentence (note + characters special to the shell, such as the `'' in this example, + must already be quoted), or, less standard but more reliable, + turning on SH_WORD_SPLIT for one variable only: + + args ${=sentence} + + always returns 8 with the above definition of `args'. (In older + versions of zsh, ${=foo} toggled SH_WORD_SPLIT; now it forces it on.) + +Note also the "$@" method of word splitting is always available in zsh + functions and scripts (though strictly this does array splitting, not + word splitting). This is more portable than the $*, since it + will work regardless of the SH_WORD_SPLIT setting; the other + difference is that $* removes empty arguments from the array. + You can fix the first half of that objection by using ${==*}, + which turns off SH_WORD_SPLIT for the duration of the expansion. + +SH_WORD_SPLIT is set when zsh is invoked with the names `ksh' or `sh', + or (entirely equivalent) when `emulate ksh' or `emulate sh' is in + effect. + +There used to be another effect of word splitting which differed between ksh + and zsh. In ksh, the builtin commands that declare parameters such + as typeset and export force word-splitting not to take place + after on an assignment argument: + + typeset param=`echo foo bar` + + in ksh will create a parameter with value `foo bar'. + +zsh used to + create a parameter param with value foo and a parameter bar + whose value was empty. Contrast this with a normal assignment (no + typeset or other command in front), which never causes a word split + unless you have GLOB_ASSIGN set. + +zsh version 4.0.2 and newer creates a single parameter with value + `foo bar', like ksh does, when the option KSH_TYPESET is set. + This option gets set automatically when in ksh compatibility mode. + +zsh 5.1 and newer create a single parameter with value `foo bar' by + default, in both compatibility and native modes. The older behaviour + can be obtained with `disable -r typeset'. + +If the options `MAGIC_EQUAL_SUBST' and `KSH_TYPESET' are both + set, arguments that look like assignments will not undergo word + splitting, whatever the command name. + + +3.2: In which startup file do I put...? + + +When zsh starts up, there are four files you can change which it will + run under various circumstances: .zshenv, .zprofile, .zshrc + and .zlogin. They are usually in your home directory, but the + variable $ZDOTDIR may be set to alter that. Here are a few simple + hints about how to use them. There are also files which the system + administrator can set for all shells; you can avoid running all except + /etc/zshenv by starting zsh with the -f option --- for this + reason it is important for administrators to make sure /etc/zshenv + is as brief as possible. + +The order in which the four files are searched (none of them + _need_ to exist) is the one just given. However, .zprofile + and .zlogin are only run when the shell is a login shell --- when + you first login, of course, and whenever you start zsh with the -l + option. The order is the only difference between those; you should + decide whether you need things set before or after .zshrc. These + files are a good place to set environment variables (i.e. `export' + commands), since they are passed on to all shells without you having + to set them again, and also to check that your terminal is set up + properly (except that if you want to change settings for terminal + emulator windows like xterm you will need to put those in + .zshrc, since usually you do not get a login shell here). + +Login shells are often interactive, but this is not necessarily the + case. It is the programme that starts the shell that decides if it is + to be a login shell, and it is not required that the shell be run + interactively. A possible example is a display manager that starts a + shell to initialise your environment before running the window manager + to create terminals: it might run this as a login shell but with no + terminal, so it is not interactive. + +The only file you can alter which is started with every zsh (unless + you use the -f option) is .zshenv, so this is a good place to put + things you want even if the shell is non-interactive: options for + changing the syntax, like EXTENDED_GLOB, any changes to set with + `limit', any more variables you want to make sure are set as for + example $fpath to find functions. You almost certainly do not + want .zshenv to produce any output. Some people prefer not to + use .zshenv for setting options, as this affects scripts; but + making zsh scripts portable usually requires special handling anyway. + +Finally, .zshrc is run for every interactive shell; that includes + login shells, but also any other time you start up a shell, such as + simply by typing `zsh' or opening a new terminal emulator window. + This file is the place to change the editing behaviour via options or + `bindkey', control how your history is saved, set aliases unless + you want to use them in scripts too, and for any other clutter which + can't be exported but you only use when interacting directly with the + shell. You probably don't want .zshrc to produce output, either, + since there are occasions when this can be a problem, such as when + using `rsh' from another host. See 3.21 for what to put in .zshrc + to save your history. + + +3.3: What is the difference between `export' and the ALL_EXPORT option? + + +Normally, you would put a variable into the environment by using + `export var'. The command `setopt allexport' causes all + variables which are subsequently set (N.B. not all the ones which + already exist) to be put into the environment. + +This may seem a useful shorthand, but in practice it can have + unhelpful side effects: + + 1. ) Since every variable is in the environment as well as remembered + by the shell, the memory for it needs to be allocated twice. + This is bigger as well as slower. + 2. ) It really is *every* variable which is exported, even loop + variables in `for' loops. This is probably a waste. + 3. ) An arbitrary variable created by the user might have a special + meaning to a command. Since all shell variables are visible to + commands, there is no protection against this. + + For these reasons it is usually best to avoid ALL_EXPORT unless you + have a specific use for it. One safe use is to set it before + creating a list of variables in an initialisation file, then unset + it immediately afterwards. Only those variables will be automatically + exported. + + +3.4: How do I turn off spelling correction/globbing for a single command? + + +In the first case, you presumably have `setopt correctall' in an + initialisation file, so that zsh checks the spelling of each word in + the command line. You probably do not want this behaviour for + commands which do not operate on existing files. + +The answer is to alias the offending command to itself with + `nocorrect' stuck on the front, e.g. + + alias mkdir='nocorrect mkdir' + + +To turn off globbing, the rationale is identical: + + alias mkdir='noglob mkdir' + + You can have both nocorrect and noglob, if you like, but the + nocorrect must come first, since it is needed by the line editor, + while noglob is only handled when the command is examined. + +Note also that a shell function won't work: the no... directives must + be expanded before the rest of the command line is parsed. + + +3.5: How do I get the Meta key to work on my xterm? + + + +The Meta key isn't present on a lot of keyboards, but on some + the Alt key has the same effect. If a character is typed on the + keyboard while the Meta key is held down, the characters is sent + as terminal input with its eighth bit set. For example, ASCII + `A', hex 65, becomes hex E5. This is sometimes used to provide + extra editing commands. + +As stated in the manual, zsh needs to be told about the Meta key by + using `bindkey -me' or `bindkey -mv' in your .zshrc or on the + command line. You probably also need to tell the terminal driver to + allow the `Meta' bit of the character through; `stty pass8' is the + usual incantation. Sample .zshrc entry: + + [[ $TERM = "xterm" ]] && stty pass8 && bindkey -me + + or, on SYSVR4-ish systems without pass8, + + [[ $TERM = "xterm" ]] && stty -parenb -istrip cs8 && bindkey -me + + (disable parity detection, don't strip high bit, use 8-bit characters). + Make sure this comes _before_ any bindkey entries in your .zshrc which + redefine keys normally defined in the emacs/vi keymap. You may also + need to set the eightBitOutput resource in your ~/.Xdefaults + file, although this is on by default and it's unlikely anybody will + have tinkered with it. + +You don't need the `bindkey' to be able to define your own sequences + with the Meta key, though you still need the `stty'. + +If you are using multibyte input directly from the keyboard you + probably don't want to use this feature since the eighth bit in + each byte is used to indicate a part of a multibyte character. See + chapter 5. + + +3.6: How do I automatically display the directory in my xterm title bar? + + +You should use the special function `chpwd', which is called when + the directory changes. The following checks that standard output is + a terminal, then puts the directory in the title bar if the terminal + is an xterm or some close relative, or a sun-cmd. + + + chpwd() { + [[ -t 1 ]] || return + case $TERM in + sun-cmd) print -Pn "\e]l%~\e\\" + ;; + *xterm*|rxvt|(dt|k|E)term) print -Pn "\e]2;%~\a" + ;; + esac + } + + +Change `%~' if you want the message to be different. (The `-P' + option interprets such sequences just like in prompts, in this case + producing the current directory; you can of course use `$PWD' here, + but that won't use the `~' notation which I find clearer.) Note that + when the xterm starts up you will probably want to call chpwd + directly: just put `chpwd' in .zshrc after it is defined or autoloaded. + + +3.7: How do I make the completion list use eight bit characters? + + +If you are sure your terminal handles this, the easiest way from versions + 3.0.6 and 3.1 of the shell is to set the option PRINT_EIGHT_BIT. In + principle, this will work automatically if your computer uses the + `locale' system and your locale variables are set properly, as zsh + understands this. However, it is quite complicated, so if it isn't + already set up, trying the option is a lot easier. For earlier versions + of zsh 3, you are stuck with trying to understand locales, see the + setlocale(3) and zshparam(1) manual pages: the simplest + possibility may be to set LC_ALL=en_US. For older versions of the + shell, there is no easy way out. + + +3.8: Why do the cursor (arrow) keys not work? (And other terminal oddities.) + + +The cursor keys send different codes depending on the terminal; zsh + only binds the most well known versions. If you see these problems, + try putting the following in your .zshrc: + + + bindkey "$(echotc kl)" backward-char + bindkey "$(echotc kr)" forward-char + bindkey "$(echotc ku)" up-line-or-history + bindkey "$(echotc kd)" down-line-or-history + + +If you use vi mode, use `vi-backward-char' and `vi-forward-char' + where appropriate. As of version 4.0.1, zsh attempts to look up these + codes and to set the key bindings for you (both emacs and vi), but in + some circumstances this may not work. + +Note, however, that up to version 3.0 binding arbitrary multiple key + sequences can cause problems, so check that this works with your set + up first. Also, from version 3.1.3, more sequences are supported by + default, namely those in the form `<ESC>O' followed by A, + B, C or D, as well as the corresponding set beginning + `<ESC>[', so this may be redundant. + +A particular problem which sometimes occurs is that there are two + different modes for arrow keys, normal mode and keypad mode, which + send different sequences. Although this is largely a historical + artifact, it sometimes happens that your terminal can be switched from + one mode to the other, for example by a rogue programme that sends the + sequence to switch one way, but not the sequence to switch back. Thus + you are stuck with the effects. Luckily in this case the arrow key + sequences are likely to be standard, and you can simply bind both sets. + The following code does this. + + bindkey '\e[A' up-line-or-history + bindkey '\e[B' down-line-or-history + bindkey '\e[C' forward-char + bindkey '\e[D' backward-char + bindkey '\eOA' up-line-or-history + bindkey '\eOB' down-line-or-history + bindkey '\eOC' forward-char + bindkey '\eOD' backward-char + + For most even vaguely VT100-compatible terminals, the above eight + instructions are a fairly safe bet for your .zshrc. Of course + you can substitute variant functions for the second argument here too. + +It should be noted that the `O' / `[' confusion can occur + with other keys such as Home and End. Some systems let you query + the key sequences sent by these keys from the system's terminal + database, terminfo. Unfortunately, the key sequences given there + typically apply to the mode that is not the one zsh uses by default (it's + the "application" mode rather than the "raw" mode). Explaining the use + of terminfo is outside the scope of this FAQ, but if you wish to use the + key sequences given there you can tell the line editor to turn on + "application" mode when it starts and turn it off when it stops: + + function zle-line-init () { echoti smkx } + function zle-line-finish () { echoti rmkx } + zle -N zle-line-init + zle -N zle-line-finish + + If you only have the predecessor to terminfo, called termcap (which is + what we used to get the cursor keys above), replace `echoti smkx' + with `echotc ks' and replace `echoti rmkx' with `echotc ke'. + + +3.9: Why does my terminal act funny in some way? + + +If you are using an OpenWindows cmdtool as your terminal, any + escape sequences (such as those produced by cursor keys) will be + swallowed up and never reach zsh. Either use shelltool or avoid + commands with escape sequences. You can also disable scrolling from + the cmdtool pane menu (which effectively turns it into a shelltool). + If you still want scrolling, try using an xterm with the scrollbar + activated. + +If that's not the problem, and you are using stty to change some tty + settings, make sure you haven't asked zsh to freeze the tty settings: + type + + ttyctl -u + + before any stty commands you use. + +On the other hand, if you aren't using stty and have problems you may + need the opposite: `ttyctl -f' freezes the terminal to protect it + from hiccups introduced by other programmes (kermit has been known to + do this). + +A problem I have experienced myself (on an AIX 3.2 workstation with + xterm) is that termcap deinitialization sequences sent by `less' + were causing automargins to be turned off --- not actually a shell + problem, but you might have thought it was. The fix is to put `X' + into the environment variable LESS to stop the sequences being sent. + Other programs (though not zsh) may also send that sequence. + +If _that_'s not the problem, and you are having difficulties with + external commands (not part of zsh), and you think some terminal + setting is wrong (e.g. ^V is getting interpreted as `literal next + character' when you don't want it to be), try + + ttyctl -u + STTY='lnext "^-"' commandname + + (in this example). Note that zsh doesn't reset the terminal completely + afterwards: just the modes it uses itself and a number of special + processing characters (see the stty(1) manual page). + + +3.10: Why does zsh not work in an Emacs shell mode any more? + + +(This information comes from Bart Schaefer and other zsh-workers.) + +Emacs 19.29 or thereabouts stopped using a terminal type of "emacs" + in shell buffers, and instead sets it to "dumb". Zsh only kicks in + its special I'm-inside-emacs initialization when the terminal type + is "emacs". + +Probably the most reliable way of dealing with this is to look for + the environment variable `$EMACS', which is set to `t' in + Emacs' shell mode. Putting + + [[ $EMACS = t ]] && unsetopt zle + + in your .zshrc should be sufficient. + +Another method is to put + + #!/bin/sh + TERM=emacs exec zsh + + into a file ~/bin/eshell, then `chmod +x ~/bin/eshell', and + tell emacs to use that as the shell by adding + + (setenv "ESHELL" (expand-file-name "~/bin/eshell")) + + to ~/.emacs. + + +3.11: Why do my autoloaded functions not autoload [the first time]? + + +The problem is that there are two possible ways of autoloading a + function (see the AUTOLOADING FUNCTIONS section of the zsh manual + page zshmisc for more detailed information): + + 1. ) The file contains just the body of the function, i.e. + there should be no line at the beginning saying `function foo {' + or `foo () {', and consequently no matching `}' at the end. + This is the traditional zsh method. The advantage is that the + file is called exactly like a script, so can double as both. + To define a function `xhead () { print -n "\033]2;$*\a"; }', + the file would just contain `print -n "\033]2;$*\a"'. + 2. ) The file contains the entire definition, and maybe even + other code: it is run when the function needs to be loaded, then + the function itself is called up. This is the method in ksh. + To define the same function `xhead', the whole of the + usual definition should be in the file. + + +In old versions of zsh, before 3.0, only the first behaviour was + allowed, so you had to make sure the file found for autoload just + contained the function body. You could still define other functions + in the file with the standard form for definitions, though they + would be redefined each time you called the main function. + +In version 3.0.x, the second behaviour is activated if the file + defines the autoloaded function. Unfortunately, this is + incompatible with the old zsh behaviour which allowed you to + redefine the function when you called it. + +From version 3.1, there is an option KSH_AUTOLOAD to allow full ksh + compatibility, i.e. the function _must_ be in the second form + above. If that is not set, zsh tries to guess which form you are + using: if the file contains only a complete definition of the + function in the second form, and nothing else apart from comments + and whitespace, it will use the function defined in the file; + otherwise, it will assume the old behaviour. The option is set + if `emulate ksh' is in effect, of course. + +(A neat trick to autoload all functions in a given directory is to + include a line like `autoload ~/fns/*(:t)' in .zshrc; the bit in + parentheses removes the directory part of the filenames, leaving + just the function names.) + + +3.12: How does base arithmetic work? + + +The ksh syntax is now understood, i.e. + + let 'foo = 16#ff' + + or equivalently + + (( foo = 16#ff )) + + or even + + foo=$((16#ff)) + + The original syntax was + + (( foo = [16]ff )) + + --- this was based on a misunderstanding of the ksh manual page. It + still works but its use is deprecated. Then + + echo $foo + + gives the answer `255'. It is possible to declare variables explicitly + to be integers, via + + typeset -i foo + + which has a different effect: namely the base used in the first + assignment (hexadecimal in the example) is subsequently used whenever + `foo' is displayed (although the internal representation is unchanged). + To ensure foo is always displayed in decimal, declare it as + + typeset -i 10 foo + + which requests base 10 for output. You can change the output base of an + existing variable in this fashion. Using the `$(( ... ))' method will + always display in decimal, except that in 3.1.9 there is a new feature + for selecting a base for displaying here: + + print $(( [#16] 255 )) + + + +3.13: How do I get a newline in my prompt? + + + +You can place a literal newline in quotes, i.e. + + PROMPT="Hi Joe, + what now?%# " + + If you have the bad taste to set the option cshjunkiequotes, which + inhibits such behaviour, you will have to bracket this with + `unsetopt cshjunkiequotes' and `setopt cshjunkiequotes', or put it + in your .zshrc before the option is set. + +In recent versions of zsh (not 3.0), there is a form of quoting which + interprets print sequences like `\n' but otherwise acts like single + quotes: surround the string with $'...'. Hence: + + PROMPT=$'Hi Joe,\nwhat now?%# ' + + is a neat way of doing what you want. Note that it is the quotes, not + the prompt expansion, which turns the `\n' into a newline. + + +3.14: Why does `bindkey ^a command-name' or `stty intr ^-' do something funny? + + +You probably have the extendedglob option set in which case ^ and # + are metacharacters. ^a matches any file except one called a, so the + line is interpreted as bindkey followed by a list of files. Quote the + ^ with a backslash or put quotation marks around ^a. + See 3.27 if you want to know more about the pattern + character `^'. + + +3.15: Why can't I bind \C-s and \C-q any more? + + +The control-s and control-q keys now do flow control by default, + unless you have turned this off with `stty -ixon' or redefined the + keys which control it with `stty start' or `stty stop'. (This is + done by the system, not zsh; the shell simply respects these + settings.) In other words, \C-s stops all output to the terminal, + while \C-q resumes it. + +There is an option NO_FLOW_CONTROL to stop zsh from allowing flow + control and hence restoring the use of the keys: put `setopt + noflowcontrol' in your .zshrc file. + + +3.16: How do I execute command `foo' within function `foo'? + + +The command `command foo' does just that. You don't need this with + aliases, but you do with functions. Note that error messages like + + zsh: job table full or recursion limit exceeded + + are a good sign that you tried calling `foo' in function `foo' without + using `command'. If `foo' is a builtin rather than an external + command, use `builtin foo' instead. + + +3.17: Why do history substitutions with single bangs do something funny? + + +If you have a command like "echo !-2:$ !$", the first history + substitution then sets a default to which later history substitutions + with single unqualified bangs refer, so that !$ becomes equivalent to + !-2:$. The option CSH_JUNKIE_HISTORY makes all single bangs refer + to the last command. + + +3.18: Why does zsh kill off all my background jobs when I logout? + + +Simple answer: you haven't asked it not to. Zsh (unlike [t]csh) gives + you the option of having background jobs killed or not: the `nohup' + option exists if you don't want them killed. Note that you can always + run programs with `nohup' in front of the pipeline whether or not the + option is set, which will prevent that job from being killed on + logout. (`nohup' is actually an external command.) + +The `disown' builtin is very useful in this respect: if zsh informs + you that you have background jobs when you try to logout, you can + `disown' all the ones you don't want killed when you exit. This is + also a good way of making jobs you don't need the shell to know about + (such as commands which create new windows) invisible to the shell. + Likewise, you can start a background job with `&!' instead of just + `&' at the end, which will automatically disown the job. + + +3.19: How do I list all my history entries? + + +Tell zsh to start from entry 1: `history 1'. Those entries at the + start which are no longer in memory will be silently omitted. + + +3.20: How does the alternative loop syntax, e.g. `while {...} {...}' work? + + +Zsh provides an alternative to the traditional sh-like forms with `do', + + while TEST; do COMMANDS; done + + allowing you to have the COMMANDS delimited with some other command + structure, often `{...}'. The rules are quite complicated and + in most scripts it is probably safer --- and certainly more + compatible --- to stick with the sh-like rules. If you are + wondering, the following is a rough guide. + +To make it work you must make sure the TEST itself is clearly + delimited. For example, this works: + + while (( i++ < 10 )) { echo i is $i; } + + but this does _not_: + + while let "i++ < 10"; { echo i is $i; } # Wrong! + + The reason is that after `while', any sort of command list is valid. + This includes the whole list `let "i++ < 10"; { echo i $i; }'; + the parser simply doesn't know when to stop. Furthermore, it is + wrong to miss out the semicolon, as this makes the `{...}' part + of the argument to `let'. A newline behaves the same as a + semicolon, so you can't put the brace on the next line as in C. + +So when using this syntax, the test following the `while' must + be wrapped up: any of `((...))', `[[...]]', `{...}' or + `(...)' will have this effect. (They have their usual syntactic + meanings too, of course; they are not interchangeable.) Note that + here too it is wrong to put in the semicolon, as then the case + becomes identical to the preceding one: + + while (( i++ < 10 )); { echo i is $i; } # Wrong! + + +The same is true of the `if' and `until' constructs: + + if { true } { echo yes } else { echo no } + + but with `for', which only needs a list of words, you can get + away with it: + + for foo in a b; { echo foo is $a; bar=$foo; } + + since the parser knows it only needs everything up to the first + semicolon. For the same reason, there is no problem with the `repeat', + `case' or `select' constructs; in fact, `repeat' doesn't even + need the semicolon since it knows the repeat count is just one word. + +This is independent of the behaviour of the SHORTLOOPS option (see + manual), which you are in any case encouraged even more strongly not + to use in programs as it can be very confusing. + + +3.21: Why is my history not being saved? + + + +In zsh, you need to set three variables to make sure your history is + written out when the shell exits. For example, + + HISTSIZE=200 + HISTFILE=~/.zsh_history + SAVEHIST=200 + + $HISTSIZE tells the shell how many lines to keep internally, + $HISTFILE tells it where to write the history, and $SAVEHIST, + the easiest one to forget, tells it how many to write out. The + simplest possibility is to set it to the same as $HISTSIZE as + above. There are also various options affecting history; see the + manual. + + +3.22: How do I get a variable's value to be evaluated as another variable? + + +The problem is that you have a variable $E containing the string + `EDITOR', and a variable $EDITOR containing the string `emacs', + or something such. How do you get from $E to emacs in one easy + stage? + +There is no standard single-stage way of doing this. However, there + is a zsh idiom (available in all versions of zsh since 3.0) for this: + + print ${(e)E:+\$$E} + + Ignore the `(e)' for now. The `:+' means: if the variable + $E is set, substitute the following, i.e. `\$$E'. This is + expanded to `$EDITOR' by the normal rules. Finally, the `(e)' means + `evaluate the expression you just made'. This gives `emacs'. + +For a standard shell way of doing this, you are stuck with `eval': + + eval echo \$$E + + produces the same result. + +Versions since 3.1.6 allow you to do this directly with a new flag; + `${(P)E}'. + +As a slight aside, sometimes people note that the syntax `${${E}}' + is valid and expect it to have this effect. It probably ought to, but + in the early days of zsh it was found convenient to have this way of + producing different substitutions on the same parameter; for example, + `${${file##**/}%.*}' removes everything up to the last slash in + `$file', then everything from the last dot on, inclusive (try + it, this works). So in `${${E}}', the internal `${...}' + actually does nothing. + + +3.23: How do I prevent the prompt overwriting output when there is no newline? + + +The problem is normally limited to zsh versions prior to 4.3.0 due to the + advent of the PROMPT_SP option (which is enabled by default, and eliminates + this problem for most terminals). An example of the overwriting is: + + % echo -n foo + % + + This shows a case where the word foo was output without a newline, and + then overwritten by the prompt line %. The reason this happens is that + the option PROMPT_CR is enabled by default, and it outputs a carriage + return before the prompt in order to ensure that the line editor knows what + column it is in (this is needed to position the right-side prompt correctly + (`$RPROMPT', `$RPS1') and to avoid screen corruption when performing + line editing). If you add unsetopt promptcr to your .zshrc, you + will see any partial output, but your screen may look weird until you press + return or refresh the screen. + +A better solution than disabling PROMPT_CR (for most terminals) is adding + a simpler version of the PROMPT_SP functionality to an older zsh using a + custom precmd function, like this one: + + # Skip defining precmd if the PROMPT_SP option is available. + if ! eval '[[ -o promptsp ]] 2>/dev/null'; then + function precmd { + # Output an inverse char and a bunch spaces. We include + # a CR at the end so that any user-input that gets echoed + # between this output and the prompt doesn't cause a wrap. + print -nP "%B%S%#%s%b${(l:$((COLUMNS-1)):::):-}\r" + } + fi + + That precmd function will only bump the screen down to a new line if there + was output on the prompt line, otherwise the extra chars get removed by + the PROMPT_CR action. Although this typically looks fine, it may result + in the spaces preceding the prompt being included when you select a line + of preserved text with the mouse. + +One final alternative is to put a newline in your prompt -- see question + 3.13 for that. + + +3.24: What's wrong with cut and paste on my xterm? + + +On the majority of modern UNIX systems, cutting text from one window and + pasting it into another should work fine. On a few, however, there are + problems due to issues about how the terminal is handled: most programs + expect the terminal to be in `canonical input mode', which means that the + program is passed a whole line of input at a time, while for editing + the shell needs a single character at a time and must be in + `non-canonical input mode'. On the systems in question, input can be + lost or re-ordered when the mode changes. There are actually two + slightly different problems: + + 1. ) When you paste something in while a programme is running, so that + the shell only retrieves it later. Traditionally, there was a test + which was used only on systems where the problem was known to exist, + so it is possible some other systems were not handled (for example, + certain versions of IRIX, it appears); also, continuation lines were + not handled properly. A more reliable approach appears from versions + 3.0.6 and 3.1.6. + 2. ) When the shell is waiting for input, and you paste in a chunk of + text consisting of more than one complete set of commands. + Unfortunately, this is a much harder problem: the line editor is + already active, and needs to be turned off when the first command is + executed. The shell doesn't even know if the remaining text is input + to a command or for the shell, so there's simply nothing it can do. + +However, if you have problems you can trick it: type `{' on a line + by itself, then paste the input, then type `}' on a line by + itself. The shell will not execute anything until the final brace is + read; all input is read as continuation lines (this may require the + fixes referred to above in order to be reliable). + +As of 5.1, this trick is not necessary on terminal emulators that + support the bracketed paste feature (this includes most modern + terminal emulators). See the description of $zle_bracketed_paste + in the zshparam manual page for details. + + + +3.25: How do I get coloured prompts on my colour xterm? + + +(Or `color xterm', if you're reading this in black and white.) + +Versions of the shell starting with the 4.3 series have this + built in. Use + + PS1='%K{white}%F{red}<red on white>%f%k<default colours>' + + to change the prompt. Names are only usable for the colours + black, red, green, yellow, blue, magenta, cyan and white, understood + by most terminals, but if you happen to know the details of how + your terminal implements colours you can specify a number, e.g. + `%20F' to turn the foreground into colour number 20. `echotc + Co' will often output the number of colours the terminal supports. + (Careful: `echotc co' is different; it also outputs a number + but it's the number of columns in the terminal.) If this is 8 + then probably you have the named colours and nothing more. + +In older versions of the shell you need to find the sequences which + generate the various colours from the manual for your terminal + emulator; these are ANSI standard on those I know about which support + colour. With a recent (post 3.1.6) distribution of zsh, there is a + theme system to handle this for you; even if you don't see that, the + installed function ``colors'' (meaning `colours', if you're not + reading this in black and white) gives the escape sequences. You will + end up with code looking like this (borrowed from Oliver Kiddle): + + PS1=$'%{\e[1;31m%}<the rest of your prompt here>%{\e[0m%}' + + The `$'' form of quoting turns the ``\e'' into a real escape + character; this only works from about version 3.1.4, so if you're using + 3.0.x, you need to do something like + + PS1="$(print '%{\e[1;31m%}<the rest goes here>%{\e[0m%}')" + + The ``%{...%}'' is used in prompts for strings which will + not appear as characters, so that the prompt code doesn't miscalculate the + length of the prompt which would have a bad effect on editing. The + resulting ``<ESC>[1;31m'' makes the prompt red, and the + ``<ESC>[0m'' puts printing back to normal so that the rest of the line + is unchanged. + + +3.26: Why is my output duplicated with `foo 2>&1 >foo.out | bar'? + + +This is a slightly unexpected effect of the option MULTIOS, which is + set by default. Let's look more closely: + + foo 2>&1 >foo.out | bar + + What you're probably expecting is that the command `foo' sends its + standard output to the pipe and so to the input of the command `bar', + while it sends its standard error to the file `foo.out'. What you + actually see is that the output is going both to the pipe and into the + file. To be more explicit, here's the same example with real commands: + + % { print output; print error >&2 } 2>&1 >foo.out | sed 's/error/erratic/' + erratic + output + % cat foo.out + output + + and you can see `output' appears twice. + +It becomes clearer what's going on if we write: + + % print output >foo1.out >foo2.out + % cat foo1.out + output + % cat foo2.out + output + + You might recognise this as a standard feature of zsh, called `multios' + and controlled by the option of the same name, whereby output is copied + to both files when the redirector appears twice. What's going on in the + first example is exactly the same, however the second redirector is + disguised as a pipe. So if you want to turn this effect off, you need + to unset the option `MULTIOS', or alternatively write the following: + + % { print output; print error >&2 } 2>&1 >&- >foo.out | sed 's/error/erratic/' + erratic + + By closing stdout with >&-, we're cancelling the previous redirections + (to the pipe) and start anew with >foo.out instead of adding it as a + redirection target to stdout. + + +3.27: What are these `^' and `~' pattern characters, anyway? + + + +The characters `^' and `~' are active when the option + EXTENDED_GLOB is set. Both are used to exclude patterns, i.e. to + say `match something other than ...'. There are some confusing + differences, however. Here are the descriptions for `^' and `~'. + +`^' means `anything except the pattern that follows'. You can + think of the combination ^pat as being like a * except + that it doesn't match pat. So, for example, `myfile^.txt' + matches anything that begins with myfile except myfile.txt. + Because it works with patterns, not just strings, `myfile^*.c' + matches anything that begins with myfile unless it ends with + .c, whatever comes in the middle --- so it matches myfile1.h + but not myfile1.c. + +Also like `*', `^' doesn't match across directories if you're + matching files when `globbing', i.e. when you use an unquoted pattern + in an ordinary command line to generate file names. So + `^dir1/^file1' matches any subdirectory of the current directory + except one called dir1, and within any directory it matches it + picks any file except one called file1. So the overall pattern + matches dir2/file2 but not dir1/file1 nor dir1/file2 nor + dir2/file1. (The rule that all the different bits of the pattern + must match is exactly the same as for any other pattern character, + it's just a little confusing that what does match in each bit is + found by telling the shell not to match something or other.) + +As with any other pattern, a `^' expression doesn't treat the + character `/' specially if it's not matching files, for example + when pattern matching in a command like `[[ $string = ^pat1/pat2 ]]'. + Here the whole string pat1/pat2 is treated as the argument that + follows the `^'. So anything matches but that one string + pat1/pat1. + +It's not obvious what something like `[[ $string = ^pat1^pat2 ]]' + means. You won't often have cause to use it, but the rule is that + each `^' takes everything that follows as an argument (unless + it's already inside parentheses --- I'll explain this below). To see + this more clearly, put those arguments in parentheses: the pattern is + equivalent to `^(pat1^(pat2))'. where now you can see exactly what + each `^' takes as its argument. I'll leave it as an exercise for + you to work out what this does and doesn't match. + +`~' is always used between two patterns --- never right at the + beginning or right at the end. Note that the other special meaning of + `~', at the start of a filename to refer to your home directory or + to another named directory, doesn't require the option + EXTENDED_GLOB to be set. (At the end of an argument `~' is + never special at all. This is useful if you have Emacs backup files.) + It means `match what's in front of the tilde, but only if it doesn't + match what's after the tilde'. So `*.c~f*' matches any file + ending in .c except one that begins with f. You'll see that, + unlike `^', the parts before and after the `~' both refer + separately to the entire test string. + +For matching files by globbing, `~' is the only globbing operator + to have a lower precedence than `/'. In other words, when you + have `/a/path/to/match~/a/path/not/to/match' the `~' considers + what's before as a complete path to a file name, and what's after as a + pattern to match against that file. You can put any other pattern + characters in the expressions before and after the `~', but as I + said the pattern after the ~ is really just a single pattern to + match against the name of every file found rather than a pattern to + generate a file. That means, for example, that a * after the + ~ will match a /. If that's confusing, you can think of + how `~' works like this: take the pattern on the left, use it as + normal to make a list of files, then for each file found see if it + matches the pattern on the right and if it does take that file out of + the list. Note, however, that this removal of files happens + immediately, before anything else happens to the file list --- before + any glob qualifiers are applied, for example. + +One rule that is common to both `^' and `~' is that they can + be put inside parentheses and the arguments to them don't extend past + the parentheses. So `(^README).txt' matches any file ending in + .txt unless the string before that was README, the same as + `*.txt~README.txt' or `(*~README).txt'. In fact, you can + always turn `^something' into `(*~something)', where + `something' mustn't contain / if the pattern is being used for + globbing. + +Likewise, `abc(<->~<10-100>).txt' matches a file consisting of + abc, then some digits, then .txt, unless the digits happen to + match a number from 10 to 100 inclusive (remember the handy `<->' + pattern for matching integers with optional limits to the range). So + this pattern matches abc1.txt or abc200.txt but not + abc20.txt nor abc100.txt nor even abc0030.txt. However, + if you're matching files by globbing note you can't put `/'s + inside the parentheses since the groups can't stretch across multiple + directories. (You can do that, of course, whenever the character + `/' isn't special.) This means that you need to take care when + using exclusions across multiple directories; see some examples below. + +You may like to know that from zsh 5.0.3 you can disable any pattern + character separately. So if you find `^' gets in your way and + you're happy using `~', put `disable -p "^"' in ~/.zshrc. + You still need to turn on EXTENDED_GLOB; the disable command + only deactivates things that would otherwise be active, you can't + specially enable something not allowed by the syntax options in effect. + +Here are some examples with files to illustrate the points. We'll + assume the option EXTENDED_GLOB is set and none of the pattern + characters is disabled. + + + 1. ) `**/foo~*bar*' matches any file called `foo' in any + subdirectory, except where `bar' occurred somewhere in the path. + For example, `users/barstaff/foo' will be excluded by the `~' + operator. As the `**' operator cannot be grouped (inside + parentheses it is treated as `*'), this is one way to exclude some + subdirectories from matching a `**'. Note that this can be quite + inefficient because the shell performs a complete search for + `**/foo' before it uses the pattern after the `~' to exclude + files from the match. The file is excluded if `bar' occurs + anywhere, in any directory segment or the final file name. + 2. ) The form `(^foo/)#' can be used to match any hierarchy of + directories where none of the path components is foo. For + example, `(^CVS/)#' selects all subdirectories to any depth + except where one component is named `CVS'. (The form + `(pat/)#' is very useful in other cases; for example, + `(../)#.cvsignore' finds the file .cvsignore if it exists + in the current directory or any parent.) + + + +3.28: How do I edit the input buffer in $EDITOR? + + + +When typing a long command interactively, it's possible to edit it in $EDITOR + before execution by using the edit-command-line ZLE widget. For example, + after putting + + autoload -U edit-command-line; + zle -N edit-command-line; + bindkey '^Fc' edit-command-line; + + in your ~/.zshrc, typing `^F c' will open the entered-so-far + command-line for editing. The command will not be automatically executed; + quitting the editor will only return to zsh's command-line editing mode. + + +3.29: Why does `which' output for missing commands go to stdout? + + +The issue is that if you run: + + which non-existent-command + + the error message goes, unusually, to standard output rather than + to standard error. Other shells send this message to standard error, + as they would if the command was about to be executed but could not be + found. + +The original reason for this is that this behaviour is inherited from + previous versions of `which', a builtin in later versions of csh, + the C shell, as well as tcsh, an adaptation of the C Shell with better + editing, and is also available as a separate script sometimes still + found in certain distributions. Other shells had equivalent commands, + `whence' and `type, that zsh has also adopted. So in fact + this has always been a feature of `which'. (It would be possible + to change this in emulation modes; however, so far this possibility + has been seen as more of an additional confusion than a help.) + +If you want some further rationalisation, you might note that + `which' is designed as a way of outputting information about a + command. So `this command can be found in ...' and `this command + can't be found' are both bits of information here, unlike the case + where the command is to be executed. So although it differs from + other Bourne-style shells it is in fact self-consistent. Note that + the exit status does reflect the fact the command can't be found. + + +3.30: Why doesn't the expansion `*.{tex,aux,pdf}' do what I expect? + + +Based on the behaviour of some other shells, you might guess that the + following expression: + + echo *.{tex,aux,pdf} + + would be the way to echo any files ending in `.tex', `.aux' or + `.pdf' in the current directory. Depending on your settings for + matching (see 2.1, in particular NO_NOMATCH), you may + see something else, in particular an error about (say) `*.aux' if + there were no files ending `.aux'. + +The reason for this is that the brace expansion isn't actually + a form of pattern matching. Instead, the line above is equivalent to + + echo *.tex *.aux *.pdf + + giving you three separate patterns. With the default `NOMATCH' + behaviour in effect, any pattern that fails to match is an error. + +However, there is a way of doing exactly what you want, using + parentheses instead of braces: + + echo *.(tex|aux|pdf) + + This is now a pattern matching expression, so is considered as a + single pattern. Now any file that exists will suppress the + `NOMATCH' behaviour, but you'll still get all the files that do + match. + +This use of parentheses is special to zsh. Modern Bourne-like shells + have a syntax like this, too, but with an `@' in front of the + parentheses: again, see 2.1, and search for `@('. + This is harder for the user to remember but easier for the shell to + parse! + + +Chapter 4: The mysteries of completion + + + +4.1: What is completion? + + +`Completion' is where you hit a particular command key (TAB is the + standard one) and the shell tries to guess the word you are typing + and finish it for you --- a godsend for long file names, in + particular, but in zsh there are many, many more possibilities than + that. + +There is also a related process, `expansion', where the shell sees + you have typed something which would be turned by the shell into + something else, such as a variable turning into its value ($PWD + becomes /home/users/mydir) or a history reference (!! becomes + everything on the last command line). In zsh, when you hit TAB it + will look to see if there is an expansion to be done; if there is, + it does that, otherwise it tries to perform completion. (You can + see if the word would be expanded --- not completed --- by TAB by + typing `\C-x g', which lists expansions.) Expansion is generally + fairly intuitive and not under user control; for the rest of the + chapter I will discuss completion only. + +An elegant completion system appeared in version 4, replacing the old + compctl command. This is based on functions called automatically for + completion in particular contexts (for example, there is a function + called _cd to handle completion for the cd command) and is + installed automatically with the shell, so all you need to do, in + principal, is to arrange for this to be loaded. Putting `autoload -U + compinit; compinit' in your .zshrc should be enough if the system is + installed properly. + + +4.2: What sorts of things can be completed? + + + +The simplest sort is filename completion, mentioned above. Unless + you have made special arrangements, as described below, then after + you type a command name, anything else you type is assumed by the + completion system to be a filename. If you type part of a word and + hit TAB, zsh will see if it matches the first part a filename and + if it does it will automatically insert the rest. + +The other simple type is command completion, which applies + (naturally) to the first word on the line. In this case, zsh + assumes the word is some command to be executed lying in your $PATH + (or something else you can execute, like a builtin command, a + function or an alias) and tries to complete that. + +However, the new completion system is highly sensitive to context + and comes with completions for many UNIX commands. These are + automatically loaded when you run compinit as described above. + So the real answer to the question `what can be completed?' is + `anything where an automated guess is possible'. Just hit TAB + and see if the shell manages to guess correctly. + + +4.3: How does zsh deal with ambiguous completions? + + +Often there will be more than one possible completion: two files + start with the same characters, for example. Zsh has a lot of + flexibility for what it does here via its options. The default is + for it to beep and completion to stop until you type another + character. You can type \C-D to see all the possible completions. + (That's assuming you're at the end of the line, otherwise \C-D will + delete the next character and you have to use ESC-\C-D.) This can be + changed by the following options, among others: + + o with NO_BEEP set, that annoying beep goes away + o with NO_LIST_BEEP, beeping is only turned off for ambiguous + completions + o with AUTO_LIST set, when the completion is ambiguous you get a + list without having to type \C-D + o with BASH_AUTO_LIST set, the list only happens the second + time you hit tab on an ambiguous completion + o with LIST_AMBIGUOUS, this is modified so that nothing is listed if + there is an unambiguous prefix or suffix to be inserted --- this + can be combined with BASH_AUTO_LIST, so that where both are + applicable you need to hit tab three times for a listing. + o with MENU_COMPLETE set, one completion is always inserted + completely, then when you hit TAB it changes to the next, and so + on until you get back to where you started + o with AUTO_MENU, you only get the menu behaviour when you hit TAB + again on the ambiguous completion. + o Finally, although it affects all completion lists, including + those explicitly requested, note also ALWAYS_LAST_PROMPT, which + causes the cursor to return to the line you were editing after + printing the list, provided that is short enough. + + Combinations of these are possible; for example, AUTO_LIST and + AUTO_MENU together give an intuitive combination. Note that + from version 3.1 LIST_AMBIGUOUS is set by default; if you use + autolist, you may well want to `unsetopt listambiguous'. + + +4.4: How do I complete in the middle of words / just what's before the cursor? + + +Sometimes you have a word on the command-line which is incomplete in the + middle. Normally if you hit tab in zsh, it will simply go to the end of + the word and try to complete there. However, there are two ways of + changing this. + +First, there is the option COMPLETE_IN_WORD. This tries to fill in + the word at the point of the cursor. For example, if the current + directory contains `foobar', then with the option set, you can + complete `fbar' to `foobar' by moving the cursor to the + `b' and hitting tab. + +To complete just what's before the cursor, ignoring anything after, you + need the function expand-or-complete-prefix: it works mostly like the + usual function bound to tab, but it ignores anything on the right of the + cursor. If you always want this behaviour (some other shells do this), + bind it to tab; otherwise put another binding, e.g. `^X TAB' in + ~/.zshrc: + + bindkey "^X^I" expand-or-complete-prefix + + +The completion system's handling of filenames allows you to complete + multiple segments of a path in one go, so for example /u/l/b + can expand to /usr/local/bin or anything else that matches. This + saves you having to expand the middle part of the path separately. + + +4.5: How do I get started with programmable completion? + + + +The main resource is the zshcompsys manual page. It's complicated, + I'm afraid, far too much to go into here. See also the user guide + referred to above, or copy one of the very many existing functions. For + a professionally produced guide, see the book `From Bash to Z Shell: + Conquering the Command Line' by Oliver Kiddle, Jerry Peek and Peter + Stephenson (me), published by Apress, ISBN 1-59059-376-6. Chapter 10 + tells you how to configure the completion system and chapter 15 how + to write your own completion functions. + + +4.6: Suppose I want to complete all files during a special completion? + + +If you're using the completion system the shell will decide what + to complete when you hit TAB. That's usually the right thing for + the context, but sometimes you just want to complete files, like + TAB used to do in the old days. You can set up this up as follows: + + zle -C complete-file complete-word _generic + zstyle ':completion:complete-file::::' completer _files + bindkey '^xF' complete-file + + This turns the key \C-x F into a command complete-file which + goes straight to the completion system's file completion command, + ignoring the normal context. Change the binding how you like. + +Note the way the form of completion to use is specified by picking a + `completer' called `_files'. You can define any completion + to be bound to a keystroke by putting the appropriate completion + function at that point. Then change all occurrences of + `complete-file' to a name of your own. + +If you simply want to try filename completion as a default when other + completions fail, add it to the `completer' style for normal + completion, for example: + + zstyle ':completion:*' completer _complete _ignored _files + + This adds filename completion to the end of the default types of + completion. Your actual completer style may include other actions, + such as expansion or approximate completion. + + +Chapter 5: Multibyte input and output + + + + +5.1: What is multibyte input? + + +For a long time computers had a simple idea of a character: each octet + (8-bit byte) of text contained one character. This meant an application + could only use 256 characters at once. The first 128 characters (0 to + 127) on Unix and similar systems usually corresponded to the ASCII + character set, as they still do. So all other possibilities had to be + crammed into the remaining 128. This was done by picking the appropriate + character set for the use you were making. For example, ISO 8859 + specified a set of extensions to ASCII for various alphabets. + +This was fine for simple extensions and certain short enough relatives of + the Latin alphabet (with no more than a few dozen alphabetic characters), + but useless for complex alphabets. Also, having a different character + set for each language is inconvenient: you have to start a new terminal + to run the shell with each character set. So the character set had to be + extended. To cut a long story short, the world has mostly standardised + on a character set called Unicode, related to the international standard + ISO 10646. The intention is that this will contain every single + character used in all the languages of the world. + +This has far too many characters to fit into a single octet. What's + more, UNIX utilities such as zsh are so used to dealing with ASCII that + removing it would cause no end of trouble. So what happens is this: the + 128 ASCII characters are kept exactly the same (and they're the same as + the first 128 characters of Unicode), but the remaining 128 characters + are used to build up any other Unicode character by combining multiple + octets together. The shell doesn't need to interpret these directly; it + just needs to ask the system library how many octets form the next + character, and if there's a valid character there at all. (It can also + ask the system what width the character takes up on the screen, so that + characters no longer need to be exactly one position wide.) + +The way this is done is called UTF-8. Multibyte encodings of other + character sets exist (you might encounter them for Asian character sets); + zsh will be able to use any such encoding as long as it contains ASCII as + a single-octet subset and the system can provide information about other + characters. However, in the case of Unicode, UTF-8 is the only one you + are likely to encounter that is useful in zsh. + +(In case you're confused: Unicode is the character set, while UTF-8 is + an encoding of it. You might hear about other encodings, such as UCS-2 + and UCS-4 which are basically the character's index in the character set + as a two-octet or four-octet integer. You might see files encoded this + way, for example on Windows, but the shell can't deal directly with text + in those formats.) + + +5.2: How does zsh handle multibyte input and output? + + +Until version 4.3, zsh didn't handle multibyte input properly at all. + Each octet in a multibyte character would look to the shell like a + separate character. If your terminal handled the character set, + characters might appear correct on screen, but trying to edit them would + cause all sorts of odd effects. (It was possible to edit in zsh using + single-byte extensions of ASCII such as the ISO 8859 family, however.) + +From version 4.3.4 (stable versions starting from 5.0), multibyte + input is handled in the line editor if zsh has been compiled with the + appropriate definitions, and is automatically activated. This is + indicated by the option MULTIBYTE, which is set by default on + shells that support multibyte mode. Hence you can test this with a + standard option test: `[[ -o multibyte ]]'. + +The MULTIBYTE option affects the entire shell: parameter expansion, + pattern matching, etc. count valid multibyte character strings as a + single character. You can unset the option locally in a function to + revert to single-byte operation. + +As multibyte characters are nowadays standard across most utilities, + since 5.1 the MULTBYTE option has been turned on when emulating + other shells. + +The other option that affects multibyte support is COMBINING_CHARS, + new in version 4.3.9. When this is set, any zero-length punctuation + characters that follow an alphanumeric character (the base character) are + assumed to be modifications (accents etc.) to the base character and to + be displayed within the same screen area as the base character. As not + all terminals handle this, even if they correctly display the base + multibyte character, this option is not on by default. Recent versions + of the KDE and GNOME terminal emulators konsole and + gnome-terminal as well as rxvt-unicode, and the Unicode version + of xterm, xterm -u8 or the front-end uxterm, are known to handle + combining characters. + +The COMBINING_CHARS option only affects output; combining characters + may always be input, but when the option is off will be displayed + specially. By default this is as a code point (the index of the + character in the character set) between angle brackets, usually + in inverse video. Highlighting of such special characters can + be modified using the new array parameter zle_highlight. + + +5.3: How do I ensure multibyte input and output work on my system? + + +Once you have a version of zsh with multibyte support, you need to + ensure the environment is correct. We'll assume you're using UTF-8. + Many modern systems may come set up correctly already. Try one of + the editing widgets described in the next section to see. + +There are basically three components. + + + o The locale. This describes a whole series of features specific + to countries or regions of which the character set is one. + Usually it is controlled by the environment variable LANG + (there are others but this is the one to start with). If you have + a recent operating system, very likely it is already set + appropriately. Otherwise, you need to find a locale whose name + contains `UTF-8'. This will be a variant on your usual + locale, which typically indicates the language and country; for + example, mine is `en_GB.UTF-8'. Luckily, zsh can complete + locale names, so if you have the new completion system loaded you + can type `export LANG=' and attempt to complete a suitable + locale. It's the locale that tells the shell to expect the right + form of multibyte input. (However, there's no guarantee that the + shell is actually going to get this input: for example, if you + edit file names that have been created using a different character + set it won't work properly.) + o The terminal emulator. Those that are supplied with a recent + desktop environment, such as konsole and gnome-terminal, are + likely to have extensive support for localization and may work + correctly as soon as they know the locale. You can enable UTF-8 + support for xterm in its application defaults file. The + following are the relevant resources; you don't actually need all of + them, as described below. If you use a `~/.Xdefaults' or + `~/.Xresources' file for setting resources, prefix all the lines + with `xterm': + + *wideChars: true + *locale: true + *utf8: 1 + *vt100Graphics: true + + This turns on support for wide characters (this is enabled by the + utf8 resource, too); enables conversions to UTF-8 from other + locales (this is the key resource and actually overrides + `utf8'); turns on UTF-8 mode (this resource is mostly used to + force use of UTF-8 characters if your locale system isn't up to it); + and allows certain graphic characters to work even with UTF-8 + enabled. (Thanks to Phil Pennock for suggestions.) + o The font. If you selected this from a menu in your terminal + emulator, there's a good chance it already selected the right + character set to go with it. If you hand-picked an old fashioned + X font with a lot of dashes, you need to make sure it ends with + the right character encoding, `iso10646-1' (and not, for + example, `iso8859-1'). Not all characters will be available + in any font, and some fonts may have a more restricted range of + Unicode characters than others. + + +As mentioned in the previous section, `bindkey -m' now outputs + a warning message telling you that multibyte input from the terminal + is likely not to work. (See 3.5 if you don't know what + this feature does.) If your terminal doesn't have characters + that need to be input as multibyte, however, you can still use + the meta bindings and can ignore the warning message. Use + `bindkey -m 2>/dev/null' to suppress it. + +You might also note that the latest version of the Cygwin environment + for Windows supports UTF-8. In previous versions, zsh was able + to compile with the MULTIBYTE option enabled, but the system + didn't provide full support for it. + + +5.4: How can I input characters that aren't on my keyboard? + + +Two functions are provided with zsh that help you input characters. + As with all editing widgets implemented by functions, you need to + mark the function for autoload, create the widget, and, if you are + going to use it frequently, bind it to a key sequence. The + following binds insert-composed-char to F5 on my keyboard: + + autoload -Uz insert-composed-char + zle -N insert-composed-char + bindkey '\e[15~' insert-composed-char + + +The two widgets are described in the zshcontrib(1) manual + page, but here is a brief summary: + +insert-composed-char is followed by two characters that + are a mnemonic for a multibyte character. For example `a:' + is a with an Umlaut; `cH' is the symbol for hearts on a playing + card. Various accented characters, European and related alphabets, + and punctuation and mathematical symbols are available. The + mnemonics are mostly those given by RFC 1345, see + http://www.faqs.org/rfcs/rfc1345.html. + +insert-unicode-char is used to input a Unicode character by + its hexadecimal number. This is the number given in the Unicode + character charts, see for example http://www.unicode.org/charts/. + You need to execute the function, then type the hexadecimal number + (you can omit any leading zeroes), then execute the function again. + +Both functions can be used without multibyte mode, provided the locale is + correct and the character selected exists in the current character set; + however, using UTF-8 massively extends the number of valid characters + that can be produced. + +If you have a recent X Window System installation, you might find + the AltGr key helps you input accented Latin characters; for + example on my keyboard AltGr-; e gives `e' with an acute accent. + See also http://www.cl.cam.ac.uk/~mgk25/unicode.html#input + for general information on entering Unicode characters from a keyboard. + + +Chapter 6: The future of zsh + + + +6.1: What bugs are currently known and unfixed? (Plus recent important changes) + + + +Bugs tend to be tracked on the zsh-workers mailing list; see the + next section. Check the mailing list to see if a bug has been + reported. (There is a bug tracker at the zsh development site + at Sourceforge, but it's not in active use.) + +To see how recent versions of the shell have changed, look at + the README file in the source distribution. This indicates the + most important changes, and in particular draws attention to + incompatibilities you might notice. + + +6.2: Where do I report bugs, get more info / who's working on zsh? + + + +The shell is being maintained by various (entirely self-appointed) + subscribers to the mailing list, + + zsh-workers@zsh.org + + so mail on any issues (bug reports, suggestions, complaints...) + related to the development of the shell should be sent there. If + you want someone to mail you directly, say so. Most patches to zsh + appear there first. + +Please note when reporting bugs that many exist only on certain + architectures, which the developers may not have access to. In + this case debugging information, as detailed as possible, is + particularly welcome. + +Two progressively lower volume lists exist, one with messages + concerning the use of zsh, + + zsh-users@zsh.org + + and one just containing announcements: about releases, about major + changes in the shell, or this FAQ, for example, + + zsh-announce@zsh.org + + (posting to the last one is currently restricted). + +Finally, there is a private mailing list (the general public cannot subscribe + to it) for discussing bug reports with security implications, i.e., potential + vulnerabilities: `zsh-security@zsh.org'. If you find a security problem + in zsh itself, please mail this address. + +Note that you should only join one of these lists: people on + zsh-workers receive all the lists, and people on zsh-users will + also receive the announcements list. + +The lists are handled by an automated server. The instructions for + zsh-announce and zsh-users are the same as for zsh-workers: just + change zsh-workers to whatever in the following. + +To join zsh-workers, send email to + + zsh-workers-subscribe@zsh.org + + (the actual content is unimportant). Replace subscribe with + unsubscribe to unsubscribe. The mailing software (Sympa) has + various bells and whistles: you can retrieve archived messages. + Mail sympa@zsh.org?subject=help <sympa@zsh.org?subject=help> for detailed information. + Administrative matters are best sent to + zsh-workers-owner@zsh.org <zsh-workers-owner@zsh.org>. + +Note that this location changed in August 2020, and the + instructions to go with it are slightly different. + +An archive of mailings for the last few years can be found at + http://www.zsh.org/mla/ + at the main zsh archive site. + +Of course, you can also post zsh queries to the Usenet group + comp.unix.shell; if all else fails, you could even e-mail me. + + +6.3: What's on the wish-list? + + +The code bears the marks of the ages and many things could be done much + better with a rewrite. A more efficient set of code for + lexing/parsing/execution might also be an advantage. Volunteers are + particularly welcome for these tasks. + +Some future possibilities which have been suggested: + + o The shell, in particular the line editor, should support Unicode + characters. Initial support for this appeared in version 4.3; + it is reasonably complete in the line editor but patchy elsewhere + (note this may require the configuration option --enable-multibyte). + o The parameter code could do with tidying up, maybe with more of the + features made available in ksh93. + o Configuration files to enable zsh startup files to be created + with the Dotfile Generator. + o Further improvements in integrating the line editor with shell + functions. + o POSIX compatibility could be improved. + o Option for glob qualifiers to follow perl syntax (a traditional item). + + + +6.4: Did zsh have problems in the year 2000? + + +Not that I heard of; it's up to you to be careful with two-digit dates, + though, which are produced by the prompt escapes `%W' and `%D', + and also by the command `print -P'. Earlier versions of zsh may + show problems here. + + +6.5: When reporting a bug, how do I reduce my `.zshrc' into a minimal reproduction recipe? + + +When reporting a bug, the gold standard is to include with the bug + a _minimal reproduction recipe_, with which anyone who reads the bug + report can reproduce the bug for themselves + at will. + +When you run into a bug in the shell, particularly during interactive + use, a reproduction recipe would ideally start by running zsh -f + and then, within that instance of the shell, run a minimal short + sequence of commands that reproduces the bug. A good way to devise + such recipes is the following: + + + 1. ) First, ensure the bug is reproducible. To do this, start + a new instance of the shell -- for example, open a new tab in + your terminal emulator -- and reproduce the bug there. + +2. ) Start a new instance of the shell by running the + command `zsh -f' from your regular shell prompt, and reproduce the + bug there. (The `-f' flag inhibits `.zshenv', + `/etc/zprofile', `.zprofile', `/etc/zshrc', and + `.zshrc' from being sourced.) + +If you succeeded in reproducing the bug in `zsh -f', copy the + commands you used and their outputs (from the `zsh -f' invocation + to the point the bug occurred) and include them in your bug report. + Skip the remaining steps of this procedure. + +If, however, the bug happens in your regular shell but not in `zsh + -f', read the next steps. + +3. ) Make a backup of your .zshrc file. + +4. ) Delete your .zshrc file, start a new instance of zsh, and confirm + that the problem does not reproduce there. (If the problem + does reproduce there, it's caused by something in `.zshenv', + `.zprofile', `/etc/zprofile', or `/etc/zshrc', so apply + this procedure from the top to those files rather than to your + `.zshrc'.) + + + +5. ) At this point, you know that the problem is caused by + something in your `.zshrc' file, but not what line exactly. + To find the responsible line, we will use + a variation + of the binary search + algorithm, as follows: + +Suppose your `.zshrc' file has 200 lines. To start, copy + the first half of your `.zshrc' -- that is, lines + 1 through 100 -- from the backup copy to your live `.zshrc' + file, and check whether the bug reproduces then. Now, empty the live + `.zshrc' file again, and copy the second half of your + `.zshrc' file from the backup to the live `.zshrc' file + -- the live file should now contain lines 101 through 200, only + -- and see whether the problem reproduces. + +Normally, the bug will reproduce either with lines 1 through 100 + or with lines 101 through 200, but not in both cases. To isolate + the specific line that causes the bug, repeat the above process on the + relevant half of the file: for example, if you've determined that the + bug reproduces when only lines 101 through 200 are installed, check + whether the bug reproduces (a) when only lines 101 through 150 are + installed, and (b) when only lines 151 through 200 are installed. + Repeat the process until the resulting `.zshrc' is minimal. + +It is not important to break the file into two halves exactly. + Breaking the file into two parts sized one-third and two-thirds, for + example, will work equally well. You can even try restoring one line + at a time, but this is impractical for all but the shortest + `.zshrc' files. + +6. ) Include the minimal set of lines you devised in the previous + step, along with the commands you used and their outputs, in your bug + report. + +7. ) Restore your `.zshrc' from backup. + + +Bug reports should be emailed to the `zsh-workers@zsh.org' public + mailing list; see 6.2 for details. + + +Acknowledgments: + + +Thanks to zsh-list, in particular Bart Schaefer, for suggestions +regarding this document. Zsh has been in the hands of archivists Jim +Mattson, Bas de Bakker, Richard Coleman, Zoltan Hidvegi and Andrew +Main, and the mailing list has been run by Peter Gray, Rick Ohnemus, +Richard Coleman, Karsten Thygesen and Geoff Wing, all of whom deserve +thanks. The world is eternally in the debt of Paul Falstad for inventing +zsh in the first place (though the wizzo extended completion is by Sven +Wischnowsky). + + +Copyright Information: + + +This document is copyright (C) P.W. Stephenson, 1995, 1996, 1997, +1998, 1999, 2000, 2012, 2020. This text originates in the U.K. and the author +asserts his moral rights under the Copyrights, Designs and Patents Act, +1988. + +Permission is hereby granted, without written agreement and without +license or royalty fees, to use, copy, modify, and distribute this +documentation for any purpose, provided that the above copyright +notice appears in all copies of this documentation. Remember, +however, that this document changes monthly and it may be more useful +to provide a pointer to it rather than the entire text. A suitable +pointer is "information on the Z-shell can be obtained on the World +Wide Web at URL https://zsh.sourceforge.io/". diff --git a/Functions/VCS_Info/test-repo-git-rebase-merge b/Functions/VCS_Info/test-repo-git-rebase-merge index fce9e9178..ce49690cd 120000..100755 --- a/Functions/VCS_Info/test-repo-git-rebase-merge +++ b/Functions/VCS_Info/test-repo-git-rebase-merge @@ -1 +1,59 @@ -test-repo-git-rebase-apply
\ No newline at end of file +#!/usr/local/bin/zsh -f +# +# This script creates a test repository for testing the git backend's behaviour during rebase-apply operations. +# +# It works in ./vcs-test/. +# +# Suggested zshrc settings: +# +# autoload vcs_info +# precmd() { vcs_info; typeset -pm vcs\* } +# zstyle ':vcs_info:*' actionformats %m +# zstyle ':vcs_info:*' patch-format '[%n+%c=%a] [%p] [%u]' +# zstyle :vcs_info:\*gen-applied-string\* hooks f1 +# +vi-f1() { typeset -p argv hook_com } +# zstyle :vcs_info:\*gen-unapplied-string\* hooks f2 +# +vi-f2() { typeset -p argv hook_com } +# zstyle :vcs_info:\* get-unapplied true +# +mkdir "vcs-test" +cd "vcs-test" +git init + +append_lines() { for 1; do echo line from r$1 >> iota && git commit -am "r$1: Append a line"; done } + +echo "This is the file 'iota'." > iota +git add iota +git commit -m "r1: Add iota" +git tag rebase_onto_this HEAD + +# Make another change to iota +append_lines 2 +git tag rebase_from_this HEAD + +# Make non-conflicting changes +for 1 in 3 4 5 6; do + touch kappa$1 + git add kappa$1 + git commit -m "r${1}: non-conflicting change" +done + +# Make more changes to iota +append_lines 7 8 9 + +# Specify a rebase that would create the history [1,3,4,5,6,7,8,9]. +# This will conflict because r7 depends on r2 which is not included. +git checkout -b myref +case $0:P in + (*/test-repo-git-rebase-apply) + git rebase --onto=rebase_onto_this rebase_from_this myref + ;; + (*/test-repo-git-rebase-merge) + git -c core.editor=true rebase -i --onto=rebase_onto_this rebase_from_this myref + ;; + (*) + echo >&2 "$0: unrecognized basename" + ;; +esac + + diff --git a/META-FAQ b/META-FAQ new file mode 100644 index 000000000..58c08a06b --- /dev/null +++ b/META-FAQ @@ -0,0 +1,102 @@ +------------------------ +META-FAQ for the Z Shell +------------------------ + +The latest version of this META-FAQ can be found at any of the FTP sites +listed below. + +Author +------ + +Zsh was originally written by Paul Falstad. 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. + +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 +https://zsh.sourceforge.io/. + + +Mailing Lists +------------- + +Zsh has several 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. + + <zsh-security@zsh.org> + Private mailing list (the general public cannot subscribe to it) for discussing + bug reports with security implications, i.e., potential vulnerabilities. + + If you find a security problem in zsh itself, please mail this address. + +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 archived; the archives can be accessed via the +administrative addresses listed above. There is also a hypertext +archive available at +https://www.zsh.org/mla/. + +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 +https://www.zsh.org/FAQ/. The contact address for FAQ-related matters +is <faqmaster@zsh.org>. + +The Zsh Web Page +---------------- + +Zsh has a web page which is located at https://www.zsh.org/. +The contact address for web-related matters is <webmaster@zsh.org>. + +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 +https://zsh.sourceforge.io/Guide/. At the time of writing, chapters +dealing with startup files and their contents and the new completion system +were essentially complete. diff --git a/Src/patchlevel.h.release b/Src/patchlevel.h.release new file mode 100644 index 000000000..b95d69ac2 --- /dev/null +++ b/Src/patchlevel.h.release @@ -0,0 +1 @@ +#define ZSH_PATCHLEVEL "zsh-5.8.1.3-test-0-g3210020" diff --git a/Util/difflog.pl b/Util/difflog.pl deleted file mode 100644 index ff2d4bc16..000000000 --- a/Util/difflog.pl +++ /dev/null @@ -1,145 +0,0 @@ -#!/usr/bin/perl - -use strict; -use IO::File; -use File::Temp qw(tempfile); - -my @differ = qw(diff -bw); - -my $newfn = pop(@ARGV); -my $oldfn = pop(@ARGV); -my (%oldhash, %newhash); - -my $article = q[(?:(?:workers?|users?)/)?\d{4,5}]; - -read_file($newfn, \%newhash); -read_file($oldfn, \%oldhash); - -my @oldentries = reverse sort keys %oldhash; -my @newentries = reverse sort keys %newhash; - -my $old = 0; -my $new = 0; - -while ($old < @oldentries && $new < @newentries) -{ - my $cmp = $oldentries[$old] cmp $newentries[$new]; - if ($cmp > 0) - { - printf("only in %s: %s\n\n", $oldfn, $oldentries[$old++]); - } - elsif ($cmp < 0) - { - printf("only in %s: %s\n\n", $newfn, $newentries[$new++]); - } - else - { - if ($oldhash{$oldentries[$old]} ne $newhash{$newentries[$new]}) { - my($oldfh, $oldtmp) = tempfile('difflog-XXXXXXXX', SUFFIX => '.old', DIR => '/tmp'); - print $oldfh $oldhash{$oldentries[$old]}; - close($oldfh); - my($newfh, $newtmp) = tempfile('difflog-XXXXXXXX', SUFFIX => '.new', DIR => '/tmp'); - print $newfh $newhash{$newentries[$new]}; - close($newfh); - open(DIFF, '-|', @differ, @ARGV, $oldtmp, $newtmp) or die $!; - my @lines = <DIFF>; - close(DIFF); - unlink($oldtmp, $newtmp); - if (@lines) - { - print "diff for ", $oldentries[$old], ":\n"; - map { - s/$oldtmp/$oldfn/; - s/$newtmp/$newfn/; - } @lines; - print @lines, "\n"; - } - } - ++$old; - ++$new; - } -} - -while ($old < @oldentries) -{ - printf("only in %s: %s\n", $oldfn, $oldentries[$old++]); -} - -while ($new < @newentries) -{ - printf("only in %s: %s\n", $newfn, $newentries[$new++]); -} - -sub append_entry -{ - my ($hashref, $entry, $tag, $block) = @_; - - if (exists($hashref->{$entry})) { - $hashref->{$entry} .= "$tag\n$block"; - } else { - $hashref->{$entry} = ''; - if (defined($tag) || defined($block)) { - $hashref->{$entry} .= "$tag\n$block"; - } - } -} - -sub make_entries -{ - my ($hashref, $entry, $tag, $block) = @_; - - if ($entry =~ s/($article)/ARTICLE/) { - my $key = $1; - $key =~ s:workers?/::; - &append_entry($hashref, $key, $tag, $block); - while ($entry =~ s/($article)/ARTICLE/) { - $key = $1; - $key =~ s:workers?/::; - &append_entry($hashref, $key, $tag, $block); - } - } else { - &append_entry($hashref, $entry, $tag, $block); - } -} - -sub read_file -{ - my $fn = shift; - my $hashref = shift; - my $fh = new IO::File($fn, 'r'); - my ($tag, $date, $entry, $block); - - my $attrib = q[(?:\w+\s+)*] . $article; - $attrib = q[(?:[^/]*\D[:,]\s*)?] . $attrib; - $attrib = qq[(?:unposted|$attrib)]; - $attrib = qq[(?:(?:$attrib,\\s*)*$attrib)]; - - $hashref->{unattributed} = $block = ''; - - while (my $line = $fh->getline()) - { - if ($line =~ /(\d{4}-\d\d-\d\d)\s+.+\s+<.+\@.+>/i) { - $date = $1; - $block =~ s/\n*\Z/\n/; - if ($entry) { - &make_entries($hashref, $entry, $tag, $block); - } elsif ($tag) { - $hashref->{unattributed} .= "\n$tag$block"; - } - $entry = $block = ''; - $tag = $line; - } elsif ($line =~ /\* ((?:$attrib)[^:]*):/) { - my $next = $1; - if ($entry) { - $block =~ s/\n*\Z/\n/; - &make_entries($hashref, $entry, $tag, $block); - } - &make_entries($hashref, $next); - $entry = $next; - $block = $line; - } else { - $block .= $line; - } - } - $fh->close(); -} diff --git a/config.h.in b/config.h.in new file mode 100644 index 000000000..2fb5f0327 --- /dev/null +++ b/config.h.in @@ -0,0 +1,1257 @@ +/* config.h.in. Generated from configure.ac by autoheader. */ + +/***** begin user configuration section *****/ + +/* Define this to be the location of your password file */ +#define PASSWD_FILE "/etc/passwd" + +/* Define this to be the name of your NIS/YP password * + * map (if applicable) */ +#define PASSWD_MAP "passwd.byname" + +/* Define to 1 if you want user names to be cached */ +#define CACHE_USERNAMES 1 + +/* Define to 1 if system supports job control */ +#define JOB_CONTROL 1 + +/* Define this if you use "suspended" instead of "stopped" */ +#define USE_SUSPENDED 1 + +/* The default history buffer size in lines */ +#define DEFAULT_HISTSIZE 30 + +/* The default editor for the fc builtin */ +#define DEFAULT_FCEDIT "vi" + +/* The default prefix for temporary files */ +#define DEFAULT_TMPPREFIX "/tmp/zsh" + +/***** end of user configuration section *****/ +/***** shouldn't have to change anything below here *****/ + + + +/* Define to 1 if you want to use dynamically loaded modules on AIX. */ +#undef AIXDYNAMIC + +/* Define to 1 if the isprint() function is broken under UTF-8 locale. */ +#undef BROKEN_ISPRINT + +/* Define to 1 if kill(pid, 0) doesn't return ESRCH, ie BeOS R4.51. */ +#undef BROKEN_KILL_ESRCH + +/* Define to 1 if sigsuspend() is broken */ +#undef BROKEN_POSIX_SIGSUSPEND + +/* Define to 1 if compiler incorrectly cast signed to unsigned. */ +#undef BROKEN_SIGNED_TO_UNSIGNED_CASTING + +/* Define to 1 if tcsetpgrp() doesn't work, ie BeOS R4.51. */ +#undef BROKEN_TCSETPGRP + +/* Define to 1 if you use BSD style signal handling (and can block signals). + */ +#undef BSD_SIGNALS + +/* Undefine if you don't want local features. By default this is defined. */ +#undef CONFIG_LOCALE + +/* Define to a custom value for the ZSH_PATCHLEVEL parameter */ +#undef CUSTOM_PATCHLEVEL + +/* Define to 1 if using 'alloca.c'. */ +#undef C_ALLOCA + +/* Define to 1 if you want to debug zsh. */ +#undef DEBUG + +/* The default path; used when running commands with command -p */ +#undef DEFAULT_PATH + +/* Define default pager used by readnullcmd */ +#undef DEFAULT_READNULLCMD + +/* Define to 1 if you want to avoid calling functions that will require + dynamic NSS modules. */ +#undef DISABLE_DYNAMIC_NSS + +/* Define to 1 if an underscore has to be prepended to dlsym() argument. */ +#undef DLSYM_NEEDS_UNDERSCORE + +/* The extension used for dynamically loaded modules. */ +#undef DL_EXT + +/* Define to 1 if you want to use dynamically loaded modules. */ +#undef DYNAMIC + +/* Define to 1 if multiple modules defining the same symbol are OK. */ +#undef DYNAMIC_NAME_CLASH_OK + +/* Define to 1 if you want use unicode9 character widths. */ +#undef ENABLE_UNICODE9 + +/* Define to 1 if getcwd() calls malloc to allocate memory. */ +#undef GETCWD_CALLS_MALLOC + +/* Define to 1 if the `getpgrp' function requires zero arguments. */ +#undef GETPGRP_VOID + +/* Define to 1 if getpwnam() is faked, ie BeOS R4.51. */ +#undef GETPWNAM_FAKED + +/* The global file to source whenever zsh is run as a login shell; if + undefined, don't source anything */ +#undef GLOBAL_ZLOGIN + +/* The global file to source whenever zsh was run as a login shell. This is + sourced right before exiting. If undefined, don't source anything. */ +#undef GLOBAL_ZLOGOUT + +/* The global file to source whenever zsh is run as a login shell, before + zshrc is read; if undefined, don't source anything. */ +#undef GLOBAL_ZPROFILE + +/* The global file to source absolutely first whenever zsh is run; if + undefined, don't source anything. */ +#undef GLOBAL_ZSHENV + +/* The global file to source whenever zsh is run; if undefined, don't source + anything */ +#undef GLOBAL_ZSHRC + +/* Define if TIOCGWINSZ is defined in sys/ioctl.h but not in termios.h. */ +#undef GWINSZ_IN_SYS_IOCTL + +/* Define to 1 if you have 'alloca', as a function or macro. */ +#undef HAVE_ALLOCA + +/* Define to 1 if <alloca.h> works. */ +#undef HAVE_ALLOCA_H + +/* Define to 1 if you have the <bind/netdb.h> header file. */ +#undef HAVE_BIND_NETDB_H + +/* Define if you have the termcap boolcodes symbol. */ +#undef HAVE_BOOLCODES + +/* Define if you have the terminfo boolnames symbol. */ +#undef HAVE_BOOLNAMES + +/* Define to 1 if you have the `brk' function. */ +#undef HAVE_BRK + +/* Define to 1 if there is a prototype defined for brk() on your system. */ +#undef HAVE_BRK_PROTO + +/* Define to 1 if you have the `canonicalize_file_name' function. */ +#undef HAVE_CANONICALIZE_FILE_NAME + +/* Define to 1 if you have the `cap_get_proc' function. */ +#undef HAVE_CAP_GET_PROC + +/* Define to 1 if you have the `clock_gettime' function. */ +#undef HAVE_CLOCK_GETTIME + +/* Define to 1 if you have the <curses.h> header file. */ +#undef HAVE_CURSES_H + +/* Define to 1 if you have the `cygwin_conv_path' function. */ +#undef HAVE_CYGWIN_CONV_PATH + +/* Define to 1 if you have the `difftime' function. */ +#undef HAVE_DIFFTIME + +/* Define to 1 if you have the <dirent.h> header file, and it defines `DIR'. + */ +#undef HAVE_DIRENT_H + +/* Define to 1 if you have the `dlclose' function. */ +#undef HAVE_DLCLOSE + +/* Define to 1 if you have the `dlerror' function. */ +#undef HAVE_DLERROR + +/* Define to 1 if you have the <dlfcn.h> header file. */ +#undef HAVE_DLFCN_H + +/* Define to 1 if you have the `dlopen' function. */ +#undef HAVE_DLOPEN + +/* Define to 1 if you have the `dlsym' function. */ +#undef HAVE_DLSYM + +/* Define to 1 if you have the <dl.h> header file. */ +#undef HAVE_DL_H + +/* Define to 1 if you have the `endutxent' function. */ +#undef HAVE_ENDUTXENT + +/* Define to 1 if you have the `erand48' function. */ +#undef HAVE_ERAND48 + +/* Define to 1 if you have the <errno.h> header file. */ +#undef HAVE_ERRNO_H + +/* Define to 1 if you have the `faccessx' function. */ +#undef HAVE_FACCESSX + +/* Define to 1 if you have the `fchdir' function. */ +#undef HAVE_FCHDIR + +/* Define to 1 if you have the `fchmod' function. */ +#undef HAVE_FCHMOD + +/* Define to 1 if you have the `fchown' function. */ +#undef HAVE_FCHOWN + +/* Define to 1 if you have the <fcntl.h> header file. */ +#undef HAVE_FCNTL_H + +/* Define to 1 if system has working FIFOs. */ +#undef HAVE_FIFOS + +/* Define to 1 if you have the `fseeko' function. */ +#undef HAVE_FSEEKO + +/* Define to 1 if you have the `fstat' function. */ +#undef HAVE_FSTAT + +/* Define to 1 if you have the `ftello' function. */ +#undef HAVE_FTELLO + +/* Define to 1 if you have the `ftruncate' function. */ +#undef HAVE_FTRUNCATE + +/* Define to 1 if you have the <gdbm.h> header file. */ +#undef HAVE_GDBM_H + +/* Define to 1 if you have the `gdbm_open' function. */ +#undef HAVE_GDBM_OPEN + +/* Define to 1 if you have the `getcchar' function. */ +#undef HAVE_GETCCHAR + +/* Define to 1 if you have the `getcwd' function. */ +#undef HAVE_GETCWD + +/* Define to 1 if you have the `getenv' function. */ +#undef HAVE_GETENV + +/* Define to 1 if you have the `getgrgid' function. */ +#undef HAVE_GETGRGID + +/* Define to 1 if you have the `getgrnam' function. */ +#undef HAVE_GETGRNAM + +/* Define to 1 if you have the `gethostbyname2' function. */ +#undef HAVE_GETHOSTBYNAME2 + +/* Define to 1 if you have the `gethostname' function. */ +#undef HAVE_GETHOSTNAME + +/* Define to 1 if you have the `getipnodebyname' function. */ +#undef HAVE_GETIPNODEBYNAME + +/* Define to 1 if you have the `getlogin' function. */ +#undef HAVE_GETLOGIN + +/* Define to 1 if you have the `getpagesize' function. */ +#undef HAVE_GETPAGESIZE + +/* Define to 1 if you have the `getpwent' function. */ +#undef HAVE_GETPWENT + +/* Define to 1 if you have the `getpwnam' function. */ +#undef HAVE_GETPWNAM + +/* Define to 1 if you have the `getpwuid' function. */ +#undef HAVE_GETPWUID + +/* Define to 1 if you have the `getrlimit' function. */ +#undef HAVE_GETRLIMIT + +/* Define to 1 if you have the `getrusage' function. */ +#undef HAVE_GETRUSAGE + +/* Define to 1 if you have the `gettimeofday' function. */ +#undef HAVE_GETTIMEOFDAY + +/* Define to 1 if you have the `getutent' function. */ +#undef HAVE_GETUTENT + +/* Define to 1 if you have the `getutxent' function. */ +#undef HAVE_GETUTXENT + +/* Define to 1 if you have the `getxattr' function. */ +#undef HAVE_GETXATTR + +/* Define to 1 if you have the `grantpt' function. */ +#undef HAVE_GRANTPT + +/* Define to 1 if you have the <grp.h> header file. */ +#undef HAVE_GRP_H + +/* Define to 1 if you have the `htons' function. */ +#undef HAVE_HTONS + +/* Define to 1 if you have the `iconv' function. */ +#undef HAVE_ICONV + +/* Define to 1 if you have the <iconv.h> header file. */ +#undef HAVE_ICONV_H + +/* Define to 1 if you have the `inet_aton' function. */ +#undef HAVE_INET_ATON + +/* Define to 1 if you have the `inet_ntop' function. */ +#undef HAVE_INET_NTOP + +/* Define to 1 if you have the `inet_pton' function. */ +#undef HAVE_INET_PTON + +/* Define to 1 if you have the `initgroups' function. */ +#undef HAVE_INITGROUPS + +/* Define to 1 if you have the `initscr' function. */ +#undef HAVE_INITSCR + +/* Define to 1 if you have the <inttypes.h> header file. */ +#undef HAVE_INTTYPES_H + +/* Define to 1 if there is a prototype defined for ioctl() on your system. */ +#undef HAVE_IOCTL_PROTO + +/* Define to 1 if you have the `isblank' function. */ +#undef HAVE_ISBLANK + +/* Define to 1 if you have the `isinf' macro or function. */ +#undef HAVE_ISINF + +/* Define to 1 if you have the `isnan' macro or function. */ +#undef HAVE_ISNAN + +/* Define to 1 if you have the `iswblank' function. */ +#undef HAVE_ISWBLANK + +/* Define to 1 if you have the `killpg' function. */ +#undef HAVE_KILLPG + +/* Define to 1 if you have the <langinfo.h> header file. */ +#undef HAVE_LANGINFO_H + +/* Define to 1 if you have the `lchown' function. */ +#undef HAVE_LCHOWN + +/* Define to 1 if you have the `cap' library (-lcap). */ +#undef HAVE_LIBCAP + +/* Define to 1 if you have the <libc.h> header file. */ +#undef HAVE_LIBC_H + +/* Define to 1 if you have the `dl' library (-ldl). */ +#undef HAVE_LIBDL + +/* Define to 1 if you have the `gdbm' library (-lgdbm). */ +#undef HAVE_LIBGDBM + +/* Define to 1 if you have the `m' library (-lm). */ +#undef HAVE_LIBM + +/* Define to 1 if you have the `rt' library (-lrt). */ +#undef HAVE_LIBRT + +/* Define to 1 if you have the `socket' library (-lsocket). */ +#undef HAVE_LIBSOCKET + +/* Define to 1 if you have the <limits.h> header file. */ +#undef HAVE_LIMITS_H + +/* Define to 1 if system has working link(). */ +#undef HAVE_LINK + +/* Define to 1 if you have the `load' function. */ +#undef HAVE_LOAD + +/* Define to 1 if you have the `loadbind' function. */ +#undef HAVE_LOADBIND + +/* Define to 1 if you have the `loadquery' function. */ +#undef HAVE_LOADQUERY + +/* Define to 1 if you have the <locale.h> header file. */ +#undef HAVE_LOCALE_H + +/* Define to 1 if you have the `log2' function. */ +#undef HAVE_LOG2 + +/* Define to 1 if you have the `lstat' function. */ +#undef HAVE_LSTAT + +/* Define to 1 if you have the `memcpy' function. */ +#undef HAVE_MEMCPY + +/* Define to 1 if you have the `memmove' function. */ +#undef HAVE_MEMMOVE + +/* Define to 1 if you have the <memory.h> header file. */ +#undef HAVE_MEMORY_H + +/* Define to 1 if you have the `mkfifo' function. */ +#undef HAVE_MKFIFO + +/* Define to 1 if there is a prototype defined for mknod() on your system. */ +#undef HAVE_MKNOD_PROTO + +/* Define to 1 if you have the `mkstemp' function. */ +#undef HAVE_MKSTEMP + +/* Define to 1 if you have the `mktime' function. */ +#undef HAVE_MKTIME + +/* Define to 1 if you have a working `mmap' system call. */ +#undef HAVE_MMAP + +/* Define to 1 if you have the `msync' function. */ +#undef HAVE_MSYNC + +/* Define to 1 if you have the `munmap' function. */ +#undef HAVE_MUNMAP + +/* Define to 1 if you have the `nanosleep' function. */ +#undef HAVE_NANOSLEEP + +/* Define to 1 if you have the <ncursesw/ncurses.h> header file. */ +#undef HAVE_NCURSESW_NCURSES_H + +/* Define to 1 if you have the <ncursesw/term.h> header file. */ +#undef HAVE_NCURSESW_TERM_H + +/* Define to 1 if you have the <ncurses.h> header file. */ +#undef HAVE_NCURSES_H + +/* Define to 1 if you have the <ncurses/ncurses.h> header file. */ +#undef HAVE_NCURSES_NCURSES_H + +/* Define to 1 if you have the <ncurses/term.h> header file. */ +#undef HAVE_NCURSES_TERM_H + +/* Define to 1 if you have the <ndir.h> header file, and it defines `DIR'. */ +#undef HAVE_NDIR_H + +/* Define to 1 if you have the <netinet/in_systm.h> header file. */ +#undef HAVE_NETINET_IN_SYSTM_H + +/* Define to 1 if you have the `nice' function. */ +#undef HAVE_NICE + +/* Define to 1 if you have the `nis_list' function. */ +#undef HAVE_NIS_LIST + +/* Define to 1 if you have the `nl_langinfo' function. */ +#undef HAVE_NL_LANGINFO + +/* Define to 1 if you have the `ntohs' function. */ +#undef HAVE_NTOHS + +/* Define if you have the termcap numcodes symbol. */ +#undef HAVE_NUMCODES + +/* Define if you have the terminfo numnames symbol. */ +#undef HAVE_NUMNAMES + +/* Define to 1 if you have the `open_memstream' function. */ +#undef HAVE_OPEN_MEMSTREAM + +/* Define to 1 if your termcap library has the ospeed variable */ +#undef HAVE_OSPEED + +/* Define to 1 if you have the `pathconf' function. */ +#undef HAVE_PATHCONF + +/* Define to 1 if you have the `pcre_compile' function. */ +#undef HAVE_PCRE_COMPILE + +/* Define to 1 if you have the `pcre_exec' function. */ +#undef HAVE_PCRE_EXEC + +/* Define to 1 if you have the <pcre.h> header file. */ +#undef HAVE_PCRE_H + +/* Define to 1 if you have the `pcre_study' function. */ +#undef HAVE_PCRE_STUDY + +/* Define to 1 if you have the `poll' function. */ +#undef HAVE_POLL + +/* Define to 1 if you have the <poll.h> header file. */ +#undef HAVE_POLL_H + +/* Define to 1 if you have the `posix_openpt' function. */ +#undef HAVE_POSIX_OPENPT + +/* Define to 1 if the system supports `prctl' to change process name */ +#undef HAVE_PRCTL + +/* Define to 1 if you have the `ptsname' function. */ +#undef HAVE_PTSNAME + +/* Define to 1 if you have the `putenv' function. */ +#undef HAVE_PUTENV + +/* Define to 1 if you have the <pwd.h> header file. */ +#undef HAVE_PWD_H + +/* Define to 1 if you have the `readlink' function. */ +#undef HAVE_READLINK + +/* Define to 1 if you have the `realpath' function. */ +#undef HAVE_REALPATH + +/* Define to 1 if you have the `regcomp' function. */ +#undef HAVE_REGCOMP + +/* Define to 1 if you have the `regerror' function. */ +#undef HAVE_REGERROR + +/* Define to 1 if you have the `regexec' function. */ +#undef HAVE_REGEXEC + +/* Define to 1 if you have the `regfree' function. */ +#undef HAVE_REGFREE + +/* Define to 1 if you have the `resize_term' function. */ +#undef HAVE_RESIZE_TERM + +/* Define to 1 if RLIMIT_AIO_MEM is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_AIO_MEM + +/* Define to 1 if RLIMIT_AIO_OPS is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_AIO_OPS + +/* Define to 1 if RLIMIT_AS is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_AS + +/* Define to 1 if RLIMIT_KQUEUES is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_KQUEUES + +/* Define to 1 if RLIMIT_LOCKS is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_LOCKS + +/* Define to 1 if RLIMIT_MEMLOCK is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_MEMLOCK + +/* Define to 1 if RLIMIT_MSGQUEUE is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_MSGQUEUE + +/* Define to 1 if RLIMIT_NICE is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_NICE + +/* Define to 1 if RLIMIT_NOFILE is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_NOFILE + +/* Define to 1 if RLIMIT_NPROC is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_NPROC + +/* Define to 1 if RLIMIT_NPTS is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_NPTS + +/* Define to 1 if RLIMIT_NTHR is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_NTHR + +/* Define to 1 if RLIMIT_POSIXLOCKS is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_POSIXLOCKS + +/* Define to 1 if RLIMIT_PTHREAD is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_PTHREAD + +/* Define to 1 if RLIMIT_RSS is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_RSS + +/* Define to 1 if RLIMIT_RTPRIO is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_RTPRIO + +/* Define to 1 if RLIMIT_RTTIME is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_RTTIME + +/* Define to 1 if RLIMIT_SBSIZE is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_SBSIZE + +/* Define to 1 if RLIMIT_SIGPENDING is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_SIGPENDING + +/* Define to 1 if RLIMIT_SWAP is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_SWAP + +/* Define to 1 if RLIMIT_TCACHE is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_TCACHE + +/* Define to 1 if RLIMIT_UMTXP is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_UMTXP + +/* Define to 1 if RLIMIT_VMEM is present (whether or not as a macro). */ +#undef HAVE_RLIMIT_VMEM + +/* Define to 1 if you have the `sbrk' function. */ +#undef HAVE_SBRK + +/* Define to 1 if there is a prototype defined for sbrk() on your system. */ +#undef HAVE_SBRK_PROTO + +/* Define to 1 if you have the `scalbn' function. */ +#undef HAVE_SCALBN + +/* Define to 1 if you have the `select' function. */ +#undef HAVE_SELECT + +/* Define to 1 if you have the `setcchar' function. */ +#undef HAVE_SETCCHAR + +/* Define to 1 if you have the `setegid' function. */ +#undef HAVE_SETEGID + +/* Define to 1 if you have the `setenv' function. */ +#undef HAVE_SETENV + +/* Define to 1 if you have the `seteuid' function. */ +#undef HAVE_SETEUID + +/* Define to 1 if you have the `setgid' function. */ +#undef HAVE_SETGID + +/* Define to 1 if you have the `setlocale' function. */ +#undef HAVE_SETLOCALE + +/* Define to 1 if you have the `setpgid' function. */ +#undef HAVE_SETPGID + +/* Define to 1 if you have the `setpgrp' function. */ +#undef HAVE_SETPGRP + +/* Define to 1 if the system supports `setproctitle' to change process name */ +#undef HAVE_SETPROCTITLE + +/* Define to 1 if you have the `setregid' function. */ +#undef HAVE_SETREGID + +/* Define to 1 if you have the `setresgid' function. */ +#undef HAVE_SETRESGID + +/* Define to 1 if you have the `setresuid' function. */ +#undef HAVE_SETRESUID + +/* Define to 1 if you have the `setreuid' function. */ +#undef HAVE_SETREUID + +/* Define to 1 if you have the `setsid' function. */ +#undef HAVE_SETSID + +/* Define to 1 if you have the `setuid' function. */ +#undef HAVE_SETUID + +/* Define to 1 if you have the `setupterm' function. */ +#undef HAVE_SETUPTERM + +/* Define to 1 if you have the `setutxent' function. */ +#undef HAVE_SETUTXENT + +/* Define to 1 if you have the `shl_findsym' function. */ +#undef HAVE_SHL_FINDSYM + +/* Define to 1 if you have the `shl_load' function. */ +#undef HAVE_SHL_LOAD + +/* Define to 1 if you have the `shl_unload' function. */ +#undef HAVE_SHL_UNLOAD + +/* Define to 1 if you have the `sigaction' function. */ +#undef HAVE_SIGACTION + +/* Define to 1 if you have the `sigblock' function. */ +#undef HAVE_SIGBLOCK + +/* Define to 1 if you have the `sighold' function. */ +#undef HAVE_SIGHOLD + +/* Define to 1 if you have the `signgam' function. */ +#undef HAVE_SIGNGAM + +/* Define to 1 if you have the `sigprocmask' function. */ +#undef HAVE_SIGPROCMASK + +/* Define to 1 if you have the `sigrelse' function. */ +#undef HAVE_SIGRELSE + +/* Define to 1 if you have the `sigsetmask' function. */ +#undef HAVE_SIGSETMASK + +/* Define to 1 if you have the `srand_deterministic' function. */ +#undef HAVE_SRAND_DETERMINISTIC + +/* Define to 1 if you have the <stdarg.h> header file. */ +#undef HAVE_STDARG_H + +/* Define to 1 if you have the <stddef.h> header file. */ +#undef HAVE_STDDEF_H + +/* Define to 1 if you have the <stdint.h> header file. */ +#undef HAVE_STDINT_H + +/* Define to 1 if you have the <stdio.h> header file. */ +#undef HAVE_STDIO_H + +/* Define to 1 if you have the <stdlib.h> header file. */ +#undef HAVE_STDLIB_H + +/* Define if you have the termcap strcodes symbol. */ +#undef HAVE_STRCODES + +/* Define to 1 if you have the `strcoll' function and it is properly defined. + */ +#undef HAVE_STRCOLL + +/* Define to 1 if you have the `strerror' function. */ +#undef HAVE_STRERROR + +/* Define to 1 if you have the `strftime' function. */ +#undef HAVE_STRFTIME + +/* Define to 1 if you have the <strings.h> header file. */ +#undef HAVE_STRINGS_H + +/* Define to 1 if you have the <string.h> header file. */ +#undef HAVE_STRING_H + +/* Define if you have the terminfo strnames symbol. */ +#undef HAVE_STRNAMES + +/* Define to 1 if you have the `strptime' function. */ +#undef HAVE_STRPTIME + +/* Define to 1 if you have the `strstr' function. */ +#undef HAVE_STRSTR + +/* Define to 1 if you have the `strtoul' function. */ +#undef HAVE_STRTOUL + +/* Define if your system's struct direct has a member named d_ino. */ +#undef HAVE_STRUCT_DIRECT_D_INO + +/* Define if your system's struct direct has a member named d_stat. */ +#undef HAVE_STRUCT_DIRECT_D_STAT + +/* Define if your system's struct dirent has a member named d_ino. */ +#undef HAVE_STRUCT_DIRENT_D_INO + +/* Define if your system's struct dirent has a member named d_stat. */ +#undef HAVE_STRUCT_DIRENT_D_STAT + +/* Define to 1 if `ru_idrss' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_IDRSS + +/* Define to 1 if `ru_inblock' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_INBLOCK + +/* Define to 1 if `ru_isrss' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_ISRSS + +/* Define to 1 if `ru_ixrss' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_IXRSS + +/* Define to 1 if `ru_majflt' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_MAJFLT + +/* Define to 1 if `ru_maxrss' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_MAXRSS + +/* Define to 1 if `ru_minflt' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_MINFLT + +/* Define to 1 if `ru_msgrcv' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_MSGRCV + +/* Define to 1 if `ru_msgsnd' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_MSGSND + +/* Define to 1 if `ru_nivcsw' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_NIVCSW + +/* Define to 1 if `ru_nsignals' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_NSIGNALS + +/* Define to 1 if `ru_nswap' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_NSWAP + +/* Define to 1 if `ru_nvcsw' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_NVCSW + +/* Define to 1 if `ru_oublock' is a member of `struct rusage'. */ +#undef HAVE_STRUCT_RUSAGE_RU_OUBLOCK + +/* Define if your system's struct sockaddr_in6 has a member named + sin6_scope_id. */ +#undef HAVE_STRUCT_SOCKADDR_IN6_SIN6_SCOPE_ID + +/* Define to 1 if `st_atimensec' is a member of `struct stat'. */ +#undef HAVE_STRUCT_STAT_ST_ATIMENSEC + +/* Define to 1 if `st_atimespec.tv_nsec' is a member of `struct stat'. */ +#undef HAVE_STRUCT_STAT_ST_ATIMESPEC_TV_NSEC + +/* Define to 1 if `st_atim.tv_nsec' is a member of `struct stat'. */ +#undef HAVE_STRUCT_STAT_ST_ATIM_TV_NSEC + +/* Define to 1 if `st_ctimensec' is a member of `struct stat'. */ +#undef HAVE_STRUCT_STAT_ST_CTIMENSEC + +/* Define to 1 if `st_ctimespec.tv_nsec' is a member of `struct stat'. */ +#undef HAVE_STRUCT_STAT_ST_CTIMESPEC_TV_NSEC + +/* Define to 1 if `st_ctim.tv_nsec' is a member of `struct stat'. */ +#undef HAVE_STRUCT_STAT_ST_CTIM_TV_NSEC + +/* Define to 1 if `st_mtimensec' is a member of `struct stat'. */ +#undef HAVE_STRUCT_STAT_ST_MTIMENSEC + +/* Define to 1 if `st_mtimespec.tv_nsec' is a member of `struct stat'. */ +#undef HAVE_STRUCT_STAT_ST_MTIMESPEC_TV_NSEC + +/* Define to 1 if `st_mtim.tv_nsec' is a member of `struct stat'. */ +#undef HAVE_STRUCT_STAT_ST_MTIM_TV_NSEC + +/* Define to 1 if struct timespec is defined by a system header */ +#undef HAVE_STRUCT_TIMESPEC + +/* Define to 1 if struct timezone is defined by a system header */ +#undef HAVE_STRUCT_TIMEZONE + +/* Define to 1 if struct utmp is defined by a system header */ +#undef HAVE_STRUCT_UTMP + +/* Define to 1 if struct utmpx is defined by a system header */ +#undef HAVE_STRUCT_UTMPX + +/* Define if your system's struct utmpx has a member named ut_host. */ +#undef HAVE_STRUCT_UTMPX_UT_HOST + +/* Define if your system's struct utmpx has a member named ut_tv. */ +#undef HAVE_STRUCT_UTMPX_UT_TV + +/* Define if your system's struct utmpx has a member named ut_xtime. */ +#undef HAVE_STRUCT_UTMPX_UT_XTIME + +/* Define if your system's struct utmp has a member named ut_host. */ +#undef HAVE_STRUCT_UTMP_UT_HOST + +/* Define to 1 if you have RFS superroot directory. */ +#undef HAVE_SUPERROOT + +/* Define to 1 if you have the `symlink' function. */ +#undef HAVE_SYMLINK + +/* Define to 1 if you have the `sysconf' function. */ +#undef HAVE_SYSCONF + +/* Define to 1 if you have the <sys/capability.h> header file. */ +#undef HAVE_SYS_CAPABILITY_H + +/* Define to 1 if you have the <sys/dir.h> header file, and it defines `DIR'. + */ +#undef HAVE_SYS_DIR_H + +/* Define to 1 if you have the <sys/filio.h> header file. */ +#undef HAVE_SYS_FILIO_H + +/* Define to 1 if you have the <sys/mman.h> header file. */ +#undef HAVE_SYS_MMAN_H + +/* Define to 1 if you have the <sys/ndir.h> header file, and it defines `DIR'. + */ +#undef HAVE_SYS_NDIR_H + +/* Define to 1 if you have the <sys/param.h> header file. */ +#undef HAVE_SYS_PARAM_H + +/* Define to 1 if you have the <sys/resource.h> header file. */ +#undef HAVE_SYS_RESOURCE_H + +/* Define to 1 if you have the <sys/select.h> header file. */ +#undef HAVE_SYS_SELECT_H + +/* Define to 1 if you have the <sys/stat.h> header file. */ +#undef HAVE_SYS_STAT_H + +/* Define to 1 if you have the <sys/stropts.h> header file. */ +#undef HAVE_SYS_STROPTS_H + +/* Define to 1 if you have the <sys/times.h> header file. */ +#undef HAVE_SYS_TIMES_H + +/* Define to 1 if you have the <sys/time.h> header file. */ +#undef HAVE_SYS_TIME_H + +/* Define to 1 if you have the <sys/types.h> header file. */ +#undef HAVE_SYS_TYPES_H + +/* Define to 1 if you have the <sys/utsname.h> header file. */ +#undef HAVE_SYS_UTSNAME_H + +/* Define to 1 if you have <sys/wait.h> that is POSIX.1 compatible. */ +#undef HAVE_SYS_WAIT_H + +/* Define to 1 if you have the <sys/xattr.h> header file. */ +#undef HAVE_SYS_XATTR_H + +/* Define to 1 if you have the `tcgetattr' function. */ +#undef HAVE_TCGETATTR + +/* Define to 1 if you have the `tcsetpgrp' function. */ +#undef HAVE_TCSETPGRP + +/* Define to 1 if you have the <termcap.h> header file. */ +#undef HAVE_TERMCAP_H + +/* Define to 1 if you have the <termios.h> header file. */ +#undef HAVE_TERMIOS_H + +/* Define to 1 if you have the <termio.h> header file. */ +#undef HAVE_TERMIO_H + +/* Define to 1 if you have the <term.h> header file. */ +#undef HAVE_TERM_H + +/* Define to 1 if you have the `tgamma' function. */ +#undef HAVE_TGAMMA + +/* Define to 1 if you have the `tgetent' function. */ +#undef HAVE_TGETENT + +/* Define to 1 if you have the `tigetflag' function. */ +#undef HAVE_TIGETFLAG + +/* Define to 1 if you have the `tigetnum' function. */ +#undef HAVE_TIGETNUM + +/* Define to 1 if you have the `tigetstr' function. */ +#undef HAVE_TIGETSTR + +/* Define to 1 if you have the `timelocal' function. */ +#undef HAVE_TIMELOCAL + +/* Define to 1 if you have the `uname' function. */ +#undef HAVE_UNAME + +/* Define to 1 if the compiler can initialise a union. */ +#undef HAVE_UNION_INIT + +/* Define to 1 if you have the <unistd.h> header file. */ +#undef HAVE_UNISTD_H + +/* Define to 1 if you have the `unload' function. */ +#undef HAVE_UNLOAD + +/* Define to 1 if you have the `unlockpt' function. */ +#undef HAVE_UNLOCKPT + +/* Define to 1 if you have the `unsetenv' function. */ +#undef HAVE_UNSETENV + +/* Define to 1 if you have the `use_default_colors' function. */ +#undef HAVE_USE_DEFAULT_COLORS + +/* Define to 1 if you have the <utmpx.h> header file. */ +#undef HAVE_UTMPX_H + +/* Define to 1 if you have the <utmp.h> header file. */ +#undef HAVE_UTMP_H + +/* Define to 1 if you have the <varargs.h> header file. */ +#undef HAVE_VARARGS_H + +/* Define to 1 if compiler supports variable-length arrays */ +#undef HAVE_VARIABLE_LENGTH_ARRAYS + +/* Define to 1 if you have the `waddwstr' function. */ +#undef HAVE_WADDWSTR + +/* Define to 1 if you have the `wait3' function. */ +#undef HAVE_WAIT3 + +/* Define to 1 if you have the `waitpid' function. */ +#undef HAVE_WAITPID + +/* Define to 1 if you have the <wchar.h> header file. */ +#undef HAVE_WCHAR_H + +/* Define to 1 if you have the `wctomb' function. */ +#undef HAVE_WCTOMB + +/* Define to 1 if you have the `wget_wch' function. */ +#undef HAVE_WGET_WCH + +/* Define to 1 if you have the `win_wch' function. */ +#undef HAVE_WIN_WCH + +/* Define to 1 if you have the `xw' function. */ +#undef HAVE_XW + +/* Define to 1 if you have the `_mktemp' function. */ +#undef HAVE__MKTEMP + +/* Define to 1 if you want to use dynamically loaded modules on HPUX 10. */ +#undef HPUX10DYNAMIC + +/* Define as const if the declaration of iconv() needs const. */ +#undef ICONV_CONST + +/* Define to 1 if iconv() is linked from libiconv */ +#undef ICONV_FROM_LIBICONV + +/* Define to 1 if ino_t is 64 bit (for large file support). */ +#undef INO_T_IS_64_BIT + +/* Define to 1 if we must include <sys/ioctl.h> to get a prototype for + ioctl(). */ +#undef IOCTL_IN_SYS_IOCTL + +/* Define to 1 if musl is being used as the C library */ +#undef LIBC_MUSL + +/* Definitions used when a long is less than eight byte, to try to provide + some support for eight byte operations. Note that ZSH_64_BIT_TYPE, + OFF_T_IS_64_BIT, INO_T_IS_64_BIT do *not* get defined if long is already 64 + bits, since in that case no special handling is required. Define to 1 if + long is 64 bits */ +#undef LONG_IS_64_BIT + +/* Define to be the machine type (microprocessor class or machine model). */ +#undef MACHTYPE + +/* Define for Maildir support */ +#undef MAILDIR_SUPPORT + +/* Define for function depth limits */ +#undef MAX_FUNCTION_DEPTH + +/* Define to 1 if you want support for multibyte character sets. */ +#undef MULTIBYTE_SUPPORT + +/* Define to 1 if you have ospeed, but it is not defined in termcap.h */ +#undef MUST_DEFINE_OSPEED + +/* Define to 1 if you have no signal blocking at all (bummer). */ +#undef NO_SIGNAL_BLOCKING + +/* Define to 1 if off_t is 64 bit (for large file support) */ +#undef OFF_T_IS_64_BIT + +/* Define to be the name of the operating system. */ +#undef OSTYPE + +/* Define to the address where bug reports for this package should be sent. */ +#undef PACKAGE_BUGREPORT + +/* Define to the full name of this package. */ +#undef PACKAGE_NAME + +/* Define to the full name and version of this package. */ +#undef PACKAGE_STRING + +/* Define to the one symbol short name of this package. */ +#undef PACKAGE_TARNAME + +/* Define to the home page for this package. */ +#undef PACKAGE_URL + +/* Define to the version of this package. */ +#undef PACKAGE_VERSION + +/* Define to the path of the /dev/fd filesystem. */ +#undef PATH_DEV_FD + +/* Define to be location of utmpx file. */ +#undef PATH_UTMPX_FILE + +/* Define to be location of utmp file. */ +#undef PATH_UTMP_FILE + +/* Define to be location of wtmpx file. */ +#undef PATH_WTMPX_FILE + +/* Define to be location of wtmp file. */ +#undef PATH_WTMP_FILE + +/* Define to 1 if you use POSIX style signal handling. */ +#undef POSIX_SIGNALS + +/* Define to 1 if printf and sprintf support %lld for long long. */ +#undef PRINTF_HAS_LLD + +/* Define to 1 if ANSI function prototypes are usable. */ +#undef PROTOTYPES + +/* Define if realpath() accepts NULL as its second argument. */ +#undef REALPATH_ACCEPTS_NULL + +/* Undefine this if you don't want to get a restricted shell when zsh is + exec'd with basename that starts with r. By default this is defined. */ +#undef RESTRICTED_R + +/* Define to 1 if RLIMIT_RSS and RLIMIT_AS both exist and are equal. */ +#undef RLIMIT_RSS_IS_AS + +/* Define to 1 if RLIMIT_VMEM and RLIMIT_AS both exist and are equal. */ +#undef RLIMIT_VMEM_IS_AS + +/* Define to 1 if RLIMIT_VMEM and RLIMIT_RSS both exist and are equal. */ +#undef RLIMIT_VMEM_IS_RSS + +/* Define to 1 if struct rlimit uses long long */ +#undef RLIM_T_IS_LONG_LONG + +/* Define to 1 if struct rlimit uses quad_t. */ +#undef RLIM_T_IS_QUAD_T + +/* Define to 1 if struct rlimit uses unsigned. */ +#undef RLIM_T_IS_UNSIGNED + +/* Define to 1 if select() is defined in <sys/socket.h>, ie BeOS R4.51 */ +#undef SELECT_IN_SYS_SOCKET_H + +/* If using the C implementation of alloca, define if you know the + direction of stack growth for your system; otherwise it will be + automatically deduced at runtime. + STACK_DIRECTION > 0 => grows toward higher addresses + STACK_DIRECTION < 0 => grows toward lower addresses + STACK_DIRECTION = 0 => direction of growth unknown */ +#undef STACK_DIRECTION + +/* Define to 1 if the `S_IS*' macros in <sys/stat.h> do not work properly. */ +#undef STAT_MACROS_BROKEN + +/* Define to 1 if all of the C90 standard headers exist (not just the ones + required in a freestanding environment). This macro is provided for + backward compatibility; new code need not use it. */ +#undef STDC_HEADERS + +/* Define to 1 if you use SYS style signal handling (and can block signals). + */ +#undef SYSV_SIGNALS + +/* Define to 1 if tgetent() accepts NULL as a buffer. */ +#undef TGETENT_ACCEPTS_NULL + +/* Define to what tgetent() returns on success (0 on HP-UX X/Open curses). */ +#undef TGETENT_SUCCESS + +/* Define if there is no prototype for the tgoto() terminal function. */ +#undef TGOTO_PROTO_MISSING + +/* Define if sys/time.h and sys/select.h cannot be both included. */ +#undef TIME_H_SELECT_H_CONFLICTS + +/* Define to 1 if all the kit for using /dev/ptmx for ptys is available. */ +#undef USE_DEV_PTMX + +/* Define to 1 if you need to use the native getcwd. */ +#undef USE_GETCWD + +/* Define to 1 if h_errno is not defined by the system. */ +#undef USE_LOCAL_H_ERRNO + +/* Define to 1 if lseek() can be used for SHIN. */ +#undef USE_LSEEK + +/* Define to 1 if you want to allocate stack memory e.g. with `alloca'. */ +#undef USE_STACK_ALLOCATION + +/* Define to be a string corresponding the vendor of the machine. */ +#undef VENDOR + +/* Define if your should include sys/stream.h and sys/ptem.h. */ +#undef WINSIZE_IN_PTEM + +/* Define if getxattr() etc. require additional MacOS-style arguments */ +#undef XATTR_EXTRA_ARGS + +/* Define to 1 if the zlong type uses 64-bit long int. */ +#undef ZLONG_IS_LONG_64 + +/* Define to 1 if the zlong type uses long long int. */ +#undef ZLONG_IS_LONG_LONG + +/* Define to a 64 bit integer type if there is one, but long is shorter. */ +#undef ZSH_64_BIT_TYPE + +/* Define to an unsigned variant of ZSH_64_BIT_TYPE if that is defined. */ +#undef ZSH_64_BIT_UTYPE + +/* Define to 1 if you want to get debugging information on internal hash + tables. This turns on the `hashinfo' builtin. */ +#undef ZSH_HASH_DEBUG + +/* Define to 1 if some variant of a curses header can be included */ +#undef ZSH_HAVE_CURSES_H + +/* Define to 1 if some variant of term.h can be included */ +#undef ZSH_HAVE_TERM_H + +/* Define to 1 if you want to turn on error checking for heap allocation. */ +#undef ZSH_HEAP_DEBUG + +/* Define to 1 if you want to use zsh's own memory allocation routines */ +#undef ZSH_MEM + +/* Define to 1 if you want to debug zsh memory allocation routines. */ +#undef ZSH_MEM_DEBUG + +/* Define to 1 if you want to turn on warnings of memory allocation errors */ +#undef ZSH_MEM_WARNING + +/* Define if _XOPEN_SOURCE_EXTENDED should not be defined to avoid clashes */ +#undef ZSH_NO_XOPEN + +/* Define to 1 if you want to turn on memory checking for free(). */ +#undef ZSH_SECURE_FREE + +/* Define to 1 if you want to add code for valgrind to debug heap memory. */ +#undef ZSH_VALGRIND + +/* Define to the base type of the third argument of accept */ +#undef ZSOCKLEN_T + +/* Number of bits in a file offset, on hosts where this is settable. */ +#undef _FILE_OFFSET_BITS + +/* Define for large files, on AIX-style hosts. */ +#undef _LARGE_FILES + +/* Define to empty if `const' does not conform to ANSI C. */ +#undef const + +/* Define to `int' if <sys/types.h> doesn't define. */ +#undef gid_t + +/* Define to `unsigned long' if <sys/types.h> doesn't define. */ +#undef ino_t + +/* Define to `int' if <sys/types.h> does not define. */ +#undef mode_t + +/* Define to `long int' if <sys/types.h> does not define. */ +#undef off_t + +/* Define as a signed integer type capable of holding a process identifier. */ +#undef pid_t + +/* Define to the type used in struct rlimit. */ +#undef rlim_t + +/* Define to `unsigned int' if <sys/types.h> or <signal.h> doesn't define */ +#undef sigset_t + +/* Define to `unsigned int' if <sys/types.h> does not define. */ +#undef size_t + +/* Define to `int' if <sys/types.h> doesn't define. */ +#undef uid_t diff --git a/configure b/configure new file mode 100755 index 000000000..745339a8e --- /dev/null +++ b/configure @@ -0,0 +1,16769 @@ +#! /bin/sh +# Guess values for system-dependent variables and create Makefiles. +# Generated by GNU Autoconf 2.71. +# +# +# Copyright (C) 1992-1996, 1998-2017, 2020-2021 Free Software Foundation, +# Inc. +# +# +# This configure script is free software; the Free Software Foundation +# gives unlimited permission to copy, distribute and modify it. +## -------------------- ## +## M4sh Initialization. ## +## -------------------- ## + +# Be more Bourne compatible +DUALCASE=1; export DUALCASE # for MKS sh +as_nop=: +if test ${ZSH_VERSION+y} && (emulate sh) >/dev/null 2>&1 +then : + emulate sh + NULLCMD=: + # Pre-4.2 versions of Zsh do word splitting on ${1+"$@"}, which + # is contrary to our usage. Disable this feature. + alias -g '${1+"$@"}'='"$@"' + setopt NO_GLOB_SUBST +else $as_nop + case `(set -o) 2>/dev/null` in #( + *posix*) : + set -o posix ;; #( + *) : + ;; +esac +fi + + + +# Reset variables that may have inherited troublesome values from +# the environment. + +# IFS needs to be set, to space, tab, and newline, in precisely that order. +# (If _AS_PATH_WALK were called with IFS unset, it would have the +# side effect of setting IFS to empty, thus disabling word splitting.) +# Quoting is to prevent editors from complaining about space-tab. +as_nl=' +' +export as_nl +IFS=" "" $as_nl" + +PS1='$ ' +PS2='> ' +PS4='+ ' + +# Ensure predictable behavior from utilities with locale-dependent output. +LC_ALL=C +export LC_ALL +LANGUAGE=C +export LANGUAGE + +# We cannot yet rely on "unset" to work, but we need these variables +# to be unset--not just set to an empty or harmless value--now, to +# avoid bugs in old shells (e.g. pre-3.0 UWIN ksh). This construct +# also avoids known problems related to "unset" and subshell syntax +# in other old shells (e.g. bash 2.01 and pdksh 5.2.14). +for as_var in BASH_ENV ENV MAIL MAILPATH CDPATH +do eval test \${$as_var+y} \ + && ( (unset $as_var) || exit 1) >/dev/null 2>&1 && unset $as_var || : +done + +# Ensure that fds 0, 1, and 2 are open. +if (exec 3>&0) 2>/dev/null; then :; else exec 0</dev/null; fi +if (exec 3>&1) 2>/dev/null; then :; else exec 1>/dev/null; fi +if (exec 3>&2) ; then :; else exec 2>/dev/null; fi + +# The user is always right. +if ${PATH_SEPARATOR+false} :; then + PATH_SEPARATOR=: + (PATH='/bin;/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 && { + (PATH='/bin:/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 || + PATH_SEPARATOR=';' + } +fi + + +# Find who we are. Look in the path if we contain no directory separator. +as_myself= +case $0 in #(( + *[\\/]* ) as_myself=$0 ;; + *) as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + test -r "$as_dir$0" && as_myself=$as_dir$0 && break + done +IFS=$as_save_IFS + + ;; +esac +# We did not find ourselves, most probably we were run as `sh COMMAND' +# in which case we are not to be found in the path. +if test "x$as_myself" = x; then + as_myself=$0 +fi +if test ! -f "$as_myself"; then + printf "%s\n" "$as_myself: error: cannot find myself; rerun with an absolute file name" >&2 + exit 1 +fi + + +# Use a proper internal environment variable to ensure we don't fall + # into an infinite loop, continuously re-executing ourselves. + if test x"${_as_can_reexec}" != xno && test "x$CONFIG_SHELL" != x; then + _as_can_reexec=no; export _as_can_reexec; + # We cannot yet assume a decent shell, so we have to provide a +# neutralization value for shells without unset; and this also +# works around shells that cannot unset nonexistent variables. +# Preserve -v and -x to the replacement shell. +BASH_ENV=/dev/null +ENV=/dev/null +(unset BASH_ENV) >/dev/null 2>&1 && unset BASH_ENV ENV +case $- in # (((( + *v*x* | *x*v* ) as_opts=-vx ;; + *v* ) as_opts=-v ;; + *x* ) as_opts=-x ;; + * ) as_opts= ;; +esac +exec $CONFIG_SHELL $as_opts "$as_myself" ${1+"$@"} +# Admittedly, this is quite paranoid, since all the known shells bail +# out after a failed `exec'. +printf "%s\n" "$0: could not re-execute with $CONFIG_SHELL" >&2 +exit 255 + fi + # We don't want this to propagate to other subprocesses. + { _as_can_reexec=; unset _as_can_reexec;} +if test "x$CONFIG_SHELL" = x; then + as_bourne_compatible="as_nop=: +if test \${ZSH_VERSION+y} && (emulate sh) >/dev/null 2>&1 +then : + emulate sh + NULLCMD=: + # Pre-4.2 versions of Zsh do word splitting on \${1+\"\$@\"}, which + # is contrary to our usage. Disable this feature. + alias -g '\${1+\"\$@\"}'='\"\$@\"' + setopt NO_GLOB_SUBST +else \$as_nop + case \`(set -o) 2>/dev/null\` in #( + *posix*) : + set -o posix ;; #( + *) : + ;; +esac +fi +" + as_required="as_fn_return () { (exit \$1); } +as_fn_success () { as_fn_return 0; } +as_fn_failure () { as_fn_return 1; } +as_fn_ret_success () { return 0; } +as_fn_ret_failure () { return 1; } + +exitcode=0 +as_fn_success || { exitcode=1; echo as_fn_success failed.; } +as_fn_failure && { exitcode=1; echo as_fn_failure succeeded.; } +as_fn_ret_success || { exitcode=1; echo as_fn_ret_success failed.; } +as_fn_ret_failure && { exitcode=1; echo as_fn_ret_failure succeeded.; } +if ( set x; as_fn_ret_success y && test x = \"\$1\" ) +then : + +else \$as_nop + exitcode=1; echo positional parameters were not saved. +fi +test x\$exitcode = x0 || exit 1 +blah=\$(echo \$(echo blah)) +test x\"\$blah\" = xblah || exit 1 +test -x / || exit 1" + as_suggested=" as_lineno_1=";as_suggested=$as_suggested$LINENO;as_suggested=$as_suggested" as_lineno_1a=\$LINENO + as_lineno_2=";as_suggested=$as_suggested$LINENO;as_suggested=$as_suggested" as_lineno_2a=\$LINENO + eval 'test \"x\$as_lineno_1'\$as_run'\" != \"x\$as_lineno_2'\$as_run'\" && + test \"x\`expr \$as_lineno_1'\$as_run' + 1\`\" = \"x\$as_lineno_2'\$as_run'\"' || exit 1 +test \$(( 1 + 1 )) = 2 || exit 1" + if (eval "$as_required") 2>/dev/null +then : + as_have_required=yes +else $as_nop + as_have_required=no +fi + if test x$as_have_required = xyes && (eval "$as_suggested") 2>/dev/null +then : + +else $as_nop + as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +as_found=false +for as_dir in /bin$PATH_SEPARATOR/usr/bin$PATH_SEPARATOR$PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + as_found=: + case $as_dir in #( + /*) + for as_base in sh bash ksh sh5; do + # Try only shells that exist, to save several forks. + as_shell=$as_dir$as_base + if { test -f "$as_shell" || test -f "$as_shell.exe"; } && + as_run=a "$as_shell" -c "$as_bourne_compatible""$as_required" 2>/dev/null +then : + CONFIG_SHELL=$as_shell as_have_required=yes + if as_run=a "$as_shell" -c "$as_bourne_compatible""$as_suggested" 2>/dev/null +then : + break 2 +fi +fi + done;; + esac + as_found=false +done +IFS=$as_save_IFS +if $as_found +then : + +else $as_nop + if { test -f "$SHELL" || test -f "$SHELL.exe"; } && + as_run=a "$SHELL" -c "$as_bourne_compatible""$as_required" 2>/dev/null +then : + CONFIG_SHELL=$SHELL as_have_required=yes +fi +fi + + + if test "x$CONFIG_SHELL" != x +then : + export CONFIG_SHELL + # We cannot yet assume a decent shell, so we have to provide a +# neutralization value for shells without unset; and this also +# works around shells that cannot unset nonexistent variables. +# Preserve -v and -x to the replacement shell. +BASH_ENV=/dev/null +ENV=/dev/null +(unset BASH_ENV) >/dev/null 2>&1 && unset BASH_ENV ENV +case $- in # (((( + *v*x* | *x*v* ) as_opts=-vx ;; + *v* ) as_opts=-v ;; + *x* ) as_opts=-x ;; + * ) as_opts= ;; +esac +exec $CONFIG_SHELL $as_opts "$as_myself" ${1+"$@"} +# Admittedly, this is quite paranoid, since all the known shells bail +# out after a failed `exec'. +printf "%s\n" "$0: could not re-execute with $CONFIG_SHELL" >&2 +exit 255 +fi + + if test x$as_have_required = xno +then : + printf "%s\n" "$0: This script requires a shell more modern than all" + printf "%s\n" "$0: the shells that I found on your system." + if test ${ZSH_VERSION+y} ; then + printf "%s\n" "$0: In particular, zsh $ZSH_VERSION has bugs and should" + printf "%s\n" "$0: be upgraded to zsh 4.3.4 or later." + else + printf "%s\n" "$0: Please tell bug-autoconf@gnu.org about your system, +$0: including any error possibly output before this +$0: message. Then install a modern shell, or manually run +$0: the script under such a shell if you do have one." + fi + exit 1 +fi +fi +fi +SHELL=${CONFIG_SHELL-/bin/sh} +export SHELL +# Unset more variables known to interfere with behavior of common tools. +CLICOLOR_FORCE= GREP_OPTIONS= +unset CLICOLOR_FORCE GREP_OPTIONS + +## --------------------- ## +## M4sh Shell Functions. ## +## --------------------- ## +# as_fn_unset VAR +# --------------- +# Portably unset VAR. +as_fn_unset () +{ + { eval $1=; unset $1;} +} +as_unset=as_fn_unset + + +# as_fn_set_status STATUS +# ----------------------- +# Set $? to STATUS, without forking. +as_fn_set_status () +{ + return $1 +} # as_fn_set_status + +# as_fn_exit STATUS +# ----------------- +# Exit the shell with STATUS, even in a "trap 0" or "set -e" context. +as_fn_exit () +{ + set +e + as_fn_set_status $1 + exit $1 +} # as_fn_exit +# as_fn_nop +# --------- +# Do nothing but, unlike ":", preserve the value of $?. +as_fn_nop () +{ + return $? +} +as_nop=as_fn_nop + +# as_fn_mkdir_p +# ------------- +# Create "$as_dir" as a directory, including parents if necessary. +as_fn_mkdir_p () +{ + + case $as_dir in #( + -*) as_dir=./$as_dir;; + esac + test -d "$as_dir" || eval $as_mkdir_p || { + as_dirs= + while :; do + case $as_dir in #( + *\'*) as_qdir=`printf "%s\n" "$as_dir" | sed "s/'/'\\\\\\\\''/g"`;; #'( + *) as_qdir=$as_dir;; + esac + as_dirs="'$as_qdir' $as_dirs" + as_dir=`$as_dirname -- "$as_dir" || +$as_expr X"$as_dir" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \ + X"$as_dir" : 'X\(//\)[^/]' \| \ + X"$as_dir" : 'X\(//\)$' \| \ + X"$as_dir" : 'X\(/\)' \| . 2>/dev/null || +printf "%s\n" X"$as_dir" | + sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{ + s//\1/ + q + } + /^X\(\/\/\)[^/].*/{ + s//\1/ + q + } + /^X\(\/\/\)$/{ + s//\1/ + q + } + /^X\(\/\).*/{ + s//\1/ + q + } + s/.*/./; q'` + test -d "$as_dir" && break + done + test -z "$as_dirs" || eval "mkdir $as_dirs" + } || test -d "$as_dir" || as_fn_error $? "cannot create directory $as_dir" + + +} # as_fn_mkdir_p + +# as_fn_executable_p FILE +# ----------------------- +# Test if FILE is an executable regular file. +as_fn_executable_p () +{ + test -f "$1" && test -x "$1" +} # as_fn_executable_p +# as_fn_append VAR VALUE +# ---------------------- +# Append the text in VALUE to the end of the definition contained in VAR. Take +# advantage of any shell optimizations that allow amortized linear growth over +# repeated appends, instead of the typical quadratic growth present in naive +# implementations. +if (eval "as_var=1; as_var+=2; test x\$as_var = x12") 2>/dev/null +then : + eval 'as_fn_append () + { + eval $1+=\$2 + }' +else $as_nop + as_fn_append () + { + eval $1=\$$1\$2 + } +fi # as_fn_append + +# as_fn_arith ARG... +# ------------------ +# Perform arithmetic evaluation on the ARGs, and store the result in the +# global $as_val. Take advantage of shells that can avoid forks. The arguments +# must be portable across $(()) and expr. +if (eval "test \$(( 1 + 1 )) = 2") 2>/dev/null +then : + eval 'as_fn_arith () + { + as_val=$(( $* )) + }' +else $as_nop + as_fn_arith () + { + as_val=`expr "$@" || test $? -eq 1` + } +fi # as_fn_arith + +# as_fn_nop +# --------- +# Do nothing but, unlike ":", preserve the value of $?. +as_fn_nop () +{ + return $? +} +as_nop=as_fn_nop + +# as_fn_error STATUS ERROR [LINENO LOG_FD] +# ---------------------------------------- +# Output "`basename $0`: error: ERROR" to stderr. If LINENO and LOG_FD are +# provided, also output the error to LOG_FD, referencing LINENO. Then exit the +# script with STATUS, using 1 if that was 0. +as_fn_error () +{ + as_status=$1; test $as_status -eq 0 && as_status=1 + if test "$4"; then + as_lineno=${as_lineno-"$3"} as_lineno_stack=as_lineno_stack=$as_lineno_stack + printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: $2" >&$4 + fi + printf "%s\n" "$as_me: error: $2" >&2 + as_fn_exit $as_status +} # as_fn_error + +if expr a : '\(a\)' >/dev/null 2>&1 && + test "X`expr 00001 : '.*\(...\)'`" = X001; then + as_expr=expr +else + as_expr=false +fi + +if (basename -- /) >/dev/null 2>&1 && test "X`basename -- / 2>&1`" = "X/"; then + as_basename=basename +else + as_basename=false +fi + +if (as_dir=`dirname -- /` && test "X$as_dir" = X/) >/dev/null 2>&1; then + as_dirname=dirname +else + as_dirname=false +fi + +as_me=`$as_basename -- "$0" || +$as_expr X/"$0" : '.*/\([^/][^/]*\)/*$' \| \ + X"$0" : 'X\(//\)$' \| \ + X"$0" : 'X\(/\)' \| . 2>/dev/null || +printf "%s\n" X/"$0" | + sed '/^.*\/\([^/][^/]*\)\/*$/{ + s//\1/ + q + } + /^X\/\(\/\/\)$/{ + s//\1/ + q + } + /^X\/\(\/\).*/{ + s//\1/ + q + } + s/.*/./; q'` + +# Avoid depending upon Character Ranges. +as_cr_letters='abcdefghijklmnopqrstuvwxyz' +as_cr_LETTERS='ABCDEFGHIJKLMNOPQRSTUVWXYZ' +as_cr_Letters=$as_cr_letters$as_cr_LETTERS +as_cr_digits='0123456789' +as_cr_alnum=$as_cr_Letters$as_cr_digits + + + as_lineno_1=$LINENO as_lineno_1a=$LINENO + as_lineno_2=$LINENO as_lineno_2a=$LINENO + eval 'test "x$as_lineno_1'$as_run'" != "x$as_lineno_2'$as_run'" && + test "x`expr $as_lineno_1'$as_run' + 1`" = "x$as_lineno_2'$as_run'"' || { + # Blame Lee E. McMahon (1931-1989) for sed's syntax. :-) + sed -n ' + p + /[$]LINENO/= + ' <$as_myself | + sed ' + s/[$]LINENO.*/&-/ + t lineno + b + :lineno + N + :loop + s/[$]LINENO\([^'$as_cr_alnum'_].*\n\)\(.*\)/\2\1\2/ + t loop + s/-\n.*// + ' >$as_me.lineno && + chmod +x "$as_me.lineno" || + { printf "%s\n" "$as_me: error: cannot create $as_me.lineno; rerun with a POSIX shell" >&2; as_fn_exit 1; } + + # If we had to re-execute with $CONFIG_SHELL, we're ensured to have + # already done that, so ensure we don't try to do so again and fall + # in an infinite loop. This has already happened in practice. + _as_can_reexec=no; export _as_can_reexec + # Don't try to exec as it changes $[0], causing all sort of problems + # (the dirname of $[0] is not the place where we might find the + # original and so on. Autoconf is especially sensitive to this). + . "./$as_me.lineno" + # Exit status is that of the last command. + exit +} + + +# Determine whether it's possible to make 'echo' print without a newline. +# These variables are no longer used directly by Autoconf, but are AC_SUBSTed +# for compatibility with existing Makefiles. +ECHO_C= ECHO_N= ECHO_T= +case `echo -n x` in #((((( +-n*) + case `echo 'xy\c'` in + *c*) ECHO_T=' ';; # ECHO_T is single tab character. + xy) ECHO_C='\c';; + *) echo `echo ksh88 bug on AIX 6.1` > /dev/null + ECHO_T=' ';; + esac;; +*) + ECHO_N='-n';; +esac + +# For backward compatibility with old third-party macros, we provide +# the shell variables $as_echo and $as_echo_n. New code should use +# AS_ECHO(["message"]) and AS_ECHO_N(["message"]), respectively. +as_echo='printf %s\n' +as_echo_n='printf %s' + + +rm -f conf$$ conf$$.exe conf$$.file +if test -d conf$$.dir; then + rm -f conf$$.dir/conf$$.file +else + rm -f conf$$.dir + mkdir conf$$.dir 2>/dev/null +fi +if (echo >conf$$.file) 2>/dev/null; then + if ln -s conf$$.file conf$$ 2>/dev/null; then + as_ln_s='ln -s' + # ... but there are two gotchas: + # 1) On MSYS, both `ln -s file dir' and `ln file dir' fail. + # 2) DJGPP < 2.04 has no symlinks; `ln -s' creates a wrapper executable. + # In both cases, we have to default to `cp -pR'. + ln -s conf$$.file conf$$.dir 2>/dev/null && test ! -f conf$$.exe || + as_ln_s='cp -pR' + elif ln conf$$.file conf$$ 2>/dev/null; then + as_ln_s=ln + else + as_ln_s='cp -pR' + fi +else + as_ln_s='cp -pR' +fi +rm -f conf$$ conf$$.exe conf$$.dir/conf$$.file conf$$.file +rmdir conf$$.dir 2>/dev/null + +if mkdir -p . 2>/dev/null; then + as_mkdir_p='mkdir -p "$as_dir"' +else + test -d ./-p && rmdir ./-p + as_mkdir_p=false +fi + +as_test_x='test -x' +as_executable_p=as_fn_executable_p + +# Sed expression to map a string onto a valid CPP name. +as_tr_cpp="eval sed 'y%*$as_cr_letters%P$as_cr_LETTERS%;s%[^_$as_cr_alnum]%_%g'" + +# Sed expression to map a string onto a valid variable name. +as_tr_sh="eval sed 'y%*+%pp%;s%[^_$as_cr_alnum]%_%g'" + + +test -n "$DJDIR" || exec 7<&0 </dev/null +exec 6>&1 + +# Name of the host. +# hostname on some systems (SVR3.2, old GNU/Linux) returns a bogus exit status, +# so uname gets run too. +ac_hostname=`(hostname || uname -n) 2>/dev/null | sed 1q` + +# +# Initializations. +# +ac_default_prefix=/usr/local +ac_clean_files= +ac_config_libobj_dir=. +LIBOBJS= +cross_compiling=no +subdirs= +MFLAGS= +MAKEFLAGS= + +# Identity of this package. +PACKAGE_NAME='' +PACKAGE_TARNAME='' +PACKAGE_VERSION='' +PACKAGE_STRING='' +PACKAGE_BUGREPORT='' +PACKAGE_URL='' + +ac_unique_file="Src/zsh.h" +# Factoring default headers for most tests. +ac_includes_default="\ +#include <stddef.h> +#ifdef HAVE_STDIO_H +# include <stdio.h> +#endif +#ifdef HAVE_STDLIB_H +# include <stdlib.h> +#endif +#ifdef HAVE_STRING_H +# include <string.h> +#endif +#ifdef HAVE_INTTYPES_H +# include <inttypes.h> +#endif +#ifdef HAVE_STDINT_H +# include <stdint.h> +#endif +#ifdef HAVE_STRINGS_H +# include <strings.h> +#endif +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#ifdef HAVE_SYS_STAT_H +# include <sys/stat.h> +#endif +#ifdef HAVE_UNISTD_H +# include <unistd.h> +#endif" + +ac_header_c_list= +ac_func_c_list= +ac_subst_vars='LTLIBOBJS +LIBOBJS +EXTRAZSHOBJS +MOD_IMPORT_FUNCTION +MOD_IMPORT_VARIABLE +MOD_EXPORT +LINKMODS +L +IMPOPT +EXPOPT +EXTRA_LDFLAGS +E +DLLDFLAGS +DLCFLAGS +DLLD +DL_EXT +D +UNINSTLIB +INSTLIB +SHORTBOOTNAMES +RLIMITS_INC_H +ZSH_TERM_H +CURSES_KEYS_H +ZSH_CURSES_H +ERRNO_H +SIGNAL_H +PCRECONF +ANSI2KNR +PAPERSIZE +TEXI2HTML +TEXI2PDF +TEXI2DVI +YODL_OPTIONS +YODL +EGREP +GREP +LN_S +LN +AWK +INSTALL_DATA +INSTALL_SCRIPT +INSTALL_PROGRAM +SET_MAKE +ALLOCA +U +CPP +LIBLDFLAGS +EXELDFLAGS +OBJEXT +EXEEXT +ac_ct_CC +CPPFLAGS +LDFLAGS +CFLAGS +CC +sitescriptdir +scriptdir +FUNCTIONS_SUBDIRS +fixed_sitefndir +sitefndir +fndir +additionalfpath +runhelp +runhelpdir +zlogout +zlogin +zprofile +zshrc +zshenv +tzsh +host_os +host_vendor +host_cpu +host +build_os +build_vendor +build_cpu +build +target_alias +host_alias +build_alias +LIBS +ECHO_T +ECHO_N +ECHO_C +DEFS +mandir +localedir +libdir +psdir +pdfdir +dvidir +htmldir +infodir +docdir +oldincludedir +includedir +runstatedir +localstatedir +sharedstatedir +sysconfdir +datadir +datarootdir +libexecdir +sbindir +bindir +program_transform_name +prefix +exec_prefix +PACKAGE_URL +PACKAGE_BUGREPORT +PACKAGE_STRING +PACKAGE_VERSION +PACKAGE_TARNAME +PACKAGE_NAME +PATH_SEPARATOR +SHELL' +ac_subst_files='CLEAN_MK +CONFIG_MK +DEFS_MK +VERSION_MK' +ac_user_opts=' +enable_option_checking +enable_cppflags +enable_cflags +enable_ldflags +enable_libs +enable_zsh_debug +enable_zsh_mem +enable_zsh_mem_debug +enable_zsh_mem_warning +enable_zsh_secure_free +enable_zsh_heap_debug +enable_zsh_valgrind +enable_zsh_hash_debug +enable_stack_allocation +enable_etcdir +enable_zshenv +enable_zshrc +enable_zprofile +enable_zlogin +enable_zlogout +enable_dynamic +enable_restricted_r +enable_locale +enable_ansi2knr +enable_runhelpdir +enable_fndir +enable_site_fndir +enable_function_subdirs +enable_additional_fpath +enable_scriptdir +enable_site_scriptdir +enable_custom_patchlevel +enable_maildir_support +enable_max_function_depth +enable_readnullcmd +enable_pcre +enable_cap +enable_gdbm +enable_largefile +with_term_lib +with_tcsetpgrp +enable_multibyte +enable_unicode9 +enable_libc_musl +enable_dynamic_nss +' + ac_precious_vars='build_alias +host_alias +target_alias +CC +CFLAGS +LDFLAGS +LIBS +CPPFLAGS +CPP' + + +# Initialize some variables set by options. +ac_init_help= +ac_init_version=false +ac_unrecognized_opts= +ac_unrecognized_sep= +# The variables have the same names as the options, with +# dashes changed to underlines. +cache_file=/dev/null +exec_prefix=NONE +no_create= +no_recursion= +prefix=NONE +program_prefix=NONE +program_suffix=NONE +program_transform_name=s,x,x, +silent= +site= +srcdir= +verbose= +x_includes=NONE +x_libraries=NONE + +# Installation directory options. +# These are left unexpanded so users can "make install exec_prefix=/foo" +# and all the variables that are supposed to be based on exec_prefix +# by default will actually change. +# Use braces instead of parens because sh, perl, etc. also accept them. +# (The list follows the same order as the GNU Coding Standards.) +bindir='${exec_prefix}/bin' +sbindir='${exec_prefix}/sbin' +libexecdir='${exec_prefix}/libexec' +datarootdir='${prefix}/share' +datadir='${datarootdir}' +sysconfdir='${prefix}/etc' +sharedstatedir='${prefix}/com' +localstatedir='${prefix}/var' +runstatedir='${localstatedir}/run' +includedir='${prefix}/include' +oldincludedir='/usr/include' +docdir='${datarootdir}/doc/${PACKAGE}' +infodir='${datarootdir}/info' +htmldir='${docdir}' +dvidir='${docdir}' +pdfdir='${docdir}' +psdir='${docdir}' +libdir='${exec_prefix}/lib' +localedir='${datarootdir}/locale' +mandir='${datarootdir}/man' + +ac_prev= +ac_dashdash= +for ac_option +do + # If the previous option needs an argument, assign it. + if test -n "$ac_prev"; then + eval $ac_prev=\$ac_option + ac_prev= + continue + fi + + case $ac_option in + *=?*) ac_optarg=`expr "X$ac_option" : '[^=]*=\(.*\)'` ;; + *=) ac_optarg= ;; + *) ac_optarg=yes ;; + esac + + case $ac_dashdash$ac_option in + --) + ac_dashdash=yes ;; + + -bindir | --bindir | --bindi | --bind | --bin | --bi) + ac_prev=bindir ;; + -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*) + bindir=$ac_optarg ;; + + -build | --build | --buil | --bui | --bu) + ac_prev=build_alias ;; + -build=* | --build=* | --buil=* | --bui=* | --bu=*) + build_alias=$ac_optarg ;; + + -cache-file | --cache-file | --cache-fil | --cache-fi \ + | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c) + ac_prev=cache_file ;; + -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \ + | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) + cache_file=$ac_optarg ;; + + --config-cache | -C) + cache_file=config.cache ;; + + -datadir | --datadir | --datadi | --datad) + ac_prev=datadir ;; + -datadir=* | --datadir=* | --datadi=* | --datad=*) + datadir=$ac_optarg ;; + + -datarootdir | --datarootdir | --datarootdi | --datarootd | --dataroot \ + | --dataroo | --dataro | --datar) + ac_prev=datarootdir ;; + -datarootdir=* | --datarootdir=* | --datarootdi=* | --datarootd=* \ + | --dataroot=* | --dataroo=* | --dataro=* | --datar=*) + datarootdir=$ac_optarg ;; + + -disable-* | --disable-*) + ac_useropt=`expr "x$ac_option" : 'x-*disable-\(.*\)'` + # Reject names that are not valid shell variable names. + expr "x$ac_useropt" : ".*[^-+._$as_cr_alnum]" >/dev/null && + as_fn_error $? "invalid feature name: \`$ac_useropt'" + ac_useropt_orig=$ac_useropt + ac_useropt=`printf "%s\n" "$ac_useropt" | sed 's/[-+.]/_/g'` + case $ac_user_opts in + *" +"enable_$ac_useropt" +"*) ;; + *) ac_unrecognized_opts="$ac_unrecognized_opts$ac_unrecognized_sep--disable-$ac_useropt_orig" + ac_unrecognized_sep=', ';; + esac + eval enable_$ac_useropt=no ;; + + -docdir | --docdir | --docdi | --doc | --do) + ac_prev=docdir ;; + -docdir=* | --docdir=* | --docdi=* | --doc=* | --do=*) + docdir=$ac_optarg ;; + + -dvidir | --dvidir | --dvidi | --dvid | --dvi | --dv) + ac_prev=dvidir ;; + -dvidir=* | --dvidir=* | --dvidi=* | --dvid=* | --dvi=* | --dv=*) + dvidir=$ac_optarg ;; + + -enable-* | --enable-*) + ac_useropt=`expr "x$ac_option" : 'x-*enable-\([^=]*\)'` + # Reject names that are not valid shell variable names. + expr "x$ac_useropt" : ".*[^-+._$as_cr_alnum]" >/dev/null && + as_fn_error $? "invalid feature name: \`$ac_useropt'" + ac_useropt_orig=$ac_useropt + ac_useropt=`printf "%s\n" "$ac_useropt" | sed 's/[-+.]/_/g'` + case $ac_user_opts in + *" +"enable_$ac_useropt" +"*) ;; + *) ac_unrecognized_opts="$ac_unrecognized_opts$ac_unrecognized_sep--enable-$ac_useropt_orig" + ac_unrecognized_sep=', ';; + esac + eval enable_$ac_useropt=\$ac_optarg ;; + + -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ + | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ + | --exec | --exe | --ex) + ac_prev=exec_prefix ;; + -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \ + | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \ + | --exec=* | --exe=* | --ex=*) + exec_prefix=$ac_optarg ;; + + -gas | --gas | --ga | --g) + # Obsolete; use --with-gas. + with_gas=yes ;; + + -help | --help | --hel | --he | -h) + ac_init_help=long ;; + -help=r* | --help=r* | --hel=r* | --he=r* | -hr*) + ac_init_help=recursive ;; + -help=s* | --help=s* | --hel=s* | --he=s* | -hs*) + ac_init_help=short ;; + + -host | --host | --hos | --ho) + ac_prev=host_alias ;; + -host=* | --host=* | --hos=* | --ho=*) + host_alias=$ac_optarg ;; + + -htmldir | --htmldir | --htmldi | --htmld | --html | --htm | --ht) + ac_prev=htmldir ;; + -htmldir=* | --htmldir=* | --htmldi=* | --htmld=* | --html=* | --htm=* \ + | --ht=*) + htmldir=$ac_optarg ;; + + -includedir | --includedir | --includedi | --included | --include \ + | --includ | --inclu | --incl | --inc) + ac_prev=includedir ;; + -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \ + | --includ=* | --inclu=* | --incl=* | --inc=*) + includedir=$ac_optarg ;; + + -infodir | --infodir | --infodi | --infod | --info | --inf) + ac_prev=infodir ;; + -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*) + infodir=$ac_optarg ;; + + -libdir | --libdir | --libdi | --libd) + ac_prev=libdir ;; + -libdir=* | --libdir=* | --libdi=* | --libd=*) + libdir=$ac_optarg ;; + + -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \ + | --libexe | --libex | --libe) + ac_prev=libexecdir ;; + -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \ + | --libexe=* | --libex=* | --libe=*) + libexecdir=$ac_optarg ;; + + -localedir | --localedir | --localedi | --localed | --locale) + ac_prev=localedir ;; + -localedir=* | --localedir=* | --localedi=* | --localed=* | --locale=*) + localedir=$ac_optarg ;; + + -localstatedir | --localstatedir | --localstatedi | --localstated \ + | --localstate | --localstat | --localsta | --localst | --locals) + ac_prev=localstatedir ;; + -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \ + | --localstate=* | --localstat=* | --localsta=* | --localst=* | --locals=*) + localstatedir=$ac_optarg ;; + + -mandir | --mandir | --mandi | --mand | --man | --ma | --m) + ac_prev=mandir ;; + -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*) + mandir=$ac_optarg ;; + + -nfp | --nfp | --nf) + # Obsolete; use --without-fp. + with_fp=no ;; + + -no-create | --no-create | --no-creat | --no-crea | --no-cre \ + | --no-cr | --no-c | -n) + no_create=yes ;; + + -no-recursion | --no-recursion | --no-recursio | --no-recursi \ + | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) + no_recursion=yes ;; + + -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \ + | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \ + | --oldin | --oldi | --old | --ol | --o) + ac_prev=oldincludedir ;; + -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \ + | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \ + | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*) + oldincludedir=$ac_optarg ;; + + -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) + ac_prev=prefix ;; + -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) + prefix=$ac_optarg ;; + + -program-prefix | --program-prefix | --program-prefi | --program-pref \ + | --program-pre | --program-pr | --program-p) + ac_prev=program_prefix ;; + -program-prefix=* | --program-prefix=* | --program-prefi=* \ + | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*) + program_prefix=$ac_optarg ;; + + -program-suffix | --program-suffix | --program-suffi | --program-suff \ + | --program-suf | --program-su | --program-s) + ac_prev=program_suffix ;; + -program-suffix=* | --program-suffix=* | --program-suffi=* \ + | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*) + program_suffix=$ac_optarg ;; + + -program-transform-name | --program-transform-name \ + | --program-transform-nam | --program-transform-na \ + | --program-transform-n | --program-transform- \ + | --program-transform | --program-transfor \ + | --program-transfo | --program-transf \ + | --program-trans | --program-tran \ + | --progr-tra | --program-tr | --program-t) + ac_prev=program_transform_name ;; + -program-transform-name=* | --program-transform-name=* \ + | --program-transform-nam=* | --program-transform-na=* \ + | --program-transform-n=* | --program-transform-=* \ + | --program-transform=* | --program-transfor=* \ + | --program-transfo=* | --program-transf=* \ + | --program-trans=* | --program-tran=* \ + | --progr-tra=* | --program-tr=* | --program-t=*) + program_transform_name=$ac_optarg ;; + + -pdfdir | --pdfdir | --pdfdi | --pdfd | --pdf | --pd) + ac_prev=pdfdir ;; + -pdfdir=* | --pdfdir=* | --pdfdi=* | --pdfd=* | --pdf=* | --pd=*) + pdfdir=$ac_optarg ;; + + -psdir | --psdir | --psdi | --psd | --ps) + ac_prev=psdir ;; + -psdir=* | --psdir=* | --psdi=* | --psd=* | --ps=*) + psdir=$ac_optarg ;; + + -q | -quiet | --quiet | --quie | --qui | --qu | --q \ + | -silent | --silent | --silen | --sile | --sil) + silent=yes ;; + + -runstatedir | --runstatedir | --runstatedi | --runstated \ + | --runstate | --runstat | --runsta | --runst | --runs \ + | --run | --ru | --r) + ac_prev=runstatedir ;; + -runstatedir=* | --runstatedir=* | --runstatedi=* | --runstated=* \ + | --runstate=* | --runstat=* | --runsta=* | --runst=* | --runs=* \ + | --run=* | --ru=* | --r=*) + runstatedir=$ac_optarg ;; + + -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb) + ac_prev=sbindir ;; + -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \ + | --sbi=* | --sb=*) + sbindir=$ac_optarg ;; + + -sharedstatedir | --sharedstatedir | --sharedstatedi \ + | --sharedstated | --sharedstate | --sharedstat | --sharedsta \ + | --sharedst | --shareds | --shared | --share | --shar \ + | --sha | --sh) + ac_prev=sharedstatedir ;; + -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \ + | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \ + | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \ + | --sha=* | --sh=*) + sharedstatedir=$ac_optarg ;; + + -site | --site | --sit) + ac_prev=site ;; + -site=* | --site=* | --sit=*) + site=$ac_optarg ;; + + -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) + ac_prev=srcdir ;; + -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) + srcdir=$ac_optarg ;; + + -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \ + | --syscon | --sysco | --sysc | --sys | --sy) + ac_prev=sysconfdir ;; + -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \ + | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*) + sysconfdir=$ac_optarg ;; + + -target | --target | --targe | --targ | --tar | --ta | --t) + ac_prev=target_alias ;; + -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) + target_alias=$ac_optarg ;; + + -v | -verbose | --verbose | --verbos | --verbo | --verb) + verbose=yes ;; + + -version | --version | --versio | --versi | --vers | -V) + ac_init_version=: ;; + + -with-* | --with-*) + ac_useropt=`expr "x$ac_option" : 'x-*with-\([^=]*\)'` + # Reject names that are not valid shell variable names. + expr "x$ac_useropt" : ".*[^-+._$as_cr_alnum]" >/dev/null && + as_fn_error $? "invalid package name: \`$ac_useropt'" + ac_useropt_orig=$ac_useropt + ac_useropt=`printf "%s\n" "$ac_useropt" | sed 's/[-+.]/_/g'` + case $ac_user_opts in + *" +"with_$ac_useropt" +"*) ;; + *) ac_unrecognized_opts="$ac_unrecognized_opts$ac_unrecognized_sep--with-$ac_useropt_orig" + ac_unrecognized_sep=', ';; + esac + eval with_$ac_useropt=\$ac_optarg ;; + + -without-* | --without-*) + ac_useropt=`expr "x$ac_option" : 'x-*without-\(.*\)'` + # Reject names that are not valid shell variable names. + expr "x$ac_useropt" : ".*[^-+._$as_cr_alnum]" >/dev/null && + as_fn_error $? "invalid package name: \`$ac_useropt'" + ac_useropt_orig=$ac_useropt + ac_useropt=`printf "%s\n" "$ac_useropt" | sed 's/[-+.]/_/g'` + case $ac_user_opts in + *" +"with_$ac_useropt" +"*) ;; + *) ac_unrecognized_opts="$ac_unrecognized_opts$ac_unrecognized_sep--without-$ac_useropt_orig" + ac_unrecognized_sep=', ';; + esac + eval with_$ac_useropt=no ;; + + --x) + # Obsolete; use --with-x. + with_x=yes ;; + + -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \ + | --x-incl | --x-inc | --x-in | --x-i) + ac_prev=x_includes ;; + -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \ + | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*) + x_includes=$ac_optarg ;; + + -x-libraries | --x-libraries | --x-librarie | --x-librari \ + | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l) + ac_prev=x_libraries ;; + -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \ + | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) + x_libraries=$ac_optarg ;; + + -*) as_fn_error $? "unrecognized option: \`$ac_option' +Try \`$0 --help' for more information" + ;; + + *=*) + ac_envvar=`expr "x$ac_option" : 'x\([^=]*\)='` + # Reject names that are not valid shell variable names. + case $ac_envvar in #( + '' | [0-9]* | *[!_$as_cr_alnum]* ) + as_fn_error $? "invalid variable name: \`$ac_envvar'" ;; + esac + eval $ac_envvar=\$ac_optarg + export $ac_envvar ;; + + *) + # FIXME: should be removed in autoconf 3.0. + printf "%s\n" "$as_me: WARNING: you should use --build, --host, --target" >&2 + expr "x$ac_option" : ".*[^-._$as_cr_alnum]" >/dev/null && + printf "%s\n" "$as_me: WARNING: invalid host type: $ac_option" >&2 + : "${build_alias=$ac_option} ${host_alias=$ac_option} ${target_alias=$ac_option}" + ;; + + esac +done + +if test -n "$ac_prev"; then + ac_option=--`echo $ac_prev | sed 's/_/-/g'` + as_fn_error $? "missing argument to $ac_option" +fi + +if test -n "$ac_unrecognized_opts"; then + case $enable_option_checking in + no) ;; + fatal) as_fn_error $? "unrecognized options: $ac_unrecognized_opts" ;; + *) printf "%s\n" "$as_me: WARNING: unrecognized options: $ac_unrecognized_opts" >&2 ;; + esac +fi + +# Check all directory arguments for consistency. +for ac_var in exec_prefix prefix bindir sbindir libexecdir datarootdir \ + datadir sysconfdir sharedstatedir localstatedir includedir \ + oldincludedir docdir infodir htmldir dvidir pdfdir psdir \ + libdir localedir mandir runstatedir +do + eval ac_val=\$$ac_var + # Remove trailing slashes. + case $ac_val in + */ ) + ac_val=`expr "X$ac_val" : 'X\(.*[^/]\)' \| "X$ac_val" : 'X\(.*\)'` + eval $ac_var=\$ac_val;; + esac + # Be sure to have absolute directory names. + case $ac_val in + [\\/$]* | ?:[\\/]* ) continue;; + NONE | '' ) case $ac_var in *prefix ) continue;; esac;; + esac + as_fn_error $? "expected an absolute directory name for --$ac_var: $ac_val" +done + +# There might be people who depend on the old broken behavior: `$host' +# used to hold the argument of --host etc. +# FIXME: To remove some day. +build=$build_alias +host=$host_alias +target=$target_alias + +# FIXME: To remove some day. +if test "x$host_alias" != x; then + if test "x$build_alias" = x; then + cross_compiling=maybe + elif test "x$build_alias" != "x$host_alias"; then + cross_compiling=yes + fi +fi + +ac_tool_prefix= +test -n "$host_alias" && ac_tool_prefix=$host_alias- + +test "$silent" = yes && exec 6>/dev/null + + +ac_pwd=`pwd` && test -n "$ac_pwd" && +ac_ls_di=`ls -di .` && +ac_pwd_ls_di=`cd "$ac_pwd" && ls -di .` || + as_fn_error $? "working directory cannot be determined" +test "X$ac_ls_di" = "X$ac_pwd_ls_di" || + as_fn_error $? "pwd does not report name of working directory" + + +# Find the source files, if location was not specified. +if test -z "$srcdir"; then + ac_srcdir_defaulted=yes + # Try the directory containing this script, then the parent directory. + ac_confdir=`$as_dirname -- "$as_myself" || +$as_expr X"$as_myself" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \ + X"$as_myself" : 'X\(//\)[^/]' \| \ + X"$as_myself" : 'X\(//\)$' \| \ + X"$as_myself" : 'X\(/\)' \| . 2>/dev/null || +printf "%s\n" X"$as_myself" | + sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{ + s//\1/ + q + } + /^X\(\/\/\)[^/].*/{ + s//\1/ + q + } + /^X\(\/\/\)$/{ + s//\1/ + q + } + /^X\(\/\).*/{ + s//\1/ + q + } + s/.*/./; q'` + srcdir=$ac_confdir + if test ! -r "$srcdir/$ac_unique_file"; then + srcdir=.. + fi +else + ac_srcdir_defaulted=no +fi +if test ! -r "$srcdir/$ac_unique_file"; then + test "$ac_srcdir_defaulted" = yes && srcdir="$ac_confdir or .." + as_fn_error $? "cannot find sources ($ac_unique_file) in $srcdir" +fi +ac_msg="sources are in $srcdir, but \`cd $srcdir' does not work" +ac_abs_confdir=`( + cd "$srcdir" && test -r "./$ac_unique_file" || as_fn_error $? "$ac_msg" + pwd)` +# When building in place, set srcdir=. +if test "$ac_abs_confdir" = "$ac_pwd"; then + srcdir=. +fi +# Remove unnecessary trailing slashes from srcdir. +# Double slashes in file names in object file debugging info +# mess up M-x gdb in Emacs. +case $srcdir in +*/) srcdir=`expr "X$srcdir" : 'X\(.*[^/]\)' \| "X$srcdir" : 'X\(.*\)'`;; +esac +for ac_var in $ac_precious_vars; do + eval ac_env_${ac_var}_set=\${${ac_var}+set} + eval ac_env_${ac_var}_value=\$${ac_var} + eval ac_cv_env_${ac_var}_set=\${${ac_var}+set} + eval ac_cv_env_${ac_var}_value=\$${ac_var} +done + +# +# Report the --help message. +# +if test "$ac_init_help" = "long"; then + # Omit some internal or obsolete options to make the list less imposing. + # This message is too long to be a string in the A/UX 3.1 sh. + cat <<_ACEOF +\`configure' configures this package to adapt to many kinds of systems. + +Usage: $0 [OPTION]... [VAR=VALUE]... + +To assign environment variables (e.g., CC, CFLAGS...), specify them as +VAR=VALUE. See below for descriptions of some of the useful variables. + +Defaults for the options are specified in brackets. + +Configuration: + -h, --help display this help and exit + --help=short display options specific to this package + --help=recursive display the short help of all the included packages + -V, --version display version information and exit + -q, --quiet, --silent do not print \`checking ...' messages + --cache-file=FILE cache test results in FILE [disabled] + -C, --config-cache alias for \`--cache-file=config.cache' + -n, --no-create do not create output files + --srcdir=DIR find the sources in DIR [configure dir or \`..'] + +Installation directories: + --prefix=PREFIX install architecture-independent files in PREFIX + [$ac_default_prefix] + --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX + [PREFIX] + +By default, \`make install' will install all the files in +\`$ac_default_prefix/bin', \`$ac_default_prefix/lib' etc. You can specify +an installation prefix other than \`$ac_default_prefix' using \`--prefix', +for instance \`--prefix=\$HOME'. + +For better control, use the options below. + +Fine tuning of the installation directories: + --bindir=DIR user executables [EPREFIX/bin] + --sbindir=DIR system admin executables [EPREFIX/sbin] + --libexecdir=DIR program executables [EPREFIX/libexec] + --sysconfdir=DIR read-only single-machine data [PREFIX/etc] + --sharedstatedir=DIR modifiable architecture-independent data [PREFIX/com] + --localstatedir=DIR modifiable single-machine data [PREFIX/var] + --runstatedir=DIR modifiable per-process data [LOCALSTATEDIR/run] + --libdir=DIR object code libraries [EPREFIX/lib] + --includedir=DIR C header files [PREFIX/include] + --oldincludedir=DIR C header files for non-gcc [/usr/include] + --datarootdir=DIR read-only arch.-independent data root [PREFIX/share] + --datadir=DIR read-only architecture-independent data [DATAROOTDIR] + --infodir=DIR info documentation [DATAROOTDIR/info] + --localedir=DIR locale-dependent data [DATAROOTDIR/locale] + --mandir=DIR man documentation [DATAROOTDIR/man] + --docdir=DIR documentation root [DATAROOTDIR/doc/PACKAGE] + --htmldir=DIR html documentation [DOCDIR] + --dvidir=DIR dvi documentation [DOCDIR] + --pdfdir=DIR pdf documentation [DOCDIR] + --psdir=DIR ps documentation [DOCDIR] +_ACEOF + + cat <<\_ACEOF + +Program names: + --program-prefix=PREFIX prepend PREFIX to installed program names + --program-suffix=SUFFIX append SUFFIX to installed program names + --program-transform-name=PROGRAM run sed PROGRAM on installed program names + +System types: + --build=BUILD configure for building on BUILD [guessed] + --host=HOST cross-compile to build programs to run on HOST [BUILD] +_ACEOF +fi + +if test -n "$ac_init_help"; then + + cat <<\_ACEOF + +Optional Features: + --disable-option-checking ignore unrecognized --enable/--with options + --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) + --enable-FEATURE[=ARG] include FEATURE [ARG=yes] + --enable-cppflags=... specify C preprocessor flags + --enable-cflags=... specify C compiler flags + --enable-ldflags=... specify linker flags + --enable-libs=... specify link libraries + --enable-zsh-debug compile with debug code and debugger symbols + --enable-zsh-mem compile with zsh memory allocation routines + --enable-zsh-mem-debug debug zsh memory allocation routines + --enable-zsh-mem-warning + print warnings for errors in memory allocation + --enable-zsh-secure-free + turn on error checking for free() + --enable-zsh-heap-debug turn on error checking for heap allocation + --enable-zsh-valgrind turn on support for valgrind debugging of heap + memory + --enable-zsh-hash-debug turn on debugging of internal hash tables + --enable-stack-allocation + allocate stack memory e.g. with `alloca' + --enable-etcdir=DIR the default directory for global zsh scripts + --enable-zshenv=FILE the full pathname of the global zshenv script + --enable-zshrc=FILE the full pathname of the global zshrc script + --enable-zprofile=FILE the full pathname of the global zprofile script + --enable-zlogin=FILE the full pathname of the global zlogin script + --enable-zlogout=FILE the full pathname of the global zlogout script + --disable-dynamic turn off dynamically loaded binary modules + --disable-restricted-r turn off r* invocation for restricted shell + --disable-locale turn off locale features + --enable-ansi2knr translate source to K&R C before compiling + --enable-runhelpdir=DIR the directory in which to install run-help files + --enable-fndir=DIR the directory in which to install functions + --enable-site-fndir=DIR same for site functions (not version specific) + --enable-function-subdirs + install functions in subdirectories + --enable-additional-fpath=DIR + add directories to default function path + --enable-scriptdir=DIR the directory in which to install scripts + --enable-site-scriptdir=DIR + same for site scripts (not version specific) + --enable-custom-patchlevel + set a custom ZSH_PATCHLEVEL value + --enable-maildir-support + enable maildir support in MAIL and MAILPATH + --enable-max-function-depth=MAX + limit function depth to MAX, default 500 + --enable-readnullcmd=PAGER + pager used when READNULLCMD is not set + --enable-pcre enable the search for the pcre library (may create + run-time library dependencies) + --enable-cap enable the search for POSIX capabilities (may + require additional headers to be added by hand) + --enable-gdbm enable the search for the GDBM library (see the + zsh/db/gdbm module) + --disable-largefile omit support for large files + --enable-multibyte support multibyte characters + --enable-unicode9 compile with unicode9 character widths + --enable-libc-musl compile with musl as the C library + --disable-dynamic-nss do not call functions that will require dynamic NSS + modules + +Optional Packages: + --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] + --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) + --with-term-lib=LIBS search space-separated LIBS for terminal handling + --with-tcsetpgrp assumes that tcsetpgrp() exists and works correctly + +Some influential environment variables: + CC C compiler command + CFLAGS C compiler flags + LDFLAGS linker flags, e.g. -L<lib dir> if you have libraries in a + nonstandard directory <lib dir> + LIBS libraries to pass to the linker, e.g. -l<library> + CPPFLAGS (Objective) C/C++ preprocessor flags, e.g. -I<include dir> if + you have headers in a nonstandard directory <include dir> + CPP C preprocessor + +Use these variables to override the choices made by `configure' or to help +it to find libraries and programs with nonstandard names/locations. + +Report bugs to the package provider. +_ACEOF +ac_status=$? +fi + +if test "$ac_init_help" = "recursive"; then + # If there are subdirs, report their specific --help. + for ac_dir in : $ac_subdirs_all; do test "x$ac_dir" = x: && continue + test -d "$ac_dir" || + { cd "$srcdir" && ac_pwd=`pwd` && srcdir=. && test -d "$ac_dir"; } || + continue + ac_builddir=. + +case "$ac_dir" in +.) ac_dir_suffix= ac_top_builddir_sub=. ac_top_build_prefix= ;; +*) + ac_dir_suffix=/`printf "%s\n" "$ac_dir" | sed 's|^\.[\\/]||'` + # A ".." for each directory in $ac_dir_suffix. + ac_top_builddir_sub=`printf "%s\n" "$ac_dir_suffix" | sed 's|/[^\\/]*|/..|g;s|/||'` + case $ac_top_builddir_sub in + "") ac_top_builddir_sub=. ac_top_build_prefix= ;; + *) ac_top_build_prefix=$ac_top_builddir_sub/ ;; + esac ;; +esac +ac_abs_top_builddir=$ac_pwd +ac_abs_builddir=$ac_pwd$ac_dir_suffix +# for backward compatibility: +ac_top_builddir=$ac_top_build_prefix + +case $srcdir in + .) # We are building in place. + ac_srcdir=. + ac_top_srcdir=$ac_top_builddir_sub + ac_abs_top_srcdir=$ac_pwd ;; + [\\/]* | ?:[\\/]* ) # Absolute name. + ac_srcdir=$srcdir$ac_dir_suffix; + ac_top_srcdir=$srcdir + ac_abs_top_srcdir=$srcdir ;; + *) # Relative name. + ac_srcdir=$ac_top_build_prefix$srcdir$ac_dir_suffix + ac_top_srcdir=$ac_top_build_prefix$srcdir + ac_abs_top_srcdir=$ac_pwd/$srcdir ;; +esac +ac_abs_srcdir=$ac_abs_top_srcdir$ac_dir_suffix + + cd "$ac_dir" || { ac_status=$?; continue; } + # Check for configure.gnu first; this name is used for a wrapper for + # Metaconfig's "Configure" on case-insensitive file systems. + if test -f "$ac_srcdir/configure.gnu"; then + echo && + $SHELL "$ac_srcdir/configure.gnu" --help=recursive + elif test -f "$ac_srcdir/configure"; then + echo && + $SHELL "$ac_srcdir/configure" --help=recursive + else + printf "%s\n" "$as_me: WARNING: no configuration information is in $ac_dir" >&2 + fi || ac_status=$? + cd "$ac_pwd" || { ac_status=$?; break; } + done +fi + +test -n "$ac_init_help" && exit $ac_status +if $ac_init_version; then + cat <<\_ACEOF +configure +generated by GNU Autoconf 2.71 + +Copyright (C) 2021 Free Software Foundation, Inc. +This configure script is free software; the Free Software Foundation +gives unlimited permission to copy, distribute and modify it. +_ACEOF + exit +fi + +## ------------------------ ## +## Autoconf initialization. ## +## ------------------------ ## + +# ac_fn_c_try_compile LINENO +# -------------------------- +# Try to compile conftest.$ac_ext, and return whether this succeeded. +ac_fn_c_try_compile () +{ + as_lineno=${as_lineno-"$1"} as_lineno_stack=as_lineno_stack=$as_lineno_stack + rm -f conftest.$ac_objext conftest.beam + if { { ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval ac_try_echo="\"\$as_me:${as_lineno-$LINENO}: $ac_try_echo\"" +printf "%s\n" "$ac_try_echo"; } >&5 + (eval "$ac_compile") 2>conftest.err + ac_status=$? + if test -s conftest.err; then + grep -v '^ *+' conftest.err >conftest.er1 + cat conftest.er1 >&5 + mv -f conftest.er1 conftest.err + fi + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest.$ac_objext +then : + ac_retval=0 +else $as_nop + printf "%s\n" "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_retval=1 +fi + eval $as_lineno_stack; ${as_lineno_stack:+:} unset as_lineno + as_fn_set_status $ac_retval + +} # ac_fn_c_try_compile + +# ac_fn_c_try_cpp LINENO +# ---------------------- +# Try to preprocess conftest.$ac_ext, and return whether this succeeded. +ac_fn_c_try_cpp () +{ + as_lineno=${as_lineno-"$1"} as_lineno_stack=as_lineno_stack=$as_lineno_stack + if { { ac_try="$ac_cpp conftest.$ac_ext" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval ac_try_echo="\"\$as_me:${as_lineno-$LINENO}: $ac_try_echo\"" +printf "%s\n" "$ac_try_echo"; } >&5 + (eval "$ac_cpp conftest.$ac_ext") 2>conftest.err + ac_status=$? + if test -s conftest.err; then + grep -v '^ *+' conftest.err >conftest.er1 + cat conftest.er1 >&5 + mv -f conftest.er1 conftest.err + fi + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; } > conftest.i && { + test -z "$ac_c_preproc_warn_flag$ac_c_werror_flag" || + test ! -s conftest.err + } +then : + ac_retval=0 +else $as_nop + printf "%s\n" "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_retval=1 +fi + eval $as_lineno_stack; ${as_lineno_stack:+:} unset as_lineno + as_fn_set_status $ac_retval + +} # ac_fn_c_try_cpp + +# ac_fn_c_check_type LINENO TYPE VAR INCLUDES +# ------------------------------------------- +# Tests whether TYPE exists after having included INCLUDES, setting cache +# variable VAR accordingly. +ac_fn_c_check_type () +{ + as_lineno=${as_lineno-"$1"} as_lineno_stack=as_lineno_stack=$as_lineno_stack + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $2" >&5 +printf %s "checking for $2... " >&6; } +if eval test \${$3+y} +then : + printf %s "(cached) " >&6 +else $as_nop + eval "$3=no" + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$4 +int +main (void) +{ +if (sizeof ($2)) + return 0; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$4 +int +main (void) +{ +if (sizeof (($2))) + return 0; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + +else $as_nop + eval "$3=yes" +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +eval ac_res=\$$3 + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_res" >&5 +printf "%s\n" "$ac_res" >&6; } + eval $as_lineno_stack; ${as_lineno_stack:+:} unset as_lineno + +} # ac_fn_c_check_type + +# ac_fn_c_check_header_compile LINENO HEADER VAR INCLUDES +# ------------------------------------------------------- +# Tests whether HEADER exists and can be compiled using the include files in +# INCLUDES, setting the cache variable VAR accordingly. +ac_fn_c_check_header_compile () +{ + as_lineno=${as_lineno-"$1"} as_lineno_stack=as_lineno_stack=$as_lineno_stack + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $2" >&5 +printf %s "checking for $2... " >&6; } +if eval test \${$3+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$4 +#include <$2> +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + eval "$3=yes" +else $as_nop + eval "$3=no" +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +eval ac_res=\$$3 + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_res" >&5 +printf "%s\n" "$ac_res" >&6; } + eval $as_lineno_stack; ${as_lineno_stack:+:} unset as_lineno + +} # ac_fn_c_check_header_compile + +# ac_fn_c_try_link LINENO +# ----------------------- +# Try to link conftest.$ac_ext, and return whether this succeeded. +ac_fn_c_try_link () +{ + as_lineno=${as_lineno-"$1"} as_lineno_stack=as_lineno_stack=$as_lineno_stack + rm -f conftest.$ac_objext conftest.beam conftest$ac_exeext + if { { ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval ac_try_echo="\"\$as_me:${as_lineno-$LINENO}: $ac_try_echo\"" +printf "%s\n" "$ac_try_echo"; } >&5 + (eval "$ac_link") 2>conftest.err + ac_status=$? + if test -s conftest.err; then + grep -v '^ *+' conftest.err >conftest.er1 + cat conftest.er1 >&5 + mv -f conftest.er1 conftest.err + fi + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; } && { + test -z "$ac_c_werror_flag" || + test ! -s conftest.err + } && test -s conftest$ac_exeext && { + test "$cross_compiling" = yes || + test -x conftest$ac_exeext + } +then : + ac_retval=0 +else $as_nop + printf "%s\n" "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_retval=1 +fi + # Delete the IPA/IPO (Inter Procedural Analysis/Optimization) information + # created by the PGI compiler (conftest_ipa8_conftest.oo), as it would + # interfere with the next link command; also delete a directory that is + # left behind by Apple's compiler. We do this before executing the actions. + rm -rf conftest.dSYM conftest_ipa8_conftest.oo + eval $as_lineno_stack; ${as_lineno_stack:+:} unset as_lineno + as_fn_set_status $ac_retval + +} # ac_fn_c_try_link + +# ac_fn_c_try_run LINENO +# ---------------------- +# Try to run conftest.$ac_ext, and return whether this succeeded. Assumes that +# executables *can* be run. +ac_fn_c_try_run () +{ + as_lineno=${as_lineno-"$1"} as_lineno_stack=as_lineno_stack=$as_lineno_stack + if { { ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval ac_try_echo="\"\$as_me:${as_lineno-$LINENO}: $ac_try_echo\"" +printf "%s\n" "$ac_try_echo"; } >&5 + (eval "$ac_link") 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; } && { ac_try='./conftest$ac_exeext' + { { case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval ac_try_echo="\"\$as_me:${as_lineno-$LINENO}: $ac_try_echo\"" +printf "%s\n" "$ac_try_echo"; } >&5 + (eval "$ac_try") 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } +then : + ac_retval=0 +else $as_nop + printf "%s\n" "$as_me: program exited with status $ac_status" >&5 + printf "%s\n" "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + + ac_retval=$ac_status +fi + rm -rf conftest.dSYM conftest_ipa8_conftest.oo + eval $as_lineno_stack; ${as_lineno_stack:+:} unset as_lineno + as_fn_set_status $ac_retval + +} # ac_fn_c_try_run + +# ac_fn_c_check_func LINENO FUNC VAR +# ---------------------------------- +# Tests whether FUNC exists, setting the cache variable VAR accordingly +ac_fn_c_check_func () +{ + as_lineno=${as_lineno-"$1"} as_lineno_stack=as_lineno_stack=$as_lineno_stack + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $2" >&5 +printf %s "checking for $2... " >&6; } +if eval test \${$3+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +/* Define $2 to an innocuous variant, in case <limits.h> declares $2. + For example, HP-UX 11i <limits.h> declares gettimeofday. */ +#define $2 innocuous_$2 + +/* System header to define __stub macros and hopefully few prototypes, + which can conflict with char $2 (); below. */ + +#include <limits.h> +#undef $2 + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +#ifdef __cplusplus +extern "C" +#endif +char $2 (); +/* The GNU C library defines this for functions which it implements + to always fail with ENOSYS. Some functions are actually named + something starting with __ and the normal name is an alias. */ +#if defined __stub_$2 || defined __stub___$2 +choke me +#endif + +int +main (void) +{ +return $2 (); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + eval "$3=yes" +else $as_nop + eval "$3=no" +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +fi +eval ac_res=\$$3 + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_res" >&5 +printf "%s\n" "$ac_res" >&6; } + eval $as_lineno_stack; ${as_lineno_stack:+:} unset as_lineno + +} # ac_fn_c_check_func + +# ac_fn_check_decl LINENO SYMBOL VAR INCLUDES EXTRA-OPTIONS FLAG-VAR +# ------------------------------------------------------------------ +# Tests whether SYMBOL is declared in INCLUDES, setting cache variable VAR +# accordingly. Pass EXTRA-OPTIONS to the compiler, using FLAG-VAR. +ac_fn_check_decl () +{ + as_lineno=${as_lineno-"$1"} as_lineno_stack=as_lineno_stack=$as_lineno_stack + as_decl_name=`echo $2|sed 's/ *(.*//'` + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether $as_decl_name is declared" >&5 +printf %s "checking whether $as_decl_name is declared... " >&6; } +if eval test \${$3+y} +then : + printf %s "(cached) " >&6 +else $as_nop + as_decl_use=`echo $2|sed -e 's/(/((/' -e 's/)/) 0&/' -e 's/,/) 0& (/g'` + eval ac_save_FLAGS=\$$6 + as_fn_append $6 " $5" + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$4 +int +main (void) +{ +#ifndef $as_decl_name +#ifdef __cplusplus + (void) $as_decl_use; +#else + (void) $as_decl_name; +#endif +#endif + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + eval "$3=yes" +else $as_nop + eval "$3=no" +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + eval $6=\$ac_save_FLAGS + +fi +eval ac_res=\$$3 + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_res" >&5 +printf "%s\n" "$ac_res" >&6; } + eval $as_lineno_stack; ${as_lineno_stack:+:} unset as_lineno + +} # ac_fn_check_decl + +# ac_fn_c_check_member LINENO AGGR MEMBER VAR INCLUDES +# ---------------------------------------------------- +# Tries to find if the field MEMBER exists in type AGGR, after including +# INCLUDES, setting cache variable VAR accordingly. +ac_fn_c_check_member () +{ + as_lineno=${as_lineno-"$1"} as_lineno_stack=as_lineno_stack=$as_lineno_stack + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $2.$3" >&5 +printf %s "checking for $2.$3... " >&6; } +if eval test \${$4+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$5 +int +main (void) +{ +static $2 ac_aggr; +if (ac_aggr.$3) +return 0; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + eval "$4=yes" +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$5 +int +main (void) +{ +static $2 ac_aggr; +if (sizeof ac_aggr.$3) +return 0; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + eval "$4=yes" +else $as_nop + eval "$4=no" +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +eval ac_res=\$$4 + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_res" >&5 +printf "%s\n" "$ac_res" >&6; } + eval $as_lineno_stack; ${as_lineno_stack:+:} unset as_lineno + +} # ac_fn_c_check_member +ac_configure_args_raw= +for ac_arg +do + case $ac_arg in + *\'*) + ac_arg=`printf "%s\n" "$ac_arg" | sed "s/'/'\\\\\\\\''/g"` ;; + esac + as_fn_append ac_configure_args_raw " '$ac_arg'" +done + +case $ac_configure_args_raw in + *$as_nl*) + ac_safe_unquote= ;; + *) + ac_unsafe_z='|&;<>()$`\\"*?[ '' ' # This string ends in space, tab. + ac_unsafe_a="$ac_unsafe_z#~" + ac_safe_unquote="s/ '\\([^$ac_unsafe_a][^$ac_unsafe_z]*\\)'/ \\1/g" + ac_configure_args_raw=` printf "%s\n" "$ac_configure_args_raw" | sed "$ac_safe_unquote"`;; +esac + +cat >config.log <<_ACEOF +This file contains any messages produced by compilers while +running configure, to aid debugging if configure makes a mistake. + +It was created by $as_me, which was +generated by GNU Autoconf 2.71. Invocation command line was + + $ $0$ac_configure_args_raw + +_ACEOF +exec 5>>config.log +{ +cat <<_ASUNAME +## --------- ## +## Platform. ## +## --------- ## + +hostname = `(hostname || uname -n) 2>/dev/null | sed 1q` +uname -m = `(uname -m) 2>/dev/null || echo unknown` +uname -r = `(uname -r) 2>/dev/null || echo unknown` +uname -s = `(uname -s) 2>/dev/null || echo unknown` +uname -v = `(uname -v) 2>/dev/null || echo unknown` + +/usr/bin/uname -p = `(/usr/bin/uname -p) 2>/dev/null || echo unknown` +/bin/uname -X = `(/bin/uname -X) 2>/dev/null || echo unknown` + +/bin/arch = `(/bin/arch) 2>/dev/null || echo unknown` +/usr/bin/arch -k = `(/usr/bin/arch -k) 2>/dev/null || echo unknown` +/usr/convex/getsysinfo = `(/usr/convex/getsysinfo) 2>/dev/null || echo unknown` +/usr/bin/hostinfo = `(/usr/bin/hostinfo) 2>/dev/null || echo unknown` +/bin/machine = `(/bin/machine) 2>/dev/null || echo unknown` +/usr/bin/oslevel = `(/usr/bin/oslevel) 2>/dev/null || echo unknown` +/bin/universe = `(/bin/universe) 2>/dev/null || echo unknown` + +_ASUNAME + +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + printf "%s\n" "PATH: $as_dir" + done +IFS=$as_save_IFS + +} >&5 + +cat >&5 <<_ACEOF + + +## ----------- ## +## Core tests. ## +## ----------- ## + +_ACEOF + + +# Keep a trace of the command line. +# Strip out --no-create and --no-recursion so they do not pile up. +# Strip out --silent because we don't want to record it for future runs. +# Also quote any args containing shell meta-characters. +# Make two passes to allow for proper duplicate-argument suppression. +ac_configure_args= +ac_configure_args0= +ac_configure_args1= +ac_must_keep_next=false +for ac_pass in 1 2 +do + for ac_arg + do + case $ac_arg in + -no-create | --no-c* | -n | -no-recursion | --no-r*) continue ;; + -q | -quiet | --quiet | --quie | --qui | --qu | --q \ + | -silent | --silent | --silen | --sile | --sil) + continue ;; + *\'*) + ac_arg=`printf "%s\n" "$ac_arg" | sed "s/'/'\\\\\\\\''/g"` ;; + esac + case $ac_pass in + 1) as_fn_append ac_configure_args0 " '$ac_arg'" ;; + 2) + as_fn_append ac_configure_args1 " '$ac_arg'" + if test $ac_must_keep_next = true; then + ac_must_keep_next=false # Got value, back to normal. + else + case $ac_arg in + *=* | --config-cache | -C | -disable-* | --disable-* \ + | -enable-* | --enable-* | -gas | --g* | -nfp | --nf* \ + | -q | -quiet | --q* | -silent | --sil* | -v | -verb* \ + | -with-* | --with-* | -without-* | --without-* | --x) + case "$ac_configure_args0 " in + "$ac_configure_args1"*" '$ac_arg' "* ) continue ;; + esac + ;; + -* ) ac_must_keep_next=true ;; + esac + fi + as_fn_append ac_configure_args " '$ac_arg'" + ;; + esac + done +done +{ ac_configure_args0=; unset ac_configure_args0;} +{ ac_configure_args1=; unset ac_configure_args1;} + +# When interrupted or exit'd, cleanup temporary files, and complete +# config.log. We remove comments because anyway the quotes in there +# would cause problems or look ugly. +# WARNING: Use '\'' to represent an apostrophe within the trap. +# WARNING: Do not start the trap code with a newline, due to a FreeBSD 4.0 bug. +trap 'exit_status=$? + # Sanitize IFS. + IFS=" "" $as_nl" + # Save into config.log some information that might help in debugging. + { + echo + + printf "%s\n" "## ---------------- ## +## Cache variables. ## +## ---------------- ##" + echo + # The following way of writing the cache mishandles newlines in values, +( + for ac_var in `(set) 2>&1 | sed -n '\''s/^\([a-zA-Z_][a-zA-Z0-9_]*\)=.*/\1/p'\''`; do + eval ac_val=\$$ac_var + case $ac_val in #( + *${as_nl}*) + case $ac_var in #( + *_cv_*) { printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: cache variable $ac_var contains a newline" >&5 +printf "%s\n" "$as_me: WARNING: cache variable $ac_var contains a newline" >&2;} ;; + esac + case $ac_var in #( + _ | IFS | as_nl) ;; #( + BASH_ARGV | BASH_SOURCE) eval $ac_var= ;; #( + *) { eval $ac_var=; unset $ac_var;} ;; + esac ;; + esac + done + (set) 2>&1 | + case $as_nl`(ac_space='\'' '\''; set) 2>&1` in #( + *${as_nl}ac_space=\ *) + sed -n \ + "s/'\''/'\''\\\\'\'''\''/g; + s/^\\([_$as_cr_alnum]*_cv_[_$as_cr_alnum]*\\)=\\(.*\\)/\\1='\''\\2'\''/p" + ;; #( + *) + sed -n "/^[_$as_cr_alnum]*_cv_[_$as_cr_alnum]*=/p" + ;; + esac | + sort +) + echo + + printf "%s\n" "## ----------------- ## +## Output variables. ## +## ----------------- ##" + echo + for ac_var in $ac_subst_vars + do + eval ac_val=\$$ac_var + case $ac_val in + *\'\''*) ac_val=`printf "%s\n" "$ac_val" | sed "s/'\''/'\''\\\\\\\\'\'''\''/g"`;; + esac + printf "%s\n" "$ac_var='\''$ac_val'\''" + done | sort + echo + + if test -n "$ac_subst_files"; then + printf "%s\n" "## ------------------- ## +## File substitutions. ## +## ------------------- ##" + echo + for ac_var in $ac_subst_files + do + eval ac_val=\$$ac_var + case $ac_val in + *\'\''*) ac_val=`printf "%s\n" "$ac_val" | sed "s/'\''/'\''\\\\\\\\'\'''\''/g"`;; + esac + printf "%s\n" "$ac_var='\''$ac_val'\''" + done | sort + echo + fi + + if test -s confdefs.h; then + printf "%s\n" "## ----------- ## +## confdefs.h. ## +## ----------- ##" + echo + cat confdefs.h + echo + fi + test "$ac_signal" != 0 && + printf "%s\n" "$as_me: caught signal $ac_signal" + printf "%s\n" "$as_me: exit $exit_status" + } >&5 + rm -f core *.core core.conftest.* && + rm -f -r conftest* confdefs* conf$$* $ac_clean_files && + exit $exit_status +' 0 +for ac_signal in 1 2 13 15; do + trap 'ac_signal='$ac_signal'; as_fn_exit 1' $ac_signal +done +ac_signal=0 + +# confdefs.h avoids OS command line length limits that DEFS can exceed. +rm -f -r conftest* confdefs.h + +printf "%s\n" "/* confdefs.h */" > confdefs.h + +# Predefined preprocessor variables. + +printf "%s\n" "#define PACKAGE_NAME \"$PACKAGE_NAME\"" >>confdefs.h + +printf "%s\n" "#define PACKAGE_TARNAME \"$PACKAGE_TARNAME\"" >>confdefs.h + +printf "%s\n" "#define PACKAGE_VERSION \"$PACKAGE_VERSION\"" >>confdefs.h + +printf "%s\n" "#define PACKAGE_STRING \"$PACKAGE_STRING\"" >>confdefs.h + +printf "%s\n" "#define PACKAGE_BUGREPORT \"$PACKAGE_BUGREPORT\"" >>confdefs.h + +printf "%s\n" "#define PACKAGE_URL \"$PACKAGE_URL\"" >>confdefs.h + + +# Let the site file select an alternate cache file if it wants to. +# Prefer an explicitly selected file to automatically selected ones. +if test -n "$CONFIG_SITE"; then + ac_site_files="$CONFIG_SITE" +elif test "x$prefix" != xNONE; then + ac_site_files="$prefix/share/config.site $prefix/etc/config.site" +else + ac_site_files="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site" +fi + +for ac_site_file in $ac_site_files +do + case $ac_site_file in #( + */*) : + ;; #( + *) : + ac_site_file=./$ac_site_file ;; +esac + if test -f "$ac_site_file" && test -r "$ac_site_file"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: loading site script $ac_site_file" >&5 +printf "%s\n" "$as_me: loading site script $ac_site_file" >&6;} + sed 's/^/| /' "$ac_site_file" >&5 + . "$ac_site_file" \ + || { { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: in \`$ac_pwd':" >&5 +printf "%s\n" "$as_me: error: in \`$ac_pwd':" >&2;} +as_fn_error $? "failed to load site script $ac_site_file +See \`config.log' for more details" "$LINENO" 5; } + fi +done + +if test -r "$cache_file"; then + # Some versions of bash will fail to source /dev/null (special files + # actually), so we avoid doing that. DJGPP emulates it as a regular file. + if test /dev/null != "$cache_file" && test -f "$cache_file"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: loading cache $cache_file" >&5 +printf "%s\n" "$as_me: loading cache $cache_file" >&6;} + case $cache_file in + [\\/]* | ?:[\\/]* ) . "$cache_file";; + *) . "./$cache_file";; + esac + fi +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: creating cache $cache_file" >&5 +printf "%s\n" "$as_me: creating cache $cache_file" >&6;} + >$cache_file +fi + +# Test code for whether the C compiler supports C89 (global declarations) +ac_c_conftest_c89_globals=' +/* Does the compiler advertise C89 conformance? + Do not test the value of __STDC__, because some compilers set it to 0 + while being otherwise adequately conformant. */ +#if !defined __STDC__ +# error "Compiler does not advertise C89 conformance" +#endif + +#include <stddef.h> +#include <stdarg.h> +struct stat; +/* Most of the following tests are stolen from RCS 5.7 src/conf.sh. */ +struct buf { int x; }; +struct buf * (*rcsopen) (struct buf *, struct stat *, int); +static char *e (p, i) + char **p; + int i; +{ + return p[i]; +} +static char *f (char * (*g) (char **, int), char **p, ...) +{ + char *s; + va_list v; + va_start (v,p); + s = g (p, va_arg (v,int)); + va_end (v); + return s; +} + +/* OSF 4.0 Compaq cc is some sort of almost-ANSI by default. It has + function prototypes and stuff, but not \xHH hex character constants. + These do not provoke an error unfortunately, instead are silently treated + as an "x". The following induces an error, until -std is added to get + proper ANSI mode. Curiously \x00 != x always comes out true, for an + array size at least. It is necessary to write \x00 == 0 to get something + that is true only with -std. */ +int osf4_cc_array ['\''\x00'\'' == 0 ? 1 : -1]; + +/* IBM C 6 for AIX is almost-ANSI by default, but it replaces macro parameters + inside strings and character constants. */ +#define FOO(x) '\''x'\'' +int xlc6_cc_array[FOO(a) == '\''x'\'' ? 1 : -1]; + +int test (int i, double x); +struct s1 {int (*f) (int a);}; +struct s2 {int (*f) (double a);}; +int pairnames (int, char **, int *(*)(struct buf *, struct stat *, int), + int, int);' + +# Test code for whether the C compiler supports C89 (body of main). +ac_c_conftest_c89_main=' +ok |= (argc == 0 || f (e, argv, 0) != argv[0] || f (e, argv, 1) != argv[1]); +' + +# Test code for whether the C compiler supports C99 (global declarations) +ac_c_conftest_c99_globals=' +// Does the compiler advertise C99 conformance? +#if !defined __STDC_VERSION__ || __STDC_VERSION__ < 199901L +# error "Compiler does not advertise C99 conformance" +#endif + +#include <stdbool.h> +extern int puts (const char *); +extern int printf (const char *, ...); +extern int dprintf (int, const char *, ...); +extern void *malloc (size_t); + +// Check varargs macros. These examples are taken from C99 6.10.3.5. +// dprintf is used instead of fprintf to avoid needing to declare +// FILE and stderr. +#define debug(...) dprintf (2, __VA_ARGS__) +#define showlist(...) puts (#__VA_ARGS__) +#define report(test,...) ((test) ? puts (#test) : printf (__VA_ARGS__)) +static void +test_varargs_macros (void) +{ + int x = 1234; + int y = 5678; + debug ("Flag"); + debug ("X = %d\n", x); + showlist (The first, second, and third items.); + report (x>y, "x is %d but y is %d", x, y); +} + +// Check long long types. +#define BIG64 18446744073709551615ull +#define BIG32 4294967295ul +#define BIG_OK (BIG64 / BIG32 == 4294967297ull && BIG64 % BIG32 == 0) +#if !BIG_OK + #error "your preprocessor is broken" +#endif +#if BIG_OK +#else + #error "your preprocessor is broken" +#endif +static long long int bignum = -9223372036854775807LL; +static unsigned long long int ubignum = BIG64; + +struct incomplete_array +{ + int datasize; + double data[]; +}; + +struct named_init { + int number; + const wchar_t *name; + double average; +}; + +typedef const char *ccp; + +static inline int +test_restrict (ccp restrict text) +{ + // See if C++-style comments work. + // Iterate through items via the restricted pointer. + // Also check for declarations in for loops. + for (unsigned int i = 0; *(text+i) != '\''\0'\''; ++i) + continue; + return 0; +} + +// Check varargs and va_copy. +static bool +test_varargs (const char *format, ...) +{ + va_list args; + va_start (args, format); + va_list args_copy; + va_copy (args_copy, args); + + const char *str = ""; + int number = 0; + float fnumber = 0; + + while (*format) + { + switch (*format++) + { + case '\''s'\'': // string + str = va_arg (args_copy, const char *); + break; + case '\''d'\'': // int + number = va_arg (args_copy, int); + break; + case '\''f'\'': // float + fnumber = va_arg (args_copy, double); + break; + default: + break; + } + } + va_end (args_copy); + va_end (args); + + return *str && number && fnumber; +} +' + +# Test code for whether the C compiler supports C99 (body of main). +ac_c_conftest_c99_main=' + // Check bool. + _Bool success = false; + success |= (argc != 0); + + // Check restrict. + if (test_restrict ("String literal") == 0) + success = true; + char *restrict newvar = "Another string"; + + // Check varargs. + success &= test_varargs ("s, d'\'' f .", "string", 65, 34.234); + test_varargs_macros (); + + // Check flexible array members. + struct incomplete_array *ia = + malloc (sizeof (struct incomplete_array) + (sizeof (double) * 10)); + ia->datasize = 10; + for (int i = 0; i < ia->datasize; ++i) + ia->data[i] = i * 1.234; + + // Check named initializers. + struct named_init ni = { + .number = 34, + .name = L"Test wide string", + .average = 543.34343, + }; + + ni.number = 58; + + int dynamic_array[ni.number]; + dynamic_array[0] = argv[0][0]; + dynamic_array[ni.number - 1] = 543; + + // work around unused variable warnings + ok |= (!success || bignum == 0LL || ubignum == 0uLL || newvar[0] == '\''x'\'' + || dynamic_array[ni.number - 1] != 543); +' + +# Test code for whether the C compiler supports C11 (global declarations) +ac_c_conftest_c11_globals=' +// Does the compiler advertise C11 conformance? +#if !defined __STDC_VERSION__ || __STDC_VERSION__ < 201112L +# error "Compiler does not advertise C11 conformance" +#endif + +// Check _Alignas. +char _Alignas (double) aligned_as_double; +char _Alignas (0) no_special_alignment; +extern char aligned_as_int; +char _Alignas (0) _Alignas (int) aligned_as_int; + +// Check _Alignof. +enum +{ + int_alignment = _Alignof (int), + int_array_alignment = _Alignof (int[100]), + char_alignment = _Alignof (char) +}; +_Static_assert (0 < -_Alignof (int), "_Alignof is signed"); + +// Check _Noreturn. +int _Noreturn does_not_return (void) { for (;;) continue; } + +// Check _Static_assert. +struct test_static_assert +{ + int x; + _Static_assert (sizeof (int) <= sizeof (long int), + "_Static_assert does not work in struct"); + long int y; +}; + +// Check UTF-8 literals. +#define u8 syntax error! +char const utf8_literal[] = u8"happens to be ASCII" "another string"; + +// Check duplicate typedefs. +typedef long *long_ptr; +typedef long int *long_ptr; +typedef long_ptr long_ptr; + +// Anonymous structures and unions -- taken from C11 6.7.2.1 Example 1. +struct anonymous +{ + union { + struct { int i; int j; }; + struct { int k; long int l; } w; + }; + int m; +} v1; +' + +# Test code for whether the C compiler supports C11 (body of main). +ac_c_conftest_c11_main=' + _Static_assert ((offsetof (struct anonymous, i) + == offsetof (struct anonymous, w.k)), + "Anonymous union alignment botch"); + v1.i = 2; + v1.w.k = 5; + ok |= v1.i != 5; +' + +# Test code for whether the C compiler supports C11 (complete). +ac_c_conftest_c11_program="${ac_c_conftest_c89_globals} +${ac_c_conftest_c99_globals} +${ac_c_conftest_c11_globals} + +int +main (int argc, char **argv) +{ + int ok = 0; + ${ac_c_conftest_c89_main} + ${ac_c_conftest_c99_main} + ${ac_c_conftest_c11_main} + return ok; +} +" + +# Test code for whether the C compiler supports C99 (complete). +ac_c_conftest_c99_program="${ac_c_conftest_c89_globals} +${ac_c_conftest_c99_globals} + +int +main (int argc, char **argv) +{ + int ok = 0; + ${ac_c_conftest_c89_main} + ${ac_c_conftest_c99_main} + return ok; +} +" + +# Test code for whether the C compiler supports C89 (complete). +ac_c_conftest_c89_program="${ac_c_conftest_c89_globals} + +int +main (int argc, char **argv) +{ + int ok = 0; + ${ac_c_conftest_c89_main} + return ok; +} +" + +as_fn_append ac_header_c_list " stdio.h stdio_h HAVE_STDIO_H" +as_fn_append ac_header_c_list " stdlib.h stdlib_h HAVE_STDLIB_H" +as_fn_append ac_header_c_list " string.h string_h HAVE_STRING_H" +as_fn_append ac_header_c_list " inttypes.h inttypes_h HAVE_INTTYPES_H" +as_fn_append ac_header_c_list " stdint.h stdint_h HAVE_STDINT_H" +as_fn_append ac_header_c_list " strings.h strings_h HAVE_STRINGS_H" +as_fn_append ac_header_c_list " sys/stat.h sys_stat_h HAVE_SYS_STAT_H" +as_fn_append ac_header_c_list " sys/types.h sys_types_h HAVE_SYS_TYPES_H" +as_fn_append ac_header_c_list " unistd.h unistd_h HAVE_UNISTD_H" +as_fn_append ac_header_c_list " sys/param.h sys_param_h HAVE_SYS_PARAM_H" +as_fn_append ac_func_c_list " getpagesize HAVE_GETPAGESIZE" + +# Auxiliary files required by this configure script. +ac_aux_files="install-sh config.guess config.sub" + +# Locations in which to look for auxiliary files. +ac_aux_dir_candidates="${srcdir}${PATH_SEPARATOR}${srcdir}/..${PATH_SEPARATOR}${srcdir}/../.." + +# Search for a directory containing all of the required auxiliary files, +# $ac_aux_files, from the $PATH-style list $ac_aux_dir_candidates. +# If we don't find one directory that contains all the files we need, +# we report the set of missing files from the *first* directory in +# $ac_aux_dir_candidates and give up. +ac_missing_aux_files="" +ac_first_candidate=: +printf "%s\n" "$as_me:${as_lineno-$LINENO}: looking for aux files: $ac_aux_files" >&5 +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +as_found=false +for as_dir in $ac_aux_dir_candidates +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + as_found=: + + printf "%s\n" "$as_me:${as_lineno-$LINENO}: trying $as_dir" >&5 + ac_aux_dir_found=yes + ac_install_sh= + for ac_aux in $ac_aux_files + do + # As a special case, if "install-sh" is required, that requirement + # can be satisfied by any of "install-sh", "install.sh", or "shtool", + # and $ac_install_sh is set appropriately for whichever one is found. + if test x"$ac_aux" = x"install-sh" + then + if test -f "${as_dir}install-sh"; then + printf "%s\n" "$as_me:${as_lineno-$LINENO}: ${as_dir}install-sh found" >&5 + ac_install_sh="${as_dir}install-sh -c" + elif test -f "${as_dir}install.sh"; then + printf "%s\n" "$as_me:${as_lineno-$LINENO}: ${as_dir}install.sh found" >&5 + ac_install_sh="${as_dir}install.sh -c" + elif test -f "${as_dir}shtool"; then + printf "%s\n" "$as_me:${as_lineno-$LINENO}: ${as_dir}shtool found" >&5 + ac_install_sh="${as_dir}shtool install -c" + else + ac_aux_dir_found=no + if $ac_first_candidate; then + ac_missing_aux_files="${ac_missing_aux_files} install-sh" + else + break + fi + fi + else + if test -f "${as_dir}${ac_aux}"; then + printf "%s\n" "$as_me:${as_lineno-$LINENO}: ${as_dir}${ac_aux} found" >&5 + else + ac_aux_dir_found=no + if $ac_first_candidate; then + ac_missing_aux_files="${ac_missing_aux_files} ${ac_aux}" + else + break + fi + fi + fi + done + if test "$ac_aux_dir_found" = yes; then + ac_aux_dir="$as_dir" + break + fi + ac_first_candidate=false + + as_found=false +done +IFS=$as_save_IFS +if $as_found +then : + +else $as_nop + as_fn_error $? "cannot find required auxiliary files:$ac_missing_aux_files" "$LINENO" 5 +fi + + +# These three variables are undocumented and unsupported, +# and are intended to be withdrawn in a future Autoconf release. +# They can cause serious problems if a builder's source tree is in a directory +# whose full name contains unusual characters. +if test -f "${ac_aux_dir}config.guess"; then + ac_config_guess="$SHELL ${ac_aux_dir}config.guess" +fi +if test -f "${ac_aux_dir}config.sub"; then + ac_config_sub="$SHELL ${ac_aux_dir}config.sub" +fi +if test -f "$ac_aux_dir/configure"; then + ac_configure="$SHELL ${ac_aux_dir}configure" +fi + +# Check that the precious variables saved in the cache have kept the same +# value. +ac_cache_corrupted=false +for ac_var in $ac_precious_vars; do + eval ac_old_set=\$ac_cv_env_${ac_var}_set + eval ac_new_set=\$ac_env_${ac_var}_set + eval ac_old_val=\$ac_cv_env_${ac_var}_value + eval ac_new_val=\$ac_env_${ac_var}_value + case $ac_old_set,$ac_new_set in + set,) + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: \`$ac_var' was set to \`$ac_old_val' in the previous run" >&5 +printf "%s\n" "$as_me: error: \`$ac_var' was set to \`$ac_old_val' in the previous run" >&2;} + ac_cache_corrupted=: ;; + ,set) + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: \`$ac_var' was not set in the previous run" >&5 +printf "%s\n" "$as_me: error: \`$ac_var' was not set in the previous run" >&2;} + ac_cache_corrupted=: ;; + ,);; + *) + if test "x$ac_old_val" != "x$ac_new_val"; then + # differences in whitespace do not lead to failure. + ac_old_val_w=`echo x $ac_old_val` + ac_new_val_w=`echo x $ac_new_val` + if test "$ac_old_val_w" != "$ac_new_val_w"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: \`$ac_var' has changed since the previous run:" >&5 +printf "%s\n" "$as_me: error: \`$ac_var' has changed since the previous run:" >&2;} + ac_cache_corrupted=: + else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: warning: ignoring whitespace changes in \`$ac_var' since the previous run:" >&5 +printf "%s\n" "$as_me: warning: ignoring whitespace changes in \`$ac_var' since the previous run:" >&2;} + eval $ac_var=\$ac_old_val + fi + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: former value: \`$ac_old_val'" >&5 +printf "%s\n" "$as_me: former value: \`$ac_old_val'" >&2;} + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: current value: \`$ac_new_val'" >&5 +printf "%s\n" "$as_me: current value: \`$ac_new_val'" >&2;} + fi;; + esac + # Pass precious variables to config.status. + if test "$ac_new_set" = set; then + case $ac_new_val in + *\'*) ac_arg=$ac_var=`printf "%s\n" "$ac_new_val" | sed "s/'/'\\\\\\\\''/g"` ;; + *) ac_arg=$ac_var=$ac_new_val ;; + esac + case " $ac_configure_args " in + *" '$ac_arg' "*) ;; # Avoid dups. Use of quotes ensures accuracy. + *) as_fn_append ac_configure_args " '$ac_arg'" ;; + esac + fi +done +if $ac_cache_corrupted; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: in \`$ac_pwd':" >&5 +printf "%s\n" "$as_me: error: in \`$ac_pwd':" >&2;} + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: changes in the environment can compromise the build" >&5 +printf "%s\n" "$as_me: error: changes in the environment can compromise the build" >&2;} + as_fn_error $? "run \`${MAKE-make} distclean' and/or \`rm $cache_file' + and start over" "$LINENO" 5 +fi +## -------------------- ## +## Main body of script. ## +## -------------------- ## + +ac_ext=c +ac_cpp='$CPP $CPPFLAGS' +ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' +ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS >&5' +ac_compiler_gnu=$ac_cv_c_compiler_gnu + + + + +ac_config_headers="$ac_config_headers config.h" + + +. ${srcdir}/Config/version.mk +echo "configuring for zsh $VERSION" + + + + + # Make sure we can run config.sub. +$SHELL "${ac_aux_dir}config.sub" sun4 >/dev/null 2>&1 || + as_fn_error $? "cannot run $SHELL ${ac_aux_dir}config.sub" "$LINENO" 5 + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking build system type" >&5 +printf %s "checking build system type... " >&6; } +if test ${ac_cv_build+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_build_alias=$build_alias +test "x$ac_build_alias" = x && + ac_build_alias=`$SHELL "${ac_aux_dir}config.guess"` +test "x$ac_build_alias" = x && + as_fn_error $? "cannot guess build type; you must specify one" "$LINENO" 5 +ac_cv_build=`$SHELL "${ac_aux_dir}config.sub" $ac_build_alias` || + as_fn_error $? "$SHELL ${ac_aux_dir}config.sub $ac_build_alias failed" "$LINENO" 5 + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_build" >&5 +printf "%s\n" "$ac_cv_build" >&6; } +case $ac_cv_build in +*-*-*) ;; +*) as_fn_error $? "invalid value of canonical build" "$LINENO" 5;; +esac +build=$ac_cv_build +ac_save_IFS=$IFS; IFS='-' +set x $ac_cv_build +shift +build_cpu=$1 +build_vendor=$2 +shift; shift +# Remember, the first character of IFS is used to create $*, +# except with old shells: +build_os=$* +IFS=$ac_save_IFS +case $build_os in *\ *) build_os=`echo "$build_os" | sed 's/ /-/g'`;; esac + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking host system type" >&5 +printf %s "checking host system type... " >&6; } +if test ${ac_cv_host+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "x$host_alias" = x; then + ac_cv_host=$ac_cv_build +else + ac_cv_host=`$SHELL "${ac_aux_dir}config.sub" $host_alias` || + as_fn_error $? "$SHELL ${ac_aux_dir}config.sub $host_alias failed" "$LINENO" 5 +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_host" >&5 +printf "%s\n" "$ac_cv_host" >&6; } +case $ac_cv_host in +*-*-*) ;; +*) as_fn_error $? "invalid value of canonical host" "$LINENO" 5;; +esac +host=$ac_cv_host +ac_save_IFS=$IFS; IFS='-' +set x $ac_cv_host +shift +host_cpu=$1 +host_vendor=$2 +shift; shift +# Remember, the first character of IFS is used to create $*, +# except with old shells: +host_os=$* +IFS=$ac_save_IFS +case $host_os in *\ *) host_os=`echo "$host_os" | sed 's/ /-/g'`;; esac + + + +printf "%s\n" "#define MACHTYPE \"$host_cpu\"" >>confdefs.h + + +printf "%s\n" "#define VENDOR \"$host_vendor\"" >>confdefs.h + + +printf "%s\n" "#define OSTYPE \"$host_os\"" >>confdefs.h + + +test "$program_prefix" != NONE && + program_transform_name="s&^&$program_prefix&;$program_transform_name" +# Use a double $ so make ignores it. +test "$program_suffix" != NONE && + program_transform_name="s&\$&$program_suffix&;$program_transform_name" +# Double any \ or $. +# By default was `s,x,x', remove it if useless. +ac_script='s/[\\$]/&&/g;s/;s,x,x,$//' +program_transform_name=`printf "%s\n" "$program_transform_name" | sed "$ac_script"` + + +# Un-double any \ or $ (doubled by AC_ARG_PROGRAM). +cat <<\EOF_SED > conftestsed +s,\\\\,\\,g; s,\$\$,$,g +EOF_SED +zsh_transform_name=`echo "${program_transform_name}" | sed -f conftestsed` +rm -f conftestsed +tzsh_name=`echo zsh | sed -e "${zsh_transform_name}"` +# Double any \ or $ in the transformed name that results. +cat <<\EOF_SED >> conftestsed +s,\\,\\\\,g; s,\$,$$,g +EOF_SED +tzsh=`echo ${tzsh_name} | sed -f conftestsed` +rm -f conftestsed + + +# Check whether --enable-cppflags was given. +if test ${enable_cppflags+y} +then : + enableval=$enable_cppflags; if test "$enableval" = "yes" + then CPPFLAGS="$CPPFLAGS" + else CPPFLAGS="$enable_cppflags" + fi +fi + + # Check whether --enable-cflags was given. +if test ${enable_cflags+y} +then : + enableval=$enable_cflags; if test "$enableval" = "yes" + then CFLAGS="$CFLAGS" + else CFLAGS="$enable_cflags" + fi +fi + + # Check whether --enable-ldflags was given. +if test ${enable_ldflags+y} +then : + enableval=$enable_ldflags; if test "$enableval" = "yes" + then LDFLAGS="$LDFLAGS" + else LDFLAGS="$enable_ldflags" + fi +fi + + # Check whether --enable-libs was given. +if test ${enable_libs+y} +then : + enableval=$enable_libs; if test "$enableval" = "yes" + then LIBS="$LIBS" + else LIBS="$enable_libs" + fi +fi + + + +# Check whether --enable-zsh-debug was given. +if test ${enable_zsh_debug+y} +then : + enableval=$enable_zsh_debug; if test x$enableval = xyes; then + printf "%s\n" "#define DEBUG 1" >>confdefs.h + +fi +fi + + + +# Check whether --enable-zsh-mem was given. +if test ${enable_zsh_mem+y} +then : + enableval=$enable_zsh_mem; if test x$enableval = xyes; then + printf "%s\n" "#define ZSH_MEM 1" >>confdefs.h + +fi +fi + + + +# Check whether --enable-zsh-mem-debug was given. +if test ${enable_zsh_mem_debug+y} +then : + enableval=$enable_zsh_mem_debug; if test x$enableval = xyes; then + printf "%s\n" "#define ZSH_MEM_DEBUG 1" >>confdefs.h + +fi +fi + + + +# Check whether --enable-zsh-mem-warning was given. +if test ${enable_zsh_mem_warning+y} +then : + enableval=$enable_zsh_mem_warning; if test x$enableval = xyes; then + printf "%s\n" "#define ZSH_MEM_WARNING 1" >>confdefs.h + +fi +fi + + + +# Check whether --enable-zsh-secure-free was given. +if test ${enable_zsh_secure_free+y} +then : + enableval=$enable_zsh_secure_free; if test x$enableval = xyes; then + printf "%s\n" "#define ZSH_SECURE_FREE 1" >>confdefs.h + +fi +fi + + + +# Check whether --enable-zsh-heap-debug was given. +if test ${enable_zsh_heap_debug+y} +then : + enableval=$enable_zsh_heap_debug; if test x$enableval = xyes; then + printf "%s\n" "#define ZSH_HEAP_DEBUG 1" >>confdefs.h + +fi +fi + + + +# Check whether --enable-zsh-valgrind was given. +if test ${enable_zsh_valgrind+y} +then : + enableval=$enable_zsh_valgrind; if test x$enableval = xyes; then + printf "%s\n" "#define ZSH_VALGRIND 1" >>confdefs.h + +fi +fi + + + +# Check whether --enable-zsh-hash-debug was given. +if test ${enable_zsh_hash_debug+y} +then : + enableval=$enable_zsh_hash_debug; if test x$enableval = xyes; then + printf "%s\n" "#define ZSH_HASH_DEBUG 1" >>confdefs.h + +fi +fi + + + +# Check whether --enable-stack-allocation was given. +if test ${enable_stack_allocation+y} +then : + enableval=$enable_stack_allocation; if test x$enableval = xyes; then + printf "%s\n" "#define USE_STACK_ALLOCATION 1" >>confdefs.h + +fi +fi + + +# Check whether --enable-etcdir was given. +if test ${enable_etcdir+y} +then : + enableval=$enable_etcdir; etcdir="$enableval" +else $as_nop + etcdir=/etc +fi + + +# Check whether --enable-zshenv was given. +if test ${enable_zshenv+y} +then : + enableval=$enable_zshenv; zshenv="$enableval" +else $as_nop + if test "x$etcdir" = xno; then + zshenv=no +else + zshenv="$etcdir/zshenv" +fi +fi + + +if test "x$zshenv" != xno; then + printf "%s\n" "#define GLOBAL_ZSHENV \"$zshenv\"" >>confdefs.h + +fi + +# Check whether --enable-zshrc was given. +if test ${enable_zshrc+y} +then : + enableval=$enable_zshrc; zshrc="$enableval" +else $as_nop + if test "x$etcdir" = xno; then + zshrc=no +else + zshrc="$etcdir/zshrc" +fi +fi + + +if test "x$zshrc" != xno; then + printf "%s\n" "#define GLOBAL_ZSHRC \"$zshrc\"" >>confdefs.h + +fi + +# Check whether --enable-zprofile was given. +if test ${enable_zprofile+y} +then : + enableval=$enable_zprofile; zprofile="$enableval" +else $as_nop + if test "x$etcdir" = xno; then + zprofile=no +else + zprofile="$etcdir/zprofile" +fi +fi + + +if test "x$zprofile" != xno; then + printf "%s\n" "#define GLOBAL_ZPROFILE \"$zprofile\"" >>confdefs.h + +fi + +# Check whether --enable-zlogin was given. +if test ${enable_zlogin+y} +then : + enableval=$enable_zlogin; zlogin="$enableval" +else $as_nop + if test "x$etcdir" = xno; then + zlogin=no +else + zlogin="$etcdir/zlogin" +fi +fi + + +if test "x$zlogin" != xno; then + printf "%s\n" "#define GLOBAL_ZLOGIN \"$zlogin\"" >>confdefs.h + +fi + +# Check whether --enable-zlogout was given. +if test ${enable_zlogout+y} +then : + enableval=$enable_zlogout; zlogout="$enableval" +else $as_nop + if test "x$etcdir" = xno; then + zlogout=no +else + zlogout="$etcdir/zlogout" +fi +fi + + +if test "x$zlogout" != xno; then + printf "%s\n" "#define GLOBAL_ZLOGOUT \"$zlogout\"" >>confdefs.h + +fi + + +# Check whether --enable-dynamic was given. +if test ${enable_dynamic+y} +then : + enableval=$enable_dynamic; dynamic="$enableval" +else $as_nop + dynamic=yes +fi + + + +# Check whether --enable-restricted-r was given. +if test ${enable_restricted_r+y} +then : + enableval=$enable_restricted_r; if test x$enableval = xyes; then + printf "%s\n" "#define RESTRICTED_R 1" >>confdefs.h + +fi +else $as_nop + printf "%s\n" "#define RESTRICTED_R 1" >>confdefs.h + + +fi + + + +# Check whether --enable-locale was given. +if test ${enable_locale+y} +then : + enableval=$enable_locale; if test x$enableval = xyes; then + printf "%s\n" "#define CONFIG_LOCALE 1" >>confdefs.h + +fi +else $as_nop + printf "%s\n" "#define CONFIG_LOCALE 1" >>confdefs.h + + +fi + + +# Check whether --enable-ansi2knr was given. +if test ${enable_ansi2knr+y} +then : + enableval=$enable_ansi2knr; ansi2knr="$enableval" +else $as_nop + ansi2knr=default +fi + + +# Check whether --enable-runhelpdir was given. +if test ${enable_runhelpdir+y} +then : + enableval=$enable_runhelpdir; if test x"$enableval" = xno; then + runhelpdir= +else + runhelpdir="$enableval" +fi +else $as_nop + runhelpdir=yes +fi + +if test x"$runhelpdir" = xyes; then + runhelpdir=${datadir}/${tzsh_name}/'${VERSION}'/help +fi +if test x"$runhelpdir" = x; then + runhelp= +else + runhelp=runhelp +fi + +# Check whether --enable-fndir was given. +if test ${enable_fndir+y} +then : + enableval=$enable_fndir; if test x$enableval = xyes; then + fndir=${datadir}/${tzsh_name}/'${VERSION}'/functions +else + fndir="$enableval" +fi +else $as_nop + fndir=${datadir}/${tzsh_name}/'${VERSION}'/functions +fi + + +# Check whether --enable-site-fndir was given. +if test ${enable_site_fndir+y} +then : + enableval=$enable_site_fndir; if test x$enableval = xyes; then + sitefndir=${datadir}/${tzsh_name}/site-functions +else + sitefndir="$enableval" +fi +else $as_nop + sitefndir=${datadir}/${tzsh_name}/site-functions +fi + + +if test X$sitefndir = X/usr/local/share/zsh/site-functions || \ + test X$sitefndir = Xno +then fixed_sitefndir='' +elif test X$prefix != X/usr/local; then + if test X$prefix = XNONE && test X$ac_default_prefix = X/usr/local; then + if test X$tzsh_name != Xzsh + then fixed_sitefndir=/usr/local/share/zsh/site-functions + else fixed_sitefndir='' + fi + else fixed_sitefndir=/usr/local/share/zsh/site-functions + fi +elif test X$tzsh_name != Xzsh +then fixed_sitefndir=/usr/local/share/zsh/site-functions +else fixed_sitefndir='' +fi + + +# Check whether --enable-function-subdirs was given. +if test ${enable_function_subdirs+y} +then : + enableval=$enable_function_subdirs; +fi + + +if test "x${enable_function_subdirs}" != x && + test "x${enable_function_subdirs}" != xno; then + FUNCTIONS_SUBDIRS=yes +else + FUNCTIONS_SUBDIRS=no +fi + +# Check whether --enable-additional-fpath was given. +if test ${enable_additional_fpath+y} +then : + enableval=$enable_additional_fpath; if test x$enableval = xyes; then + additionalfpath="" +else + additionalfpath="${enableval}" +fi +else $as_nop + additionalfpath="" +fi + + + + +# Check whether --enable-scriptdir was given. +if test ${enable_scriptdir+y} +then : + enableval=$enable_scriptdir; if test x$enableval = xyes; then + scriptdir=${datadir}/${tzsh_name}/'${VERSION}'/scripts +else + scriptdir="$enableval" +fi +else $as_nop + scriptdir=${datadir}/${tzsh_name}/'${VERSION}'/scripts +fi + + +# Check whether --enable-site-scriptdir was given. +if test ${enable_site_scriptdir+y} +then : + enableval=$enable_site_scriptdir; if test x$enableval = xyes; then + sitescriptdir=${datadir}/${tzsh_name}/scripts +else + sitescriptdir="$enableval" +fi +else $as_nop + sitescriptdir=${datadir}/${tzsh_name}/scripts +fi + + + +if test x$htmldir = x'${docdir}' || test x$htmldir = x; then + htmldir='$(datadir)/$(tzsh)/htmldoc' +fi + + +# Check whether --enable-custom-patchlevel was given. +if test ${enable_custom_patchlevel+y} +then : + enableval=$enable_custom_patchlevel; if test x$enableval != x && test x$enableval != xno; then + printf "%s\n" "#define CUSTOM_PATCHLEVEL \"$enableval\"" >>confdefs.h + +fi +fi + + + +# Check whether --enable-maildir-support was given. +if test ${enable_maildir_support+y} +then : + enableval=$enable_maildir_support; if test x$enableval = xyes; then + printf "%s\n" "#define MAILDIR_SUPPORT 1" >>confdefs.h + +fi +fi + + + +# Check whether --enable-max-function-depth was given. +if test ${enable_max_function_depth+y} +then : + enableval=$enable_max_function_depth; if test x$enableval = xyes; then + printf "%s\n" "#define MAX_FUNCTION_DEPTH 500" >>confdefs.h + +elif test x$enableval != xno; then + printf "%s\n" "#define MAX_FUNCTION_DEPTH $enableval" >>confdefs.h + +fi +else $as_nop + printf "%s\n" "#define MAX_FUNCTION_DEPTH 500" >>confdefs.h + + +fi + + + +# Check whether --enable-readnullcmd was given. +if test ${enable_readnullcmd+y} +then : + enableval=$enable_readnullcmd; if test x$enableval = xyes; then + printf "%s\n" "#define DEFAULT_READNULLCMD \"more\"" >>confdefs.h + +elif test x$enableval != xno; then + printf "%s\n" "#define DEFAULT_READNULLCMD \"$enableval\"" >>confdefs.h + +fi +else $as_nop + printf "%s\n" "#define DEFAULT_READNULLCMD \"more\"" >>confdefs.h + + +fi + + +# Check whether --enable-pcre was given. +if test ${enable_pcre+y} +then : + enableval=$enable_pcre; +fi + + +# Check whether --enable-cap was given. +if test ${enable_cap+y} +then : + enableval=$enable_cap; +fi + + +# Default off for licensing reasons +# Check whether --enable-gdbm was given. +if test ${enable_gdbm+y} +then : + enableval=$enable_gdbm; gdbm="$enableval" +else $as_nop + gdbm=no +fi + + +test -z "${CFLAGS+set}" && CFLAGS= auto_cflags=1 +test -z "${LDFLAGS+set}" && LDFLAGS= auto_ldflags=1 + + + + + + + + + + +ac_ext=c +ac_cpp='$CPP $CPPFLAGS' +ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' +ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS >&5' +ac_compiler_gnu=$ac_cv_c_compiler_gnu +if test -n "$ac_tool_prefix"; then + # Extract the first word of "${ac_tool_prefix}gcc", so it can be a program name with args. +set dummy ${ac_tool_prefix}gcc; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_CC+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_CC="${ac_tool_prefix}gcc" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +CC=$ac_cv_prog_CC +if test -n "$CC"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $CC" >&5 +printf "%s\n" "$CC" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + +fi +if test -z "$ac_cv_prog_CC"; then + ac_ct_CC=$CC + # Extract the first word of "gcc", so it can be a program name with args. +set dummy gcc; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_ac_ct_CC+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$ac_ct_CC"; then + ac_cv_prog_ac_ct_CC="$ac_ct_CC" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_ac_ct_CC="gcc" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +ac_ct_CC=$ac_cv_prog_ac_ct_CC +if test -n "$ac_ct_CC"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_ct_CC" >&5 +printf "%s\n" "$ac_ct_CC" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + if test "x$ac_ct_CC" = x; then + CC="" + else + case $cross_compiling:$ac_tool_warned in +yes:) +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: using cross tools not prefixed with host triplet" >&5 +printf "%s\n" "$as_me: WARNING: using cross tools not prefixed with host triplet" >&2;} +ac_tool_warned=yes ;; +esac + CC=$ac_ct_CC + fi +else + CC="$ac_cv_prog_CC" +fi + +if test -z "$CC"; then + if test -n "$ac_tool_prefix"; then + # Extract the first word of "${ac_tool_prefix}cc", so it can be a program name with args. +set dummy ${ac_tool_prefix}cc; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_CC+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_CC="${ac_tool_prefix}cc" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +CC=$ac_cv_prog_CC +if test -n "$CC"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $CC" >&5 +printf "%s\n" "$CC" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + + fi +fi +if test -z "$CC"; then + # Extract the first word of "cc", so it can be a program name with args. +set dummy cc; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_CC+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +else + ac_prog_rejected=no +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + if test "$as_dir$ac_word$ac_exec_ext" = "/usr/ucb/cc"; then + ac_prog_rejected=yes + continue + fi + ac_cv_prog_CC="cc" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +if test $ac_prog_rejected = yes; then + # We found a bogon in the path, so make sure we never use it. + set dummy $ac_cv_prog_CC + shift + if test $# != 0; then + # We chose a different compiler from the bogus one. + # However, it has the same basename, so the bogon will be chosen + # first if we set CC to just the basename; use the full file name. + shift + ac_cv_prog_CC="$as_dir$ac_word${1+' '}$@" + fi +fi +fi +fi +CC=$ac_cv_prog_CC +if test -n "$CC"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $CC" >&5 +printf "%s\n" "$CC" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + +fi +if test -z "$CC"; then + if test -n "$ac_tool_prefix"; then + for ac_prog in cl.exe + do + # Extract the first word of "$ac_tool_prefix$ac_prog", so it can be a program name with args. +set dummy $ac_tool_prefix$ac_prog; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_CC+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_CC="$ac_tool_prefix$ac_prog" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +CC=$ac_cv_prog_CC +if test -n "$CC"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $CC" >&5 +printf "%s\n" "$CC" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + + test -n "$CC" && break + done +fi +if test -z "$CC"; then + ac_ct_CC=$CC + for ac_prog in cl.exe +do + # Extract the first word of "$ac_prog", so it can be a program name with args. +set dummy $ac_prog; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_ac_ct_CC+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$ac_ct_CC"; then + ac_cv_prog_ac_ct_CC="$ac_ct_CC" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_ac_ct_CC="$ac_prog" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +ac_ct_CC=$ac_cv_prog_ac_ct_CC +if test -n "$ac_ct_CC"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_ct_CC" >&5 +printf "%s\n" "$ac_ct_CC" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + + test -n "$ac_ct_CC" && break +done + + if test "x$ac_ct_CC" = x; then + CC="" + else + case $cross_compiling:$ac_tool_warned in +yes:) +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: using cross tools not prefixed with host triplet" >&5 +printf "%s\n" "$as_me: WARNING: using cross tools not prefixed with host triplet" >&2;} +ac_tool_warned=yes ;; +esac + CC=$ac_ct_CC + fi +fi + +fi +if test -z "$CC"; then + if test -n "$ac_tool_prefix"; then + # Extract the first word of "${ac_tool_prefix}clang", so it can be a program name with args. +set dummy ${ac_tool_prefix}clang; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_CC+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$CC"; then + ac_cv_prog_CC="$CC" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_CC="${ac_tool_prefix}clang" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +CC=$ac_cv_prog_CC +if test -n "$CC"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $CC" >&5 +printf "%s\n" "$CC" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + +fi +if test -z "$ac_cv_prog_CC"; then + ac_ct_CC=$CC + # Extract the first word of "clang", so it can be a program name with args. +set dummy clang; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_ac_ct_CC+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$ac_ct_CC"; then + ac_cv_prog_ac_ct_CC="$ac_ct_CC" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_ac_ct_CC="clang" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +ac_ct_CC=$ac_cv_prog_ac_ct_CC +if test -n "$ac_ct_CC"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_ct_CC" >&5 +printf "%s\n" "$ac_ct_CC" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + if test "x$ac_ct_CC" = x; then + CC="" + else + case $cross_compiling:$ac_tool_warned in +yes:) +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: using cross tools not prefixed with host triplet" >&5 +printf "%s\n" "$as_me: WARNING: using cross tools not prefixed with host triplet" >&2;} +ac_tool_warned=yes ;; +esac + CC=$ac_ct_CC + fi +else + CC="$ac_cv_prog_CC" +fi + +fi + + +test -z "$CC" && { { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: in \`$ac_pwd':" >&5 +printf "%s\n" "$as_me: error: in \`$ac_pwd':" >&2;} +as_fn_error $? "no acceptable C compiler found in \$PATH +See \`config.log' for more details" "$LINENO" 5; } + +# Provide some information about the compiler. +printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for C compiler version" >&5 +set X $ac_compile +ac_compiler=$2 +for ac_option in --version -v -V -qversion -version; do + { { ac_try="$ac_compiler $ac_option >&5" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval ac_try_echo="\"\$as_me:${as_lineno-$LINENO}: $ac_try_echo\"" +printf "%s\n" "$ac_try_echo"; } >&5 + (eval "$ac_compiler $ac_option >&5") 2>conftest.err + ac_status=$? + if test -s conftest.err; then + sed '10a\ +... rest of stderr output deleted ... + 10q' conftest.err >conftest.er1 + cat conftest.er1 >&5 + fi + rm -f conftest.er1 conftest.err + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; } +done + +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +int +main (void) +{ + + ; + return 0; +} +_ACEOF +ac_clean_files_save=$ac_clean_files +ac_clean_files="$ac_clean_files a.out a.out.dSYM a.exe b.out" +# Try to create an executable without -o first, disregard a.out. +# It will help us diagnose broken compilers, and finding out an intuition +# of exeext. +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether the C compiler works" >&5 +printf %s "checking whether the C compiler works... " >&6; } +ac_link_default=`printf "%s\n" "$ac_link" | sed 's/ -o *conftest[^ ]*//'` + +# The possible output files: +ac_files="a.out conftest.exe conftest a.exe a_out.exe b.out conftest.*" + +ac_rmfiles= +for ac_file in $ac_files +do + case $ac_file in + *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.dSYM | *.o | *.obj ) ;; + * ) ac_rmfiles="$ac_rmfiles $ac_file";; + esac +done +rm -f $ac_rmfiles + +if { { ac_try="$ac_link_default" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval ac_try_echo="\"\$as_me:${as_lineno-$LINENO}: $ac_try_echo\"" +printf "%s\n" "$ac_try_echo"; } >&5 + (eval "$ac_link_default") 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; } +then : + # Autoconf-2.13 could set the ac_cv_exeext variable to `no'. +# So ignore a value of `no', otherwise this would lead to `EXEEXT = no' +# in a Makefile. We should not override ac_cv_exeext if it was cached, +# so that the user can short-circuit this test for compilers unknown to +# Autoconf. +for ac_file in $ac_files '' +do + test -f "$ac_file" || continue + case $ac_file in + *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.dSYM | *.o | *.obj ) + ;; + [ab].out ) + # We found the default executable, but exeext='' is most + # certainly right. + break;; + *.* ) + if test ${ac_cv_exeext+y} && test "$ac_cv_exeext" != no; + then :; else + ac_cv_exeext=`expr "$ac_file" : '[^.]*\(\..*\)'` + fi + # We set ac_cv_exeext here because the later test for it is not + # safe: cross compilers may not add the suffix if given an `-o' + # argument, so we may need to know it at that point already. + # Even if this section looks crufty: it has the advantage of + # actually working. + break;; + * ) + break;; + esac +done +test "$ac_cv_exeext" = no && ac_cv_exeext= + +else $as_nop + ac_file='' +fi +if test -z "$ac_file" +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +printf "%s\n" "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + +{ { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: in \`$ac_pwd':" >&5 +printf "%s\n" "$as_me: error: in \`$ac_pwd':" >&2;} +as_fn_error 77 "C compiler cannot create executables +See \`config.log' for more details" "$LINENO" 5; } +else $as_nop + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: yes" >&5 +printf "%s\n" "yes" >&6; } +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for C compiler default output file name" >&5 +printf %s "checking for C compiler default output file name... " >&6; } +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_file" >&5 +printf "%s\n" "$ac_file" >&6; } +ac_exeext=$ac_cv_exeext + +rm -f -r a.out a.out.dSYM a.exe conftest$ac_cv_exeext b.out +ac_clean_files=$ac_clean_files_save +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for suffix of executables" >&5 +printf %s "checking for suffix of executables... " >&6; } +if { { ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval ac_try_echo="\"\$as_me:${as_lineno-$LINENO}: $ac_try_echo\"" +printf "%s\n" "$ac_try_echo"; } >&5 + (eval "$ac_link") 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; } +then : + # If both `conftest.exe' and `conftest' are `present' (well, observable) +# catch `conftest.exe'. For instance with Cygwin, `ls conftest' will +# work properly (i.e., refer to `conftest.exe'), while it won't with +# `rm'. +for ac_file in conftest.exe conftest conftest.*; do + test -f "$ac_file" || continue + case $ac_file in + *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.dSYM | *.o | *.obj ) ;; + *.* ) ac_cv_exeext=`expr "$ac_file" : '[^.]*\(\..*\)'` + break;; + * ) break;; + esac +done +else $as_nop + { { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: in \`$ac_pwd':" >&5 +printf "%s\n" "$as_me: error: in \`$ac_pwd':" >&2;} +as_fn_error $? "cannot compute suffix of executables: cannot compile and link +See \`config.log' for more details" "$LINENO" 5; } +fi +rm -f conftest conftest$ac_cv_exeext +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_exeext" >&5 +printf "%s\n" "$ac_cv_exeext" >&6; } + +rm -f conftest.$ac_ext +EXEEXT=$ac_cv_exeext +ac_exeext=$EXEEXT +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <stdio.h> +int +main (void) +{ +FILE *f = fopen ("conftest.out", "w"); + return ferror (f) || fclose (f) != 0; + + ; + return 0; +} +_ACEOF +ac_clean_files="$ac_clean_files conftest.out" +# Check that the compiler produces executables we can run. If not, either +# the compiler is broken, or we cross compile. +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether we are cross compiling" >&5 +printf %s "checking whether we are cross compiling... " >&6; } +if test "$cross_compiling" != yes; then + { { ac_try="$ac_link" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval ac_try_echo="\"\$as_me:${as_lineno-$LINENO}: $ac_try_echo\"" +printf "%s\n" "$ac_try_echo"; } >&5 + (eval "$ac_link") 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; } + if { ac_try='./conftest$ac_cv_exeext' + { { case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval ac_try_echo="\"\$as_me:${as_lineno-$LINENO}: $ac_try_echo\"" +printf "%s\n" "$ac_try_echo"; } >&5 + (eval "$ac_try") 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; }; then + cross_compiling=no + else + if test "$cross_compiling" = maybe; then + cross_compiling=yes + else + { { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: in \`$ac_pwd':" >&5 +printf "%s\n" "$as_me: error: in \`$ac_pwd':" >&2;} +as_fn_error 77 "cannot run C compiled programs. +If you meant to cross compile, use \`--host'. +See \`config.log' for more details" "$LINENO" 5; } + fi + fi +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $cross_compiling" >&5 +printf "%s\n" "$cross_compiling" >&6; } + +rm -f conftest.$ac_ext conftest$ac_cv_exeext conftest.out +ac_clean_files=$ac_clean_files_save +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for suffix of object files" >&5 +printf %s "checking for suffix of object files... " >&6; } +if test ${ac_cv_objext+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +int +main (void) +{ + + ; + return 0; +} +_ACEOF +rm -f conftest.o conftest.obj +if { { ac_try="$ac_compile" +case "(($ac_try" in + *\"* | *\`* | *\\*) ac_try_echo=\$ac_try;; + *) ac_try_echo=$ac_try;; +esac +eval ac_try_echo="\"\$as_me:${as_lineno-$LINENO}: $ac_try_echo\"" +printf "%s\n" "$ac_try_echo"; } >&5 + (eval "$ac_compile") 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; } +then : + for ac_file in conftest.o conftest.obj conftest.*; do + test -f "$ac_file" || continue; + case $ac_file in + *.$ac_ext | *.xcoff | *.tds | *.d | *.pdb | *.xSYM | *.bb | *.bbg | *.map | *.inf | *.dSYM ) ;; + *) ac_cv_objext=`expr "$ac_file" : '.*\.\(.*\)'` + break;; + esac +done +else $as_nop + printf "%s\n" "$as_me: failed program was:" >&5 +sed 's/^/| /' conftest.$ac_ext >&5 + +{ { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: in \`$ac_pwd':" >&5 +printf "%s\n" "$as_me: error: in \`$ac_pwd':" >&2;} +as_fn_error $? "cannot compute suffix of object files: cannot compile +See \`config.log' for more details" "$LINENO" 5; } +fi +rm -f conftest.$ac_cv_objext conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_objext" >&5 +printf "%s\n" "$ac_cv_objext" >&6; } +OBJEXT=$ac_cv_objext +ac_objext=$OBJEXT +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether the compiler supports GNU C" >&5 +printf %s "checking whether the compiler supports GNU C... " >&6; } +if test ${ac_cv_c_compiler_gnu+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +int +main (void) +{ +#ifndef __GNUC__ + choke me +#endif + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_compiler_gnu=yes +else $as_nop + ac_compiler_gnu=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +ac_cv_c_compiler_gnu=$ac_compiler_gnu + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_c_compiler_gnu" >&5 +printf "%s\n" "$ac_cv_c_compiler_gnu" >&6; } +ac_compiler_gnu=$ac_cv_c_compiler_gnu + +if test $ac_compiler_gnu = yes; then + GCC=yes +else + GCC= +fi +ac_test_CFLAGS=${CFLAGS+y} +ac_save_CFLAGS=$CFLAGS +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether $CC accepts -g" >&5 +printf %s "checking whether $CC accepts -g... " >&6; } +if test ${ac_cv_prog_cc_g+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_save_c_werror_flag=$ac_c_werror_flag + ac_c_werror_flag=yes + ac_cv_prog_cc_g=no + CFLAGS="-g" + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +int +main (void) +{ + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_prog_cc_g=yes +else $as_nop + CFLAGS="" + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +int +main (void) +{ + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + +else $as_nop + ac_c_werror_flag=$ac_save_c_werror_flag + CFLAGS="-g" + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +int +main (void) +{ + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_prog_cc_g=yes +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + ac_c_werror_flag=$ac_save_c_werror_flag +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_prog_cc_g" >&5 +printf "%s\n" "$ac_cv_prog_cc_g" >&6; } +if test $ac_test_CFLAGS; then + CFLAGS=$ac_save_CFLAGS +elif test $ac_cv_prog_cc_g = yes; then + if test "$GCC" = yes; then + CFLAGS="-g -O2" + else + CFLAGS="-g" + fi +else + if test "$GCC" = yes; then + CFLAGS="-O2" + else + CFLAGS= + fi +fi +ac_prog_cc_stdc=no +if test x$ac_prog_cc_stdc = xno +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CC option to enable C11 features" >&5 +printf %s "checking for $CC option to enable C11 features... " >&6; } +if test ${ac_cv_prog_cc_c11+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_cv_prog_cc_c11=no +ac_save_CC=$CC +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$ac_c_conftest_c11_program +_ACEOF +for ac_arg in '' -std=gnu11 +do + CC="$ac_save_CC $ac_arg" + if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_prog_cc_c11=$ac_arg +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam + test "x$ac_cv_prog_cc_c11" != "xno" && break +done +rm -f conftest.$ac_ext +CC=$ac_save_CC +fi + +if test "x$ac_cv_prog_cc_c11" = xno +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: unsupported" >&5 +printf "%s\n" "unsupported" >&6; } +else $as_nop + if test "x$ac_cv_prog_cc_c11" = x +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: none needed" >&5 +printf "%s\n" "none needed" >&6; } +else $as_nop + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_prog_cc_c11" >&5 +printf "%s\n" "$ac_cv_prog_cc_c11" >&6; } + CC="$CC $ac_cv_prog_cc_c11" +fi + ac_cv_prog_cc_stdc=$ac_cv_prog_cc_c11 + ac_prog_cc_stdc=c11 +fi +fi +if test x$ac_prog_cc_stdc = xno +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CC option to enable C99 features" >&5 +printf %s "checking for $CC option to enable C99 features... " >&6; } +if test ${ac_cv_prog_cc_c99+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_cv_prog_cc_c99=no +ac_save_CC=$CC +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$ac_c_conftest_c99_program +_ACEOF +for ac_arg in '' -std=gnu99 -std=c99 -c99 -qlanglvl=extc1x -qlanglvl=extc99 -AC99 -D_STDC_C99= +do + CC="$ac_save_CC $ac_arg" + if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_prog_cc_c99=$ac_arg +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam + test "x$ac_cv_prog_cc_c99" != "xno" && break +done +rm -f conftest.$ac_ext +CC=$ac_save_CC +fi + +if test "x$ac_cv_prog_cc_c99" = xno +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: unsupported" >&5 +printf "%s\n" "unsupported" >&6; } +else $as_nop + if test "x$ac_cv_prog_cc_c99" = x +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: none needed" >&5 +printf "%s\n" "none needed" >&6; } +else $as_nop + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_prog_cc_c99" >&5 +printf "%s\n" "$ac_cv_prog_cc_c99" >&6; } + CC="$CC $ac_cv_prog_cc_c99" +fi + ac_cv_prog_cc_stdc=$ac_cv_prog_cc_c99 + ac_prog_cc_stdc=c99 +fi +fi +if test x$ac_prog_cc_stdc = xno +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CC option to enable C89 features" >&5 +printf %s "checking for $CC option to enable C89 features... " >&6; } +if test ${ac_cv_prog_cc_c89+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_cv_prog_cc_c89=no +ac_save_CC=$CC +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$ac_c_conftest_c89_program +_ACEOF +for ac_arg in '' -qlanglvl=extc89 -qlanglvl=ansi -std -Ae "-Aa -D_HPUX_SOURCE" "-Xc -D__EXTENSIONS__" +do + CC="$ac_save_CC $ac_arg" + if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_prog_cc_c89=$ac_arg +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam + test "x$ac_cv_prog_cc_c89" != "xno" && break +done +rm -f conftest.$ac_ext +CC=$ac_save_CC +fi + +if test "x$ac_cv_prog_cc_c89" = xno +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: unsupported" >&5 +printf "%s\n" "unsupported" >&6; } +else $as_nop + if test "x$ac_cv_prog_cc_c89" = x +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: none needed" >&5 +printf "%s\n" "none needed" >&6; } +else $as_nop + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_prog_cc_c89" >&5 +printf "%s\n" "$ac_cv_prog_cc_c89" >&6; } + CC="$CC $ac_cv_prog_cc_c89" +fi + ac_cv_prog_cc_stdc=$ac_cv_prog_cc_c89 + ac_prog_cc_stdc=c89 +fi +fi + +ac_ext=c +ac_cpp='$CPP $CPPFLAGS' +ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' +ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS >&5' +ac_compiler_gnu=$ac_cv_c_compiler_gnu + + + +if test "$host" = mips-sni-sysv4 && test -n "$GCC"; then + : +else + +# Check whether --enable-largefile was given. +if test ${enable_largefile+y} +then : + enableval=$enable_largefile; +fi + +if test "$enable_largefile" != no; then + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for special C compiler options needed for large files" >&5 +printf %s "checking for special C compiler options needed for large files... " >&6; } +if test ${ac_cv_sys_largefile_CC+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_cv_sys_largefile_CC=no + if test "$GCC" != yes; then + ac_save_CC=$CC + while :; do + # IRIX 6.2 and later do not support large files by default, + # so use the C compiler's -n32 option if that helps. + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/types.h> + /* Check that off_t can represent 2**63 - 1 correctly. + We can't simply define LARGE_OFF_T to be 9223372036854775807, + since some C++ compilers masquerading as C compilers + incorrectly reject 9223372036854775807. */ +#define LARGE_OFF_T (((off_t) 1 << 31 << 31) - 1 + ((off_t) 1 << 31 << 31)) + int off_t_is_large[(LARGE_OFF_T % 2147483629 == 721 + && LARGE_OFF_T % 2147483647 == 1) + ? 1 : -1]; +int +main (void) +{ + + ; + return 0; +} +_ACEOF + if ac_fn_c_try_compile "$LINENO" +then : + break +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam + CC="$CC -n32" + if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_sys_largefile_CC=' -n32'; break +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam + break + done + CC=$ac_save_CC + rm -f conftest.$ac_ext + fi +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_sys_largefile_CC" >&5 +printf "%s\n" "$ac_cv_sys_largefile_CC" >&6; } + if test "$ac_cv_sys_largefile_CC" != no; then + CC=$CC$ac_cv_sys_largefile_CC + fi + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for _FILE_OFFSET_BITS value needed for large files" >&5 +printf %s "checking for _FILE_OFFSET_BITS value needed for large files... " >&6; } +if test ${ac_cv_sys_file_offset_bits+y} +then : + printf %s "(cached) " >&6 +else $as_nop + while :; do + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/types.h> + /* Check that off_t can represent 2**63 - 1 correctly. + We can't simply define LARGE_OFF_T to be 9223372036854775807, + since some C++ compilers masquerading as C compilers + incorrectly reject 9223372036854775807. */ +#define LARGE_OFF_T (((off_t) 1 << 31 << 31) - 1 + ((off_t) 1 << 31 << 31)) + int off_t_is_large[(LARGE_OFF_T % 2147483629 == 721 + && LARGE_OFF_T % 2147483647 == 1) + ? 1 : -1]; +int +main (void) +{ + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_sys_file_offset_bits=no; break +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#define _FILE_OFFSET_BITS 64 +#include <sys/types.h> + /* Check that off_t can represent 2**63 - 1 correctly. + We can't simply define LARGE_OFF_T to be 9223372036854775807, + since some C++ compilers masquerading as C compilers + incorrectly reject 9223372036854775807. */ +#define LARGE_OFF_T (((off_t) 1 << 31 << 31) - 1 + ((off_t) 1 << 31 << 31)) + int off_t_is_large[(LARGE_OFF_T % 2147483629 == 721 + && LARGE_OFF_T % 2147483647 == 1) + ? 1 : -1]; +int +main (void) +{ + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_sys_file_offset_bits=64; break +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + ac_cv_sys_file_offset_bits=unknown + break +done +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_sys_file_offset_bits" >&5 +printf "%s\n" "$ac_cv_sys_file_offset_bits" >&6; } +case $ac_cv_sys_file_offset_bits in #( + no | unknown) ;; + *) +printf "%s\n" "#define _FILE_OFFSET_BITS $ac_cv_sys_file_offset_bits" >>confdefs.h +;; +esac +rm -rf conftest* + if test $ac_cv_sys_file_offset_bits = unknown; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for _LARGE_FILES value needed for large files" >&5 +printf %s "checking for _LARGE_FILES value needed for large files... " >&6; } +if test ${ac_cv_sys_large_files+y} +then : + printf %s "(cached) " >&6 +else $as_nop + while :; do + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/types.h> + /* Check that off_t can represent 2**63 - 1 correctly. + We can't simply define LARGE_OFF_T to be 9223372036854775807, + since some C++ compilers masquerading as C compilers + incorrectly reject 9223372036854775807. */ +#define LARGE_OFF_T (((off_t) 1 << 31 << 31) - 1 + ((off_t) 1 << 31 << 31)) + int off_t_is_large[(LARGE_OFF_T % 2147483629 == 721 + && LARGE_OFF_T % 2147483647 == 1) + ? 1 : -1]; +int +main (void) +{ + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_sys_large_files=no; break +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#define _LARGE_FILES 1 +#include <sys/types.h> + /* Check that off_t can represent 2**63 - 1 correctly. + We can't simply define LARGE_OFF_T to be 9223372036854775807, + since some C++ compilers masquerading as C compilers + incorrectly reject 9223372036854775807. */ +#define LARGE_OFF_T (((off_t) 1 << 31 << 31) - 1 + ((off_t) 1 << 31 << 31)) + int off_t_is_large[(LARGE_OFF_T % 2147483629 == 721 + && LARGE_OFF_T % 2147483647 == 1) + ? 1 : -1]; +int +main (void) +{ + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_sys_large_files=1; break +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + ac_cv_sys_large_files=unknown + break +done +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_sys_large_files" >&5 +printf "%s\n" "$ac_cv_sys_large_files" >&6; } +case $ac_cv_sys_large_files in #( + no | unknown) ;; + *) +printf "%s\n" "#define _LARGE_FILES $ac_cv_sys_large_files" >>confdefs.h +;; +esac +rm -rf conftest* + fi +fi + +fi + +if test -n "$auto_cflags" && test ."$ansi2knr" != .yes; then + if test "${enable_zsh_debug}" = yes; then + if test -n "$GCC"; then + CFLAGS="$CFLAGS -Wall -Wmissing-prototypes -ggdb" + else + CFLAGS="$CFLAGS -g" + fi + else + if test -n "$GCC"; then + CFLAGS="$CFLAGS -Wall -Wmissing-prototypes -O2" + else + CFLAGS="$CFLAGS -O" + fi + fi +fi +if test -n "$auto_ldflags"; then + case "${enable_zsh_debug}$host_os" in + yesaix*|yeshpux*|yesnetbsd*|yesopenbsd*) ;; # "ld -g" is not valid on these systems + darwin*) LDFLAGS=-Wl,-x ;; + yes*) LDFLAGS=-g ;; + *) LDFLAGS=-s ;; + esac +fi + +case "$host_os" in + sco*) CFLAGS="-D__sco $CFLAGS" ;; +esac + +sed=':1 + s/ -s / /g + t1 + s/^ *// + s/ *$//' + +case " $LDFLAGS " in + *" -s "*) strip_exeldflags=true strip_libldflags=true + LDFLAGS=`echo " $LDFLAGS " | sed "$sed"` ;; + *) strip_exeldflags=false strip_libldflags=false ;; +esac + +case " ${EXELDFLAGS+$EXELDFLAGS }" in + " ") ;; + *" -s "*) strip_exeldflags=true + EXELDFLAGS=`echo " $EXELDFLAGS " | sed "$sed"` ;; + *) strip_exeldflags=false ;; +esac + +case " ${LIBLDFLAGS+$LIBLDFLAGS }" in + " ") ;; + *" -s "*) strip_libldflags=true + LIBLDFLAGS=`echo " $LIBLDFLAGS " | sed "$sed"` ;; + *) strip_libldflags=false ;; +esac + + +ac_ext=c +ac_cpp='$CPP $CPPFLAGS' +ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' +ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS >&5' +ac_compiler_gnu=$ac_cv_c_compiler_gnu +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking how to run the C preprocessor" >&5 +printf %s "checking how to run the C preprocessor... " >&6; } +# On Suns, sometimes $CPP names a directory. +if test -n "$CPP" && test -d "$CPP"; then + CPP= +fi +if test -z "$CPP"; then + if test ${ac_cv_prog_CPP+y} +then : + printf %s "(cached) " >&6 +else $as_nop + # Double quotes because $CC needs to be expanded + for CPP in "$CC -E" "$CC -E -traditional-cpp" cpp /lib/cpp + do + ac_preproc_ok=false +for ac_c_preproc_warn_flag in '' yes +do + # Use a header file that comes with gcc, so configuring glibc + # with a fresh cross-compiler works. + # On the NeXT, cc -E runs the code through the compiler's parser, + # not just through cpp. "Syntax error" is here to catch this case. + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <limits.h> + Syntax error +_ACEOF +if ac_fn_c_try_cpp "$LINENO" +then : + +else $as_nop + # Broken: fails on valid input. +continue +fi +rm -f conftest.err conftest.i conftest.$ac_ext + + # OK, works on sane cases. Now check whether nonexistent headers + # can be detected and how. + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <ac_nonexistent.h> +_ACEOF +if ac_fn_c_try_cpp "$LINENO" +then : + # Broken: success on invalid input. +continue +else $as_nop + # Passes both tests. +ac_preproc_ok=: +break +fi +rm -f conftest.err conftest.i conftest.$ac_ext + +done +# Because of `break', _AC_PREPROC_IFELSE's cleaning code was skipped. +rm -f conftest.i conftest.err conftest.$ac_ext +if $ac_preproc_ok +then : + break +fi + + done + ac_cv_prog_CPP=$CPP + +fi + CPP=$ac_cv_prog_CPP +else + ac_cv_prog_CPP=$CPP +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $CPP" >&5 +printf "%s\n" "$CPP" >&6; } +ac_preproc_ok=false +for ac_c_preproc_warn_flag in '' yes +do + # Use a header file that comes with gcc, so configuring glibc + # with a fresh cross-compiler works. + # On the NeXT, cc -E runs the code through the compiler's parser, + # not just through cpp. "Syntax error" is here to catch this case. + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <limits.h> + Syntax error +_ACEOF +if ac_fn_c_try_cpp "$LINENO" +then : + +else $as_nop + # Broken: fails on valid input. +continue +fi +rm -f conftest.err conftest.i conftest.$ac_ext + + # OK, works on sane cases. Now check whether nonexistent headers + # can be detected and how. + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <ac_nonexistent.h> +_ACEOF +if ac_fn_c_try_cpp "$LINENO" +then : + # Broken: success on invalid input. +continue +else $as_nop + # Passes both tests. +ac_preproc_ok=: +break +fi +rm -f conftest.err conftest.i conftest.$ac_ext + +done +# Because of `break', _AC_PREPROC_IFELSE's cleaning code was skipped. +rm -f conftest.i conftest.err conftest.$ac_ext +if $ac_preproc_ok +then : + +else $as_nop + { { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: in \`$ac_pwd':" >&5 +printf "%s\n" "$as_me: error: in \`$ac_pwd':" >&2;} +as_fn_error $? "C preprocessor \"$CPP\" fails sanity check +See \`config.log' for more details" "$LINENO" 5; } +fi + +ac_ext=c +ac_cpp='$CPP $CPPFLAGS' +ac_compile='$CC -c $CFLAGS $CPPFLAGS conftest.$ac_ext >&5' +ac_link='$CC -o conftest$ac_exeext $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS >&5' +ac_compiler_gnu=$ac_cv_c_compiler_gnu + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for an ANSI C-conforming const" >&5 +printf %s "checking for an ANSI C-conforming const... " >&6; } +if test ${ac_cv_c_const+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +int +main (void) +{ + +#ifndef __cplusplus + /* Ultrix mips cc rejects this sort of thing. */ + typedef int charset[2]; + const charset cs = { 0, 0 }; + /* SunOS 4.1.1 cc rejects this. */ + char const *const *pcpcc; + char **ppc; + /* NEC SVR4.0.2 mips cc rejects this. */ + struct point {int x, y;}; + static struct point const zero = {0,0}; + /* IBM XL C 1.02.0.0 rejects this. + It does not let you subtract one const X* pointer from another in + an arm of an if-expression whose if-part is not a constant + expression */ + const char *g = "string"; + pcpcc = &g + (g ? g-g : 0); + /* HPUX 7.0 cc rejects these. */ + ++pcpcc; + ppc = (char**) pcpcc; + pcpcc = (char const *const *) ppc; + { /* SCO 3.2v4 cc rejects this sort of thing. */ + char tx; + char *t = &tx; + char const *s = 0 ? (char *) 0 : (char const *) 0; + + *t++ = 0; + if (s) return 0; + } + { /* Someone thinks the Sun supposedly-ANSI compiler will reject this. */ + int x[] = {25, 17}; + const int *foo = &x[0]; + ++foo; + } + { /* Sun SC1.0 ANSI compiler rejects this -- but not the above. */ + typedef const int *iptr; + iptr p = 0; + ++p; + } + { /* IBM XL C 1.02.0.0 rejects this sort of thing, saying + "k.c", line 2.27: 1506-025 (S) Operand must be a modifiable lvalue. */ + struct s { int j; const int *ap[3]; } bx; + struct s *b = &bx; b->j = 5; + } + { /* ULTRIX-32 V3.1 (Rev 9) vcc rejects this */ + const int foo = 10; + if (!foo) return 0; + } + return !cs[0] && !zero.x; +#endif + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_c_const=yes +else $as_nop + ac_cv_c_const=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_c_const" >&5 +printf "%s\n" "$ac_cv_c_const" >&6; } +if test $ac_cv_c_const = no; then + +printf "%s\n" "#define const /**/" >>confdefs.h + +fi + +case "$host_os" in + darwin[0-9].*) CPP="$CPP -traditional-cpp" ;; +esac + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for ${CC-cc} option to accept ANSI C" >&5 +printf %s "checking for ${CC-cc} option to accept ANSI C... " >&6; } +if test ${fp_cv_prog_cc_stdc+y} +then : + printf %s "(cached) " >&6 +else $as_nop + fp_cv_prog_cc_stdc=no +ac_save_CFLAGS="$CFLAGS" +# Don't try gcc -ansi; that turns off useful extensions and +# breaks some systems' header files. +# AIX -qlanglvl=ansi +# Ultrix and OSF/1 -std1 +# HP-UX -Ae or -Aa -D_HPUX_SOURCE +# SVR4 -Xc +# For HP-UX, we try -Ae first; this turns on ANSI but also extensions, +# as well as defining _HPUX_SOURCE, and we can then use long long. +# We keep the old version for backward compatibility. +for ac_arg in "" -qlanglvl=ansi -std1 -Ae "-Aa -D_HPUX_SOURCE" -Xc +do + CFLAGS="$ac_save_CFLAGS $ac_arg" + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifndef __STDC__ +choke me +#endif + +int +main (void) +{ +int test (int i, double x); +struct s1 {int (*f) (int a);}; +struct s2 {int (*f) (double a);}; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + fp_cv_prog_cc_stdc="$ac_arg"; break +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +done +CFLAGS="$ac_save_CFLAGS" + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $fp_cv_prog_cc_stdc" >&5 +printf "%s\n" "$fp_cv_prog_cc_stdc" >&6; } +case "x$fp_cv_prog_cc_stdc" in + x|xno) ;; + *) CC="$CC $fp_cv_prog_cc_stdc" ;; +esac + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether to use prototypes" >&5 +printf %s "checking whether to use prototypes... " >&6; } +if test ."$ansi2knr" = .yes || test ."$ansi2knr" = .no; then + msg="(overridden) " +else + msg= + if test ."$fp_cv_prog_cc_stdc" = .no; then + ansi2knr=yes + else + ansi2knr=no + fi +fi + +if test "$ansi2knr" = yes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: ${msg}no" >&5 +printf "%s\n" "${msg}no" >&6; } + U=_ +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: ${msg}yes" >&5 +printf "%s\n" "${msg}yes" >&6; } + printf "%s\n" "#define PROTOTYPES 1" >>confdefs.h + + U= +fi + + +ac_header= ac_cache= +for ac_item in $ac_header_c_list +do + if test $ac_cache; then + ac_fn_c_check_header_compile "$LINENO" $ac_header ac_cv_header_$ac_cache "$ac_includes_default" + if eval test \"x\$ac_cv_header_$ac_cache\" = xyes; then + printf "%s\n" "#define $ac_item 1" >> confdefs.h + fi + ac_header= ac_cache= + elif test $ac_header; then + ac_cache=$ac_item + else + ac_header=$ac_item + fi +done + + + + + + + + +if test $ac_cv_header_stdlib_h = yes && test $ac_cv_header_string_h = yes +then : + +printf "%s\n" "#define STDC_HEADERS 1" >>confdefs.h + +fi +ac_fn_c_check_type "$LINENO" "size_t" "ac_cv_type_size_t" "$ac_includes_default" +if test "x$ac_cv_type_size_t" = xyes +then : + +else $as_nop + +printf "%s\n" "#define size_t unsigned int" >>confdefs.h + +fi + +# The Ultrix 4.2 mips builtin alloca declared by alloca.h only works +# for constant arguments. Useless! +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for working alloca.h" >&5 +printf %s "checking for working alloca.h... " >&6; } +if test ${ac_cv_working_alloca_h+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <alloca.h> +int +main (void) +{ +char *p = (char *) alloca (2 * sizeof (int)); + if (p) return 0; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + ac_cv_working_alloca_h=yes +else $as_nop + ac_cv_working_alloca_h=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_working_alloca_h" >&5 +printf "%s\n" "$ac_cv_working_alloca_h" >&6; } +if test $ac_cv_working_alloca_h = yes; then + +printf "%s\n" "#define HAVE_ALLOCA_H 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for alloca" >&5 +printf %s "checking for alloca... " >&6; } +if test ${ac_cv_func_alloca_works+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test $ac_cv_working_alloca_h = yes; then + ac_cv_func_alloca_works=yes +else + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <stdlib.h> +#include <stddef.h> +#ifndef alloca +# ifdef __GNUC__ +# define alloca __builtin_alloca +# elif defined _MSC_VER +# include <malloc.h> +# define alloca _alloca +# else +# ifdef __cplusplus +extern "C" +# endif +void *alloca (size_t); +# endif +#endif + +int +main (void) +{ +char *p = (char *) alloca (1); + if (p) return 0; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + ac_cv_func_alloca_works=yes +else $as_nop + ac_cv_func_alloca_works=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_func_alloca_works" >&5 +printf "%s\n" "$ac_cv_func_alloca_works" >&6; } +fi + +if test $ac_cv_func_alloca_works = yes; then + +printf "%s\n" "#define HAVE_ALLOCA 1" >>confdefs.h + +else + # The SVR3 libPW and SVR4 libucb both contain incompatible functions +# that cause trouble. Some versions do not even contain alloca or +# contain a buggy version. If you still want to use their alloca, +# use ar to extract alloca.o from them instead of compiling alloca.c. + +ALLOCA=\${LIBOBJDIR}alloca.$ac_objext + +printf "%s\n" "#define C_ALLOCA 1" >>confdefs.h + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking stack direction for C alloca" >&5 +printf %s "checking stack direction for C alloca... " >&6; } +if test ${ac_cv_c_stack_direction+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + ac_cv_c_stack_direction=0 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$ac_includes_default +int +find_stack_direction (int *addr, int depth) +{ + int dir, dummy = 0; + if (! addr) + addr = &dummy; + *addr = addr < &dummy ? 1 : addr == &dummy ? 0 : -1; + dir = depth ? find_stack_direction (addr, depth - 1) : 0; + return dir + dummy; +} + +int +main (int argc, char **argv) +{ + return find_stack_direction (0, argc + !argv + 20) < 0; +} +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + ac_cv_c_stack_direction=1 +else $as_nop + ac_cv_c_stack_direction=-1 +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_c_stack_direction" >&5 +printf "%s\n" "$ac_cv_c_stack_direction" >&6; } +printf "%s\n" "#define STACK_DIRECTION $ac_cv_c_stack_direction" >>confdefs.h + + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if the compiler supports union initialisation" >&5 +printf %s "checking if the compiler supports union initialisation... " >&6; } +if test ${zsh_cv_c_have_union_init+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +union{void *p;long l;}u={0}; +int +main (void) +{ +u.l=1; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_c_have_union_init=yes +else $as_nop + zsh_cv_c_have_union_init=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_c_have_union_init" >&5 +printf "%s\n" "$zsh_cv_c_have_union_init" >&6; } + +if test x$zsh_cv_c_have_union_init = xyes; then + printf "%s\n" "#define HAVE_UNION_INIT 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if signed to unsigned casting is broken" >&5 +printf %s "checking if signed to unsigned casting is broken... " >&6; } +if test ${zsh_cv_c_broken_signed_to_unsigned_casting+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_c_broken_signed_to_unsigned_casting=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +main(){return((int)(unsigned char)((char) -1) == 255);} +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_c_broken_signed_to_unsigned_casting=yes +else $as_nop + zsh_cv_c_broken_signed_to_unsigned_casting=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_c_broken_signed_to_unsigned_casting" >&5 +printf "%s\n" "$zsh_cv_c_broken_signed_to_unsigned_casting" >&6; } + +if test x$zsh_cv_c_broken_signed_to_unsigned_casting = xyes; then + printf "%s\n" "#define BROKEN_SIGNED_TO_UNSIGNED_CASTING 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if the compiler supports variable-length arrays" >&5 +printf %s "checking if the compiler supports variable-length arrays... " >&6; } +if test ${zsh_cv_c_variable_length_arrays+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +int foo(), n; +int +main (void) +{ +int i[foo()], a[n+1]; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_c_variable_length_arrays=yes +else $as_nop + zsh_cv_c_variable_length_arrays=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_c_variable_length_arrays" >&5 +printf "%s\n" "$zsh_cv_c_variable_length_arrays" >&6; } + +if test x$zsh_cv_c_variable_length_arrays = xyes; then + printf "%s\n" "#define HAVE_VARIABLE_LENGTH_ARRAYS 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether ${MAKE-make} sets \$(MAKE)" >&5 +printf %s "checking whether ${MAKE-make} sets \$(MAKE)... " >&6; } +set x ${MAKE-make} +ac_make=`printf "%s\n" "$2" | sed 's/+/p/g; s/[^a-zA-Z0-9_]/_/g'` +if eval test \${ac_cv_prog_make_${ac_make}_set+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat >conftest.make <<\_ACEOF +SHELL = /bin/sh +all: + @echo '@@@%%%=$(MAKE)=@@@%%%' +_ACEOF +# GNU make sometimes prints "make[1]: Entering ...", which would confuse us. +case `${MAKE-make} -f conftest.make 2>/dev/null` in + *@@@%%%=?*=@@@%%%*) + eval ac_cv_prog_make_${ac_make}_set=yes;; + *) + eval ac_cv_prog_make_${ac_make}_set=no;; +esac +rm -f conftest.make +fi +if eval test \$ac_cv_prog_make_${ac_make}_set = yes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: yes" >&5 +printf "%s\n" "yes" >&6; } + SET_MAKE= +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } + SET_MAKE="MAKE=${MAKE-make}" +fi + + # Find a good install program. We prefer a C program (faster), +# so one script is as good as another. But avoid the broken or +# incompatible versions: +# SysV /etc/install, /usr/sbin/install +# SunOS /usr/etc/install +# IRIX /sbin/install +# AIX /bin/install +# AmigaOS /C/install, which installs bootblocks on floppy discs +# AIX 4 /usr/bin/installbsd, which doesn't work without a -g flag +# AFS /usr/afsws/bin/install, which mishandles nonexistent args +# SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff" +# OS/2's system install, which has a completely different semantic +# ./install, which can be erroneously created by make from ./install.sh. +# Reject install programs that cannot install multiple files. +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for a BSD-compatible install" >&5 +printf %s "checking for a BSD-compatible install... " >&6; } +if test -z "$INSTALL"; then +if test ${ac_cv_path_install+y} +then : + printf %s "(cached) " >&6 +else $as_nop + as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + # Account for fact that we put trailing slashes in our PATH walk. +case $as_dir in #(( + ./ | /[cC]/* | \ + /etc/* | /usr/sbin/* | /usr/etc/* | /sbin/* | /usr/afsws/bin/* | \ + ?:[\\/]os2[\\/]install[\\/]* | ?:[\\/]OS2[\\/]INSTALL[\\/]* | \ + /usr/ucb/* ) ;; + *) + # OSF1 and SCO ODT 3.0 have their own names for install. + # Don't use installbsd from OSF since it installs stuff as root + # by default. + for ac_prog in ginstall scoinst install; do + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_prog$ac_exec_ext"; then + if test $ac_prog = install && + grep dspmsg "$as_dir$ac_prog$ac_exec_ext" >/dev/null 2>&1; then + # AIX install. It has an incompatible calling convention. + : + elif test $ac_prog = install && + grep pwplus "$as_dir$ac_prog$ac_exec_ext" >/dev/null 2>&1; then + # program-specific install script used by HP pwplus--don't use. + : + else + rm -rf conftest.one conftest.two conftest.dir + echo one > conftest.one + echo two > conftest.two + mkdir conftest.dir + if "$as_dir$ac_prog$ac_exec_ext" -c conftest.one conftest.two "`pwd`/conftest.dir/" && + test -s conftest.one && test -s conftest.two && + test -s conftest.dir/conftest.one && + test -s conftest.dir/conftest.two + then + ac_cv_path_install="$as_dir$ac_prog$ac_exec_ext -c" + break 3 + fi + fi + fi + done + done + ;; +esac + + done +IFS=$as_save_IFS + +rm -rf conftest.one conftest.two conftest.dir + +fi + if test ${ac_cv_path_install+y}; then + INSTALL=$ac_cv_path_install + else + # As a last resort, use the slow shell script. Don't cache a + # value for INSTALL within a source directory, because that will + # break other packages using the cache if that directory is + # removed, or if the value is a relative name. + INSTALL=$ac_install_sh + fi +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $INSTALL" >&5 +printf "%s\n" "$INSTALL" >&6; } + +# Use test -z because SunOS4 sh mishandles braces in ${var-val}. +# It thinks the first close brace ends the variable substitution. +test -z "$INSTALL_PROGRAM" && INSTALL_PROGRAM='${INSTALL}' + +test -z "$INSTALL_SCRIPT" && INSTALL_SCRIPT='${INSTALL}' + +test -z "$INSTALL_DATA" && INSTALL_DATA='${INSTALL} -m 644' + for ac_prog in gawk mawk nawk awk +do + # Extract the first word of "$ac_prog", so it can be a program name with args. +set dummy $ac_prog; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_AWK+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$AWK"; then + ac_cv_prog_AWK="$AWK" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_AWK="$ac_prog" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +AWK=$ac_cv_prog_AWK +if test -n "$AWK"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $AWK" >&5 +printf "%s\n" "$AWK" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + + test -n "$AWK" && break +done + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether ln works" >&5 +printf %s "checking whether ln works... " >&6; } +if test ${ac_cv_prog_LN+y} +then : + printf %s "(cached) " >&6 +else $as_nop + rm -f conftestdata conftestlink +echo > conftestdata +if ln conftestdata conftestlink 2>/dev/null +then + rm -f conftestdata conftestlink + ac_cv_prog_LN="ln" +else + rm -f conftestdata + ac_cv_prog_LN="cp" +fi +fi +LN="$ac_cv_prog_LN" +if test "$ac_cv_prog_LN" = "ln"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: yes" >&5 +printf "%s\n" "yes" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether ln -s works" >&5 +printf %s "checking whether ln -s works... " >&6; } +LN_S=$as_ln_s +if test "$LN_S" = "ln -s"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: yes" >&5 +printf "%s\n" "yes" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no, using $LN_S" >&5 +printf "%s\n" "no, using $LN_S" >&6; } +fi + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for grep that handles long lines and -e" >&5 +printf %s "checking for grep that handles long lines and -e... " >&6; } +if test ${ac_cv_path_GREP+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -z "$GREP"; then + ac_path_GREP_found=false + # Loop through the user's path and test for each of PROGNAME-LIST + as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH$PATH_SEPARATOR/usr/xpg4/bin +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_prog in grep ggrep + do + for ac_exec_ext in '' $ac_executable_extensions; do + ac_path_GREP="$as_dir$ac_prog$ac_exec_ext" + as_fn_executable_p "$ac_path_GREP" || continue +# Check for GNU ac_path_GREP and select it if it is found. + # Check for GNU $ac_path_GREP +case `"$ac_path_GREP" --version 2>&1` in +*GNU*) + ac_cv_path_GREP="$ac_path_GREP" ac_path_GREP_found=:;; +*) + ac_count=0 + printf %s 0123456789 >"conftest.in" + while : + do + cat "conftest.in" "conftest.in" >"conftest.tmp" + mv "conftest.tmp" "conftest.in" + cp "conftest.in" "conftest.nl" + printf "%s\n" 'GREP' >> "conftest.nl" + "$ac_path_GREP" -e 'GREP$' -e '-(cannot match)-' < "conftest.nl" >"conftest.out" 2>/dev/null || break + diff "conftest.out" "conftest.nl" >/dev/null 2>&1 || break + as_fn_arith $ac_count + 1 && ac_count=$as_val + if test $ac_count -gt ${ac_path_GREP_max-0}; then + # Best one so far, save it but keep looking for a better one + ac_cv_path_GREP="$ac_path_GREP" + ac_path_GREP_max=$ac_count + fi + # 10*(2^10) chars as input seems more than enough + test $ac_count -gt 10 && break + done + rm -f conftest.in conftest.tmp conftest.nl conftest.out;; +esac + + $ac_path_GREP_found && break 3 + done + done + done +IFS=$as_save_IFS + if test -z "$ac_cv_path_GREP"; then + as_fn_error $? "no acceptable grep could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" "$LINENO" 5 + fi +else + ac_cv_path_GREP=$GREP +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_path_GREP" >&5 +printf "%s\n" "$ac_cv_path_GREP" >&6; } + GREP="$ac_cv_path_GREP" + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for egrep" >&5 +printf %s "checking for egrep... " >&6; } +if test ${ac_cv_path_EGREP+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if echo a | $GREP -E '(a|b)' >/dev/null 2>&1 + then ac_cv_path_EGREP="$GREP -E" + else + if test -z "$EGREP"; then + ac_path_EGREP_found=false + # Loop through the user's path and test for each of PROGNAME-LIST + as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH$PATH_SEPARATOR/usr/xpg4/bin +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_prog in egrep + do + for ac_exec_ext in '' $ac_executable_extensions; do + ac_path_EGREP="$as_dir$ac_prog$ac_exec_ext" + as_fn_executable_p "$ac_path_EGREP" || continue +# Check for GNU ac_path_EGREP and select it if it is found. + # Check for GNU $ac_path_EGREP +case `"$ac_path_EGREP" --version 2>&1` in +*GNU*) + ac_cv_path_EGREP="$ac_path_EGREP" ac_path_EGREP_found=:;; +*) + ac_count=0 + printf %s 0123456789 >"conftest.in" + while : + do + cat "conftest.in" "conftest.in" >"conftest.tmp" + mv "conftest.tmp" "conftest.in" + cp "conftest.in" "conftest.nl" + printf "%s\n" 'EGREP' >> "conftest.nl" + "$ac_path_EGREP" 'EGREP$' < "conftest.nl" >"conftest.out" 2>/dev/null || break + diff "conftest.out" "conftest.nl" >/dev/null 2>&1 || break + as_fn_arith $ac_count + 1 && ac_count=$as_val + if test $ac_count -gt ${ac_path_EGREP_max-0}; then + # Best one so far, save it but keep looking for a better one + ac_cv_path_EGREP="$ac_path_EGREP" + ac_path_EGREP_max=$ac_count + fi + # 10*(2^10) chars as input seems more than enough + test $ac_count -gt 10 && break + done + rm -f conftest.in conftest.tmp conftest.nl conftest.out;; +esac + + $ac_path_EGREP_found && break 3 + done + done + done +IFS=$as_save_IFS + if test -z "$ac_cv_path_EGREP"; then + as_fn_error $? "no acceptable egrep could be found in $PATH$PATH_SEPARATOR/usr/xpg4/bin" "$LINENO" 5 + fi +else + ac_cv_path_EGREP=$EGREP +fi + + fi +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_path_EGREP" >&5 +printf "%s\n" "$ac_cv_path_EGREP" >&6; } + EGREP="$ac_cv_path_EGREP" + + for ac_prog in yodl +do + # Extract the first word of "$ac_prog", so it can be a program name with args. +set dummy $ac_prog; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_YODL+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$YODL"; then + ac_cv_prog_YODL="$YODL" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_YODL="$ac_prog" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +YODL=$ac_cv_prog_YODL +if test -n "$YODL"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $YODL" >&5 +printf "%s\n" "$YODL" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + + test -n "$YODL" && break +done +test -n "$YODL" || YODL=": yodl" + + +YODL_OPTIONS='' +if test "x$ac_cv_prog_YODL" = xyodl; then + case `yodl --version` in + *"version 2."*) YODL_OPTIONS='-k' ;; + *"version 3."*) YODL_OPTIONS='-k -L' ;; + *"version 4."*) YODL_OPTIONS='-k -L' ;; + esac +fi + + +for ac_prog in texi2dvi +do + # Extract the first word of "$ac_prog", so it can be a program name with args. +set dummy $ac_prog; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_TEXI2DVI+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$TEXI2DVI"; then + ac_cv_prog_TEXI2DVI="$TEXI2DVI" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_TEXI2DVI="$ac_prog" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +TEXI2DVI=$ac_cv_prog_TEXI2DVI +if test -n "$TEXI2DVI"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $TEXI2DVI" >&5 +printf "%s\n" "$TEXI2DVI" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + + test -n "$TEXI2DVI" && break +done +test -n "$TEXI2DVI" || TEXI2DVI=": texi2dvi" + +for ac_prog in texi2pdf +do + # Extract the first word of "$ac_prog", so it can be a program name with args. +set dummy $ac_prog; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_TEXI2PDF+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$TEXI2PDF"; then + ac_cv_prog_TEXI2PDF="$TEXI2PDF" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_TEXI2PDF="$ac_prog" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +TEXI2PDF=$ac_cv_prog_TEXI2PDF +if test -n "$TEXI2PDF"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $TEXI2PDF" >&5 +printf "%s\n" "$TEXI2PDF" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + + test -n "$TEXI2PDF" && break +done +test -n "$TEXI2PDF" || TEXI2PDF=": texi2pdf" + +for ac_prog in texi2any texi2html +do + # Extract the first word of "$ac_prog", so it can be a program name with args. +set dummy $ac_prog; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_TEXI2HTML+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$TEXI2HTML"; then + ac_cv_prog_TEXI2HTML="$TEXI2HTML" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_TEXI2HTML="$ac_prog" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +TEXI2HTML=$ac_cv_prog_TEXI2HTML +if test -n "$TEXI2HTML"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $TEXI2HTML" >&5 +printf "%s\n" "$TEXI2HTML" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + + test -n "$TEXI2HTML" && break +done +test -n "$TEXI2HTML" || TEXI2HTML=": texi2html" + + +if test x"$TEXI2PDF" != xtexi2pdf && test x"$TEXI2DVI" = xtexi2dvi; then + TEXI2PDF='texi2dvi --pdf' +fi + +if test x"$TEXI2HTML" = xtexi2any; then + TEXI2HTML='texi2any -c TEXI2HTML=1' +fi + +case "$LC_PAPER" in + ??_US*) PAPERSIZE=us ;; + *) PAPERSIZE=a4 ;; +esac + + +for ac_prog in ansi2knr +do + # Extract the first word of "$ac_prog", so it can be a program name with args. +set dummy $ac_prog; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_ANSI2KNR+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$ANSI2KNR"; then + ac_cv_prog_ANSI2KNR="$ANSI2KNR" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_ANSI2KNR="$ac_prog" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +ANSI2KNR=$ac_cv_prog_ANSI2KNR +if test -n "$ANSI2KNR"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ANSI2KNR" >&5 +printf "%s\n" "$ANSI2KNR" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + + test -n "$ANSI2KNR" && break +done +test -n "$ANSI2KNR" || ANSI2KNR=": ansi2knr" + + +if test x"$ansi2knr" = xyes && test x"$ANSI2KNR" = x": ansi2knr"; then + echo "----------" + echo "configure fatal error:" + echo "ansi2knr was specified (--enable-ansi2knr) but the program could not be found." + echo "Either remove the configure option if it is not required or build the ansi2knr" + echo "program before reconfiguring Zsh. The source code for ansi2knr is also" + echo "available in the GPL directory on Zsh distribution sites." + exit 1 +fi + +ac_header_dirent=no +for ac_hdr in dirent.h sys/ndir.h sys/dir.h ndir.h; do + as_ac_Header=`printf "%s\n" "ac_cv_header_dirent_$ac_hdr" | $as_tr_sh` +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_hdr that defines DIR" >&5 +printf %s "checking for $ac_hdr that defines DIR... " >&6; } +if eval test \${$as_ac_Header+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/types.h> +#include <$ac_hdr> + +int +main (void) +{ +if ((DIR *) 0) +return 0; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + eval "$as_ac_Header=yes" +else $as_nop + eval "$as_ac_Header=no" +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +eval ac_res=\$$as_ac_Header + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_res" >&5 +printf "%s\n" "$ac_res" >&6; } +if eval test \"x\$"$as_ac_Header"\" = x"yes" +then : + cat >>confdefs.h <<_ACEOF +#define `printf "%s\n" "HAVE_$ac_hdr" | $as_tr_cpp` 1 +_ACEOF + +ac_header_dirent=$ac_hdr; break +fi + +done +# Two versions of opendir et al. are in -ldir and -lx on SCO Xenix. +if test $ac_header_dirent = dirent.h; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing opendir" >&5 +printf %s "checking for library containing opendir... " >&6; } +if test ${ac_cv_search_opendir+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char opendir (); +int +main (void) +{ +return opendir (); + ; + return 0; +} +_ACEOF +for ac_lib in '' dir +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_opendir=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_opendir+y} +then : + break +fi +done +if test ${ac_cv_search_opendir+y} +then : + +else $as_nop + ac_cv_search_opendir=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_opendir" >&5 +printf "%s\n" "$ac_cv_search_opendir" >&6; } +ac_res=$ac_cv_search_opendir +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing opendir" >&5 +printf %s "checking for library containing opendir... " >&6; } +if test ${ac_cv_search_opendir+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char opendir (); +int +main (void) +{ +return opendir (); + ; + return 0; +} +_ACEOF +for ac_lib in '' x +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_opendir=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_opendir+y} +then : + break +fi +done +if test ${ac_cv_search_opendir+y} +then : + +else $as_nop + ac_cv_search_opendir=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_opendir" >&5 +printf "%s\n" "$ac_cv_search_opendir" >&6; } +ac_res=$ac_cv_search_opendir +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether stat file-mode macros are broken" >&5 +printf %s "checking whether stat file-mode macros are broken... " >&6; } +if test ${ac_cv_header_stat_broken+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/types.h> +#include <sys/stat.h> + +#if defined S_ISBLK && defined S_IFDIR +extern char c1[S_ISBLK (S_IFDIR) ? -1 : 1]; +#endif + +#if defined S_ISBLK && defined S_IFCHR +extern char c2[S_ISBLK (S_IFCHR) ? -1 : 1]; +#endif + +#if defined S_ISLNK && defined S_IFREG +extern char c3[S_ISLNK (S_IFREG) ? -1 : 1]; +#endif + +#if defined S_ISSOCK && defined S_IFREG +extern char c4[S_ISSOCK (S_IFREG) ? -1 : 1]; +#endif + +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_header_stat_broken=no +else $as_nop + ac_cv_header_stat_broken=yes +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_header_stat_broken" >&5 +printf "%s\n" "$ac_cv_header_stat_broken" >&6; } +if test $ac_cv_header_stat_broken = yes; then + +printf "%s\n" "#define STAT_MACROS_BROKEN 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for sys/wait.h that is POSIX.1 compatible" >&5 +printf %s "checking for sys/wait.h that is POSIX.1 compatible... " >&6; } +if test ${ac_cv_header_sys_wait_h+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/types.h> +#include <sys/wait.h> +#ifndef WEXITSTATUS +# define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8) +#endif +#ifndef WIFEXITED +# define WIFEXITED(stat_val) (((stat_val) & 255) == 0) +#endif + +int +main (void) +{ + int s; + wait (&s); + s = WIFEXITED (s) ? WEXITSTATUS (s) : 1; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_header_sys_wait_h=yes +else $as_nop + ac_cv_header_sys_wait_h=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_header_sys_wait_h" >&5 +printf "%s\n" "$ac_cv_header_sys_wait_h" >&6; } +if test $ac_cv_header_sys_wait_h = yes; then + +printf "%s\n" "#define HAVE_SYS_WAIT_H 1" >>confdefs.h + +fi + + +oldcflags="$CFLAGS" +if test x$enable_pcre = xyes; then +# Extract the first word of "pcre-config", so it can be a program name with args. +set dummy pcre-config; ac_word=$2 +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 +printf %s "checking for $ac_word... " >&6; } +if test ${ac_cv_prog_PCRECONF+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -n "$PCRECONF"; then + ac_cv_prog_PCRECONF="$PCRECONF" # Let the user override the test. +else +as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + for ac_exec_ext in '' $ac_executable_extensions; do + if as_fn_executable_p "$as_dir$ac_word$ac_exec_ext"; then + ac_cv_prog_PCRECONF="pcre-config" + printf "%s\n" "$as_me:${as_lineno-$LINENO}: found $as_dir$ac_word$ac_exec_ext" >&5 + break 2 + fi +done + done +IFS=$as_save_IFS + +fi +fi +PCRECONF=$ac_cv_prog_PCRECONF +if test -n "$PCRECONF"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $PCRECONF" >&5 +printf "%s\n" "$PCRECONF" >&6; } +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi + + +if test "x$ac_cv_prog_PCRECONF" = xpcre-config; then + CPPFLAGS="$CPPFLAGS `pcre-config --cflags`" +fi +fi + +ac_fn_c_check_header_compile "$LINENO" "sys/time.h" "ac_cv_header_sys_time_h" "$ac_includes_default" +if test "x$ac_cv_header_sys_time_h" = xyes +then : + printf "%s\n" "#define HAVE_SYS_TIME_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "sys/times.h" "ac_cv_header_sys_times_h" "$ac_includes_default" +if test "x$ac_cv_header_sys_times_h" = xyes +then : + printf "%s\n" "#define HAVE_SYS_TIMES_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "sys/select.h" "ac_cv_header_sys_select_h" "$ac_includes_default" +if test "x$ac_cv_header_sys_select_h" = xyes +then : + printf "%s\n" "#define HAVE_SYS_SELECT_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "termcap.h" "ac_cv_header_termcap_h" "$ac_includes_default" +if test "x$ac_cv_header_termcap_h" = xyes +then : + printf "%s\n" "#define HAVE_TERMCAP_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "termio.h" "ac_cv_header_termio_h" "$ac_includes_default" +if test "x$ac_cv_header_termio_h" = xyes +then : + printf "%s\n" "#define HAVE_TERMIO_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "termios.h" "ac_cv_header_termios_h" "$ac_includes_default" +if test "x$ac_cv_header_termios_h" = xyes +then : + printf "%s\n" "#define HAVE_TERMIOS_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "sys/param.h" "ac_cv_header_sys_param_h" "$ac_includes_default" +if test "x$ac_cv_header_sys_param_h" = xyes +then : + printf "%s\n" "#define HAVE_SYS_PARAM_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "sys/filio.h" "ac_cv_header_sys_filio_h" "$ac_includes_default" +if test "x$ac_cv_header_sys_filio_h" = xyes +then : + printf "%s\n" "#define HAVE_SYS_FILIO_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "string.h" "ac_cv_header_string_h" "$ac_includes_default" +if test "x$ac_cv_header_string_h" = xyes +then : + printf "%s\n" "#define HAVE_STRING_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "memory.h" "ac_cv_header_memory_h" "$ac_includes_default" +if test "x$ac_cv_header_memory_h" = xyes +then : + printf "%s\n" "#define HAVE_MEMORY_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "limits.h" "ac_cv_header_limits_h" "$ac_includes_default" +if test "x$ac_cv_header_limits_h" = xyes +then : + printf "%s\n" "#define HAVE_LIMITS_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "fcntl.h" "ac_cv_header_fcntl_h" "$ac_includes_default" +if test "x$ac_cv_header_fcntl_h" = xyes +then : + printf "%s\n" "#define HAVE_FCNTL_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "libc.h" "ac_cv_header_libc_h" "$ac_includes_default" +if test "x$ac_cv_header_libc_h" = xyes +then : + printf "%s\n" "#define HAVE_LIBC_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "sys/utsname.h" "ac_cv_header_sys_utsname_h" "$ac_includes_default" +if test "x$ac_cv_header_sys_utsname_h" = xyes +then : + printf "%s\n" "#define HAVE_SYS_UTSNAME_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "sys/resource.h" "ac_cv_header_sys_resource_h" "$ac_includes_default" +if test "x$ac_cv_header_sys_resource_h" = xyes +then : + printf "%s\n" "#define HAVE_SYS_RESOURCE_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "locale.h" "ac_cv_header_locale_h" "$ac_includes_default" +if test "x$ac_cv_header_locale_h" = xyes +then : + printf "%s\n" "#define HAVE_LOCALE_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "errno.h" "ac_cv_header_errno_h" "$ac_includes_default" +if test "x$ac_cv_header_errno_h" = xyes +then : + printf "%s\n" "#define HAVE_ERRNO_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "stdio.h" "ac_cv_header_stdio_h" "$ac_includes_default" +if test "x$ac_cv_header_stdio_h" = xyes +then : + printf "%s\n" "#define HAVE_STDIO_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "stdarg.h" "ac_cv_header_stdarg_h" "$ac_includes_default" +if test "x$ac_cv_header_stdarg_h" = xyes +then : + printf "%s\n" "#define HAVE_STDARG_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "varargs.h" "ac_cv_header_varargs_h" "$ac_includes_default" +if test "x$ac_cv_header_varargs_h" = xyes +then : + printf "%s\n" "#define HAVE_VARARGS_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "stdlib.h" "ac_cv_header_stdlib_h" "$ac_includes_default" +if test "x$ac_cv_header_stdlib_h" = xyes +then : + printf "%s\n" "#define HAVE_STDLIB_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "unistd.h" "ac_cv_header_unistd_h" "$ac_includes_default" +if test "x$ac_cv_header_unistd_h" = xyes +then : + printf "%s\n" "#define HAVE_UNISTD_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "sys/capability.h" "ac_cv_header_sys_capability_h" "$ac_includes_default" +if test "x$ac_cv_header_sys_capability_h" = xyes +then : + printf "%s\n" "#define HAVE_SYS_CAPABILITY_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "utmp.h" "ac_cv_header_utmp_h" "$ac_includes_default" +if test "x$ac_cv_header_utmp_h" = xyes +then : + printf "%s\n" "#define HAVE_UTMP_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "utmpx.h" "ac_cv_header_utmpx_h" "$ac_includes_default" +if test "x$ac_cv_header_utmpx_h" = xyes +then : + printf "%s\n" "#define HAVE_UTMPX_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "sys/types.h" "ac_cv_header_sys_types_h" "$ac_includes_default" +if test "x$ac_cv_header_sys_types_h" = xyes +then : + printf "%s\n" "#define HAVE_SYS_TYPES_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "pwd.h" "ac_cv_header_pwd_h" "$ac_includes_default" +if test "x$ac_cv_header_pwd_h" = xyes +then : + printf "%s\n" "#define HAVE_PWD_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "grp.h" "ac_cv_header_grp_h" "$ac_includes_default" +if test "x$ac_cv_header_grp_h" = xyes +then : + printf "%s\n" "#define HAVE_GRP_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "poll.h" "ac_cv_header_poll_h" "$ac_includes_default" +if test "x$ac_cv_header_poll_h" = xyes +then : + printf "%s\n" "#define HAVE_POLL_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "sys/mman.h" "ac_cv_header_sys_mman_h" "$ac_includes_default" +if test "x$ac_cv_header_sys_mman_h" = xyes +then : + printf "%s\n" "#define HAVE_SYS_MMAN_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "netinet/in_systm.h" "ac_cv_header_netinet_in_systm_h" "$ac_includes_default" +if test "x$ac_cv_header_netinet_in_systm_h" = xyes +then : + printf "%s\n" "#define HAVE_NETINET_IN_SYSTM_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "pcre.h" "ac_cv_header_pcre_h" "$ac_includes_default" +if test "x$ac_cv_header_pcre_h" = xyes +then : + printf "%s\n" "#define HAVE_PCRE_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "langinfo.h" "ac_cv_header_langinfo_h" "$ac_includes_default" +if test "x$ac_cv_header_langinfo_h" = xyes +then : + printf "%s\n" "#define HAVE_LANGINFO_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "wchar.h" "ac_cv_header_wchar_h" "$ac_includes_default" +if test "x$ac_cv_header_wchar_h" = xyes +then : + printf "%s\n" "#define HAVE_WCHAR_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "stddef.h" "ac_cv_header_stddef_h" "$ac_includes_default" +if test "x$ac_cv_header_stddef_h" = xyes +then : + printf "%s\n" "#define HAVE_STDDEF_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "sys/stropts.h" "ac_cv_header_sys_stropts_h" "$ac_includes_default" +if test "x$ac_cv_header_sys_stropts_h" = xyes +then : + printf "%s\n" "#define HAVE_SYS_STROPTS_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "iconv.h" "ac_cv_header_iconv_h" "$ac_includes_default" +if test "x$ac_cv_header_iconv_h" = xyes +then : + printf "%s\n" "#define HAVE_ICONV_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "ncurses.h" "ac_cv_header_ncurses_h" "$ac_includes_default" +if test "x$ac_cv_header_ncurses_h" = xyes +then : + printf "%s\n" "#define HAVE_NCURSES_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "ncursesw/ncurses.h" "ac_cv_header_ncursesw_ncurses_h" "$ac_includes_default" +if test "x$ac_cv_header_ncursesw_ncurses_h" = xyes +then : + printf "%s\n" "#define HAVE_NCURSESW_NCURSES_H 1" >>confdefs.h + +fi +ac_fn_c_check_header_compile "$LINENO" "ncurses/ncurses.h" "ac_cv_header_ncurses_ncurses_h" "$ac_includes_default" +if test "x$ac_cv_header_ncurses_ncurses_h" = xyes +then : + printf "%s\n" "#define HAVE_NCURSES_NCURSES_H 1" >>confdefs.h + +fi + +if test x$dynamic = xyes; then + ac_fn_c_check_header_compile "$LINENO" "dlfcn.h" "ac_cv_header_dlfcn_h" "$ac_includes_default" +if test "x$ac_cv_header_dlfcn_h" = xyes +then : + printf "%s\n" "#define HAVE_DLFCN_H 1" >>confdefs.h + +fi + + ac_fn_c_check_header_compile "$LINENO" "dl.h" "ac_cv_header_dl_h" "$ac_includes_default" +if test "x$ac_cv_header_dl_h" = xyes +then : + printf "%s\n" "#define HAVE_DL_H 1" >>confdefs.h + +fi + +fi + + +if test x$ac_cv_header_sys_time_h = xyes && test x$ac_cv_header_sys_select_h = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for conflicts in sys/time.h and sys/select.h" >&5 +printf %s "checking for conflicts in sys/time.h and sys/select.h... " >&6; } +if test ${zsh_cv_header_time_h_select_h_conflicts+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/time.h> +#include <sys/select.h> +int +main (void) +{ +int i; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_header_time_h_select_h_conflicts=no +else $as_nop + zsh_cv_header_time_h_select_h_conflicts=yes +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_header_time_h_select_h_conflicts" >&5 +printf "%s\n" "$zsh_cv_header_time_h_select_h_conflicts" >&6; } + if test x$zsh_cv_header_time_h_select_h_conflicts = xyes; then + printf "%s\n" "#define TIME_H_SELECT_H_CONFLICTS 1" >>confdefs.h + + fi +fi + + +if test x$ac_cv_header_termios_h = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking TIOCGWINSZ in termios.h" >&5 +printf %s "checking TIOCGWINSZ in termios.h... " >&6; } +if test ${zsh_cv_header_termios_h_tiocgwinsz+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#include <termios.h> +int +main (void) +{ +int x = TIOCGWINSZ; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + zsh_cv_header_termios_h_tiocgwinsz=yes +else $as_nop + zsh_cv_header_termios_h_tiocgwinsz=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_header_termios_h_tiocgwinsz" >&5 +printf "%s\n" "$zsh_cv_header_termios_h_tiocgwinsz" >&6; } +else + zsh_cv_header_termios_h_tiocgwinsz=no +fi +if test x$zsh_cv_header_termios_h_tiocgwinsz = xno; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking TIOCGWINSZ in sys/ioctl.h" >&5 +printf %s "checking TIOCGWINSZ in sys/ioctl.h... " >&6; } +if test ${zsh_cv_header_sys_ioctl_h_tiocgwinsz+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#include <sys/ioctl.h> +int +main (void) +{ +int x = TIOCGWINSZ; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + zsh_cv_header_sys_ioctl_h_tiocgwinsz=yes +else $as_nop + zsh_cv_header_sys_ioctl_h_tiocgwinsz=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_header_sys_ioctl_h_tiocgwinsz" >&5 +printf "%s\n" "$zsh_cv_header_sys_ioctl_h_tiocgwinsz" >&6; } + if test x$zsh_cv_header_sys_ioctl_h_tiocgwinsz = xyes; then + printf "%s\n" "#define GWINSZ_IN_SYS_IOCTL 1" >>confdefs.h + + fi +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for streams headers including struct winsize" >&5 +printf %s "checking for streams headers including struct winsize... " >&6; } +if test ${ac_cv_winsize_in_ptem+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/stream.h> +#include <sys/ptem.h> +int +main (void) +{ +struct winsize wsz + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_winsize_in_ptem=yes +else $as_nop + ac_cv_winsize_in_ptem=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_winsize_in_ptem" >&5 +printf "%s\n" "$ac_cv_winsize_in_ptem" >&6; } +if test x$ac_cv_winsize_in_ptem = xyes; then + printf "%s\n" "#define WINSIZE_IN_PTEM 1" >>confdefs.h + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for printf in -lc" >&5 +printf %s "checking for printf in -lc... " >&6; } +if test ${ac_cv_lib_c_printf+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_check_lib_save_LIBS=$LIBS +LIBS="-lc $LIBS" +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char printf (); +int +main (void) +{ +return printf (); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + ac_cv_lib_c_printf=yes +else $as_nop + ac_cv_lib_c_printf=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +LIBS=$ac_check_lib_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_lib_c_printf" >&5 +printf "%s\n" "$ac_cv_lib_c_printf" >&6; } +if test "x$ac_cv_lib_c_printf" = xyes +then : + LIBS="$LIBS -lc" +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for pow in -lm" >&5 +printf %s "checking for pow in -lm... " >&6; } +if test ${ac_cv_lib_m_pow+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_check_lib_save_LIBS=$LIBS +LIBS="-lm $LIBS" +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char pow (); +int +main (void) +{ +return pow (); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + ac_cv_lib_m_pow=yes +else $as_nop + ac_cv_lib_m_pow=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +LIBS=$ac_check_lib_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_lib_m_pow" >&5 +printf "%s\n" "$ac_cv_lib_m_pow" >&6; } +if test "x$ac_cv_lib_m_pow" = xyes +then : + printf "%s\n" "#define HAVE_LIBM 1" >>confdefs.h + + LIBS="-lm $LIBS" + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for clock_gettime in -lrt" >&5 +printf %s "checking for clock_gettime in -lrt... " >&6; } +if test ${ac_cv_lib_rt_clock_gettime+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_check_lib_save_LIBS=$LIBS +LIBS="-lrt $LIBS" +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char clock_gettime (); +int +main (void) +{ +return clock_gettime (); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + ac_cv_lib_rt_clock_gettime=yes +else $as_nop + ac_cv_lib_rt_clock_gettime=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +LIBS=$ac_check_lib_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_lib_rt_clock_gettime" >&5 +printf "%s\n" "$ac_cv_lib_rt_clock_gettime" >&6; } +if test "x$ac_cv_lib_rt_clock_gettime" = xyes +then : + printf "%s\n" "#define HAVE_LIBRT 1" >>confdefs.h + + LIBS="-lrt $LIBS" + +fi + + +if test x$ac_cv_header_ncurses_h = xyes || test x$ac_cv_header_ncurses_ncurses_h = xyes || test x$ac_cv_header_ncursesw_ncurses_h = xyes; then + ncursesw_test=ncursesw + ncurses_test=ncurses +else + ncursesw_test= + ncurses_test= +fi + + +# Check whether --with-term-lib was given. +if test ${with_term_lib+y} +then : + withval=$with_term_lib; if test "x$withval" != xno && test "x$withval" != x ; then + termcap_curses_order="$withval" + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing tigetstr" >&5 +printf %s "checking for library containing tigetstr... " >&6; } +if test ${ac_cv_search_tigetstr+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char tigetstr (); +int +main (void) +{ +return tigetstr (); + ; + return 0; +} +_ACEOF +for ac_lib in '' $termcap_curses_order +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_tigetstr=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_tigetstr+y} +then : + break +fi +done +if test ${ac_cv_search_tigetstr+y} +then : + +else $as_nop + ac_cv_search_tigetstr=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_tigetstr" >&5 +printf "%s\n" "$ac_cv_search_tigetstr" >&6; } +ac_res=$ac_cv_search_tigetstr +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + +else + termcap_curses_order="$ncursesw_test $ncurses_test tinfow tinfo termcap curses" +fi +else $as_nop + case "$host_os" in + solaris*) + termcap_curses_order="$ncursesw_test $ncurses_test curses termcap" ;; + hpux10.*|hpux11.*) + DL_EXT="${DL_EXT=sl}" + termcap_curses_order="Hcurses $ncursesw_test $ncurses_test curses termcap" ;; + *) + termcap_curses_order="$ncursesw_test $ncurses_test tinfow tinfo termcap curses" ;; +esac +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if _XOPEN_SOURCE_EXTENDED should not be defined" >&5 +printf %s "checking if _XOPEN_SOURCE_EXTENDED should not be defined... " >&6; } +if test ${zsh_cv_no_xopen+y} +then : + printf %s "(cached) " >&6 +else $as_nop + case "$host_os" in + *freebsd5*|*freebsd6.[012]*|*aix*) + zsh_cv_no_xopen=yes + ;; + *) + zsh_cv_no_xopen=no + ;; +esac +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_no_xopen" >&5 +printf "%s\n" "$zsh_cv_no_xopen" >&6; } +if test x$zsh_cv_no_xopen = xyes; then + printf "%s\n" "#define ZSH_NO_XOPEN 1" >>confdefs.h + +fi + +LIBS_save_pre_term="$LIBS" +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing tigetstr" >&5 +printf %s "checking for library containing tigetstr... " >&6; } +if test ${ac_cv_search_tigetstr+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char tigetstr (); +int +main (void) +{ +return tigetstr (); + ; + return 0; +} +_ACEOF +for ac_lib in '' $termcap_curses_order +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_tigetstr=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_tigetstr+y} +then : + break +fi +done +if test ${ac_cv_search_tigetstr+y} +then : + +else $as_nop + ac_cv_search_tigetstr=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_tigetstr" >&5 +printf "%s\n" "$ac_cv_search_tigetstr" >&6; } +ac_res=$ac_cv_search_tigetstr +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing tigetflag" >&5 +printf %s "checking for library containing tigetflag... " >&6; } +if test ${ac_cv_search_tigetflag+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char tigetflag (); +int +main (void) +{ +return tigetflag (); + ; + return 0; +} +_ACEOF +for ac_lib in '' $termcap_curses_order +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_tigetflag=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_tigetflag+y} +then : + break +fi +done +if test ${ac_cv_search_tigetflag+y} +then : + +else $as_nop + ac_cv_search_tigetflag=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_tigetflag" >&5 +printf "%s\n" "$ac_cv_search_tigetflag" >&6; } +ac_res=$ac_cv_search_tigetflag +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing tgetent" >&5 +printf %s "checking for library containing tgetent... " >&6; } +if test ${ac_cv_search_tgetent+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char tgetent (); +int +main (void) +{ +return tgetent (); + ; + return 0; +} +_ACEOF +for ac_lib in '' $termcap_curses_order +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_tgetent=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_tgetent+y} +then : + break +fi +done +if test ${ac_cv_search_tgetent+y} +then : + +else $as_nop + ac_cv_search_tgetent=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_tgetent" >&5 +printf "%s\n" "$ac_cv_search_tgetent" >&6; } +ac_res=$ac_cv_search_tgetent +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + true +else $as_nop + { { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: in \`$ac_pwd':" >&5 +printf "%s\n" "$as_me: error: in \`$ac_pwd':" >&2;} +as_fn_error 255 "\"No terminal handling library was found on your system. +This is probably a library called 'curses' or 'ncurses'. You may +need to install a package called 'curses-devel' or 'ncurses-devel' on your +system.\" +See \`config.log' for more details" "$LINENO" 5; } +fi + + for ac_header in curses.h +do : + ac_fn_c_check_header_compile "$LINENO" "curses.h" "ac_cv_header_curses_h" "$ac_includes_default" +if test "x$ac_cv_header_curses_h" = xyes +then : + printf "%s\n" "#define HAVE_CURSES_H 1" >>confdefs.h + +else $as_nop + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for Solaris 8 curses.h mistake" >&5 +printf %s "checking for Solaris 8 curses.h mistake... " >&6; } +if test ${ac_cv_header_curses_solaris+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <curses.h> +int +main (void) +{ + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_header_curses_h=yes +ac_cv_header_curses_solaris=yes +else $as_nop + ac_cv_header_curses_h=no +ac_cv_header_curses_solaris=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_header_curses_solaris" >&5 +printf "%s\n" "$ac_cv_header_curses_solaris" >&6; } +if test x$ac_cv_header_curses_solaris = xyes; then +printf "%s\n" "#define HAVE_CURSES_H 1" >>confdefs.h + +fi +fi + +done + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if we need to ignore ncurses" >&5 +printf %s "checking if we need to ignore ncurses... " >&6; } +if test ${zsh_cv_ignore_ncurses+y} +then : + printf %s "(cached) " >&6 +else $as_nop + case $LIBS in + *-lncurses*) + zsh_cv_ignore_ncurses=no + ;; + *) + LIBS_save="$LIBS" + ac_cv_search_tigetstr_SAVE="$ac_cv_search_tigetstr" + ac_cv_search_tigetnum_SAVE="$ac_cv_search_tigetnum" + ac_cv_search_tigetflag_SAVE="$ac_cv_search_tigetflag" + ac_cv_search_tgetent_SAVE="$ac_cv_search_tgetent" + unset ac_cv_search_tigetstr ac_cv_search_tigetnum ac_cv_search_tigetflag ac_cv_search_tgetent + LIBS="$LIBS_save_pre_term" + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing tigetstr" >&5 +printf %s "checking for library containing tigetstr... " >&6; } +if test ${ac_cv_search_tigetstr+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char tigetstr (); +int +main (void) +{ +return tigetstr (); + ; + return 0; +} +_ACEOF +for ac_lib in '' ncursesw ncurses curses +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_tigetstr=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_tigetstr+y} +then : + break +fi +done +if test ${ac_cv_search_tigetstr+y} +then : + +else $as_nop + ac_cv_search_tigetstr=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_tigetstr" >&5 +printf "%s\n" "$ac_cv_search_tigetstr" >&6; } +ac_res=$ac_cv_search_tigetstr +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing tigetnum" >&5 +printf %s "checking for library containing tigetnum... " >&6; } +if test ${ac_cv_search_tigetnum+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char tigetnum (); +int +main (void) +{ +return tigetnum (); + ; + return 0; +} +_ACEOF +for ac_lib in '' ncursesw ncurses curses +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_tigetnum=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_tigetnum+y} +then : + break +fi +done +if test ${ac_cv_search_tigetnum+y} +then : + +else $as_nop + ac_cv_search_tigetnum=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_tigetnum" >&5 +printf "%s\n" "$ac_cv_search_tigetnum" >&6; } +ac_res=$ac_cv_search_tigetnum +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing tigetflag" >&5 +printf %s "checking for library containing tigetflag... " >&6; } +if test ${ac_cv_search_tigetflag+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char tigetflag (); +int +main (void) +{ +return tigetflag (); + ; + return 0; +} +_ACEOF +for ac_lib in '' ncursesw ncurses curses +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_tigetflag=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_tigetflag+y} +then : + break +fi +done +if test ${ac_cv_search_tigetflag+y} +then : + +else $as_nop + ac_cv_search_tigetflag=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_tigetflag" >&5 +printf "%s\n" "$ac_cv_search_tigetflag" >&6; } +ac_res=$ac_cv_search_tigetflag +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing tgetent" >&5 +printf %s "checking for library containing tgetent... " >&6; } +if test ${ac_cv_search_tgetent+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char tgetent (); +int +main (void) +{ +return tgetent (); + ; + return 0; +} +_ACEOF +for ac_lib in '' ncursesw ncurses curses +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_tgetent=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_tgetent+y} +then : + break +fi +done +if test ${ac_cv_search_tgetent+y} +then : + +else $as_nop + ac_cv_search_tgetent=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_tgetent" >&5 +printf "%s\n" "$ac_cv_search_tgetent" >&6; } +ac_res=$ac_cv_search_tgetent +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + + LIBS_result="$LIBS" + + LIBS="$LIBS_save" + ac_cv_search_tigetstr="$ac_cv_search_tigetstr_SAVE" + ac_cv_search_tigetnum="$ac_cv_search_tigetnum_SAVE" + ac_cv_search_tigetflag="$ac_cv_search_tigetflag_SAVE" + ac_cv_search_tgetent="$ac_cv_search_tgetent_SAVE" + + case $LIBS_result in + *-lncurses*|*-lcurses*) + zsh_cv_ignore_ncurses=yes + ;; + *) + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing initscr" >&5 +printf %s "checking for library containing initscr... " >&6; } +if test ${ac_cv_search_initscr+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char initscr (); +int +main (void) +{ +return initscr (); + ; + return 0; +} +_ACEOF +for ac_lib in '' ncursesw ncurses curses +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_initscr=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_initscr+y} +then : + break +fi +done +if test ${ac_cv_search_initscr+y} +then : + +else $as_nop + ac_cv_search_initscr=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_initscr" >&5 +printf "%s\n" "$ac_cv_search_initscr" >&6; } +ac_res=$ac_cv_search_initscr +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + + case $LIBS in + *-lncurses*|*-lcurses*) + zsh_cv_ignore_ncurses=no + ;; + *) + zsh_cv_ignore_ncurses=yes + ;; + esac + esac + ;; +esac +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_ignore_ncurses" >&5 +printf "%s\n" "$zsh_cv_ignore_ncurses" >&6; } + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing getpwnam" >&5 +printf %s "checking for library containing getpwnam... " >&6; } +if test ${ac_cv_search_getpwnam+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char getpwnam (); +int +main (void) +{ +return getpwnam (); + ; + return 0; +} +_ACEOF +for ac_lib in '' nsl +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_getpwnam=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_getpwnam+y} +then : + break +fi +done +if test ${ac_cv_search_getpwnam+y} +then : + +else $as_nop + ac_cv_search_getpwnam=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_getpwnam" >&5 +printf "%s\n" "$ac_cv_search_getpwnam" >&6; } +ac_res=$ac_cv_search_getpwnam +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + + +if test `echo $host_os | sed 's/^\(unicos\).*/\1/'` = unicos; then + LIBS="-lcraylm -lkrb -lnisdb -lnsl -lrpcsvc $LIBS" +fi + +if test "x$dynamic" = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for dlopen in -ldl" >&5 +printf %s "checking for dlopen in -ldl... " >&6; } +if test ${ac_cv_lib_dl_dlopen+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_check_lib_save_LIBS=$LIBS +LIBS="-ldl $LIBS" +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char dlopen (); +int +main (void) +{ +return dlopen (); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + ac_cv_lib_dl_dlopen=yes +else $as_nop + ac_cv_lib_dl_dlopen=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +LIBS=$ac_check_lib_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_lib_dl_dlopen" >&5 +printf "%s\n" "$ac_cv_lib_dl_dlopen" >&6; } +if test "x$ac_cv_lib_dl_dlopen" = xyes +then : + printf "%s\n" "#define HAVE_LIBDL 1" >>confdefs.h + + LIBS="-ldl $LIBS" + +fi + +fi + +if test x$enable_cap = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for cap_get_proc in -lcap" >&5 +printf %s "checking for cap_get_proc in -lcap... " >&6; } +if test ${ac_cv_lib_cap_cap_get_proc+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_check_lib_save_LIBS=$LIBS +LIBS="-lcap $LIBS" +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char cap_get_proc (); +int +main (void) +{ +return cap_get_proc (); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + ac_cv_lib_cap_cap_get_proc=yes +else $as_nop + ac_cv_lib_cap_cap_get_proc=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +LIBS=$ac_check_lib_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_lib_cap_cap_get_proc" >&5 +printf "%s\n" "$ac_cv_lib_cap_cap_get_proc" >&6; } +if test "x$ac_cv_lib_cap_cap_get_proc" = xyes +then : + printf "%s\n" "#define HAVE_LIBCAP 1" >>confdefs.h + + LIBS="-lcap $LIBS" + +fi + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for socket in -lsocket" >&5 +printf %s "checking for socket in -lsocket... " >&6; } +if test ${ac_cv_lib_socket_socket+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_check_lib_save_LIBS=$LIBS +LIBS="-lsocket $LIBS" +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char socket (); +int +main (void) +{ +return socket (); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + ac_cv_lib_socket_socket=yes +else $as_nop + ac_cv_lib_socket_socket=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +LIBS=$ac_check_lib_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_lib_socket_socket" >&5 +printf "%s\n" "$ac_cv_lib_socket_socket" >&6; } +if test "x$ac_cv_lib_socket_socket" = xyes +then : + printf "%s\n" "#define HAVE_LIBSOCKET 1" >>confdefs.h + + LIBS="-lsocket $LIBS" + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing gethostbyname2" >&5 +printf %s "checking for library containing gethostbyname2... " >&6; } +if test ${ac_cv_search_gethostbyname2+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char gethostbyname2 (); +int +main (void) +{ +return gethostbyname2 (); + ; + return 0; +} +_ACEOF +for ac_lib in '' bind +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_gethostbyname2=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_gethostbyname2+y} +then : + break +fi +done +if test ${ac_cv_search_gethostbyname2+y} +then : + +else $as_nop + ac_cv_search_gethostbyname2=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_gethostbyname2" >&5 +printf "%s\n" "$ac_cv_search_gethostbyname2" >&6; } +ac_res=$ac_cv_search_gethostbyname2 +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + +fi + + +case $LIBS in + *-lbind*) + ac_fn_c_check_header_compile "$LINENO" "bind/netdb.h" "ac_cv_header_bind_netdb_h" "$ac_includes_default" +if test "x$ac_cv_header_bind_netdb_h" = xyes +then : + printf "%s\n" "#define HAVE_BIND_NETDB_H 1" >>confdefs.h + +fi + + ;; +esac + + +if test "x$ac_cv_header_iconv_h" = "xyes"; then + ac_fn_c_check_func "$LINENO" "iconv" "ac_cv_func_iconv" +if test "x$ac_cv_func_iconv" = xyes +then : + ac_found_iconv=yes +else $as_nop + ac_found_iconv=no +fi + + if test "x$ac_found_iconv" = "xno"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for iconv in -liconv" >&5 +printf %s "checking for iconv in -liconv... " >&6; } +if test ${ac_cv_lib_iconv_iconv+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_check_lib_save_LIBS=$LIBS +LIBS="-liconv $LIBS" +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char iconv (); +int +main (void) +{ +return iconv (); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + ac_cv_lib_iconv_iconv=yes +else $as_nop + ac_cv_lib_iconv_iconv=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +LIBS=$ac_check_lib_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_lib_iconv_iconv" >&5 +printf "%s\n" "$ac_cv_lib_iconv_iconv" >&6; } +if test "x$ac_cv_lib_iconv_iconv" = xyes +then : + ac_found_iconv=yes +fi + + if test "x$ac_found_iconv" = "xno"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for libiconv in -liconv" >&5 +printf %s "checking for libiconv in -liconv... " >&6; } +if test ${ac_cv_lib_iconv_libiconv+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_check_lib_save_LIBS=$LIBS +LIBS="-liconv $LIBS" +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char libiconv (); +int +main (void) +{ +return libiconv (); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + ac_cv_lib_iconv_libiconv=yes +else $as_nop + ac_cv_lib_iconv_libiconv=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +LIBS=$ac_check_lib_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_lib_iconv_libiconv" >&5 +printf "%s\n" "$ac_cv_lib_iconv_libiconv" >&6; } +if test "x$ac_cv_lib_iconv_libiconv" = xyes +then : + ac_found_iconv=yes +fi + + fi + if test "x$ac_found_iconv" != "xno"; then + LIBS="-liconv $LIBS" + fi + else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for $CC options needed to detect all undeclared functions" >&5 +printf %s "checking for $CC options needed to detect all undeclared functions... " >&6; } +if test ${ac_cv_c_undeclared_builtin_options+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_save_CFLAGS=$CFLAGS + ac_cv_c_undeclared_builtin_options='cannot detect' + for ac_arg in '' -fno-builtin; do + CFLAGS="$ac_save_CFLAGS $ac_arg" + # This test program should *not* compile successfully. + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +int +main (void) +{ +(void) strchr; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + +else $as_nop + # This test program should compile successfully. + # No library function is consistently available on + # freestanding implementations, so test against a dummy + # declaration. Include always-available headers on the + # off chance that they somehow elicit warnings. + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <float.h> +#include <limits.h> +#include <stdarg.h> +#include <stddef.h> +extern void ac_decl (int, char *); + +int +main (void) +{ +(void) ac_decl (0, (char *) 0); + (void) ac_decl; + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + if test x"$ac_arg" = x +then : + ac_cv_c_undeclared_builtin_options='none needed' +else $as_nop + ac_cv_c_undeclared_builtin_options=$ac_arg +fi + break +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + done + CFLAGS=$ac_save_CFLAGS + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_c_undeclared_builtin_options" >&5 +printf "%s\n" "$ac_cv_c_undeclared_builtin_options" >&6; } + case $ac_cv_c_undeclared_builtin_options in #( + 'cannot detect') : + { { printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: in \`$ac_pwd':" >&5 +printf "%s\n" "$as_me: error: in \`$ac_pwd':" >&2;} +as_fn_error $? "cannot make $CC report undeclared builtins +See \`config.log' for more details" "$LINENO" 5; } ;; #( + 'none needed') : + ac_c_undeclared_builtin_options='' ;; #( + *) : + ac_c_undeclared_builtin_options=$ac_cv_c_undeclared_builtin_options ;; +esac + +ac_fn_check_decl "$LINENO" "_libiconv_version" "ac_cv_have_decl__libiconv_version" " #include <iconv.h> +" "$ac_c_undeclared_builtin_options" "CFLAGS" +if test "x$ac_cv_have_decl__libiconv_version" = xyes +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for libiconv in -liconv" >&5 +printf %s "checking for libiconv in -liconv... " >&6; } +if test ${ac_cv_lib_iconv_libiconv+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_check_lib_save_LIBS=$LIBS +LIBS="-liconv $LIBS" +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char libiconv (); +int +main (void) +{ +return libiconv (); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + ac_cv_lib_iconv_libiconv=yes +else $as_nop + ac_cv_lib_iconv_libiconv=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +LIBS=$ac_check_lib_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_lib_iconv_libiconv" >&5 +printf "%s\n" "$ac_cv_lib_iconv_libiconv" >&6; } +if test "x$ac_cv_lib_iconv_libiconv" = xyes +then : + LIBS="-liconv $LIBS" +fi + +fi + fi +fi + +if test "x$ac_found_iconv" = xyes; then + +printf "%s\n" "#define HAVE_ICONV 1" >>confdefs.h + + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <iconv.h> +int +main (void) +{ +int myversion = _libiconv_version + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + printf "%s\n" "#define ICONV_FROM_LIBICONV 1" >>confdefs.h + +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +fi + +if test "x$ac_found_iconv" = "xyes"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for iconv declaration" >&5 +printf %s "checking for iconv declaration... " >&6; } +if test ${ac_cv_iconv_const+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <stdlib.h> + #include <iconv.h> +int +main (void) +{ +#ifdef __cplusplus + "C" + #endif + #if defined(__STDC__) || defined(__cplusplus) + size_t iconv (iconv_t cd, char * *inbuf, size_t *inbytesleft, char * *outbuf, size_t *outbytesleft); + #else + size_t iconv(); + #endif + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_iconv_const= +else $as_nop + ac_cv_iconv_const=const +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_iconv_const" >&5 +printf "%s\n" "$ac_cv_iconv_const" >&6; } + +printf "%s\n" "#define ICONV_CONST $ac_cv_iconv_const" >>confdefs.h + +fi + +if test x$enable_pcre = xyes; then + LIBS="`$ac_cv_prog_PCRECONF --libs` $LIBS" +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if an include file defines ospeed" >&5 +printf %s "checking if an include file defines ospeed... " >&6; } +if test ${zsh_cv_decl_ospeed_include_defines+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/types.h> +#if HAVE_TERMIOS_H +#include <termios.h> +#endif +#if HAVE_TERMCAP_H +#include <termcap.h> +#endif +int +main (void) +{ +ospeed = 0; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + zsh_cv_decl_ospeed_include_defines=yes +else $as_nop + zsh_cv_decl_ospeed_include_defines=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_decl_ospeed_include_defines" >&5 +printf "%s\n" "$zsh_cv_decl_ospeed_include_defines" >&6; } + +if test x$zsh_cv_decl_ospeed_include_defines = xno; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if you must define ospeed" >&5 +printf %s "checking if you must define ospeed... " >&6; } +if test ${zsh_cv_decl_ospeed_must_define+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +int +main (void) +{ +extern short ospeed; ospeed = 0; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + zsh_cv_decl_ospeed_must_define=yes +else $as_nop + zsh_cv_decl_ospeed_must_define=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_decl_ospeed_must_define" >&5 +printf "%s\n" "$zsh_cv_decl_ospeed_must_define" >&6; } +fi + + + +if test x$zsh_cv_decl_ospeed_include_defines = xyes; then + printf "%s\n" "#define HAVE_OSPEED 1" >>confdefs.h + +elif test x$zsh_cv_decl_ospeed_must_define = xyes; then + printf "%s\n" "#define HAVE_OSPEED 1" >>confdefs.h + + printf "%s\n" "#define MUST_DEFINE_OSPEED 1" >>confdefs.h + +fi + +if test x$gdbm != xno; then + ac_fn_c_check_header_compile "$LINENO" "gdbm.h" "ac_cv_header_gdbm_h" "$ac_includes_default" +if test "x$ac_cv_header_gdbm_h" = xyes +then : + printf "%s\n" "#define HAVE_GDBM_H 1" >>confdefs.h + +fi + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for gdbm_open in -lgdbm" >&5 +printf %s "checking for gdbm_open in -lgdbm... " >&6; } +if test ${ac_cv_lib_gdbm_gdbm_open+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_check_lib_save_LIBS=$LIBS +LIBS="-lgdbm $LIBS" +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char gdbm_open (); +int +main (void) +{ +return gdbm_open (); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + ac_cv_lib_gdbm_gdbm_open=yes +else $as_nop + ac_cv_lib_gdbm_gdbm_open=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +LIBS=$ac_check_lib_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_lib_gdbm_gdbm_open" >&5 +printf "%s\n" "$ac_cv_lib_gdbm_gdbm_open" >&6; } +if test "x$ac_cv_lib_gdbm_gdbm_open" = xyes +then : + printf "%s\n" "#define HAVE_LIBGDBM 1" >>confdefs.h + + LIBS="-lgdbm $LIBS" + +fi + +fi + +ac_fn_c_check_header_compile "$LINENO" "sys/xattr.h" "ac_cv_header_sys_xattr_h" "$ac_includes_default" +if test "x$ac_cv_header_sys_xattr_h" = xyes +then : + printf "%s\n" "#define HAVE_SYS_XATTR_H 1" >>confdefs.h + +fi + + + + + ac_fn_c_check_type "$LINENO" "pid_t" "ac_cv_type_pid_t" "$ac_includes_default +" +if test "x$ac_cv_type_pid_t" = xyes +then : + +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + + #if defined _WIN64 && !defined __CYGWIN__ + LLP64 + #endif + +int +main (void) +{ + + ; + return 0; +} + +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_pid_type='int' +else $as_nop + ac_pid_type='__int64' +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +printf "%s\n" "#define pid_t $ac_pid_type" >>confdefs.h + + +fi + + +ac_fn_c_check_type "$LINENO" "off_t" "ac_cv_type_off_t" "$ac_includes_default" +if test "x$ac_cv_type_off_t" = xyes +then : + +else $as_nop + +printf "%s\n" "#define off_t long int" >>confdefs.h + +fi + +ac_fn_c_check_type "$LINENO" "ino_t" "ac_cv_type_ino_t" "$ac_includes_default" +if test "x$ac_cv_type_ino_t" = xyes +then : + +else $as_nop + +printf "%s\n" "#define ino_t unsigned long" >>confdefs.h + +fi + +ac_fn_c_check_type "$LINENO" "mode_t" "ac_cv_type_mode_t" "$ac_includes_default" +if test "x$ac_cv_type_mode_t" = xyes +then : + +else $as_nop + +printf "%s\n" "#define mode_t int" >>confdefs.h + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for uid_t in sys/types.h" >&5 +printf %s "checking for uid_t in sys/types.h... " >&6; } +if test ${ac_cv_type_uid_t+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/types.h> + +_ACEOF +if (eval "$ac_cpp conftest.$ac_ext") 2>&5 | + $EGREP "uid_t" >/dev/null 2>&1 +then : + ac_cv_type_uid_t=yes +else $as_nop + ac_cv_type_uid_t=no +fi +rm -rf conftest* + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_type_uid_t" >&5 +printf "%s\n" "$ac_cv_type_uid_t" >&6; } +if test $ac_cv_type_uid_t = no; then + +printf "%s\n" "#define uid_t int" >>confdefs.h + + +printf "%s\n" "#define gid_t int" >>confdefs.h + +fi + +ac_fn_c_check_type "$LINENO" "size_t" "ac_cv_type_size_t" "$ac_includes_default" +if test "x$ac_cv_type_size_t" = xyes +then : + +else $as_nop + +printf "%s\n" "#define size_t unsigned int" >>confdefs.h + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if long is 64 bits" >&5 +printf %s "checking if long is 64 bits... " >&6; } +if test ${zsh_cv_long_is_64_bit+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_long_is_64_bit=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +int main() { return sizeof(long) < 8; } +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_long_is_64_bit=yes +else $as_nop + zsh_cv_long_is_64_bit=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_long_is_64_bit" >&5 +printf "%s\n" "$zsh_cv_long_is_64_bit" >&6; } + + + + + + + +if test x$zsh_cv_long_is_64_bit = xyes; then + printf "%s\n" "#define LONG_IS_64_BIT 1" >>confdefs.h + +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if off_t is 64 bit" >&5 +printf %s "checking if off_t is 64 bit... " >&6; } +if test ${zsh_cv_off_t_is_64_bit+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_off_t_is_64_bit=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> + +main() { return sizeof(off_t) < 8; } + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_off_t_is_64_bit=yes +else $as_nop + zsh_cv_off_t_is_64_bit=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_off_t_is_64_bit" >&5 +printf "%s\n" "$zsh_cv_off_t_is_64_bit" >&6; } + if test x$zsh_cv_off_t_is_64_bit = xyes; then + printf "%s\n" "#define OFF_T_IS_64_BIT 1" >>confdefs.h + + fi + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if ino_t is 64 bit" >&5 +printf %s "checking if ino_t is 64 bit... " >&6; } +if test ${zsh_cv_ino_t_is_64_bit+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_ino_t_is_64_bit=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> + +main() { return sizeof(ino_t) < 8; } + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_ino_t_is_64_bit=yes +else $as_nop + zsh_cv_ino_t_is_64_bit=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_ino_t_is_64_bit" >&5 +printf "%s\n" "$zsh_cv_ino_t_is_64_bit" >&6; } + if test x$zsh_cv_ino_t_is_64_bit = xyes; then + printf "%s\n" "#define INO_T_IS_64_BIT 1" >>confdefs.h + + fi + + if test x$enable_largefile != xno -o x$zsh_cv_off_t_is_64_bit = xyes \ + -o $zsh_cv_ino_t_is_64_bit = yes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if compiler has a 64 bit type" >&5 +printf %s "checking if compiler has a 64 bit type... " >&6; } +if test ${zsh_cv_64_bit_type+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + if test x != x ; then + zsh_cv_64_bit_type="long long" + else + zsh_cv_64_bit_type=no + fi +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +#include <sys/types.h> +#endif + +main() +{ + long long foo = 0; + int bar = (int) foo; + return sizeof(long long) != 8; +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_64_bit_type="long long" +else $as_nop + zsh_cv_64_bit_type=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + + + if test "$zsh_cv_64_bit_type" = no; then + if test "$cross_compiling" = yes +then : + if test x != x ; then + zsh_cv_64_bit_type="quad_t" + else + zsh_cv_64_bit_type=no + fi +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +#include <sys/types.h> +#endif + +main() +{ + quad_t foo = 0; + int bar = (int) foo; + return sizeof(quad_t) != 8; +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_64_bit_type="quad_t" +else $as_nop + zsh_cv_64_bit_type=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + + + fi + if test "$zsh_cv_64_bit_type" = no; then + if test "$cross_compiling" = yes +then : + if test x != x ; then + zsh_cv_64_bit_type="__int64_t" + else + zsh_cv_64_bit_type=no + fi +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +#include <sys/types.h> +#endif + +main() +{ + __int64_t foo = 0; + int bar = (int) foo; + return sizeof(__int64_t) != 8; +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_64_bit_type="__int64_t" +else $as_nop + zsh_cv_64_bit_type=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + + + fi + if test "$zsh_cv_64_bit_type" = no && + test "$zsh_cv_off_t_is_64_bit" = yes; then + if test "$cross_compiling" = yes +then : + if test x != x ; then + zsh_cv_64_bit_type="off_t" + else + zsh_cv_64_bit_type=no + fi +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +#include <sys/types.h> +#endif + +main() +{ + off_t foo = 0; + int bar = (int) foo; + return sizeof(off_t) != 8; +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_64_bit_type="off_t" +else $as_nop + zsh_cv_64_bit_type=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + + + fi +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_64_bit_type" >&5 +printf "%s\n" "$zsh_cv_64_bit_type" >&6; } + if test "$zsh_cv_64_bit_type" != no; then + printf "%s\n" "#define ZSH_64_BIT_TYPE $zsh_cv_64_bit_type" >>confdefs.h + + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for a corresponding unsigned 64 bit type" >&5 +printf %s "checking for a corresponding unsigned 64 bit type... " >&6; } +if test ${zsh_cv_64_bit_utype+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + if test xforce != x ; then + zsh_cv_64_bit_utype="unsigned $zsh_cv_64_bit_type" + else + zsh_cv_64_bit_utype=no + fi +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +#include <sys/types.h> +#endif + +main() +{ + unsigned $zsh_cv_64_bit_type foo = 0; + int bar = (int) foo; + return sizeof(unsigned $zsh_cv_64_bit_type) != 8; +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_64_bit_utype="unsigned $zsh_cv_64_bit_type" +else $as_nop + zsh_cv_64_bit_utype=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + + + if test "$zsh_cv_64_bit_utype" = no; then + if test "$cross_compiling" = yes +then : + if test x != x ; then + zsh_cv_64_bit_utype="__uint64_t" + else + zsh_cv_64_bit_utype=no + fi +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +#include <sys/types.h> +#endif + +main() +{ + __uint64_t foo = 0; + int bar = (int) foo; + return sizeof(__uint64_t) != 8; +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_64_bit_utype="__uint64_t" +else $as_nop + zsh_cv_64_bit_utype=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + + + fi +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_64_bit_utype" >&5 +printf "%s\n" "$zsh_cv_64_bit_utype" >&6; } + if test "$zsh_cv_64_bit_utype" != no; then + printf "%s\n" "#define ZSH_64_BIT_UTYPE $zsh_cv_64_bit_utype" >>confdefs.h + + fi + fi + fi +fi + + +if test "$zsh_cv_64_bit_type" = "long long"; then + printf "%s\n" "#define ZLONG_IS_LONG_LONG 1" >>confdefs.h + +else + if test "$zsh_cv_64_bit_type" = "long"; then + printf "%s\n" "#define ZLONG_IS_LONG_64 1" >>confdefs.h + + fi +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for %lld printf support" >&5 +printf %s "checking for %lld printf support... " >&6; } +if test ${zsh_cv_printf_has_lld+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_printf_has_lld=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <stdio.h> +#include <string.h> +int main(int argc, char **argv) +{ + long long foo = ((long long)0xdead << 40) | 0xf00d; + char buf[80]; + sprintf(buf, "before%lldafter", foo); + if (!strcmp(buf, "before62677660341432333after")) { + return 0; + } + return 1; +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_printf_has_lld=yes +else $as_nop + zsh_cv_printf_has_lld=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_printf_has_lld" >&5 +printf "%s\n" "$zsh_cv_printf_has_lld" >&6; } + +if test x$zsh_cv_printf_has_lld = xyes; then + printf "%s\n" "#define PRINTF_HAS_LLD 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for sigset_t" >&5 +printf %s "checking for sigset_t... " >&6; } +if test ${zsh_cv_type_sigset_t+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/types.h> +#include <signal.h> +int +main (void) +{ +sigset_t tempsigset; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_type_sigset_t=yes +else $as_nop + zsh_cv_type_sigset_t=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_type_sigset_t" >&5 +printf "%s\n" "$zsh_cv_type_sigset_t" >&6; } + +if test x$zsh_cv_type_sigset_t = xno; then + printf "%s\n" "#define sigset_t unsigned int" >>confdefs.h + +fi + +ac_fn_c_check_member "$LINENO" "struct stat" "st_atim.tv_nsec" "ac_cv_member_struct_stat_st_atim_tv_nsec" "$ac_includes_default" +if test "x$ac_cv_member_struct_stat_st_atim_tv_nsec" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_STAT_ST_ATIM_TV_NSEC 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct stat" "st_atimespec.tv_nsec" "ac_cv_member_struct_stat_st_atimespec_tv_nsec" "$ac_includes_default" +if test "x$ac_cv_member_struct_stat_st_atimespec_tv_nsec" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_STAT_ST_ATIMESPEC_TV_NSEC 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct stat" "st_atimensec" "ac_cv_member_struct_stat_st_atimensec" "$ac_includes_default" +if test "x$ac_cv_member_struct_stat_st_atimensec" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_STAT_ST_ATIMENSEC 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct stat" "st_mtim.tv_nsec" "ac_cv_member_struct_stat_st_mtim_tv_nsec" "$ac_includes_default" +if test "x$ac_cv_member_struct_stat_st_mtim_tv_nsec" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_STAT_ST_MTIM_TV_NSEC 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct stat" "st_mtimespec.tv_nsec" "ac_cv_member_struct_stat_st_mtimespec_tv_nsec" "$ac_includes_default" +if test "x$ac_cv_member_struct_stat_st_mtimespec_tv_nsec" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_STAT_ST_MTIMESPEC_TV_NSEC 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct stat" "st_mtimensec" "ac_cv_member_struct_stat_st_mtimensec" "$ac_includes_default" +if test "x$ac_cv_member_struct_stat_st_mtimensec" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_STAT_ST_MTIMENSEC 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct stat" "st_ctim.tv_nsec" "ac_cv_member_struct_stat_st_ctim_tv_nsec" "$ac_includes_default" +if test "x$ac_cv_member_struct_stat_st_ctim_tv_nsec" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_STAT_ST_CTIM_TV_NSEC 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct stat" "st_ctimespec.tv_nsec" "ac_cv_member_struct_stat_st_ctimespec_tv_nsec" "$ac_includes_default" +if test "x$ac_cv_member_struct_stat_st_ctimespec_tv_nsec" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_STAT_ST_CTIMESPEC_TV_NSEC 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct stat" "st_ctimensec" "ac_cv_member_struct_stat_st_ctimensec" "$ac_includes_default" +if test "x$ac_cv_member_struct_stat_st_ctimensec" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_STAT_ST_CTIMENSEC 1" >>confdefs.h + + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for struct timezone" >&5 +printf %s "checking for struct timezone... " >&6; } +if test ${zsh_cv_type_exists_struct_timezone+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#define _GNU_SOURCE 1 +#ifdef HAVE_SYS_TIME_H +# include <sys/time.h> +#endif + +int +main (void) +{ +struct timezone testvar; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_type_exists_struct_timezone=yes +else $as_nop + zsh_cv_type_exists_struct_timezone=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_type_exists_struct_timezone" >&5 +printf "%s\n" "$zsh_cv_type_exists_struct_timezone" >&6; } + +if test $zsh_cv_type_exists_struct_timezone = yes; then + printf "%s\n" "#define HAVE_STRUCT_TIMEZONE 1" >>confdefs.h + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for struct timespec" >&5 +printf %s "checking for struct timespec... " >&6; } +if test ${zsh_cv_type_exists_struct_timespec+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#define _GNU_SOURCE 1 +#ifdef HAVE_SYS_TIME_H +# include <sys/time.h> +#endif + +int +main (void) +{ +struct timespec testvar; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_type_exists_struct_timespec=yes +else $as_nop + zsh_cv_type_exists_struct_timespec=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_type_exists_struct_timespec" >&5 +printf "%s\n" "$zsh_cv_type_exists_struct_timespec" >&6; } + +if test $zsh_cv_type_exists_struct_timespec = yes; then + printf "%s\n" "#define HAVE_STRUCT_TIMESPEC 1" >>confdefs.h + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for struct utmp" >&5 +printf %s "checking for struct utmp... " >&6; } +if test ${zsh_cv_type_exists_struct_utmp+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#ifdef HAVE_UTMP_H +# include <utmp.h> +#endif + +int +main (void) +{ +struct utmp testvar; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_type_exists_struct_utmp=yes +else $as_nop + zsh_cv_type_exists_struct_utmp=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_type_exists_struct_utmp" >&5 +printf "%s\n" "$zsh_cv_type_exists_struct_utmp" >&6; } + +if test $zsh_cv_type_exists_struct_utmp = yes; then + printf "%s\n" "#define HAVE_STRUCT_UTMP 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for struct utmpx" >&5 +printf %s "checking for struct utmpx... " >&6; } +if test ${zsh_cv_type_exists_struct_utmpx+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#ifdef HAVE_UTMPX_H +# include <utmpx.h> +#endif + +int +main (void) +{ +struct utmpx testvar; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_type_exists_struct_utmpx=yes +else $as_nop + zsh_cv_type_exists_struct_utmpx=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_type_exists_struct_utmpx" >&5 +printf "%s\n" "$zsh_cv_type_exists_struct_utmpx" >&6; } + +if test $zsh_cv_type_exists_struct_utmpx = yes; then + printf "%s\n" "#define HAVE_STRUCT_UTMPX 1" >>confdefs.h + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for ut_host in struct utmp" >&5 +printf %s "checking for ut_host in struct utmp... " >&6; } +if test ${zsh_cv_struct_member_struct_utmp_ut_host+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#ifdef HAVE_UTMP_H +# include <utmp.h> +#endif + +int +main (void) +{ +struct utmp testvar; testvar.ut_host; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_struct_member_struct_utmp_ut_host=yes +else $as_nop + zsh_cv_struct_member_struct_utmp_ut_host=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_struct_member_struct_utmp_ut_host" >&5 +printf "%s\n" "$zsh_cv_struct_member_struct_utmp_ut_host" >&6; } + +if test $zsh_cv_struct_member_struct_utmp_ut_host = yes; then + printf "%s\n" "#define HAVE_STRUCT_UTMP_UT_HOST 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for ut_host in struct utmpx" >&5 +printf %s "checking for ut_host in struct utmpx... " >&6; } +if test ${zsh_cv_struct_member_struct_utmpx_ut_host+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#ifdef HAVE_UTMPX_H +# include <utmpx.h> +#endif + +int +main (void) +{ +struct utmpx testvar; testvar.ut_host; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_struct_member_struct_utmpx_ut_host=yes +else $as_nop + zsh_cv_struct_member_struct_utmpx_ut_host=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_struct_member_struct_utmpx_ut_host" >&5 +printf "%s\n" "$zsh_cv_struct_member_struct_utmpx_ut_host" >&6; } + +if test $zsh_cv_struct_member_struct_utmpx_ut_host = yes; then + printf "%s\n" "#define HAVE_STRUCT_UTMPX_UT_HOST 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for ut_xtime in struct utmpx" >&5 +printf %s "checking for ut_xtime in struct utmpx... " >&6; } +if test ${zsh_cv_struct_member_struct_utmpx_ut_xtime+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#ifdef HAVE_UTMPX_H +# include <utmpx.h> +#endif + +int +main (void) +{ +struct utmpx testvar; testvar.ut_xtime; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_struct_member_struct_utmpx_ut_xtime=yes +else $as_nop + zsh_cv_struct_member_struct_utmpx_ut_xtime=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_struct_member_struct_utmpx_ut_xtime" >&5 +printf "%s\n" "$zsh_cv_struct_member_struct_utmpx_ut_xtime" >&6; } + +if test $zsh_cv_struct_member_struct_utmpx_ut_xtime = yes; then + printf "%s\n" "#define HAVE_STRUCT_UTMPX_UT_XTIME 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for ut_tv in struct utmpx" >&5 +printf %s "checking for ut_tv in struct utmpx... " >&6; } +if test ${zsh_cv_struct_member_struct_utmpx_ut_tv+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#ifdef HAVE_UTMPX_H +# include <utmpx.h> +#endif + +int +main (void) +{ +struct utmpx testvar; testvar.ut_tv; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_struct_member_struct_utmpx_ut_tv=yes +else $as_nop + zsh_cv_struct_member_struct_utmpx_ut_tv=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_struct_member_struct_utmpx_ut_tv" >&5 +printf "%s\n" "$zsh_cv_struct_member_struct_utmpx_ut_tv" >&6; } + +if test $zsh_cv_struct_member_struct_utmpx_ut_tv = yes; then + printf "%s\n" "#define HAVE_STRUCT_UTMPX_UT_TV 1" >>confdefs.h + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for d_ino in struct dirent" >&5 +printf %s "checking for d_ino in struct dirent... " >&6; } +if test ${zsh_cv_struct_member_struct_dirent_d_ino+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#ifdef HAVE_DIRENT_H +# include <dirent.h> +#endif + +int +main (void) +{ +struct dirent testvar; testvar.d_ino; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_struct_member_struct_dirent_d_ino=yes +else $as_nop + zsh_cv_struct_member_struct_dirent_d_ino=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_struct_member_struct_dirent_d_ino" >&5 +printf "%s\n" "$zsh_cv_struct_member_struct_dirent_d_ino" >&6; } + +if test $zsh_cv_struct_member_struct_dirent_d_ino = yes; then + printf "%s\n" "#define HAVE_STRUCT_DIRENT_D_INO 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for d_stat in struct dirent" >&5 +printf %s "checking for d_stat in struct dirent... " >&6; } +if test ${zsh_cv_struct_member_struct_dirent_d_stat+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#ifdef HAVE_DIRENT_H +# include <dirent.h> +#endif + +int +main (void) +{ +struct dirent testvar; testvar.d_stat; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_struct_member_struct_dirent_d_stat=yes +else $as_nop + zsh_cv_struct_member_struct_dirent_d_stat=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_struct_member_struct_dirent_d_stat" >&5 +printf "%s\n" "$zsh_cv_struct_member_struct_dirent_d_stat" >&6; } + +if test $zsh_cv_struct_member_struct_dirent_d_stat = yes; then + printf "%s\n" "#define HAVE_STRUCT_DIRENT_D_STAT 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for d_ino in struct direct" >&5 +printf %s "checking for d_ino in struct direct... " >&6; } +if test ${zsh_cv_struct_member_struct_direct_d_ino+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#ifdef HAVE_SYS_NDIR_H +# include <sys/ndir.h> +#endif +#ifdef HAVE_SYS_DIR_H +# include <sys/dir.h> +#endif +#ifdef HAVE_NDIR_H +# include <ndir.h> +#endif + +int +main (void) +{ +struct direct testvar; testvar.d_ino; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_struct_member_struct_direct_d_ino=yes +else $as_nop + zsh_cv_struct_member_struct_direct_d_ino=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_struct_member_struct_direct_d_ino" >&5 +printf "%s\n" "$zsh_cv_struct_member_struct_direct_d_ino" >&6; } + +if test $zsh_cv_struct_member_struct_direct_d_ino = yes; then + printf "%s\n" "#define HAVE_STRUCT_DIRECT_D_INO 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for d_stat in struct direct" >&5 +printf %s "checking for d_stat in struct direct... " >&6; } +if test ${zsh_cv_struct_member_struct_direct_d_stat+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#ifdef HAVE_SYS_NDIR_H +# include <sys/ndir.h> +#endif +#ifdef HAVE_SYS_DIR_H +# include <sys/dir.h> +#endif +#ifdef HAVE_NDIR_H +# include <ndir.h> +#endif + +int +main (void) +{ +struct direct testvar; testvar.d_stat; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_struct_member_struct_direct_d_stat=yes +else $as_nop + zsh_cv_struct_member_struct_direct_d_stat=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_struct_member_struct_direct_d_stat" >&5 +printf "%s\n" "$zsh_cv_struct_member_struct_direct_d_stat" >&6; } + +if test $zsh_cv_struct_member_struct_direct_d_stat = yes; then + printf "%s\n" "#define HAVE_STRUCT_DIRECT_D_STAT 1" >>confdefs.h + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for sin6_scope_id in struct sockaddr_in6" >&5 +printf %s "checking for sin6_scope_id in struct sockaddr_in6... " >&6; } +if test ${zsh_cv_struct_member_struct_sockaddr_in6_sin6_scope_id+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#include <netinet/in.h> + +int +main (void) +{ +struct sockaddr_in6 testvar; testvar.sin6_scope_id; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_struct_member_struct_sockaddr_in6_sin6_scope_id=yes +else $as_nop + zsh_cv_struct_member_struct_sockaddr_in6_sin6_scope_id=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_struct_member_struct_sockaddr_in6_sin6_scope_id" >&5 +printf "%s\n" "$zsh_cv_struct_member_struct_sockaddr_in6_sin6_scope_id" >&6; } + +if test $zsh_cv_struct_member_struct_sockaddr_in6_sin6_scope_id = yes; then + printf "%s\n" "#define HAVE_STRUCT_SOCKADDR_IN6_SIN6_SCOPE_ID 1" >>confdefs.h + +fi + + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if we need our own h_errno" >&5 +printf %s "checking if we need our own h_errno... " >&6; } +if test ${zsh_cv_decl_h_errno_use_local+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +int +main (void) +{ +extern int h_errno; h_errno = 0; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + zsh_cv_decl_h_errno_use_local=no +else $as_nop + zsh_cv_decl_h_errno_use_local=yes +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_decl_h_errno_use_local" >&5 +printf "%s\n" "$zsh_cv_decl_h_errno_use_local" >&6; } + +if test x$zsh_cv_decl_h_errno_use_local = xyes; then + printf "%s\n" "#define USE_LOCAL_H_ERRNO 1" >>confdefs.h + +fi + + + +ac_fn_c_check_func "$LINENO" "strftime" "ac_cv_func_strftime" +if test "x$ac_cv_func_strftime" = xyes +then : + printf "%s\n" "#define HAVE_STRFTIME 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "strptime" "ac_cv_func_strptime" +if test "x$ac_cv_func_strptime" = xyes +then : + printf "%s\n" "#define HAVE_STRPTIME 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "mktime" "ac_cv_func_mktime" +if test "x$ac_cv_func_mktime" = xyes +then : + printf "%s\n" "#define HAVE_MKTIME 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "timelocal" "ac_cv_func_timelocal" +if test "x$ac_cv_func_timelocal" = xyes +then : + printf "%s\n" "#define HAVE_TIMELOCAL 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "difftime" "ac_cv_func_difftime" +if test "x$ac_cv_func_difftime" = xyes +then : + printf "%s\n" "#define HAVE_DIFFTIME 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "gettimeofday" "ac_cv_func_gettimeofday" +if test "x$ac_cv_func_gettimeofday" = xyes +then : + printf "%s\n" "#define HAVE_GETTIMEOFDAY 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "clock_gettime" "ac_cv_func_clock_gettime" +if test "x$ac_cv_func_clock_gettime" = xyes +then : + printf "%s\n" "#define HAVE_CLOCK_GETTIME 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "select" "ac_cv_func_select" +if test "x$ac_cv_func_select" = xyes +then : + printf "%s\n" "#define HAVE_SELECT 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "poll" "ac_cv_func_poll" +if test "x$ac_cv_func_poll" = xyes +then : + printf "%s\n" "#define HAVE_POLL 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "readlink" "ac_cv_func_readlink" +if test "x$ac_cv_func_readlink" = xyes +then : + printf "%s\n" "#define HAVE_READLINK 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "faccessx" "ac_cv_func_faccessx" +if test "x$ac_cv_func_faccessx" = xyes +then : + printf "%s\n" "#define HAVE_FACCESSX 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "fchdir" "ac_cv_func_fchdir" +if test "x$ac_cv_func_fchdir" = xyes +then : + printf "%s\n" "#define HAVE_FCHDIR 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "ftruncate" "ac_cv_func_ftruncate" +if test "x$ac_cv_func_ftruncate" = xyes +then : + printf "%s\n" "#define HAVE_FTRUNCATE 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "fstat" "ac_cv_func_fstat" +if test "x$ac_cv_func_fstat" = xyes +then : + printf "%s\n" "#define HAVE_FSTAT 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "lstat" "ac_cv_func_lstat" +if test "x$ac_cv_func_lstat" = xyes +then : + printf "%s\n" "#define HAVE_LSTAT 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "lchown" "ac_cv_func_lchown" +if test "x$ac_cv_func_lchown" = xyes +then : + printf "%s\n" "#define HAVE_LCHOWN 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "fchown" "ac_cv_func_fchown" +if test "x$ac_cv_func_fchown" = xyes +then : + printf "%s\n" "#define HAVE_FCHOWN 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "fchmod" "ac_cv_func_fchmod" +if test "x$ac_cv_func_fchmod" = xyes +then : + printf "%s\n" "#define HAVE_FCHMOD 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "fseeko" "ac_cv_func_fseeko" +if test "x$ac_cv_func_fseeko" = xyes +then : + printf "%s\n" "#define HAVE_FSEEKO 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "ftello" "ac_cv_func_ftello" +if test "x$ac_cv_func_ftello" = xyes +then : + printf "%s\n" "#define HAVE_FTELLO 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "mkfifo" "ac_cv_func_mkfifo" +if test "x$ac_cv_func_mkfifo" = xyes +then : + printf "%s\n" "#define HAVE_MKFIFO 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "_mktemp" "ac_cv_func__mktemp" +if test "x$ac_cv_func__mktemp" = xyes +then : + printf "%s\n" "#define HAVE__MKTEMP 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "mkstemp" "ac_cv_func_mkstemp" +if test "x$ac_cv_func_mkstemp" = xyes +then : + printf "%s\n" "#define HAVE_MKSTEMP 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "waitpid" "ac_cv_func_waitpid" +if test "x$ac_cv_func_waitpid" = xyes +then : + printf "%s\n" "#define HAVE_WAITPID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "wait3" "ac_cv_func_wait3" +if test "x$ac_cv_func_wait3" = xyes +then : + printf "%s\n" "#define HAVE_WAIT3 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "sigaction" "ac_cv_func_sigaction" +if test "x$ac_cv_func_sigaction" = xyes +then : + printf "%s\n" "#define HAVE_SIGACTION 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "sigblock" "ac_cv_func_sigblock" +if test "x$ac_cv_func_sigblock" = xyes +then : + printf "%s\n" "#define HAVE_SIGBLOCK 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "sighold" "ac_cv_func_sighold" +if test "x$ac_cv_func_sighold" = xyes +then : + printf "%s\n" "#define HAVE_SIGHOLD 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "sigrelse" "ac_cv_func_sigrelse" +if test "x$ac_cv_func_sigrelse" = xyes +then : + printf "%s\n" "#define HAVE_SIGRELSE 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "sigsetmask" "ac_cv_func_sigsetmask" +if test "x$ac_cv_func_sigsetmask" = xyes +then : + printf "%s\n" "#define HAVE_SIGSETMASK 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "sigprocmask" "ac_cv_func_sigprocmask" +if test "x$ac_cv_func_sigprocmask" = xyes +then : + printf "%s\n" "#define HAVE_SIGPROCMASK 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "killpg" "ac_cv_func_killpg" +if test "x$ac_cv_func_killpg" = xyes +then : + printf "%s\n" "#define HAVE_KILLPG 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setpgid" "ac_cv_func_setpgid" +if test "x$ac_cv_func_setpgid" = xyes +then : + printf "%s\n" "#define HAVE_SETPGID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setpgrp" "ac_cv_func_setpgrp" +if test "x$ac_cv_func_setpgrp" = xyes +then : + printf "%s\n" "#define HAVE_SETPGRP 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "tcsetpgrp" "ac_cv_func_tcsetpgrp" +if test "x$ac_cv_func_tcsetpgrp" = xyes +then : + printf "%s\n" "#define HAVE_TCSETPGRP 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "tcgetattr" "ac_cv_func_tcgetattr" +if test "x$ac_cv_func_tcgetattr" = xyes +then : + printf "%s\n" "#define HAVE_TCGETATTR 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "nice" "ac_cv_func_nice" +if test "x$ac_cv_func_nice" = xyes +then : + printf "%s\n" "#define HAVE_NICE 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "gethostname" "ac_cv_func_gethostname" +if test "x$ac_cv_func_gethostname" = xyes +then : + printf "%s\n" "#define HAVE_GETHOSTNAME 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "gethostbyname2" "ac_cv_func_gethostbyname2" +if test "x$ac_cv_func_gethostbyname2" = xyes +then : + printf "%s\n" "#define HAVE_GETHOSTBYNAME2 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getipnodebyname" "ac_cv_func_getipnodebyname" +if test "x$ac_cv_func_getipnodebyname" = xyes +then : + printf "%s\n" "#define HAVE_GETIPNODEBYNAME 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "inet_aton" "ac_cv_func_inet_aton" +if test "x$ac_cv_func_inet_aton" = xyes +then : + printf "%s\n" "#define HAVE_INET_ATON 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "inet_pton" "ac_cv_func_inet_pton" +if test "x$ac_cv_func_inet_pton" = xyes +then : + printf "%s\n" "#define HAVE_INET_PTON 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "inet_ntop" "ac_cv_func_inet_ntop" +if test "x$ac_cv_func_inet_ntop" = xyes +then : + printf "%s\n" "#define HAVE_INET_NTOP 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getlogin" "ac_cv_func_getlogin" +if test "x$ac_cv_func_getlogin" = xyes +then : + printf "%s\n" "#define HAVE_GETLOGIN 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getpwent" "ac_cv_func_getpwent" +if test "x$ac_cv_func_getpwent" = xyes +then : + printf "%s\n" "#define HAVE_GETPWENT 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getpwnam" "ac_cv_func_getpwnam" +if test "x$ac_cv_func_getpwnam" = xyes +then : + printf "%s\n" "#define HAVE_GETPWNAM 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getpwuid" "ac_cv_func_getpwuid" +if test "x$ac_cv_func_getpwuid" = xyes +then : + printf "%s\n" "#define HAVE_GETPWUID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getgrgid" "ac_cv_func_getgrgid" +if test "x$ac_cv_func_getgrgid" = xyes +then : + printf "%s\n" "#define HAVE_GETGRGID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getgrnam" "ac_cv_func_getgrnam" +if test "x$ac_cv_func_getgrnam" = xyes +then : + printf "%s\n" "#define HAVE_GETGRNAM 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "initgroups" "ac_cv_func_initgroups" +if test "x$ac_cv_func_initgroups" = xyes +then : + printf "%s\n" "#define HAVE_INITGROUPS 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "nis_list" "ac_cv_func_nis_list" +if test "x$ac_cv_func_nis_list" = xyes +then : + printf "%s\n" "#define HAVE_NIS_LIST 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setuid" "ac_cv_func_setuid" +if test "x$ac_cv_func_setuid" = xyes +then : + printf "%s\n" "#define HAVE_SETUID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "seteuid" "ac_cv_func_seteuid" +if test "x$ac_cv_func_seteuid" = xyes +then : + printf "%s\n" "#define HAVE_SETEUID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setreuid" "ac_cv_func_setreuid" +if test "x$ac_cv_func_setreuid" = xyes +then : + printf "%s\n" "#define HAVE_SETREUID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setresuid" "ac_cv_func_setresuid" +if test "x$ac_cv_func_setresuid" = xyes +then : + printf "%s\n" "#define HAVE_SETRESUID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setsid" "ac_cv_func_setsid" +if test "x$ac_cv_func_setsid" = xyes +then : + printf "%s\n" "#define HAVE_SETSID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setgid" "ac_cv_func_setgid" +if test "x$ac_cv_func_setgid" = xyes +then : + printf "%s\n" "#define HAVE_SETGID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setegid" "ac_cv_func_setegid" +if test "x$ac_cv_func_setegid" = xyes +then : + printf "%s\n" "#define HAVE_SETEGID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setregid" "ac_cv_func_setregid" +if test "x$ac_cv_func_setregid" = xyes +then : + printf "%s\n" "#define HAVE_SETREGID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setresgid" "ac_cv_func_setresgid" +if test "x$ac_cv_func_setresgid" = xyes +then : + printf "%s\n" "#define HAVE_SETRESGID 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "memcpy" "ac_cv_func_memcpy" +if test "x$ac_cv_func_memcpy" = xyes +then : + printf "%s\n" "#define HAVE_MEMCPY 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "memmove" "ac_cv_func_memmove" +if test "x$ac_cv_func_memmove" = xyes +then : + printf "%s\n" "#define HAVE_MEMMOVE 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "strstr" "ac_cv_func_strstr" +if test "x$ac_cv_func_strstr" = xyes +then : + printf "%s\n" "#define HAVE_STRSTR 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "strerror" "ac_cv_func_strerror" +if test "x$ac_cv_func_strerror" = xyes +then : + printf "%s\n" "#define HAVE_STRERROR 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "strtoul" "ac_cv_func_strtoul" +if test "x$ac_cv_func_strtoul" = xyes +then : + printf "%s\n" "#define HAVE_STRTOUL 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getrlimit" "ac_cv_func_getrlimit" +if test "x$ac_cv_func_getrlimit" = xyes +then : + printf "%s\n" "#define HAVE_GETRLIMIT 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getrusage" "ac_cv_func_getrusage" +if test "x$ac_cv_func_getrusage" = xyes +then : + printf "%s\n" "#define HAVE_GETRUSAGE 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setlocale" "ac_cv_func_setlocale" +if test "x$ac_cv_func_setlocale" = xyes +then : + printf "%s\n" "#define HAVE_SETLOCALE 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "isblank" "ac_cv_func_isblank" +if test "x$ac_cv_func_isblank" = xyes +then : + printf "%s\n" "#define HAVE_ISBLANK 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "iswblank" "ac_cv_func_iswblank" +if test "x$ac_cv_func_iswblank" = xyes +then : + printf "%s\n" "#define HAVE_ISWBLANK 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "uname" "ac_cv_func_uname" +if test "x$ac_cv_func_uname" = xyes +then : + printf "%s\n" "#define HAVE_UNAME 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "signgam" "ac_cv_func_signgam" +if test "x$ac_cv_func_signgam" = xyes +then : + printf "%s\n" "#define HAVE_SIGNGAM 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "tgamma" "ac_cv_func_tgamma" +if test "x$ac_cv_func_tgamma" = xyes +then : + printf "%s\n" "#define HAVE_TGAMMA 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "log2" "ac_cv_func_log2" +if test "x$ac_cv_func_log2" = xyes +then : + printf "%s\n" "#define HAVE_LOG2 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "scalbn" "ac_cv_func_scalbn" +if test "x$ac_cv_func_scalbn" = xyes +then : + printf "%s\n" "#define HAVE_SCALBN 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "putenv" "ac_cv_func_putenv" +if test "x$ac_cv_func_putenv" = xyes +then : + printf "%s\n" "#define HAVE_PUTENV 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getenv" "ac_cv_func_getenv" +if test "x$ac_cv_func_getenv" = xyes +then : + printf "%s\n" "#define HAVE_GETENV 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setenv" "ac_cv_func_setenv" +if test "x$ac_cv_func_setenv" = xyes +then : + printf "%s\n" "#define HAVE_SETENV 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "unsetenv" "ac_cv_func_unsetenv" +if test "x$ac_cv_func_unsetenv" = xyes +then : + printf "%s\n" "#define HAVE_UNSETENV 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "xw" "ac_cv_func_xw" +if test "x$ac_cv_func_xw" = xyes +then : + printf "%s\n" "#define HAVE_XW 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "brk" "ac_cv_func_brk" +if test "x$ac_cv_func_brk" = xyes +then : + printf "%s\n" "#define HAVE_BRK 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "sbrk" "ac_cv_func_sbrk" +if test "x$ac_cv_func_sbrk" = xyes +then : + printf "%s\n" "#define HAVE_SBRK 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "pathconf" "ac_cv_func_pathconf" +if test "x$ac_cv_func_pathconf" = xyes +then : + printf "%s\n" "#define HAVE_PATHCONF 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "sysconf" "ac_cv_func_sysconf" +if test "x$ac_cv_func_sysconf" = xyes +then : + printf "%s\n" "#define HAVE_SYSCONF 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "tgetent" "ac_cv_func_tgetent" +if test "x$ac_cv_func_tgetent" = xyes +then : + printf "%s\n" "#define HAVE_TGETENT 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "tigetflag" "ac_cv_func_tigetflag" +if test "x$ac_cv_func_tigetflag" = xyes +then : + printf "%s\n" "#define HAVE_TIGETFLAG 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "tigetnum" "ac_cv_func_tigetnum" +if test "x$ac_cv_func_tigetnum" = xyes +then : + printf "%s\n" "#define HAVE_TIGETNUM 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "tigetstr" "ac_cv_func_tigetstr" +if test "x$ac_cv_func_tigetstr" = xyes +then : + printf "%s\n" "#define HAVE_TIGETSTR 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setupterm" "ac_cv_func_setupterm" +if test "x$ac_cv_func_setupterm" = xyes +then : + printf "%s\n" "#define HAVE_SETUPTERM 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "initscr" "ac_cv_func_initscr" +if test "x$ac_cv_func_initscr" = xyes +then : + printf "%s\n" "#define HAVE_INITSCR 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "resize_term" "ac_cv_func_resize_term" +if test "x$ac_cv_func_resize_term" = xyes +then : + printf "%s\n" "#define HAVE_RESIZE_TERM 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getcchar" "ac_cv_func_getcchar" +if test "x$ac_cv_func_getcchar" = xyes +then : + printf "%s\n" "#define HAVE_GETCCHAR 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setcchar" "ac_cv_func_setcchar" +if test "x$ac_cv_func_setcchar" = xyes +then : + printf "%s\n" "#define HAVE_SETCCHAR 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "waddwstr" "ac_cv_func_waddwstr" +if test "x$ac_cv_func_waddwstr" = xyes +then : + printf "%s\n" "#define HAVE_WADDWSTR 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "wget_wch" "ac_cv_func_wget_wch" +if test "x$ac_cv_func_wget_wch" = xyes +then : + printf "%s\n" "#define HAVE_WGET_WCH 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "win_wch" "ac_cv_func_win_wch" +if test "x$ac_cv_func_win_wch" = xyes +then : + printf "%s\n" "#define HAVE_WIN_WCH 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "use_default_colors" "ac_cv_func_use_default_colors" +if test "x$ac_cv_func_use_default_colors" = xyes +then : + printf "%s\n" "#define HAVE_USE_DEFAULT_COLORS 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "pcre_compile" "ac_cv_func_pcre_compile" +if test "x$ac_cv_func_pcre_compile" = xyes +then : + printf "%s\n" "#define HAVE_PCRE_COMPILE 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "pcre_study" "ac_cv_func_pcre_study" +if test "x$ac_cv_func_pcre_study" = xyes +then : + printf "%s\n" "#define HAVE_PCRE_STUDY 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "pcre_exec" "ac_cv_func_pcre_exec" +if test "x$ac_cv_func_pcre_exec" = xyes +then : + printf "%s\n" "#define HAVE_PCRE_EXEC 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "nl_langinfo" "ac_cv_func_nl_langinfo" +if test "x$ac_cv_func_nl_langinfo" = xyes +then : + printf "%s\n" "#define HAVE_NL_LANGINFO 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "erand48" "ac_cv_func_erand48" +if test "x$ac_cv_func_erand48" = xyes +then : + printf "%s\n" "#define HAVE_ERAND48 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "open_memstream" "ac_cv_func_open_memstream" +if test "x$ac_cv_func_open_memstream" = xyes +then : + printf "%s\n" "#define HAVE_OPEN_MEMSTREAM 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "posix_openpt" "ac_cv_func_posix_openpt" +if test "x$ac_cv_func_posix_openpt" = xyes +then : + printf "%s\n" "#define HAVE_POSIX_OPENPT 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "wctomb" "ac_cv_func_wctomb" +if test "x$ac_cv_func_wctomb" = xyes +then : + printf "%s\n" "#define HAVE_WCTOMB 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "iconv" "ac_cv_func_iconv" +if test "x$ac_cv_func_iconv" = xyes +then : + printf "%s\n" "#define HAVE_ICONV 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "grantpt" "ac_cv_func_grantpt" +if test "x$ac_cv_func_grantpt" = xyes +then : + printf "%s\n" "#define HAVE_GRANTPT 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "unlockpt" "ac_cv_func_unlockpt" +if test "x$ac_cv_func_unlockpt" = xyes +then : + printf "%s\n" "#define HAVE_UNLOCKPT 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "ptsname" "ac_cv_func_ptsname" +if test "x$ac_cv_func_ptsname" = xyes +then : + printf "%s\n" "#define HAVE_PTSNAME 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "htons" "ac_cv_func_htons" +if test "x$ac_cv_func_htons" = xyes +then : + printf "%s\n" "#define HAVE_HTONS 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "ntohs" "ac_cv_func_ntohs" +if test "x$ac_cv_func_ntohs" = xyes +then : + printf "%s\n" "#define HAVE_NTOHS 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "regcomp" "ac_cv_func_regcomp" +if test "x$ac_cv_func_regcomp" = xyes +then : + printf "%s\n" "#define HAVE_REGCOMP 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "regexec" "ac_cv_func_regexec" +if test "x$ac_cv_func_regexec" = xyes +then : + printf "%s\n" "#define HAVE_REGEXEC 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "regerror" "ac_cv_func_regerror" +if test "x$ac_cv_func_regerror" = xyes +then : + printf "%s\n" "#define HAVE_REGERROR 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "regfree" "ac_cv_func_regfree" +if test "x$ac_cv_func_regfree" = xyes +then : + printf "%s\n" "#define HAVE_REGFREE 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "gdbm_open" "ac_cv_func_gdbm_open" +if test "x$ac_cv_func_gdbm_open" = xyes +then : + printf "%s\n" "#define HAVE_GDBM_OPEN 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getxattr" "ac_cv_func_getxattr" +if test "x$ac_cv_func_getxattr" = xyes +then : + printf "%s\n" "#define HAVE_GETXATTR 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "realpath" "ac_cv_func_realpath" +if test "x$ac_cv_func_realpath" = xyes +then : + printf "%s\n" "#define HAVE_REALPATH 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "canonicalize_file_name" "ac_cv_func_canonicalize_file_name" +if test "x$ac_cv_func_canonicalize_file_name" = xyes +then : + printf "%s\n" "#define HAVE_CANONICALIZE_FILE_NAME 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "symlink" "ac_cv_func_symlink" +if test "x$ac_cv_func_symlink" = xyes +then : + printf "%s\n" "#define HAVE_SYMLINK 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getcwd" "ac_cv_func_getcwd" +if test "x$ac_cv_func_getcwd" = xyes +then : + printf "%s\n" "#define HAVE_GETCWD 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "cygwin_conv_path" "ac_cv_func_cygwin_conv_path" +if test "x$ac_cv_func_cygwin_conv_path" = xyes +then : + printf "%s\n" "#define HAVE_CYGWIN_CONV_PATH 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "nanosleep" "ac_cv_func_nanosleep" +if test "x$ac_cv_func_nanosleep" = xyes +then : + printf "%s\n" "#define HAVE_NANOSLEEP 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "srand_deterministic" "ac_cv_func_srand_deterministic" +if test "x$ac_cv_func_srand_deterministic" = xyes +then : + printf "%s\n" "#define HAVE_SRAND_DETERMINISTIC 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "setutxent" "ac_cv_func_setutxent" +if test "x$ac_cv_func_setutxent" = xyes +then : + printf "%s\n" "#define HAVE_SETUTXENT 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getutxent" "ac_cv_func_getutxent" +if test "x$ac_cv_func_getutxent" = xyes +then : + printf "%s\n" "#define HAVE_GETUTXENT 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "endutxent" "ac_cv_func_endutxent" +if test "x$ac_cv_func_endutxent" = xyes +then : + printf "%s\n" "#define HAVE_ENDUTXENT 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "getutent" "ac_cv_func_getutent" +if test "x$ac_cv_func_getutent" = xyes +then : + printf "%s\n" "#define HAVE_GETUTENT 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for working strcoll" >&5 +printf %s "checking for working strcoll... " >&6; } +if test ${ac_cv_func_strcoll_works+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + case "$host_os" in # (( + # Guess yes on glibc systems. + *-gnu*) ac_cv_func_strcoll_works=yes ;; + # If we don't know, assume the worst. + *) ac_cv_func_strcoll_works=no ;; + esac +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$ac_includes_default +int +main (void) +{ +return (strcoll ("abc", "def") >= 0 || + strcoll ("ABC", "DEF") >= 0 || + strcoll ("123", "456") >= 0) + ; + return 0; +} +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + ac_cv_func_strcoll_works=yes +else $as_nop + ac_cv_func_strcoll_works=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_func_strcoll_works" >&5 +printf "%s\n" "$ac_cv_func_strcoll_works" >&6; } +if test $ac_cv_func_strcoll_works = yes; then + +printf "%s\n" "#define HAVE_STRCOLL 1" >>confdefs.h + +fi + + +# isinf() and isnan() can exist as either functions or macros. + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for isinf" >&5 +printf %s "checking for isinf... " >&6; } +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <math.h> +int main () { return (isinf(1.0) != 0); } +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: yes" >&5 +printf "%s\n" "yes" >&6; } + printf "%s\n" "#define HAVE_ISINF 1" >>confdefs.h + +else $as_nop + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for isnan" >&5 +printf %s "checking for isnan... " >&6; } +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <math.h> +int main () { return (isnan(1.0) != 0); } +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: yes" >&5 +printf "%s\n" "yes" >&6; } + printf "%s\n" "#define HAVE_ISNAN 1" >>confdefs.h + +else $as_nop + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5 +printf "%s\n" "no" >&6; } +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if realpath accepts NULL" >&5 +printf %s "checking if realpath accepts NULL... " >&6; } +if test ${zsh_cv_func_realpath_accepts_null+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_func_realpath_accepts_null=$ac_cv_func_canonicalize_file_name +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <stdlib.h> +#include <limits.h> + +int +main (void) +{ + +exit(!realpath("/", (char*)0)); + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_func_realpath_accepts_null=yes +else $as_nop + zsh_cv_func_realpath_accepts_null=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_func_realpath_accepts_null" >&5 +printf "%s\n" "$zsh_cv_func_realpath_accepts_null" >&6; } +if test x$zsh_cv_func_realpath_accepts_null = xyes; then + printf "%s\n" "#define REALPATH_ACCEPTS_NULL 1" >>confdefs.h + +fi + +if test x$enable_cap = xyes; then + ac_fn_c_check_func "$LINENO" "cap_get_proc" "ac_cv_func_cap_get_proc" +if test "x$ac_cv_func_cap_get_proc" = xyes +then : + printf "%s\n" "#define HAVE_CAP_GET_PROC 1" >>confdefs.h + +fi + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if tgetent accepts NULL" >&5 +printf %s "checking if tgetent accepts NULL... " >&6; } +if test ${zsh_cv_func_tgetent_accepts_null+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_func_tgetent_accepts_null=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <fcntl.h> +#include <stdlib.h> +int tgetent(char *, char *); +char *tgetstr(char *, char **); +main() +{ + char buf[4096]; + int r1 = tgetent(buf, "vt100"); + int r2 = tgetent((char*)0,"vt100"); + if (r1 >= 0 && r1 == r2) { + char tbuf[1024], *u; + u = tbuf; + tgetstr("cl", &u); + creat("conftest.tgetent", 0640); + } + exit((r1 != r2) || r2 == -1); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + if test -f conftest.tgetent; then + zsh_cv_func_tgetent_accepts_null=yes + else + zsh_cv_func_tgetent_accepts_null=no + fi +else $as_nop + zsh_cv_func_tgetent_accepts_null=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_func_tgetent_accepts_null" >&5 +printf "%s\n" "$zsh_cv_func_tgetent_accepts_null" >&6; } +if test x$zsh_cv_func_tgetent_accepts_null = xyes; then + printf "%s\n" "#define TGETENT_ACCEPTS_NULL 1" >>confdefs.h + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if tgetent returns 0 on success" >&5 +printf %s "checking if tgetent returns 0 on success... " >&6; } +if test ${zsh_cv_func_tgetent_zero_success+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_func_tgetent_zero_success=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <fcntl.h> +#include <stdlib.h> +int tgetent(char *, char*); +char *tgetstr(char *, char **); +main() +{ + char buf[4096]; + int r1 = tgetent(buf, "!@#$%^&*"); + int r2 = tgetent(buf, "vt100"); + if (r1 < 0 && r2 == 0) { + char tbuf[1024], *u; + u = tbuf; + tgetstr("cl", &u); + creat("conftest.tgetent0", 0640); + } + exit(r1 == r2); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + if test -f conftest.tgetent0; then + zsh_cv_func_tgetent_zero_success=yes + else + zsh_cv_func_tgetent_zero_success=no + fi +else $as_nop + zsh_cv_func_tgetent_zero_success=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_func_tgetent_zero_success" >&5 +printf "%s\n" "$zsh_cv_func_tgetent_zero_success" >&6; } + +if test x$zsh_cv_func_tgetent_zero_success = xyes; then + printf "%s\n" "#define TGETENT_SUCCESS 0" >>confdefs.h + +else + printf "%s\n" "#define TGETENT_SUCCESS 1" >>confdefs.h + +fi + + +ac_func= +for ac_item in $ac_func_c_list +do + if test $ac_func; then + ac_fn_c_check_func "$LINENO" $ac_func ac_cv_func_$ac_func + if eval test \"x\$ac_cv_func_$ac_func\" = xyes; then + echo "#define $ac_item 1" >> confdefs.h + fi + ac_func= + else + ac_func=$ac_item + fi +done + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for working mmap" >&5 +printf %s "checking for working mmap... " >&6; } +if test ${ac_cv_func_mmap_fixed_mapped+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + case "$host_os" in # (( + # Guess yes on platforms where we know the result. + linux*) ac_cv_func_mmap_fixed_mapped=yes ;; + # If we don't know, assume the worst. + *) ac_cv_func_mmap_fixed_mapped=no ;; + esac +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$ac_includes_default +/* malloc might have been renamed as rpl_malloc. */ +#undef malloc + +/* Thanks to Mike Haertel and Jim Avera for this test. + Here is a matrix of mmap possibilities: + mmap private not fixed + mmap private fixed at somewhere currently unmapped + mmap private fixed at somewhere already mapped + mmap shared not fixed + mmap shared fixed at somewhere currently unmapped + mmap shared fixed at somewhere already mapped + For private mappings, we should verify that changes cannot be read() + back from the file, nor mmap's back from the file at a different + address. (There have been systems where private was not correctly + implemented like the infamous i386 svr4.0, and systems where the + VM page cache was not coherent with the file system buffer cache + like early versions of FreeBSD and possibly contemporary NetBSD.) + For shared mappings, we should conversely verify that changes get + propagated back to all the places they're supposed to be. + + Grep wants private fixed already mapped. + The main things grep needs to know about mmap are: + * does it exist and is it safe to write into the mmap'd area + * how to use it (BSD variants) */ + +#include <fcntl.h> +#include <sys/mman.h> + +/* This mess was copied from the GNU getpagesize.h. */ +#ifndef HAVE_GETPAGESIZE +# ifdef _SC_PAGESIZE +# define getpagesize() sysconf(_SC_PAGESIZE) +# else /* no _SC_PAGESIZE */ +# ifdef HAVE_SYS_PARAM_H +# include <sys/param.h> +# ifdef EXEC_PAGESIZE +# define getpagesize() EXEC_PAGESIZE +# else /* no EXEC_PAGESIZE */ +# ifdef NBPG +# define getpagesize() NBPG * CLSIZE +# ifndef CLSIZE +# define CLSIZE 1 +# endif /* no CLSIZE */ +# else /* no NBPG */ +# ifdef NBPC +# define getpagesize() NBPC +# else /* no NBPC */ +# ifdef PAGESIZE +# define getpagesize() PAGESIZE +# endif /* PAGESIZE */ +# endif /* no NBPC */ +# endif /* no NBPG */ +# endif /* no EXEC_PAGESIZE */ +# else /* no HAVE_SYS_PARAM_H */ +# define getpagesize() 8192 /* punt totally */ +# endif /* no HAVE_SYS_PARAM_H */ +# endif /* no _SC_PAGESIZE */ + +#endif /* no HAVE_GETPAGESIZE */ + +int +main (void) +{ + char *data, *data2, *data3; + const char *cdata2; + int i, pagesize; + int fd, fd2; + + pagesize = getpagesize (); + + /* First, make a file with some known garbage in it. */ + data = (char *) malloc (pagesize); + if (!data) + return 1; + for (i = 0; i < pagesize; ++i) + *(data + i) = rand (); + umask (0); + fd = creat ("conftest.mmap", 0600); + if (fd < 0) + return 2; + if (write (fd, data, pagesize) != pagesize) + return 3; + close (fd); + + /* Next, check that the tail of a page is zero-filled. File must have + non-zero length, otherwise we risk SIGBUS for entire page. */ + fd2 = open ("conftest.txt", O_RDWR | O_CREAT | O_TRUNC, 0600); + if (fd2 < 0) + return 4; + cdata2 = ""; + if (write (fd2, cdata2, 1) != 1) + return 5; + data2 = (char *) mmap (0, pagesize, PROT_READ | PROT_WRITE, MAP_SHARED, fd2, 0L); + if (data2 == MAP_FAILED) + return 6; + for (i = 0; i < pagesize; ++i) + if (*(data2 + i)) + return 7; + close (fd2); + if (munmap (data2, pagesize)) + return 8; + + /* Next, try to mmap the file at a fixed address which already has + something else allocated at it. If we can, also make sure that + we see the same garbage. */ + fd = open ("conftest.mmap", O_RDWR); + if (fd < 0) + return 9; + if (data2 != mmap (data2, pagesize, PROT_READ | PROT_WRITE, + MAP_PRIVATE | MAP_FIXED, fd, 0L)) + return 10; + for (i = 0; i < pagesize; ++i) + if (*(data + i) != *(data2 + i)) + return 11; + + /* Finally, make sure that changes to the mapped area do not + percolate back to the file as seen by read(). (This is a bug on + some variants of i386 svr4.0.) */ + for (i = 0; i < pagesize; ++i) + *(data2 + i) = *(data2 + i) + 1; + data3 = (char *) malloc (pagesize); + if (!data3) + return 12; + if (read (fd, data3, pagesize) != pagesize) + return 13; + for (i = 0; i < pagesize; ++i) + if (*(data + i) != *(data3 + i)) + return 14; + close (fd); + free (data); + free (data3); + return 0; +} +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + ac_cv_func_mmap_fixed_mapped=yes +else $as_nop + ac_cv_func_mmap_fixed_mapped=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_func_mmap_fixed_mapped" >&5 +printf "%s\n" "$ac_cv_func_mmap_fixed_mapped" >&6; } +if test $ac_cv_func_mmap_fixed_mapped = yes; then + +printf "%s\n" "#define HAVE_MMAP 1" >>confdefs.h + +fi +rm -f conftest.mmap conftest.txt + +if test x$ac_cv_func_mmap_fixed_mapped = xyes; then + ac_fn_c_check_func "$LINENO" "munmap" "ac_cv_func_munmap" +if test "x$ac_cv_func_munmap" = xyes +then : + printf "%s\n" "#define HAVE_MUNMAP 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "msync" "ac_cv_func_msync" +if test "x$ac_cv_func_msync" = xyes +then : + printf "%s\n" "#define HAVE_MSYNC 1" >>confdefs.h + +fi + +fi + +if test x$ac_cv_func_setpgrp = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether getpgrp requires zero arguments" >&5 +printf %s "checking whether getpgrp requires zero arguments... " >&6; } +if test ${ac_cv_func_getpgrp_void+y} +then : + printf %s "(cached) " >&6 +else $as_nop + # Use it with a single arg. +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$ac_includes_default +int +main (void) +{ +getpgrp (0); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_func_getpgrp_void=no +else $as_nop + ac_cv_func_getpgrp_void=yes +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_func_getpgrp_void" >&5 +printf "%s\n" "$ac_cv_func_getpgrp_void" >&6; } +if test $ac_cv_func_getpgrp_void = yes; then + +printf "%s\n" "#define GETPGRP_VOID 1" >>confdefs.h + +fi + +else + ac_cv_func_getpgrp_void=yes + printf "%s\n" "#define GETPGRP_VOID 1" >>confdefs.h + +fi + +if test x$dynamic = xyes; then + ac_fn_c_check_func "$LINENO" "dlopen" "ac_cv_func_dlopen" +if test "x$ac_cv_func_dlopen" = xyes +then : + printf "%s\n" "#define HAVE_DLOPEN 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "dlerror" "ac_cv_func_dlerror" +if test "x$ac_cv_func_dlerror" = xyes +then : + printf "%s\n" "#define HAVE_DLERROR 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "dlsym" "ac_cv_func_dlsym" +if test "x$ac_cv_func_dlsym" = xyes +then : + printf "%s\n" "#define HAVE_DLSYM 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "dlclose" "ac_cv_func_dlclose" +if test "x$ac_cv_func_dlclose" = xyes +then : + printf "%s\n" "#define HAVE_DLCLOSE 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "load" "ac_cv_func_load" +if test "x$ac_cv_func_load" = xyes +then : + printf "%s\n" "#define HAVE_LOAD 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "loadquery" "ac_cv_func_loadquery" +if test "x$ac_cv_func_loadquery" = xyes +then : + printf "%s\n" "#define HAVE_LOADQUERY 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "loadbind" "ac_cv_func_loadbind" +if test "x$ac_cv_func_loadbind" = xyes +then : + printf "%s\n" "#define HAVE_LOADBIND 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "unload" "ac_cv_func_unload" +if test "x$ac_cv_func_unload" = xyes +then : + printf "%s\n" "#define HAVE_UNLOAD 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "shl_load" "ac_cv_func_shl_load" +if test "x$ac_cv_func_shl_load" = xyes +then : + printf "%s\n" "#define HAVE_SHL_LOAD 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "shl_unload" "ac_cv_func_shl_unload" +if test "x$ac_cv_func_shl_unload" = xyes +then : + printf "%s\n" "#define HAVE_SHL_UNLOAD 1" >>confdefs.h + +fi +ac_fn_c_check_func "$LINENO" "shl_findsym" "ac_cv_func_shl_findsym" +if test "x$ac_cv_func_shl_findsym" = xyes +then : + printf "%s\n" "#define HAVE_SHL_FINDSYM 1" >>confdefs.h + +fi + +fi + + +if test x$ac_cv_func_getxattr = xyes && test x$ac_cv_header_sys_xattr_h = xyes +then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if getxattr etc. are Linux-like" >&5 +printf %s "checking if getxattr etc. are Linux-like... " >&6; } +if test ${zsh_cv_getxattr_linux+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/types.h> +#include <sys/xattr.h> +int +main (void) +{ + + (void)listxattr("", 0, 0); + (void)getxattr("", "", 0, 0); + (void)setxattr("", "", "", 0, 0); + (void)removexattr("", ""); + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_getxattr_linux=yes +else $as_nop + zsh_cv_getxattr_linux=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_getxattr_linux" >&5 +printf "%s\n" "$zsh_cv_getxattr_linux" >&6; } + + if test x$zsh_cv_getxattr_linux != xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if getxattr etc. are MAC-like" >&5 +printf %s "checking if getxattr etc. are MAC-like... " >&6; } +if test ${zsh_cv_getxattr_mac+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/types.h> +#include <sys/xattr.h> +int +main (void) +{ +(void)listxattr("", 0, 0, 0); + (void)getxattr("", "", 0, 0, 0, 0); + (void)setxattr("", "", "", 0, 0, 0); + (void)removexattr("", "", 0); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_getxattr_mac=yes +else $as_nop + zsh_cv_getxattr_mac=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_getxattr_mac" >&5 +printf "%s\n" "$zsh_cv_getxattr_mac" >&6; } + + if test x$zsh_cv_getxattr_mac = xyes; then + printf "%s\n" "#define XATTR_EXTRA_ARGS 1" >>confdefs.h + + fi + fi +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if getxattr etc. are usable" >&5 +printf %s "checking if getxattr etc. are usable... " >&6; } +if test ${zsh_cv_use_xattr+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test x$zsh_cv_getxattr_linux = xyes || test x$zsh_cv_getxattr_mac = xyes +then +zsh_cv_use_xattr=yes +else +zsh_cv_use_xattr=no +fi +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_use_xattr" >&5 +printf "%s\n" "$zsh_cv_use_xattr" >&6; } + + + + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking what style of signals to use" >&5 +printf %s "checking what style of signals to use... " >&6; } +if test x$ac_cv_func_sigaction = xyes && test x$ac_cv_func_sigprocmask = xyes; then + signals_style=POSIX_SIGNALS + printf "%s\n" "#define POSIX_SIGNALS 1" >>confdefs.h + +elif test x$ac_cv_func_sigblock = xyes && test x$ac_cv_func_sigsetmask = xyes; then + signals_style=BSD_SIGNALS + printf "%s\n" "#define BSD_SIGNALS 1" >>confdefs.h + +elif test x$ac_cv_func_sighold = xyes && test x$ac_cv_func_sigrelse = xyes; then + signals_style=SYSV_SIGNALS + printf "%s\n" "#define SYSV_SIGNALS 1" >>confdefs.h + +else + signals_style=NO_SIGNAL_BLOCKING + printf "%s\n" "#define NO_SIGNAL_BLOCKING 1" >>confdefs.h + +fi +printf "%s\n" "#define $signals_style 1" >>confdefs.h + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $signals_style" >&5 +printf "%s\n" "$signals_style" >&6; } + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking where signal.h is located" >&5 +printf %s "checking where signal.h is located... " >&6; } +if test ${zsh_cv_path_signal_h+y} +then : + printf %s "(cached) " >&6 +else $as_nop + echo "#include <signal.h>" > nametmp.c +sigfile_list="`$CPP $CPPFLAGS nametmp.c | +sed -n -e 's/^#line[ ].*\"\(.*\)\"/\1/p' \ + -e 's/^#[ ].*\"\(.*\)\"/\1/p' | +sed 's/\\\\\\\\/\//g' | +$AWK '{ if ($1 ~ /sig/) files[$1] = $1 } + END { for (var in files) print var }'`" +rm -f nametmp.c +if test -z "$sigfile_list"; then + sigfile_list="/usr/include/sys/iso/signal_iso.h +/usr/include/bsd/sys/signal.h +/usr/include/signum.h +/usr/include/asm/signum.h +/usr/include/asm/signal.h +/usr/include/linux/signal.h +/usr/include/sys/signal.h +/usr/include/bits/signum.h +/dev/null" +fi +for SIGNAL_TRY_H in $sigfile_list +do + nsigs=`test -f $SIGNAL_TRY_H && \ + grep '#[ ]*define[ ][ ]*SIG[0-9A-Z]*[ ]*[0-9][0-9]*' $SIGNAL_TRY_H | \ + wc -l | sed 's/ //g'` + if test "x$nsigs" != x && test "$nsigs" -ge 7 + then + SIGNAL_H="$SIGNAL_H $SIGNAL_TRY_H" + fi +done +if test "x$SIGNAL_H" = x; then + as_fn_error $? "SIGNAL MACROS NOT FOUND: please report to developers" "$LINENO" 5 +fi +zsh_cv_path_signal_h="$SIGNAL_H" + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_path_signal_h" >&5 +printf "%s\n" "$zsh_cv_path_signal_h" >&6; } +SIGNAL_H="$zsh_cv_path_signal_h" + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking where error names are located" >&5 +printf %s "checking where error names are located... " >&6; } +if test ${zsh_cv_path_errno_h+y} +then : + printf %s "(cached) " >&6 +else $as_nop + echo "#include <errno.h>" > nametmp.c +errfile_list="`$CPP $CPPFLAGS nametmp.c | +sed -n -e 's/^#line[ ].*\"\(.*\)\"/\1/p' \ + -e 's/^#[ 0-9].*\"\(.*\)\"/\1/p' | +sed 's/\\\\\\\\/\//g' | +$AWK '{ if ($1 ~ /err/) files[$1] = $1 } + END { for (var in files) print var }'`" +rm -f nametmp.c +for ERRNO_TRY_H in $errfile_list /dev/null +do + nerrs=`test -f $ERRNO_TRY_H && \ + $EGREP '#[ ]*define[ ][ ]*E[0-9A-Z]*[ ]*(_HURD_ERRNO )?\(?[_A-Z0-9]' $ERRNO_TRY_H | \ + wc -l | sed 's/ //g'` + if test "x$nerrs" != x && test "$nerrs" -ge 1 + then + ERRNO_H="$ERRNO_H $ERRNO_TRY_H" + fi +done +if test x"$ERRNO_H" = x; then + as_fn_error $? "ERROR MACROS NOT FOUND: please report to developers" "$LINENO" 5 +fi +zsh_cv_path_errno_h="$ERRNO_H" + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_path_errno_h" >&5 +printf "%s\n" "$zsh_cv_path_errno_h" >&6; } +ERRNO_H="$zsh_cv_path_errno_h" + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking location of curses header" >&5 +printf %s "checking location of curses header... " >&6; } +if test ${zsh_cv_path_curses_header+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test x$zsh_cv_ignore_ncurses = xyes; then + if test x$ac_cv_header_curses_h = xyes; then + zsh_cv_path_curses_header=curses.h + else + zsh_cv_path_curses_header=none + fi +elif test x$ac_cv_header_ncursesw_ncurses_h = xyes; then + zsh_cv_path_curses_header=ncursesw/ncurses.h +elif test x$ac_cv_header_ncurses_ncurses_h = xyes; then + zsh_cv_path_curses_header=ncurses/ncurses.h +elif test x$ac_cv_header_ncurses_h = xyes; then + zsh_cv_path_curses_header=ncurses.h +elif test x$ac_cv_header_curses_h = xyes; then + zsh_cv_path_curses_header=curses.h +else + zsh_cv_path_curses_header=none +fi +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_path_curses_header" >&5 +printf "%s\n" "$zsh_cv_path_curses_header" >&6; } + +if test x$zsh_cv_path_curses_header != xnone; then + printf "%s\n" "#define ZSH_HAVE_CURSES_H 1" >>confdefs.h + + ZSH_CURSES_H=$zsh_cv_path_curses_header +else + ZSH_CURSES_H= +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking where curses key definitions are located" >&5 +printf %s "checking where curses key definitions are located... " >&6; } +if test ${zsh_cv_path_curses_keys_h+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test x$zsh_cv_path_curses_header = xnone; then + echo >nametmp.c +else + echo "#include <$zsh_cv_path_curses_header>" >nametmp.c +fi + +curses_list="`$CPP $CPPFLAGS nametmp.c | +sed -n -e 's/^#line[ ].*\"\(.*\)\"/\1/p' \ + -e 's/^#[ 0-9].*\"\(.*\)\"/\1/p' | +sed 's/\\\\\\\\/\//g' | +$AWK '{ if ($1 ~ /\.h/) files[$1] = $1 } + END { for (var in files) print var }'`" +rm -f nametmp.c +for CURSES_TRY_H in $curses_list /dev/null +do + nkeys=`test -f $CURSES_TRY_H && \ + $EGREP '#[ ]*define[ ][ ]*KEY_' $CURSES_TRY_H | \ + wc -l | sed 's/ //g'` + if test "x$nkeys" != x && test "$nkeys" -ge 10 + then + CURSES_KEYS_H=$CURSES_TRY_H + break + fi +done +zsh_cv_path_curses_keys_h="$CURSES_KEYS_H" + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_path_curses_keys_h" >&5 +printf "%s\n" "$zsh_cv_path_curses_keys_h" >&6; } +CURSES_KEYS_H="$zsh_cv_path_curses_keys_h" + + for ac_header in ncursesw/term.h +do : + ac_fn_c_check_header_compile "$LINENO" "ncursesw/term.h" "ac_cv_header_ncursesw_term_h" "#include <ncursesw/ncurses.h> +" +if test "x$ac_cv_header_ncursesw_term_h" = xyes +then : + printf "%s\n" "#define HAVE_NCURSESW_TERM_H 1" >>confdefs.h + true +else $as_nop + true +fi + +done + for ac_header in ncurses/term.h +do : + ac_fn_c_check_header_compile "$LINENO" "ncurses/term.h" "ac_cv_header_ncurses_term_h" "#include <ncurses/ncurses.h> +" +if test "x$ac_cv_header_ncurses_term_h" = xyes +then : + printf "%s\n" "#define HAVE_NCURSES_TERM_H 1" >>confdefs.h + true +else $as_nop + true +fi + +done + for ac_header in term.h +do : + ac_fn_c_check_header_compile "$LINENO" "term.h" "ac_cv_header_term_h" "#include <curses.h> +" +if test "x$ac_cv_header_term_h" = xyes +then : + printf "%s\n" "#define HAVE_TERM_H 1" >>confdefs.h + true +else $as_nop + true +fi + +done + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking where term.h is located" >&5 +printf %s "checking where term.h is located... " >&6; } +if test ${zsh_cv_path_term_header+y} +then : + printf %s "(cached) " >&6 +else $as_nop + case x$zsh_cv_path_curses_header in + xncursesw/*) + if test x$ac_cv_header_ncursesw_term_h = xyes; then + zsh_cv_path_term_header=ncursesw/term.h + fi + ;; + xncurses/*) + if test x$ac_cv_header_ncurses_term_h = xyes; then + zsh_cv_path_term_header=ncurses/term.h + fi + ;; +esac +if test x$zsh_cv_path_term_header = x; then + if test x$ac_cv_header_term_h = xyes; then + zsh_cv_path_term_header=term.h + else + zsh_cv_path_term_header=none + fi +fi +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_path_term_header" >&5 +printf "%s\n" "$zsh_cv_path_term_header" >&6; } + + + + + + + + + + +if test x$zsh_cv_path_term_header != xnone; then + printf "%s\n" "#define ZSH_HAVE_TERM_H 1" >>confdefs.h + + ZSH_TERM_H=$zsh_cv_path_term_header + if test x$zsh_cv_path_curses_header != xnone; then + term_includes="#include <$zsh_cv_path_curses_header> +#include <$zsh_cv_path_term_header>" + else + term_includes="#include <$zsh_cv_path_term_header>" + fi + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if boolcodes is available" >&5 +printf %s "checking if boolcodes is available... " >&6; } + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$term_includes +int +main (void) +{ +char **test = boolcodes; puts(*test); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + printf "%s\n" "#define HAVE_BOOLCODES 1" >>confdefs.h + boolcodes=yes +else $as_nop + boolcodes=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $boolcodes" >&5 +printf "%s\n" "$boolcodes" >&6; } + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if numcodes is available" >&5 +printf %s "checking if numcodes is available... " >&6; } + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$term_includes +int +main (void) +{ +char **test = numcodes; puts(*test); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + printf "%s\n" "#define HAVE_NUMCODES 1" >>confdefs.h + numcodes=yes +else $as_nop + numcodes=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $numcodes" >&5 +printf "%s\n" "$numcodes" >&6; } + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if strcodes is available" >&5 +printf %s "checking if strcodes is available... " >&6; } + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$term_includes +int +main (void) +{ +char **test = strcodes; puts(*test); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + printf "%s\n" "#define HAVE_STRCODES 1" >>confdefs.h + strcodes=yes +else $as_nop + strcodes=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $strcodes" >&5 +printf "%s\n" "$strcodes" >&6; } + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if boolnames is available" >&5 +printf %s "checking if boolnames is available... " >&6; } + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$term_includes +int +main (void) +{ +char **test = boolnames; puts(*test); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + printf "%s\n" "#define HAVE_BOOLNAMES 1" >>confdefs.h + boolnames=yes +else $as_nop + boolnames=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $boolnames" >&5 +printf "%s\n" "$boolnames" >&6; } + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if numnames is available" >&5 +printf %s "checking if numnames is available... " >&6; } + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$term_includes +int +main (void) +{ +char **test = numnames; puts(*test); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + printf "%s\n" "#define HAVE_NUMNAMES 1" >>confdefs.h + numnames=yes +else $as_nop + numnames=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $numnames" >&5 +printf "%s\n" "$numnames" >&6; } + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if strnames is available" >&5 +printf %s "checking if strnames is available... " >&6; } + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$term_includes +int +main (void) +{ +char **test = strnames; puts(*test); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + printf "%s\n" "#define HAVE_STRNAMES 1" >>confdefs.h + strnames=yes +else $as_nop + strnames=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $strnames" >&5 +printf "%s\n" "$strnames" >&6; } + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if tgoto prototype is missing" >&5 +printf %s "checking if tgoto prototype is missing... " >&6; } + tgoto_includes="$term_includes +/* guaranteed to clash with any valid tgoto prototype */ +extern void tgoto(int **stuff, float **more_stuff);" + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$tgoto_includes +int +main (void) +{ +int *stuff; float *more_stuff; tgoto(&stuff, &more_stuff); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + printf "%s\n" "#define TGOTO_PROTO_MISSING 1" >>confdefs.h + tgotoprotomissing=yes +else $as_nop + tgotoprotomissing=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $tgotoprotomissing" >&5 +printf "%s\n" "$tgotoprotomissing" >&6; } +else + ZSH_TERM_H= +fi + + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking where the RLIMIT macros are located" >&5 +printf %s "checking where the RLIMIT macros are located... " >&6; } +if test ${zsh_cv_path_rlimit_h+y} +then : + printf %s "(cached) " >&6 +else $as_nop + echo "#include <sys/resource.h>" >restmp.c +resourcefile_list="`$CPP $CPPFLAGS restmp.c | +sed -n -e 's/^#line[ ].*\"\(.*\)\"/\1/p' \ + -e 's/^#[ ].*\"\(.*\)\"/\1/p' | +sed 's/\\\\\\\\/\//g' | +$AWK '{ if ($1 ~ /resource/) files[$1] = $1 } + END { for (var in files) print var }'`" +rm -f restmp.c +if test -z "$resourcefile_list"; then + resourcefile_list="/usr/include/bsd/sys/resource.h +/usr/include/asm/resource.h +/usr/include/linux/resource.h +/usr/include/sys/resource.h +/usr/include/bits/resource.h +/usr/include/resourcebits.h" +fi +for RESOURCE_H in $resourcefile_list /dev/null; +do + test -f $RESOURCE_H && \ + grep '#[ ]*define[ ][ ]*RLIMIT_[A-Z]*[ ]*[0-9A-Z][0-9]*' $RESOURCE_H > /dev/null && \ + break +done +zsh_cv_path_rlimit_h=$RESOURCE_H +if test x$RESOURCE_H = x"/dev/null" && test x$ac_cv_func_getrlimit = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: RLIMIT MACROS NOT FOUND: please report to developers" >&5 +printf "%s\n" "$as_me: WARNING: RLIMIT MACROS NOT FOUND: please report to developers" >&2;} +fi +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_path_rlimit_h" >&5 +printf "%s\n" "$zsh_cv_path_rlimit_h" >&6; } +RLIMITS_INC_H=$zsh_cv_path_rlimit_h +if test "$RLIMITS_INC_H" = "/dev/null"; then + RLIMITS_INC_H='' +fi + + + + + +DEFAULT_RLIM_T=long +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if rlim_t is longer than a long" >&5 +printf %s "checking if rlim_t is longer than a long... " >&6; } +if test ${zsh_cv_rlim_t_is_longer+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_rlim_t_is_longer=yes +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +#include <stdlib.h> +main(){struct rlimit r;exit(sizeof(r.rlim_cur) <= sizeof(long));} +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_rlim_t_is_longer=yes +else $as_nop + zsh_cv_rlim_t_is_longer=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_rlim_t_is_longer" >&5 +printf "%s\n" "$zsh_cv_rlim_t_is_longer" >&6; } +if test x$zsh_cv_rlim_t_is_longer = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if rlim_t is a quad" >&5 +printf %s "checking if rlim_t is a quad... " >&6; } +if test ${zsh_cv_rlim_t_is_quad_t+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_rlim_t_is_quad_t=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <stdio.h> +#include <sys/resource.h> +#include <stdlib.h> +main() { + struct rlimit r; + char buf[20]; + r.rlim_cur = 0; + sprintf(buf, "%qd", r.rlim_cur); + exit(strcmp(buf, "0")); +} +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_rlim_t_is_quad_t=yes +else $as_nop + zsh_cv_rlim_t_is_quad_t=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_rlim_t_is_quad_t" >&5 +printf "%s\n" "$zsh_cv_rlim_t_is_quad_t" >&6; } + if test x$zsh_cv_rlim_t_is_quad_t = xyes; then + printf "%s\n" "#define RLIM_T_IS_QUAD_T 1" >>confdefs.h + + DEFAULT_RLIM_T=quad_t + else + printf "%s\n" "#define RLIM_T_IS_LONG_LONG 1" >>confdefs.h + + DEFAULT_RLIM_T='long long' + fi +else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if the rlim_t is unsigned" >&5 +printf %s "checking if the rlim_t is unsigned... " >&6; } +if test ${zsh_cv_type_rlim_t_is_unsigned+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_type_rlim_t_is_unsigned=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +#include <stdlib.h> + main(){struct rlimit r;r.rlim_cur=-1;exit(r.rlim_cur<0);} +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_type_rlim_t_is_unsigned=yes +else $as_nop + zsh_cv_type_rlim_t_is_unsigned=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_type_rlim_t_is_unsigned" >&5 +printf "%s\n" "$zsh_cv_type_rlim_t_is_unsigned" >&6; } + if test x$zsh_cv_type_rlim_t_is_unsigned = xyes; then + printf "%s\n" "#define RLIM_T_IS_UNSIGNED 1" >>confdefs.h + + DEFAULT_RLIM_T="unsigned $DEFAULT_RLIM_T" + fi +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for rlim_t" >&5 +printf %s "checking for rlim_t... " >&6; } +if test ${zsh_cv_type_rlim_t+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +rlim_t l; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_type_rlim_t=yes +else $as_nop + zsh_cv_type_rlim_t=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_type_rlim_t" >&5 +printf "%s\n" "$zsh_cv_type_rlim_t" >&6; } +if test x$zsh_cv_type_rlim_t = xno; then + printf "%s\n" "#define rlim_t $DEFAULT_RLIM_T" >>confdefs.h + +fi + + + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_AIO_MEM" >&5 +printf %s "checking for limit RLIMIT_AIO_MEM... " >&6; } +if test ${zsh_cv_have_RLIMIT_AIO_MEM+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_AIO_MEM + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_AIO_MEM=yes +else $as_nop + zsh_cv_have_RLIMIT_AIO_MEM=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_AIO_MEM" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_AIO_MEM" >&6; } + +if test $zsh_cv_have_RLIMIT_AIO_MEM = yes; then + printf "%s\n" "#define HAVE_RLIMIT_AIO_MEM 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_AIO_OPS" >&5 +printf %s "checking for limit RLIMIT_AIO_OPS... " >&6; } +if test ${zsh_cv_have_RLIMIT_AIO_OPS+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_AIO_OPS + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_AIO_OPS=yes +else $as_nop + zsh_cv_have_RLIMIT_AIO_OPS=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_AIO_OPS" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_AIO_OPS" >&6; } + +if test $zsh_cv_have_RLIMIT_AIO_OPS = yes; then + printf "%s\n" "#define HAVE_RLIMIT_AIO_OPS 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_AS" >&5 +printf %s "checking for limit RLIMIT_AS... " >&6; } +if test ${zsh_cv_have_RLIMIT_AS+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_AS + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_AS=yes +else $as_nop + zsh_cv_have_RLIMIT_AS=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_AS" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_AS" >&6; } + +if test $zsh_cv_have_RLIMIT_AS = yes; then + printf "%s\n" "#define HAVE_RLIMIT_AS 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_LOCKS" >&5 +printf %s "checking for limit RLIMIT_LOCKS... " >&6; } +if test ${zsh_cv_have_RLIMIT_LOCKS+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_LOCKS + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_LOCKS=yes +else $as_nop + zsh_cv_have_RLIMIT_LOCKS=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_LOCKS" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_LOCKS" >&6; } + +if test $zsh_cv_have_RLIMIT_LOCKS = yes; then + printf "%s\n" "#define HAVE_RLIMIT_LOCKS 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_MEMLOCK" >&5 +printf %s "checking for limit RLIMIT_MEMLOCK... " >&6; } +if test ${zsh_cv_have_RLIMIT_MEMLOCK+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_MEMLOCK + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_MEMLOCK=yes +else $as_nop + zsh_cv_have_RLIMIT_MEMLOCK=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_MEMLOCK" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_MEMLOCK" >&6; } + +if test $zsh_cv_have_RLIMIT_MEMLOCK = yes; then + printf "%s\n" "#define HAVE_RLIMIT_MEMLOCK 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_NPROC" >&5 +printf %s "checking for limit RLIMIT_NPROC... " >&6; } +if test ${zsh_cv_have_RLIMIT_NPROC+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_NPROC + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_NPROC=yes +else $as_nop + zsh_cv_have_RLIMIT_NPROC=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_NPROC" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_NPROC" >&6; } + +if test $zsh_cv_have_RLIMIT_NPROC = yes; then + printf "%s\n" "#define HAVE_RLIMIT_NPROC 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_NTHR" >&5 +printf %s "checking for limit RLIMIT_NTHR... " >&6; } +if test ${zsh_cv_have_RLIMIT_NTHR+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_NTHR + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_NTHR=yes +else $as_nop + zsh_cv_have_RLIMIT_NTHR=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_NTHR" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_NTHR" >&6; } + +if test $zsh_cv_have_RLIMIT_NTHR = yes; then + printf "%s\n" "#define HAVE_RLIMIT_NTHR 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_NOFILE" >&5 +printf %s "checking for limit RLIMIT_NOFILE... " >&6; } +if test ${zsh_cv_have_RLIMIT_NOFILE+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_NOFILE + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_NOFILE=yes +else $as_nop + zsh_cv_have_RLIMIT_NOFILE=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_NOFILE" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_NOFILE" >&6; } + +if test $zsh_cv_have_RLIMIT_NOFILE = yes; then + printf "%s\n" "#define HAVE_RLIMIT_NOFILE 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_PTHREAD" >&5 +printf %s "checking for limit RLIMIT_PTHREAD... " >&6; } +if test ${zsh_cv_have_RLIMIT_PTHREAD+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_PTHREAD + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_PTHREAD=yes +else $as_nop + zsh_cv_have_RLIMIT_PTHREAD=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_PTHREAD" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_PTHREAD" >&6; } + +if test $zsh_cv_have_RLIMIT_PTHREAD = yes; then + printf "%s\n" "#define HAVE_RLIMIT_PTHREAD 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_RSS" >&5 +printf %s "checking for limit RLIMIT_RSS... " >&6; } +if test ${zsh_cv_have_RLIMIT_RSS+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_RSS + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_RSS=yes +else $as_nop + zsh_cv_have_RLIMIT_RSS=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_RSS" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_RSS" >&6; } + +if test $zsh_cv_have_RLIMIT_RSS = yes; then + printf "%s\n" "#define HAVE_RLIMIT_RSS 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_SBSIZE" >&5 +printf %s "checking for limit RLIMIT_SBSIZE... " >&6; } +if test ${zsh_cv_have_RLIMIT_SBSIZE+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_SBSIZE + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_SBSIZE=yes +else $as_nop + zsh_cv_have_RLIMIT_SBSIZE=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_SBSIZE" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_SBSIZE" >&6; } + +if test $zsh_cv_have_RLIMIT_SBSIZE = yes; then + printf "%s\n" "#define HAVE_RLIMIT_SBSIZE 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_TCACHE" >&5 +printf %s "checking for limit RLIMIT_TCACHE... " >&6; } +if test ${zsh_cv_have_RLIMIT_TCACHE+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_TCACHE + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_TCACHE=yes +else $as_nop + zsh_cv_have_RLIMIT_TCACHE=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_TCACHE" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_TCACHE" >&6; } + +if test $zsh_cv_have_RLIMIT_TCACHE = yes; then + printf "%s\n" "#define HAVE_RLIMIT_TCACHE 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_VMEM" >&5 +printf %s "checking for limit RLIMIT_VMEM... " >&6; } +if test ${zsh_cv_have_RLIMIT_VMEM+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_VMEM + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_VMEM=yes +else $as_nop + zsh_cv_have_RLIMIT_VMEM=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_VMEM" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_VMEM" >&6; } + +if test $zsh_cv_have_RLIMIT_VMEM = yes; then + printf "%s\n" "#define HAVE_RLIMIT_VMEM 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_SIGPENDING" >&5 +printf %s "checking for limit RLIMIT_SIGPENDING... " >&6; } +if test ${zsh_cv_have_RLIMIT_SIGPENDING+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_SIGPENDING + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_SIGPENDING=yes +else $as_nop + zsh_cv_have_RLIMIT_SIGPENDING=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_SIGPENDING" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_SIGPENDING" >&6; } + +if test $zsh_cv_have_RLIMIT_SIGPENDING = yes; then + printf "%s\n" "#define HAVE_RLIMIT_SIGPENDING 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_MSGQUEUE" >&5 +printf %s "checking for limit RLIMIT_MSGQUEUE... " >&6; } +if test ${zsh_cv_have_RLIMIT_MSGQUEUE+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_MSGQUEUE + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_MSGQUEUE=yes +else $as_nop + zsh_cv_have_RLIMIT_MSGQUEUE=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_MSGQUEUE" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_MSGQUEUE" >&6; } + +if test $zsh_cv_have_RLIMIT_MSGQUEUE = yes; then + printf "%s\n" "#define HAVE_RLIMIT_MSGQUEUE 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_NICE" >&5 +printf %s "checking for limit RLIMIT_NICE... " >&6; } +if test ${zsh_cv_have_RLIMIT_NICE+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_NICE + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_NICE=yes +else $as_nop + zsh_cv_have_RLIMIT_NICE=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_NICE" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_NICE" >&6; } + +if test $zsh_cv_have_RLIMIT_NICE = yes; then + printf "%s\n" "#define HAVE_RLIMIT_NICE 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_RTPRIO" >&5 +printf %s "checking for limit RLIMIT_RTPRIO... " >&6; } +if test ${zsh_cv_have_RLIMIT_RTPRIO+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_RTPRIO + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_RTPRIO=yes +else $as_nop + zsh_cv_have_RLIMIT_RTPRIO=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_RTPRIO" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_RTPRIO" >&6; } + +if test $zsh_cv_have_RLIMIT_RTPRIO = yes; then + printf "%s\n" "#define HAVE_RLIMIT_RTPRIO 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_RTTIME" >&5 +printf %s "checking for limit RLIMIT_RTTIME... " >&6; } +if test ${zsh_cv_have_RLIMIT_RTTIME+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_RTTIME + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_RTTIME=yes +else $as_nop + zsh_cv_have_RLIMIT_RTTIME=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_RTTIME" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_RTTIME" >&6; } + +if test $zsh_cv_have_RLIMIT_RTTIME = yes; then + printf "%s\n" "#define HAVE_RLIMIT_RTTIME 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_POSIXLOCKS" >&5 +printf %s "checking for limit RLIMIT_POSIXLOCKS... " >&6; } +if test ${zsh_cv_have_RLIMIT_POSIXLOCKS+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_POSIXLOCKS + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_POSIXLOCKS=yes +else $as_nop + zsh_cv_have_RLIMIT_POSIXLOCKS=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_POSIXLOCKS" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_POSIXLOCKS" >&6; } + +if test $zsh_cv_have_RLIMIT_POSIXLOCKS = yes; then + printf "%s\n" "#define HAVE_RLIMIT_POSIXLOCKS 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_NPTS" >&5 +printf %s "checking for limit RLIMIT_NPTS... " >&6; } +if test ${zsh_cv_have_RLIMIT_NPTS+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_NPTS + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_NPTS=yes +else $as_nop + zsh_cv_have_RLIMIT_NPTS=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_NPTS" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_NPTS" >&6; } + +if test $zsh_cv_have_RLIMIT_NPTS = yes; then + printf "%s\n" "#define HAVE_RLIMIT_NPTS 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_SWAP" >&5 +printf %s "checking for limit RLIMIT_SWAP... " >&6; } +if test ${zsh_cv_have_RLIMIT_SWAP+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_SWAP + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_SWAP=yes +else $as_nop + zsh_cv_have_RLIMIT_SWAP=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_SWAP" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_SWAP" >&6; } + +if test $zsh_cv_have_RLIMIT_SWAP = yes; then + printf "%s\n" "#define HAVE_RLIMIT_SWAP 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_KQUEUES" >&5 +printf %s "checking for limit RLIMIT_KQUEUES... " >&6; } +if test ${zsh_cv_have_RLIMIT_KQUEUES+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_KQUEUES + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_KQUEUES=yes +else $as_nop + zsh_cv_have_RLIMIT_KQUEUES=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_KQUEUES" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_KQUEUES" >&6; } + +if test $zsh_cv_have_RLIMIT_KQUEUES = yes; then + printf "%s\n" "#define HAVE_RLIMIT_KQUEUES 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for limit RLIMIT_UMTXP" >&5 +printf %s "checking for limit RLIMIT_UMTXP... " >&6; } +if test ${zsh_cv_have_RLIMIT_UMTXP+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +RLIMIT_UMTXP + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_have_RLIMIT_UMTXP=yes +else $as_nop + zsh_cv_have_RLIMIT_UMTXP=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_have_RLIMIT_UMTXP" >&5 +printf "%s\n" "$zsh_cv_have_RLIMIT_UMTXP" >&6; } + +if test $zsh_cv_have_RLIMIT_UMTXP = yes; then + printf "%s\n" "#define HAVE_RLIMIT_UMTXP 1" >>confdefs.h + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if RLIMIT_VMEM and RLIMIT_RSS are the same" >&5 +printf %s "checking if RLIMIT_VMEM and RLIMIT_RSS are the same... " >&6; } +if test ${zsh_cv_rlimit_vmem_is_rss+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +static char x[(RLIMIT_VMEM == RLIMIT_RSS)? 1 : -1] + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_rlimit_vmem_is_rss=yes +else $as_nop + zsh_cv_rlimit_vmem_is_rss=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_rlimit_vmem_is_rss" >&5 +printf "%s\n" "$zsh_cv_rlimit_vmem_is_rss" >&6; } +if test x$zsh_cv_rlimit_vmem_is_rss = xyes; then + printf "%s\n" "#define RLIMIT_VMEM_IS_RSS 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if RLIMIT_VMEM and RLIMIT_AS are the same" >&5 +printf %s "checking if RLIMIT_VMEM and RLIMIT_AS are the same... " >&6; } +if test ${zsh_cv_rlimit_vmem_is_as+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +static char x[(RLIMIT_VMEM == RLIMIT_AS)? 1 : -1] + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_rlimit_vmem_is_as=yes +else $as_nop + zsh_cv_rlimit_vmem_is_as=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_rlimit_vmem_is_as" >&5 +printf "%s\n" "$zsh_cv_rlimit_vmem_is_as" >&6; } +if test x$zsh_cv_rlimit_vmem_is_as = xyes; then + printf "%s\n" "#define RLIMIT_VMEM_IS_AS 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if RLIMIT_RSS and RLIMIT_AS are the same" >&5 +printf %s "checking if RLIMIT_RSS and RLIMIT_AS are the same... " >&6; } +if test ${zsh_cv_rlimit_rss_is_as+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +int +main (void) +{ +static char x[(RLIMIT_RSS == RLIMIT_AS)? 1 : -1] + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_rlimit_rss_is_as=yes +else $as_nop + zsh_cv_rlimit_rss_is_as=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_rlimit_rss_is_as" >&5 +printf "%s\n" "$zsh_cv_rlimit_rss_is_as" >&6; } +if test x$zsh_cv_rlimit_rss_is_as = xyes; then + printf "%s\n" "#define RLIMIT_RSS_IS_AS 1" >>confdefs.h + +fi + +if test x$ac_cv_func_getrusage = xyes; then + ac_fn_c_check_member "$LINENO" "struct rusage" "ru_maxrss" "ac_cv_member_struct_rusage_ru_maxrss" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_maxrss" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_MAXRSS 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_ixrss" "ac_cv_member_struct_rusage_ru_ixrss" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_ixrss" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_IXRSS 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_idrss" "ac_cv_member_struct_rusage_ru_idrss" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_idrss" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_IDRSS 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_isrss" "ac_cv_member_struct_rusage_ru_isrss" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_isrss" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_ISRSS 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_minflt" "ac_cv_member_struct_rusage_ru_minflt" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_minflt" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_MINFLT 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_majflt" "ac_cv_member_struct_rusage_ru_majflt" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_majflt" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_MAJFLT 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_nswap" "ac_cv_member_struct_rusage_ru_nswap" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_nswap" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_NSWAP 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_inblock" "ac_cv_member_struct_rusage_ru_inblock" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_inblock" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_INBLOCK 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_oublock" "ac_cv_member_struct_rusage_ru_oublock" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_oublock" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_OUBLOCK 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_msgsnd" "ac_cv_member_struct_rusage_ru_msgsnd" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_msgsnd" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_MSGSND 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_msgrcv" "ac_cv_member_struct_rusage_ru_msgrcv" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_msgrcv" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_MSGRCV 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_nsignals" "ac_cv_member_struct_rusage_ru_nsignals" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_nsignals" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_NSIGNALS 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_nvcsw" "ac_cv_member_struct_rusage_ru_nvcsw" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_nvcsw" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_NVCSW 1" >>confdefs.h + + +fi +ac_fn_c_check_member "$LINENO" "struct rusage" "ru_nivcsw" "ac_cv_member_struct_rusage_ru_nivcsw" "#include <sys/types.h> +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#include <sys/resource.h> +" +if test "x$ac_cv_member_struct_rusage_ru_nivcsw" = xyes +then : + +printf "%s\n" "#define HAVE_STRUCT_RUSAGE_RU_NIVCSW 1" >>confdefs.h + + +fi + +fi + + +if test ${zsh_cv_cs_path+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if getconf _CS_PATH >/dev/null 2>&1; then + zsh_cv_cs_path=`getconf _CS_PATH` +elif getconf CS_PATH >/dev/null 2>&1; then + zsh_cv_cs_path=`getconf CS_PATH` +elif getconf PATH >/dev/null 2>&1; then + zsh_cv_cs_path=`getconf PATH` +else + zsh_cv_cs_path="/bin:/usr/bin" +fi +fi + + +printf "%s\n" "#define DEFAULT_PATH \"$zsh_cv_cs_path\"" >>confdefs.h + + + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for /dev/fd filesystem" >&5 +printf %s "checking for /dev/fd filesystem... " >&6; } +if test ${zsh_cv_sys_path_dev_fd+y} +then : + printf %s "(cached) " >&6 +else $as_nop + for zsh_cv_sys_path_dev_fd in /proc/self/fd /dev/fd no; do + test x`echo ok|(exec 3<&0; cat $zsh_cv_sys_path_dev_fd/3 2>/dev/null;)` = xok && break + done +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_path_dev_fd" >&5 +printf "%s\n" "$zsh_cv_sys_path_dev_fd" >&6; } +if test x$zsh_cv_sys_path_dev_fd != xno; then + printf "%s\n" "#define PATH_DEV_FD \"$zsh_cv_sys_path_dev_fd\"" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for RFS superroot directory" >&5 +printf %s "checking for RFS superroot directory... " >&6; } +if test ${zsh_cv_sys_superroot+y} +then : + printf %s "(cached) " >&6 +else $as_nop + test -d /../.LOCALROOT && zsh_cv_sys_superroot=yes || zsh_cv_sys_superroot=no +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_superroot" >&5 +printf "%s\n" "$zsh_cv_sys_superroot" >&6; } + +if test x$zsh_cv_sys_superroot = xyes; then + printf "%s\n" "#define HAVE_SUPERROOT 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether we should use the native getcwd" >&5 +printf %s "checking whether we should use the native getcwd... " >&6; } +if test ${zsh_cv_use_getcwd+y} +then : + printf %s "(cached) " >&6 +else $as_nop + case "${host_cpu}-${host_vendor}-${host_os}" in + *QNX*) zsh_cv_use_getcwd=yes ;; + *) zsh_cv_use_getcwd=no ;; + esac +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_use_getcwd" >&5 +printf "%s\n" "$zsh_cv_use_getcwd" >&6; } + +if test x$zsh_cv_use_getcwd = xyes; then + printf "%s\n" "#define USE_GETCWD 1" >>confdefs.h + +fi + + +if test x$ac_cv_func_getcwd = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether getcwd calls malloc to allocate memory" >&5 +printf %s "checking whether getcwd calls malloc to allocate memory... " >&6; } +if test ${zsh_cv_getcwd_malloc+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_getcwd_malloc=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <unistd.h> +#include <string.h> +int main() { + char buf[1024], *ptr1, *ptr2; + ptr1 = getcwd(buf, 1024); + ptr2 = getcwd(NULL, 0); + if (ptr1 && ptr2 && !strcmp(ptr1, ptr2)) { + return 0; + } + return 1; +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_getcwd_malloc=yes +else $as_nop + zsh_cv_getcwd_malloc=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_getcwd_malloc" >&5 +printf "%s\n" "$zsh_cv_getcwd_malloc" >&6; } + if test x$zsh_cv_getcwd_malloc = xyes; then + printf "%s\n" "#define GETCWD_CALLS_MALLOC 1" >>confdefs.h + + fi +fi + + +ac_fn_c_check_func "$LINENO" "setproctitle" "ac_cv_func_setproctitle" +if test "x$ac_cv_func_setproctitle" = xyes +then : + printf "%s\n" "#define HAVE_SETPROCTITLE 1" >>confdefs.h + +else $as_nop + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing setproctitle" >&5 +printf %s "checking for library containing setproctitle... " >&6; } +if test ${ac_cv_search_setproctitle+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char setproctitle (); +int +main (void) +{ +return setproctitle (); + ; + return 0; +} +_ACEOF +for ac_lib in '' util +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_setproctitle=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_setproctitle+y} +then : + break +fi +done +if test ${ac_cv_search_setproctitle+y} +then : + +else $as_nop + ac_cv_search_setproctitle=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_setproctitle" >&5 +printf "%s\n" "$ac_cv_search_setproctitle" >&6; } +ac_res=$ac_cv_search_setproctitle +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + printf "%s\n" "#define HAVE_SETPROCTITLE 1" >>confdefs.h + +fi + +fi + + + +ac_fn_c_check_func "$LINENO" "prctl" "ac_cv_func_prctl" +if test "x$ac_cv_func_prctl" = xyes +then : + printf "%s\n" "#define HAVE_PRCTL 1" >>confdefs.h + +else $as_nop + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for library containing prctl" >&5 +printf %s "checking for library containing prctl... " >&6; } +if test ${ac_cv_search_prctl+y} +then : + printf %s "(cached) " >&6 +else $as_nop + ac_func_search_save_LIBS=$LIBS +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +/* Override any GCC internal prototype to avoid an error. + Use char because int might match the return type of a GCC + builtin and then its argument prototype would still apply. */ +char prctl (); +int +main (void) +{ +return prctl (); + ; + return 0; +} +_ACEOF +for ac_lib in '' c +do + if test -z "$ac_lib"; then + ac_res="none required" + else + ac_res=-l$ac_lib + LIBS="-l$ac_lib $ac_func_search_save_LIBS" + fi + if ac_fn_c_try_link "$LINENO" +then : + ac_cv_search_prctl=$ac_res +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext + if test ${ac_cv_search_prctl+y} +then : + break +fi +done +if test ${ac_cv_search_prctl+y} +then : + +else $as_nop + ac_cv_search_prctl=no +fi +rm conftest.$ac_ext +LIBS=$ac_func_search_save_LIBS +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_search_prctl" >&5 +printf "%s\n" "$ac_cv_search_prctl" >&6; } +ac_res=$ac_cv_search_prctl +if test "$ac_res" != no +then : + test "$ac_res" = "none required" || LIBS="$ac_res $LIBS" + printf "%s\n" "#define HAVE_PRCTL 1" >>confdefs.h + +fi + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for utmp file" >&5 +printf %s "checking for utmp file... " >&6; } +if test ${zsh_cv_path_utmp+y} +then : + printf %s "(cached) " >&6 +else $as_nop + for dir in /etc /usr/etc /var/adm /usr/adm /var/run /var/log ./conftest; do + zsh_cv_path_utmp=${dir}/utmp + test -f $zsh_cv_path_utmp && break + zsh_cv_path_utmp=no +done + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_path_utmp" >&5 +printf "%s\n" "$zsh_cv_path_utmp" >&6; } + +if test $zsh_cv_path_utmp != no; then + printf "%s\n" "#define PATH_UTMP_FILE \"$zsh_cv_path_utmp\"" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for wtmp file" >&5 +printf %s "checking for wtmp file... " >&6; } +if test ${zsh_cv_path_wtmp+y} +then : + printf %s "(cached) " >&6 +else $as_nop + for dir in /etc /usr/etc /var/adm /usr/adm /var/run /var/log ./conftest; do + zsh_cv_path_wtmp=${dir}/wtmp + test -f $zsh_cv_path_wtmp && break + zsh_cv_path_wtmp=no +done + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_path_wtmp" >&5 +printf "%s\n" "$zsh_cv_path_wtmp" >&6; } + +if test $zsh_cv_path_wtmp != no; then + printf "%s\n" "#define PATH_WTMP_FILE \"$zsh_cv_path_wtmp\"" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for utmpx file" >&5 +printf %s "checking for utmpx file... " >&6; } +if test ${zsh_cv_path_utmpx+y} +then : + printf %s "(cached) " >&6 +else $as_nop + for dir in /etc /usr/etc /var/adm /usr/adm /var/run /var/log ./conftest; do + zsh_cv_path_utmpx=${dir}/utmpx + test -f $zsh_cv_path_utmpx && break + zsh_cv_path_utmpx=${dir}/utx.active + test -f $zsh_cv_path_utmpx && break + zsh_cv_path_utmpx=no +done + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_path_utmpx" >&5 +printf "%s\n" "$zsh_cv_path_utmpx" >&6; } + +if test $zsh_cv_path_utmpx != no; then + printf "%s\n" "#define PATH_UTMPX_FILE \"$zsh_cv_path_utmpx\"" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for wtmpx file" >&5 +printf %s "checking for wtmpx file... " >&6; } +if test ${zsh_cv_path_wtmpx+y} +then : + printf %s "(cached) " >&6 +else $as_nop + for dir in /etc /usr/etc /var/adm /usr/adm /var/run /var/log ./conftest; do + zsh_cv_path_wtmpx=${dir}/wtmpx + test -f $zsh_cv_path_wtmpx && break + zsh_cv_path_wtmpx=no +done + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_path_wtmpx" >&5 +printf "%s\n" "$zsh_cv_path_wtmpx" >&6; } + +if test $zsh_cv_path_wtmpx != no; then + printf "%s\n" "#define PATH_WTMPX_FILE \"$zsh_cv_path_wtmpx\"" >>confdefs.h + +fi + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for brk() prototype in <unistd.h>" >&5 +printf %s "checking for brk() prototype in <unistd.h>... " >&6; } +if test ${zsh_cv_header_unistd_h_brk_proto+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <unistd.h> +double brk(); +int +main (void) +{ +int i; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_header_unistd_h_brk_proto=no +else $as_nop + zsh_cv_header_unistd_h_brk_proto=yes +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_header_unistd_h_brk_proto" >&5 +printf "%s\n" "$zsh_cv_header_unistd_h_brk_proto" >&6; } + +if test x$zsh_cv_header_unistd_h_brk_proto = xyes; then + printf "%s\n" "#define HAVE_BRK_PROTO 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for sbrk() prototype in <unistd.h>" >&5 +printf %s "checking for sbrk() prototype in <unistd.h>... " >&6; } +if test ${zsh_cv_header_unistd_h_sbrk_proto+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <unistd.h> +double sbrk(); +int +main (void) +{ +int i; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_header_unistd_h_sbrk_proto=no +else $as_nop + zsh_cv_header_unistd_h_sbrk_proto=yes +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_header_unistd_h_sbrk_proto" >&5 +printf "%s\n" "$zsh_cv_header_unistd_h_sbrk_proto" >&6; } + +if test x$zsh_cv_header_unistd_h_sbrk_proto = xyes; then + printf "%s\n" "#define HAVE_SBRK_PROTO 1" >>confdefs.h + +fi + + +if test "$ac_cv_prog_cc_stdc" != no; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for mknod prototype in <sys/stat.h>" >&5 +printf %s "checking for mknod prototype in <sys/stat.h>... " >&6; } +if test ${zsh_cv_header_sys_stat_h_mknod_proto+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/stat.h> + int mknod(double x); +int +main (void) +{ +int i; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_header_sys_stat_h_mknod_proto=no +else $as_nop + zsh_cv_header_sys_stat_h_mknod_proto=yes +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_header_sys_stat_h_mknod_proto" >&5 +printf "%s\n" "$zsh_cv_header_sys_stat_h_mknod_proto" >&6; } + if test x$zsh_cv_header_sys_stat_h_mknod_proto = xyes; then + printf "%s\n" "#define HAVE_MKNOD_PROTO 1" >>confdefs.h + + fi +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for ioctl prototype in <unistd.h> or <termios.h>" >&5 +printf %s "checking for ioctl prototype in <unistd.h> or <termios.h>... " >&6; } +if test ${zsh_cv_header_unistd_h_termios_h_ioctl_proto+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#ifdef HAVE_UNISTD_H +# include <unistd.h> +#endif +#ifdef HAVE_TERMIOS_H +# include <termios.h> +#endif +double ioctl(); +int +main (void) +{ +int i; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_header_unistd_h_termios_h_ioctl_proto=no +else $as_nop + zsh_cv_header_unistd_h_termios_h_ioctl_proto=yes +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_header_unistd_h_termios_h_ioctl_proto" >&5 +printf "%s\n" "$zsh_cv_header_unistd_h_termios_h_ioctl_proto" >&6; } + +if test x$zsh_cv_header_unistd_h_termios_h_ioctl_proto = xno; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for ioctl prototype in <sys/ioctl.h>" >&5 +printf %s "checking for ioctl prototype in <sys/ioctl.h>... " >&6; } +if test ${zsh_cv_header_sys_ioctl_h_ioctl_proto+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/ioctl.h> + double ioctl(); +int +main (void) +{ +int i; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_header_sys_ioctl_h_ioctl_proto=no +else $as_nop + zsh_cv_header_sys_ioctl_h_ioctl_proto=yes +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_header_sys_ioctl_h_ioctl_proto" >&5 +printf "%s\n" "$zsh_cv_header_sys_ioctl_h_ioctl_proto" >&6; } +else + zsh_cv_header_sys_ioctl_h_ioctl_proto=no +fi + + +if test x$zsh_cv_header_unistd_h_termios_h_ioctl_proto = xyes || \ + test x$zsh_cv_header_sys_ioctl_h_ioctl_proto = xyes; then + printf "%s\n" "#define HAVE_IOCTL_PROTO 1" >>confdefs.h + +fi + +if test x$zsh_cv_header_sys_ioctl_h_ioctl_proto = xyes; then + printf "%s\n" "#define IOCTL_IN_SYS_IOCTL 1" >>confdefs.h + +fi + + +if test x$ac_cv_header_sys_select_h != xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for select() in <sys/socket.h>" >&5 +printf %s "checking for select() in <sys/socket.h>... " >&6; } +if test ${zsh_cv_header_socket_h_select_proto+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/socket.h> +int +main (void) +{ +fd_set fd; + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_header_socket_h_select_proto=yes +else $as_nop + zsh_cv_header_socket_h_select_proto=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_header_socket_h_select_proto" >&5 +printf "%s\n" "$zsh_cv_header_socket_h_select_proto" >&6; } + if test x$zsh_cv_header_socket_h_select_proto = xyes; then + printf "%s\n" "#define SELECT_IN_SYS_SOCKET_H 1" >>confdefs.h + + fi +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if named FIFOs work" >&5 +printf %s "checking if named FIFOs work... " >&6; } +if test ${zsh_cv_sys_fifo+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_sys_fifo=yes +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <fcntl.h> +#include <signal.h> +#include <unistd.h> +#include <stdlib.h> +#include <sys/stat.h> +main() +{ + char c; + int fd; + int pid, ret; + unlink("/tmp/fifo$$"); +#ifdef HAVE_MKFIFO + if(mkfifo("/tmp/fifo$$", 0600) < 0) +#else + if(mknod("/tmp/fifo$$", 0010600, 0) < 0) +#endif + exit(1); + pid = fork(); + if(pid < 0) + exit(1); + if(pid) { + fd = open("/tmp/fifo$$", O_RDONLY); + exit(fd < 0 || read(fd, &c, 1) != 1 || c != 'x'); + } + fd = open("/tmp/fifo$$", O_WRONLY); + ret = (fd < 0 || write(fd, "x", 1) < 1); + unlink("/tmp/fifo$$"); + exit(ret); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_fifo=yes +else $as_nop + zsh_cv_sys_fifo=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_fifo" >&5 +printf "%s\n" "$zsh_cv_sys_fifo" >&6; } + +if test x$zsh_cv_sys_fifo = xyes; then + printf "%s\n" "#define HAVE_FIFOS 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if lseek() correctly reports seekability" >&5 +printf %s "checking if lseek() correctly reports seekability... " >&6; } +if test ${zsh_cv_sys_lseek+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_sys_lseek=yes +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <stdio.h> +#include <sys/types.h> +#include <fcntl.h> +#include <unistd.h> +#include <sys/socket.h> +#include <sys/stat.h> +int main() { + int pipefd[2], fd; + off_t ret; + char* tmpfile = "seekfiletest.tmp"; + if ((fd = open(tmpfile, O_CREAT, S_IRUSR)) < 0) { + fprintf(stderr, "creating file failed\n"); + return 1; + } + ret = lseek(fd, 0, SEEK_CUR); + close(fd); + unlink(tmpfile); + if (ret == (off_t)-1) { + fprintf(stderr, "lseek on regular file failed\n"); + return 1; + } + if (pipe(pipefd) < 0) { + fprintf(stderr, "creating pipe failed\n"); + return 1; + } + write(pipefd[1], "abcdefgh", 8); + ret = lseek(pipefd[0], 0, SEEK_CUR); + close(pipefd[0]); + close(pipefd[1]); + if (ret != (off_t)-1) { + fprintf(stderr, "lseek on pipe succeeded\n"); + return 1; + } + if ((fd = socket(AF_UNIX, SOCK_STREAM, 0)) < 0) { + fprintf(stderr, "creating UNIX domain socket failed\n"); + return 1; + } + ret = lseek(fd, 0, SEEK_CUR); + close(fd); + if (ret != (off_t)-1) { + fprintf(stderr, "lseek on UNIX domain socket succeeded\n"); + return 1; + } + return 0; +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_lseek=yes +else $as_nop + zsh_cv_sys_lseek=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_lseek" >&5 +printf "%s\n" "$zsh_cv_sys_lseek" >&6; } + +if test x$zsh_cv_sys_lseek = xyes; then + printf "%s\n" "#define USE_LSEEK 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if link() works" >&5 +printf %s "checking if link() works... " >&6; } +if test ${zsh_cv_sys_link+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_sys_link=yes +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <unistd.h> +#include <fcntl.h> +#include <stdlib.h> +main() +{ + int ret; + char *tmpfile, *newfile; + tmpfile="/tmp/zsh.linktest$$"; + newfile="/tmp/zsh.linktest2$$"; + unlink(tmpfile); + unlink(newfile); + if(creat(tmpfile, 0644) < 0) + exit(1); + ret = link(tmpfile, newfile); + unlink(tmpfile); + unlink(newfile); + exit(ret<0); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_link=yes +else $as_nop + zsh_cv_sys_link=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_link" >&5 +printf "%s\n" "$zsh_cv_sys_link" >&6; } + +if test x$zsh_cv_sys_link = xyes; then + printf "%s\n" "#define HAVE_LINK 1" >>confdefs.h + +fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if kill(pid, 0) returns ESRCH correctly" >&5 +printf %s "checking if kill(pid, 0) returns ESRCH correctly... " >&6; } +if test ${zsh_cv_sys_killesrch+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_sys_killesrch=yes +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <unistd.h> +#include <signal.h> +#include <errno.h> +#include <stdlib.h> +main() +{ + int pid = (getpid() + 10000) & 0xffffff; + while (pid && (kill(pid, 0) == 0 || errno != ESRCH)) pid >>= 1; + exit(errno!=ESRCH); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_killesrch=yes +else $as_nop + zsh_cv_sys_killesrch=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_killesrch" >&5 +printf "%s\n" "$zsh_cv_sys_killesrch" >&6; } + +if test x$zsh_cv_sys_killesrch = xno; then + printf "%s\n" "#define BROKEN_KILL_ESRCH 1" >>confdefs.h + +fi + + +if test x$signals_style = xPOSIX_SIGNALS; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if POSIX sigsuspend() works" >&5 +printf %s "checking if POSIX sigsuspend() works... " >&6; } +if test ${zsh_cv_sys_sigsuspend+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_sys_sigsuspend=yes +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <signal.h> +#include <unistd.h> +#include <stdlib.h> +int child=0; +void handler(sig) + int sig; +{if(sig==SIGCHLD) child=1;} +main() { + struct sigaction act; + sigset_t set; + int pid, ret; + act.sa_handler = &handler; + sigfillset(&act.sa_mask); + act.sa_flags = 0; + sigaction(SIGCHLD, &act, 0); + sigfillset(&set); + sigprocmask(SIG_SETMASK, &set, 0); + pid=fork(); + if(pid==0) return 0; + if(pid>0) { + sigemptyset(&set); + ret=sigsuspend(&set); + exit(child==0); + } +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_sigsuspend=yes +else $as_nop + zsh_cv_sys_sigsuspend=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_sigsuspend" >&5 +printf "%s\n" "$zsh_cv_sys_sigsuspend" >&6; } + if test x$zsh_cv_sys_sigsuspend = xno; then + printf "%s\n" "#define BROKEN_POSIX_SIGSUSPEND 1" >>confdefs.h + + fi +fi + + + +# Check whether --with-tcsetpgrp was given. +if test ${with_tcsetpgrp+y} +then : + withval=$with_tcsetpgrp; +case "x$withval" in + xyes) zsh_working_tcsetpgrp=yes;; + xno) zsh_working_tcsetpgrp=no;; + *) as_fn_error $? "please use --with-tcsetpgrp=yes or --with-tcsetpgrp=no" "$LINENO" 5;; +esac +else $as_nop + zsh_working_tcsetpgrp=check +fi + +if test "x$ac_cv_func_tcsetpgrp" = xyes; then +case "x$zsh_working_tcsetpgrp" in + xcheck) + trap "" TTOU > /dev/null 2>&1 || : + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if tcsetpgrp() actually works" >&5 +printf %s "checking if tcsetpgrp() actually works... " >&6; } +if test ${zsh_cv_sys_tcsetpgrp+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_sys_tcsetpgrp=yes +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <sys/types.h> +#include <unistd.h> +#include <fcntl.h> +#include <stdlib.h> +main() { + int fd; + int ret; + fd=open("/dev/tty", O_RDWR); + if (fd < 0) exit(2); + ret=tcsetpgrp(fd, tcgetpgrp(fd)); + if (ret < 0) exit(1); + exit(0); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_tcsetpgrp=yes +else $as_nop + +case $? in + 1) zsh_cv_sys_tcsetpgrp=no;; + 2) zsh_cv_sys_tcsetpgrp=notty;; + *) zsh_cv_sys_tcsetpgrp=error;; +esac + +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_tcsetpgrp" >&5 +printf "%s\n" "$zsh_cv_sys_tcsetpgrp" >&6; } + case "x$zsh_cv_sys_tcsetpgrp" in + xno) printf "%s\n" "#define BROKEN_TCSETPGRP 1" >>confdefs.h +;; + xyes) :;; + xnotty) as_fn_error $? "no controlling tty +Try running configure with --with-tcsetpgrp or --without-tcsetpgrp" "$LINENO" 5;; + *) as_fn_error $? "unexpected return status" "$LINENO" 5;; + esac + trap - TTOU > /dev/null 2>&1 || : + ;; + xyes) :;; + xno) printf "%s\n" "#define BROKEN_TCSETPGRP 1" >>confdefs.h +;; + *) as_fn_error $? "unexpected value zsh_working_tcsetpgrp=$zsh_working_tcsetpgrp" "$LINENO" 5;; +esac +fi + + +if test x$ac_cv_func_getpwnam = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if getpwnam() is faked" >&5 +printf %s "checking if getpwnam() is faked... " >&6; } +if test ${zsh_cv_sys_getpwnam_faked+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_sys_getpwnam_faked=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <pwd.h> +#include <stdio.h> +#include <string.h> +#include <stdlib.h> +#include <unistd.h> +main() { + struct passwd *pw1, *pw2; + char buf[1024], name[1024]; + sprintf(buf, "%d:%d", getpid(), rand()); + pw1=getpwnam(buf); + if (pw1) strcpy(name, pw1->pw_name); + sprintf(buf, "%d:%d", rand(), getpid()); + pw2=getpwnam(buf); + exit(pw1!=0 && pw2!=0 && !strcmp(name, pw2->pw_name)); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_getpwnam_faked=no +else $as_nop + zsh_cv_sys_getpwnam_faked=yes +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_getpwnam_faked" >&5 +printf "%s\n" "$zsh_cv_sys_getpwnam_faked" >&6; } + if test x$zsh_cv_sys_getpwnam_faked = xyes; then + printf "%s\n" "#define GETPWNAM_FAKED 1" >>confdefs.h + + fi +fi + + + + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking base type of the third argument to accept" >&5 +printf %s "checking base type of the third argument to accept... " >&6; } +if test ${zsh_cv_type_socklen_t+y} +then : + printf %s "(cached) " >&6 +else $as_nop + zsh_cv_type_socklen_t= + for zsh_type in socklen_t int "unsigned long" size_t ; do + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#include <sys/types.h> + #include <sys/socket.h> +int +main (void) +{ +extern int accept (int, struct sockaddr *, $zsh_type *); + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + zsh_cv_type_socklen_t="$zsh_type"; break +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext + done + if test -z "$zsh_cv_type_socklen_t"; then + zsh_cv_type_socklen_t=int + fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_type_socklen_t" >&5 +printf "%s\n" "$zsh_cv_type_socklen_t" >&6; } + +printf "%s\n" "#define ZSOCKLEN_T $zsh_cv_type_socklen_t" >>confdefs.h + + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if your system has /dev/ptmx" >&5 +printf %s "checking if your system has /dev/ptmx... " >&6; } +if test ${ac_cv_have_dev_ptmx+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test -w /dev/ptmx; then + ac_cv_have_dev_ptmx=yes +else + ac_cv_have_dev_ptmx=no +fi +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_have_dev_ptmx" >&5 +printf "%s\n" "$ac_cv_have_dev_ptmx" >&6; } + + +if test x$ac_cv_have_dev_ptmx = xyes -o x$ac_cv_func_posix_openpt = xyes && \ + test x$ac_cv_func_grantpt = xyes && \ + test x$ac_cv_func_unlockpt = xyes && \ + test x$ac_cv_func_ptsname = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if /dev/ptmx is usable" >&5 +printf %s "checking if /dev/ptmx is usable... " >&6; } +if test ${ac_cv_use_dev_ptmx+y} +then : + printf %s "(cached) " >&6 +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +#if defined(__linux) || defined(__CYGWIN__) +#define _GNU_SOURCE 1 +#endif +#include <stdlib.h> +int ptsname(); +int +main (void) +{ + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_compile "$LINENO" +then : + ac_cv_use_dev_ptmx=no +else $as_nop + ac_cv_use_dev_ptmx=yes +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam conftest.$ac_ext +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $ac_cv_use_dev_ptmx" >&5 +printf "%s\n" "$ac_cv_use_dev_ptmx" >&6; } + if test x$ac_cv_use_dev_ptmx = xyes; then + printf "%s\n" "#define USE_DEV_PTMX 1" >>confdefs.h + + fi +fi + +# Check whether --enable-multibyte was given. +if test ${enable_multibyte+y} +then : + enableval=$enable_multibyte; zsh_cv_c_unicode_support=$enableval +else $as_nop + if test ${zsh_cv_c_unicode_support+y} +then : + printf %s "(cached) " >&6 +else $as_nop + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for functions supporting multibyte characters" >&5 +printf "%s\n" "$as_me: checking for functions supporting multibyte characters" >&6;} + zfuncs_absent= + for zfunc in iswalnum iswcntrl iswdigit iswgraph iswlower iswprint \ +iswpunct iswspace iswupper iswxdigit mbrlen mbrtowc towupper towlower \ +wcschr wcscpy wcslen wcsncmp wcsncpy wcrtomb wcwidth wmemchr wmemcmp \ +wmemcpy wmemmove wmemset; do + as_ac_var=`printf "%s\n" "ac_cv_func_$zfunc" | $as_tr_sh` +ac_fn_c_check_func "$LINENO" "$zfunc" "$as_ac_var" +if eval test \"x\$"$as_ac_var"\" = x"yes" +then : + : +else $as_nop + zfuncs_absent="$zfuncs_absent $zfunc" +fi + + done + if test x"$zfuncs_absent" = x; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: all functions found, multibyte support enabled" >&5 +printf "%s\n" "$as_me: all functions found, multibyte support enabled" >&6;} + zsh_cv_c_unicode_support=yes + else + # Warns at the end of configure + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: missing functions, multibyte support disabled" >&5 +printf "%s\n" "$as_me: missing functions, multibyte support disabled" >&6;} + zsh_cv_c_unicode_support=no + fi + +fi + + +fi + + + + +# Check whether --enable-unicode9 was given. +if test ${enable_unicode9+y} +then : + enableval=$enable_unicode9; if test x$enableval = xyes; then + printf "%s\n" "#define ENABLE_UNICODE9 1" >>confdefs.h + +fi +fi + + + + +if test x$zsh_cv_c_unicode_support = xyes; then + printf "%s\n" "#define MULTIBYTE_SUPPORT 1" >>confdefs.h + + + locale_prog='char *my_locales[] = { + "en_US.UTF-8", "en_GB.UTF-8", "en.UTF-8", ' + locale_prog="$locale_prog"`locale -a 2>/dev/null | \ + sed -e 's/utf8/UTF-8/' | grep UTF-8 | \ + while read line; do echo " \"$line\","; done;` + locale_prog="$locale_prog 0 }; + #define _XOPEN_SOURCE + #include <stdlib.h> + #include <locale.h> + #include <wchar.h> + #include <wctype.h> + + int main() { + char **localep; + char comb_acute_mb[] = { (char)0xcc, (char)0x81 }; + char u_0234[] = { (char)0xc8, (char)0xb4 }; + wchar_t wc; + #if !defined(__STDC_ISO_10646__) && !defined(__APPLE__) + return 1; + #endif + + for (localep = my_locales; *localep; localep++) + if (setlocale(LC_ALL, *localep)) + break; + if (!*localep) + return 1; + if (mbtowc(&wc, comb_acute_mb, 2) == 2 && (wcwidth(wc) != 0 || !iswprint(wc))) + return 0; + if (mbtowc(&wc, u_0234, 2) == 2 && (wcwidth(wc) != 1 || !iswprint(wc))) + return 0; + return 1; + } + " + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if the wcwidth() and/or iswprint() functions are broken" >&5 +printf %s "checking if the wcwidth() and/or iswprint() functions are broken... " >&6; } +if test ${zsh_cv_c_broken_wcwidth+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_c_broken_wcwidth=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$locale_prog +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_c_broken_wcwidth=yes +else $as_nop + zsh_cv_c_broken_wcwidth=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_c_broken_wcwidth" >&5 +printf "%s\n" "$zsh_cv_c_broken_wcwidth" >&6; } + if test x$zsh_cv_c_broken_wcwidth = xyes; then + printf "%s\n" "#define ENABLE_UNICODE9 1" >>confdefs.h + + fi + + locale_prog='char *my_locales[] = { + "en_US.UTF-8", "en_GB.UTF-8", "en.UTF-8", ' + locale_prog="$locale_prog"`locale -a 2>/dev/null | \ + sed -e 's/utf8/UTF-8/' | grep UTF-8 | \ + while read line; do echo " \"$line\","; done;` + locale_prog="$locale_prog 0 }; + #include <locale.h> + #include <ctype.h> + + int main() { + char **localep; + for (localep = my_locales; *localep; localep++) + if (setlocale(LC_ALL, *localep) && isprint(0xa0)) + return 0; + return 1; + } + " + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if the isprint() function is broken" >&5 +printf %s "checking if the isprint() function is broken... " >&6; } +if test ${zsh_cv_c_broken_isprint+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_c_broken_isprint=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +$locale_prog +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_c_broken_isprint=yes +else $as_nop + zsh_cv_c_broken_isprint=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_c_broken_isprint" >&5 +printf "%s\n" "$zsh_cv_c_broken_isprint" >&6; } + if test x$zsh_cv_c_broken_isprint = xyes; then + printf "%s\n" "#define BROKEN_ISPRINT 1" >>confdefs.h + + fi +fi + + +# Check whether --enable-libc-musl was given. +if test ${enable_libc_musl+y} +then : + enableval=$enable_libc_musl; if test x$enableval = xyes; then + printf "%s\n" "#define LIBC_MUSL 1" >>confdefs.h + +fi +fi + + +# Check whether --enable-dynamic-nss was given. +if test ${enable_dynamic_nss+y} +then : + enableval=$enable_dynamic_nss; zsh_cv_c_dynamic_nss=$enableval +fi + + + +if test x$zsh_cv_c_dynamic_nss = xno; then + printf "%s\n" "#define DISABLE_DYNAMIC_NSS 1" >>confdefs.h + +fi + + +L=N +INSTLIB="install.bin-\$(L)" +UNINSTLIB="uninstall.bin-\$(L)" +LINKMODS=NOLINKMODS +MOD_EXPORT= +MOD_IMPORT_VARIABLE= +MOD_IMPORT_FUNCTION= +aixdynamic=no +hpuxdynamic=no +if test "$ac_cv_func_load" = yes && + test "$ac_cv_func_unload" = yes && + test "$ac_cv_func_loadbind" = yes && + test "$ac_cv_func_loadquery" = yes; then + if test "x$dynamic" = xyes; then + aixdynamic=yes + fi +elif test "$ac_cv_func_dlopen" != yes || + test "$ac_cv_func_dlsym" != yes || + test "$ac_cv_func_dlerror" != yes; then + if test "$ac_cv_func_shl_load" != yes || + test "$ac_cv_func_shl_unload" != yes || + test "$ac_cv_func_shl_findsym" != yes; then + dynamic=no + elif test "x$dynamic" = xyes; then + hpuxdynamic=yes + DL_EXT="${DL_EXT=sl}" + printf "%s\n" "#define HPUX10DYNAMIC 1" >>confdefs.h + fi +fi + +test -n "$GCC" && LDARG=-Wl, + + + +if test "x$aixdynamic" = xyes; then + DL_EXT="${DL_EXT=so}" + DLLD="${DLLD=$CC}" + zsh_cv_func_dlsym_needs_underscore=no + if test -n "$GCC"; then + DLLDFLAGS=${DLLDFLAGS=-shared} + else + DLLDFLAGS=${DLLDFLAGS=-bM:SRE} + fi + DLLDFLAGS=${DLLDFLAGS=} + EXTRA_LDFLAGS=${EXTRA_LDFLAGS=} + EXPOPT=${LDARG}-bE: + IMPOPT=${LDARG}-bI: + zsh_cv_sys_dynamic_clash_ok="${zsh_cv_sys_dynamic_clash_ok=yes}" + zsh_cv_sys_dynamic_rtld_global="${zsh_cv_sys_dynamic_rtld_global=yes}" + zsh_cv_sys_dynamic_execsyms="${zsh_cv_sys_dynamic_execsyms=yes}" + zsh_cv_sys_dynamic_strip_exe="${zsh_cv_sys_dynamic_strip_exe=yes}" + zsh_cv_sys_dynamic_strip_lib="${zsh_cv_sys_dynamic_strip_lib=yes}" + zsh_cv_shared_environ="${zsh_cv_shared_environ=yes}" +elif test "$host_os" = cygwin; then + DL_EXT="${DL_EXT=dll}" +##DLLD="${DLLD=dllwrap}" + DLLD="${DLLD=$CC}" +##DLLDFLAGS="${DLLDFLAGS=--export-all-symbols}" + DLLDFLAGS=${DLLDFLAGS=-shared -Wl,--export-all-symbols} + zsh_cv_func_dlsym_needs_underscore=no + DLLDFLAGS=${DLLDFLAGS=} + EXTRA_LDFLAGS=${EXTRA_LDFLAGS=} + zsh_cv_sys_dynamic_clash_ok="${zsh_cv_sys_dynamic_clash_ok=no}" + zsh_cv_sys_dynamic_rtld_global="${zsh_cv_sys_dynamic_rtld_global=yes}" + zsh_cv_sys_dynamic_execsyms="${zsh_cv_sys_dynamic_execsyms=no}" + zsh_cv_sys_dynamic_strip_exe="${zsh_cv_sys_dynamic_strip_exe=yes}" + zsh_cv_sys_dynamic_strip_lib="${zsh_cv_sys_dynamic_strip_lib=yes}" + # + # THAT SUCKS! and must be changed + # + zsh_cv_shared_environ="${zsh_cv_shared_environ=yes}" + LINKMODS=LINKMODS + MOD_EXPORT="__attribute__((__dllexport__))" + MOD_IMPORT_VARIABLE="__attribute__((__dllimport__))" + MOD_IMPORT_FUNCTION= +elif test "x$dynamic" = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if your system uses ELF binaries" >&5 +printf %s "checking if your system uses ELF binaries... " >&6; } +if test ${zsh_cv_sys_elf+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$cross_compiling" = yes +then : + zsh_cv_sys_elf=yes +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ +/* Test for whether ELF binaries are produced */ +#include <fcntl.h> +#include <stdlib.h> +#include <unistd.h> +main(argc, argv) +int argc; +char *argv[]; +{ + char b[4]; + int i = open(argv[0],O_RDONLY); + if(i == -1) + exit(1); /* fail */ + if(read(i,b,4)==4 && b[0]==127 && b[1]=='E' && b[2]=='L' && b[3]=='F') + exit(0); /* succeed (yes, it's ELF) */ + else + exit(1); /* fail */ +} +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_elf=yes +else $as_nop + zsh_cv_sys_elf=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_elf" >&5 +printf "%s\n" "$zsh_cv_sys_elf" >&6; } + + # We use [0-9]* in case statements, so need to change quoting + + + DL_EXT="${DL_EXT=so}" + if test x$zsh_cv_sys_elf = xyes; then + case "$host" in + mips-sni-sysv4*) + # Forcibly set ld to native compiler to avoid obscure GCC problems + DLLD="${DLLD=/usr/ccs/bin/cc}" + DLLDARG="${LDARG}" + ;; + * ) + DLLD="${DLLD=$CC}" + DLLDARG="${LDARG}" + ;; + esac + else + case "$host" in + *openbsd*) + case "$host_os" in + openbsd[01].* | openbsd2.[0-7] | openbsd2.[0-7].*) + DLLD="${DLLD=ld}" + ;; + *) + DLLD="${DLLD=$CC}" + ;; + esac + DLLDARG="${LDARG}" + ;; + *darwin*) + DLLD="${DLLD=$CC}" + DLLDARG="" + ;; + *interix*) + DLLD="${DLLD=$CC}" + DLLDARG="" + ;; + * ) + DLLD="${DLLD=ld}" + DLLDARG="" + ;; + esac + fi + if test -n "$GCC"; then + case "$host_os" in + hpux*) DLLDFLAGS="${DLLDFLAGS=-shared}" ;; + darwin*) DLCFLAGS="${DLCFLAGS=-fno-common}" ;; + interix*) DLCFLAGS="${DLCFLAGS=}" ;; + *) DLCFLAGS="${DLCFLAGS=-fPIC}" ;; + esac + else + case "$host_os" in + hpux*) + DLCFLAGS="${DLCFLAGS=+z}" + DLLDFLAGS="${DLLDFLAGS=-b}" + ;; + sunos*) DLCFLAGS="${DLCFLAGS=-pic}" ;; + solaris*|sysv4*|esix*) DLCFLAGS="${DLCFLAGS=-KPIC}" ;; + esac + fi + case "$host_os" in + osf*) DLLDFLAGS="${DLLDFLAGS=-shared -expect_unresolved '*'}" ;; + *freebsd*|*netbsd*|linux*|irix*|gnu*|interix*|dragonfly*) DLLDFLAGS="${DLLDFLAGS=-shared}" ;; + sunos*) DLLDFLAGS="${DLLDFLAGS=-assert nodefinitions}" ;; + sysv4*|esix*) DLLDFLAGS="${DLLDFLAGS=-G $ldflags}" ;; + aix*) DLLDFLAGS="${DLLDFLAGS=-G -bexpall -lc}" ;; + solaris*|sysv4*|esix*) DLLDFLAGS="${DLLDFLAGS=-G}" ;; + darwin*) DLLDFLAGS="${DLLDFLAGS=-bundle -flat_namespace -undefined suppress}" ;; + beos*|haiku*) DLLDFLAGS="${DLLDFLAGS=-nostart}" ;; + openbsd*) + if test x$zsh_cv_sys_elf = xyes; then + DLLDFLAGS="${DLLDFLAGS=-shared -fPIC}" + else + case "$host_os" in + openbsd[01].* | openbsd2.[0-7] | openbsd2.[0-7].*) + DLLDFLAGS="${DLLDFLAGS=-Bshareable}" + ;; + *) + DLLDFLAGS="${DLLDFLAGS=-shared -fPIC}" + ;; + esac + fi + ;; + esac + case "$host" in + *-hpux*) EXTRA_LDFLAGS="${EXTRA_LDFLAGS=-Wl,-E}" ;; + *openbsd*) + if test x$zsh_cv_sys_elf = xyes; then + EXTRA_LDFLAGS="${EXTRA_LDFLAGS=-Wl,-E}" + fi + ;; + mips-sni-sysv4) + # + # unfortunately, we have different compilers + # that need different flags + # + if test -n "$GCC"; then + sni_cc_version=GCC + else + sni_cc_version=`$CC -V 2>&1 | head -1` + fi + case "$sni_cc_version" in + *CDS*|GCC ) + EXTRA_LDFLAGS="${EXTRA_LDFLAGS=-Wl,-Blargedynsym}" + ;; + * ) + EXTRA_LDFLAGS="${EXTRA_LDFLAGS=-LD-Blargedynsym}" + ;; + esac + ;; + *-beos*) + # gcc on BeOS doesn't like -rdynamic... + EXTRA_LDFLAGS="${EXTRA_LDFLAGS= }" + # also, dlopen() at least in Zeta respects $LIBRARY_PATH, so needs %A added to it. + export LIBRARY_PATH="$LIBRARY_PATH:%A/" + ;; + *-haiku*) + # + ;; + esac + + # Done with our shell code, so restore autotools quoting + + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if we can use -rdynamic" >&5 +printf %s "checking if we can use -rdynamic... " >&6; } +if test ${zsh_cv_rdynamic_available+y} +then : + printf %s "(cached) " >&6 +else $as_nop + old_LDFLAGS="$LDFLAGS" +LDFLAGS="$LDFLAGS -rdynamic" +cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +int +main (void) +{ + + ; + return 0; +} +_ACEOF +if ac_fn_c_try_link "$LINENO" +then : + zsh_cv_rdynamic_available=yes +EXTRA_LDFLAGS="${EXTRA_LDFLAGS=-rdynamic}" +else $as_nop + zsh_cvs_rdynamic_available=no +fi +rm -f core conftest.err conftest.$ac_objext conftest.beam \ + conftest$ac_exeext conftest.$ac_ext +LDFLAGS="$old_LDFLAGS" +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_rdynamic_available" >&5 +printf "%s\n" "$zsh_cv_rdynamic_available" >&6; } + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if your dlsym() needs a leading underscore" >&5 +printf %s "checking if your dlsym() needs a leading underscore... " >&6; } +if test ${zsh_cv_func_dlsym_needs_underscore+y} +then : + printf %s "(cached) " >&6 +else $as_nop + echo failed >conftestval && cat >conftest.c <<EOM +fred () { } +EOM + { ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && + { ac_try='$DLLD $LDFLAGS $DLLDFLAGS -o conftest.$DL_EXT conftest.o 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && + if test "$cross_compiling" = yes +then : + zsh_cv_func_dlsym_needs_underscore=no +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <stdio.h> +#include <stdlib.h> +#ifdef HPUX10DYNAMIC +#include <dl.h> +#define RTLD_LAZY BIND_DEFERRED +#define RTLD_GLOBAL DYNAMIC_PATH + +char *zsh_gl_sym_addr ; + +#define dlopen(file,mode) (void *)shl_load((file), (mode), (long) 0) +#define dlclose(handle) shl_unload((shl_t)(handle)) +#define dlsym(handle,name) (zsh_gl_sym_addr=0,shl_findsym((shl_t *)&(handle),name,TYPE_UNDEFINED,&zsh_gl_sym_addr), (void *)zsh_gl_sym_addr) +#define dlerror() 0 +#else +#ifdef HAVE_DLFCN_H +#include <dlfcn.h> +#else +#include <sys/types.h> +#include <nlist.h> +#include <link.h> +#endif +#endif +#ifndef RTLD_LAZY +#define RTLD_LAZY 1 +#endif + +extern int fred() ; + +main() +{ + void * handle ; + void * symbol ; + FILE *f=fopen("conftestval", "w"); + if (!f) exit(1); + handle = dlopen("./conftest.$DL_EXT", RTLD_LAZY) ; + if (handle == NULL) { + fprintf (f, "dlopen failed") ; + exit(1); + } + symbol = dlsym(handle, "fred") ; + if (symbol == NULL) { + /* try putting a leading underscore */ + symbol = dlsym(handle, "_fred") ; + if (symbol == NULL) { + fprintf (f, "dlsym failed") ; + exit(1); + } + fprintf (f, "yes") ; + } + else + fprintf (f, "no") ; + exit(0); +} +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_func_dlsym_needs_underscore=`cat conftestval` +else $as_nop + zsh_cv_func_dlsym_needs_underscore=failed + dynamic=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_func_dlsym_needs_underscore" >&5 +printf "%s\n" "$zsh_cv_func_dlsym_needs_underscore" >&6; } + if test "x$zsh_cv_func_dlsym_needs_underscore" = xyes; then + printf "%s\n" "#define DLSYM_NEEDS_UNDERSCORE 1" >>confdefs.h + + elif test "x$zsh_cv_func_dlsym_needs_underscore" != xno; then + unset zsh_cv_func_dlsym_needs_underscore + fi +fi + +if test "x$dynamic" = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if environ is available in shared libraries" >&5 +printf %s "checking if environ is available in shared libraries... " >&6; } +if test ${zsh_cv_shared_environ+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$zsh_cv_func_dlsym_needs_underscore" = yes; then + us=_ +else + us= +fi +echo ' +void *zsh_getaddr1() +{ +#ifdef __CYGWIN__ + __attribute__((__dllimport__)) +#endif + extern char ** environ; + return &environ; +}; +' > conftest1.c +sed 's/zsh_getaddr1/zsh_getaddr2/' < conftest1.c > conftest2.c +if { ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest1.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$DLLD -o conftest1.$DL_EXT $LDFLAGS $DLLDFLAGS conftest1.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest2.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$DLLD -o conftest2.$DL_EXT $LDFLAGS $DLLDFLAGS conftest2.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; }; then + if test "$cross_compiling" = yes +then : + zsh_cv_shared_environ=no + +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <stdlib.h> +#ifdef HPUX10DYNAMIC +#include <dl.h> +#define RTLD_LAZY BIND_DEFERRED +#define RTLD_GLOBAL DYNAMIC_PATH + +char *zsh_gl_sym_addr ; + +#define dlopen(file,mode) (void *)shl_load((file), (mode), (long) 0) +#define dlclose(handle) shl_unload((shl_t)(handle)) +#define dlsym(handle,name) (zsh_gl_sym_addr=0,shl_findsym((shl_t *)&(handle),name,TYPE_UNDEFINED,&zsh_gl_sym_addr), (void *)zsh_gl_sym_addr) +#define dlerror() 0 +#else +#ifdef HAVE_DLFCN_H +#include <dlfcn.h> +#else +#include <sys/types.h> +#include <nlist.h> +#include <link.h> +#endif +#endif +#ifndef RTLD_LAZY +#define RTLD_LAZY 1 +#endif +#ifndef RTLD_GLOBAL +#define RTLD_GLOBAL 0 +#endif + +main() +{ + void *handle1, *handle2; + void *(*zsh_getaddr1)(), *(*zsh_getaddr2)(); + void *sym1, *sym2; + handle1 = dlopen("./conftest1.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle1) exit(1); + handle2 = dlopen("./conftest2.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle2) exit(1); + zsh_getaddr1 = (void *(*)()) dlsym(handle1, "${us}zsh_getaddr1"); + zsh_getaddr2 = (void *(*)()) dlsym(handle2, "${us}zsh_getaddr2"); + sym1 = zsh_getaddr1(); + sym2 = zsh_getaddr2(); + if(!sym1 || !sym2) exit(1); + if(sym1 != sym2) exit(1); + dlclose(handle1); + handle1 = dlopen("./conftest1.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle1) exit(1); + zsh_getaddr1 = (void *(*)()) dlsym(handle1, "${us}zsh_getaddr1"); + sym1 = zsh_getaddr1(); + if(!sym1) exit(1); + if(sym1 != sym2) exit(1); + exit(0); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_shared_environ=yes +else $as_nop + zsh_cv_shared_environ=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +else + zsh_cv_shared_environ=no +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_shared_environ" >&5 +printf "%s\n" "$zsh_cv_shared_environ" >&6; } + + test "$zsh_cv_shared_environ" = yes || dynamic=no + if test "$ac_cv_func_tgetent" = yes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if tgetent is available in shared libraries" >&5 +printf %s "checking if tgetent is available in shared libraries... " >&6; } +if test ${zsh_cv_shared_tgetent+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$zsh_cv_func_dlsym_needs_underscore" = yes; then + us=_ +else + us= +fi +echo ' +void *zsh_getaddr1() +{ +#ifdef __CYGWIN__ + __attribute__((__dllimport__)) +#endif + extern int tgetent ( ); + return tgetent; +}; +' > conftest1.c +sed 's/zsh_getaddr1/zsh_getaddr2/' < conftest1.c > conftest2.c +if { ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest1.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$DLLD -o conftest1.$DL_EXT $LDFLAGS $DLLDFLAGS conftest1.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest2.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$DLLD -o conftest2.$DL_EXT $LDFLAGS $DLLDFLAGS conftest2.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; }; then + if test "$cross_compiling" = yes +then : + zsh_cv_shared_tgetent=no + +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <stdlib.h> +#ifdef HPUX10DYNAMIC +#include <dl.h> +#define RTLD_LAZY BIND_DEFERRED +#define RTLD_GLOBAL DYNAMIC_PATH + +char *zsh_gl_sym_addr ; + +#define dlopen(file,mode) (void *)shl_load((file), (mode), (long) 0) +#define dlclose(handle) shl_unload((shl_t)(handle)) +#define dlsym(handle,name) (zsh_gl_sym_addr=0,shl_findsym((shl_t *)&(handle),name,TYPE_UNDEFINED,&zsh_gl_sym_addr), (void *)zsh_gl_sym_addr) +#define dlerror() 0 +#else +#ifdef HAVE_DLFCN_H +#include <dlfcn.h> +#else +#include <sys/types.h> +#include <nlist.h> +#include <link.h> +#endif +#endif +#ifndef RTLD_LAZY +#define RTLD_LAZY 1 +#endif +#ifndef RTLD_GLOBAL +#define RTLD_GLOBAL 0 +#endif + +main() +{ + void *handle1, *handle2; + void *(*zsh_getaddr1)(), *(*zsh_getaddr2)(); + void *sym1, *sym2; + handle1 = dlopen("./conftest1.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle1) exit(1); + handle2 = dlopen("./conftest2.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle2) exit(1); + zsh_getaddr1 = (void *(*)()) dlsym(handle1, "${us}zsh_getaddr1"); + zsh_getaddr2 = (void *(*)()) dlsym(handle2, "${us}zsh_getaddr2"); + sym1 = zsh_getaddr1(); + sym2 = zsh_getaddr2(); + if(!sym1 || !sym2) exit(1); + if(sym1 != sym2) exit(1); + dlclose(handle1); + handle1 = dlopen("./conftest1.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle1) exit(1); + zsh_getaddr1 = (void *(*)()) dlsym(handle1, "${us}zsh_getaddr1"); + sym1 = zsh_getaddr1(); + if(!sym1) exit(1); + if(sym1 != sym2) exit(1); + exit(0); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_shared_tgetent=yes +else $as_nop + zsh_cv_shared_tgetent=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +else + zsh_cv_shared_tgetent=no +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_shared_tgetent" >&5 +printf "%s\n" "$zsh_cv_shared_tgetent" >&6; } + + fi + if test "$ac_cv_func_tigetstr" = yes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if tigetstr is available in shared libraries" >&5 +printf %s "checking if tigetstr is available in shared libraries... " >&6; } +if test ${zsh_cv_shared_tigetstr+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$zsh_cv_func_dlsym_needs_underscore" = yes; then + us=_ +else + us= +fi +echo ' +void *zsh_getaddr1() +{ +#ifdef __CYGWIN__ + __attribute__((__dllimport__)) +#endif + extern int tigetstr ( ); + return tigetstr; +}; +' > conftest1.c +sed 's/zsh_getaddr1/zsh_getaddr2/' < conftest1.c > conftest2.c +if { ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest1.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$DLLD -o conftest1.$DL_EXT $LDFLAGS $DLLDFLAGS conftest1.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest2.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$DLLD -o conftest2.$DL_EXT $LDFLAGS $DLLDFLAGS conftest2.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; }; then + if test "$cross_compiling" = yes +then : + zsh_cv_shared_tigetstr=no + +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <stdlib.h> +#ifdef HPUX10DYNAMIC +#include <dl.h> +#define RTLD_LAZY BIND_DEFERRED +#define RTLD_GLOBAL DYNAMIC_PATH + +char *zsh_gl_sym_addr ; + +#define dlopen(file,mode) (void *)shl_load((file), (mode), (long) 0) +#define dlclose(handle) shl_unload((shl_t)(handle)) +#define dlsym(handle,name) (zsh_gl_sym_addr=0,shl_findsym((shl_t *)&(handle),name,TYPE_UNDEFINED,&zsh_gl_sym_addr), (void *)zsh_gl_sym_addr) +#define dlerror() 0 +#else +#ifdef HAVE_DLFCN_H +#include <dlfcn.h> +#else +#include <sys/types.h> +#include <nlist.h> +#include <link.h> +#endif +#endif +#ifndef RTLD_LAZY +#define RTLD_LAZY 1 +#endif +#ifndef RTLD_GLOBAL +#define RTLD_GLOBAL 0 +#endif + +main() +{ + void *handle1, *handle2; + void *(*zsh_getaddr1)(), *(*zsh_getaddr2)(); + void *sym1, *sym2; + handle1 = dlopen("./conftest1.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle1) exit(1); + handle2 = dlopen("./conftest2.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle2) exit(1); + zsh_getaddr1 = (void *(*)()) dlsym(handle1, "${us}zsh_getaddr1"); + zsh_getaddr2 = (void *(*)()) dlsym(handle2, "${us}zsh_getaddr2"); + sym1 = zsh_getaddr1(); + sym2 = zsh_getaddr2(); + if(!sym1 || !sym2) exit(1); + if(sym1 != sym2) exit(1); + dlclose(handle1); + handle1 = dlopen("./conftest1.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle1) exit(1); + zsh_getaddr1 = (void *(*)()) dlsym(handle1, "${us}zsh_getaddr1"); + sym1 = zsh_getaddr1(); + if(!sym1) exit(1); + if(sym1 != sym2) exit(1); + exit(0); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_shared_tigetstr=yes +else $as_nop + zsh_cv_shared_tigetstr=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +else + zsh_cv_shared_tigetstr=no +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_shared_tigetstr" >&5 +printf "%s\n" "$zsh_cv_shared_tigetstr" >&6; } + + fi +fi + +if test "x$dynamic" = xyes; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking if name clashes in shared objects are OK" >&5 +printf %s "checking if name clashes in shared objects are OK... " >&6; } +if test ${zsh_cv_sys_dynamic_clash_ok+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$zsh_cv_func_dlsym_needs_underscore" = yes; then + us=_ +else + us= +fi +echo 'int fred () { return 42; }' > conftest1.c +echo 'int fred () { return 69; }' > conftest2.c +if { ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest1.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$DLLD -o conftest1.$DL_EXT $LDFLAGS $DLLDFLAGS conftest1.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest2.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$DLLD -o conftest2.$DL_EXT $LDFLAGS $DLLDFLAGS conftest2.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; }; then + if test "$cross_compiling" = yes +then : + zsh_cv_sys_dynamic_clash_ok=no + +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <stdlib.h> +#ifdef HPUX10DYNAMIC +#include <dl.h> +#define RTLD_LAZY BIND_DEFERRED +#define RTLD_GLOBAL DYNAMIC_PATH + +char *zsh_gl_sym_addr ; + +#define dlopen(file,mode) (void *)shl_load((file), (mode), (long) 0) +#define dlclose(handle) shl_unload((shl_t)(handle)) +#define dlsym(handle,name) (zsh_gl_sym_addr=0,shl_findsym((shl_t *)&(handle),name,TYPE_UNDEFINED,&zsh_gl_sym_addr), (void *)zsh_gl_sym_addr) +#define dlerror() 0 +#else +#ifdef HAVE_DLFCN_H +#include <dlfcn.h> +#else +#include <sys/types.h> +#include <nlist.h> +#include <link.h> +#endif +#endif +#ifndef RTLD_LAZY +#define RTLD_LAZY 1 +#endif +#ifndef RTLD_GLOBAL +#define RTLD_GLOBAL 0 +#endif + + +main() +{ + void *handle1, *handle2; + int (*fred1)(), (*fred2)(); + handle1 = dlopen("./conftest1.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle1) exit(1); + handle2 = dlopen("./conftest2.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle2) exit(1); + fred1 = (int (*)()) dlsym(handle1, "${us}fred"); + fred2 = (int (*)()) dlsym(handle2, "${us}fred"); + if(!fred1 || !fred2) exit(1); + exit((*fred1)() != 42 || (*fred2)() != 69); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_dynamic_clash_ok=yes +else $as_nop + zsh_cv_sys_dynamic_clash_ok=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +else + zsh_cv_sys_dynamic_clash_ok=no +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_dynamic_clash_ok" >&5 +printf "%s\n" "$zsh_cv_sys_dynamic_clash_ok" >&6; } +if test "$zsh_cv_sys_dynamic_clash_ok" = yes; then + printf "%s\n" "#define DYNAMIC_NAME_CLASH_OK 1" >>confdefs.h + +fi + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for working RTLD_GLOBAL" >&5 +printf %s "checking for working RTLD_GLOBAL... " >&6; } +if test ${zsh_cv_sys_dynamic_rtld_global+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$zsh_cv_func_dlsym_needs_underscore" = yes; then + us=_ +else + us= +fi +echo 'int fred () { return 42; }' > conftest1.c +echo 'extern int fred(); int barney () { return fred() + 27; }' > conftest2.c +if { ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest1.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$DLLD -o conftest1.$DL_EXT $LDFLAGS $DLLDFLAGS conftest1.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest2.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$DLLD -o conftest2.$DL_EXT $LDFLAGS $DLLDFLAGS conftest2.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; }; then + if test "$cross_compiling" = yes +then : + zsh_cv_sys_dynamic_rtld_global=no + +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <stdlib.h> +#ifdef HPUX10DYNAMIC +#include <dl.h> +#define RTLD_LAZY BIND_DEFERRED +#define RTLD_GLOBAL DYNAMIC_PATH + +char *zsh_gl_sym_addr ; + +#define dlopen(file,mode) (void *)shl_load((file), (mode), (long) 0) +#define dlclose(handle) shl_unload((shl_t)(handle)) +#define dlsym(handle,name) (zsh_gl_sym_addr=0,shl_findsym((shl_t *)&(handle),name,TYPE_UNDEFINED,&zsh_gl_sym_addr), (void *)zsh_gl_sym_addr) +#define dlerror() 0 +#else +#ifdef HAVE_DLFCN_H +#include <dlfcn.h> +#else +#include <sys/types.h> +#include <nlist.h> +#include <link.h> +#endif +#endif +#ifndef RTLD_LAZY +#define RTLD_LAZY 1 +#endif +#ifndef RTLD_GLOBAL +#define RTLD_GLOBAL 0 +#endif + +main() +{ + void *handle; + int (*barneysym)(); + handle = dlopen("./conftest1.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle) exit(1); + handle = dlopen("./conftest2.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle) exit(1); + barneysym = (int (*)()) dlsym(handle, "${us}barney"); + if(!barneysym) exit(1); + exit((*barneysym)() != 69); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_dynamic_rtld_global=yes +else $as_nop + zsh_cv_sys_dynamic_rtld_global=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +else + zsh_cv_sys_dynamic_rtld_global=no +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_dynamic_rtld_global" >&5 +printf "%s\n" "$zsh_cv_sys_dynamic_rtld_global" >&6; } + + RTLD_GLOBAL_OK=$zsh_cv_sys_dynamic_rtld_global + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether symbols in the executable are available" >&5 +printf %s "checking whether symbols in the executable are available... " >&6; } +if test ${zsh_cv_sys_dynamic_execsyms+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$zsh_cv_func_dlsym_needs_underscore" = yes; then + us=_ +else + us= +fi +echo 'extern int fred(); int barney () { return fred() + 27; }' > conftest1.c +if { ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest1.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$DLLD -o conftest1.$DL_EXT $LDFLAGS $DLLDFLAGS conftest1.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; }; then + save_ldflags=$LDFLAGS + LDFLAGS="$LDFLAGS $EXTRA_LDFLAGS" + if test "$cross_compiling" = yes +then : + zsh_cv_sys_dynamic_execsyms=no + +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <stdlib.h> +#ifdef HPUX10DYNAMIC +#include <dl.h> +#define RTLD_LAZY BIND_DEFERRED +#define RTLD_GLOBAL DYNAMIC_PATH + +char *zsh_gl_sym_addr ; + +#define dlopen(file,mode) (void *)shl_load((file), (mode), (long) 0) +#define dlclose(handle) shl_unload((shl_t)(handle)) +#define dlsym(handle,name) (zsh_gl_sym_addr=0,shl_findsym((shl_t *)&(handle),name,TYPE_UNDEFINED,&zsh_gl_sym_addr), (void *)zsh_gl_sym_addr) +#define dlerror() 0 +#else +#ifdef HAVE_DLFCN_H +#include <dlfcn.h> +#else +#include <sys/types.h> +#include <nlist.h> +#include <link.h> +#endif +#endif +#ifndef RTLD_LAZY +#define RTLD_LAZY 1 +#endif +#ifndef RTLD_GLOBAL +#define RTLD_GLOBAL 0 +#endif + +main() +{ + void *handle; + int (*barneysym)(); + handle = dlopen("./conftest1.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle) exit(1); + barneysym = (int (*)()) dlsym(handle, "${us}barney"); + if(!barneysym) exit(1); + exit((*barneysym)() != 69); +} + +int fred () { return 42; } + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_dynamic_execsyms=yes +else $as_nop + zsh_cv_sys_dynamic_execsyms=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + + LDFLAGS=$save_ldflags +else + zsh_cv_sys_dynamic_execsyms=no +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_dynamic_execsyms" >&5 +printf "%s\n" "$zsh_cv_sys_dynamic_execsyms" >&6; } + + if test "$zsh_cv_sys_dynamic_execsyms" != yes; then + L=L + fi + +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether executables can be stripped" >&5 +printf %s "checking whether executables can be stripped... " >&6; } +if test ${zsh_cv_sys_dynamic_strip_exe+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$zsh_cv_sys_dynamic_execsyms" != yes; then + zsh_cv_sys_dynamic_strip_exe=yes +elif + if test "$zsh_cv_func_dlsym_needs_underscore" = yes; then + us=_ + else + us= + fi + echo 'extern int fred(); int barney() { return fred() + 27; }' > conftest1.c + { ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest1.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && + { ac_try='$DLLD -o conftest1.$DL_EXT $LDFLAGS $DLLDFLAGS conftest1.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; }; then + save_ldflags=$LDFLAGS + LDFLAGS="$LDFLAGS $EXTRA_LDFLAGS -s" + if test "$cross_compiling" = yes +then : + zsh_cv_sys_dynamic_strip_exe=no + +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <stdlib.h> +#ifdef HPUX10DYNAMIC +#include <dl.h> +#define RTLD_LAZY BIND_DEFERRED +#define RTLD_GLOBAL DYNAMIC_PATH + +char *zsh_gl_sym_addr ; + +#define dlopen(file,mode) (void *)shl_load((file), (mode), (long) 0) +#define dlclose(handle) shl_unload((shl_t)(handle)) +#define dlsym(handle,name) (zsh_gl_sym_addr=0,shl_findsym((shl_t *)&(handle),name,TYPE_UNDEFINED,&zsh_gl_sym_addr), (void *)zsh_gl_sym_addr) +#define dlerror() 0 +#else +#ifdef HAVE_DLFCN_H +#include <dlfcn.h> +#else +#include <sys/types.h> +#include <nlist.h> +#include <link.h> +#endif +#endif +#ifndef RTLD_LAZY +#define RTLD_LAZY 1 +#endif +#ifndef RTLD_GLOBAL +#define RTLD_GLOBAL 0 +#endif + +main() +{ + void *handle; + int (*barneysym)(); + handle = dlopen("./conftest1.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle) exit(1); + barneysym = (int (*)()) dlsym(handle, "${us}barney"); + if(!barneysym) exit(1); + exit((*barneysym)() != 69); +} + +int fred () { return 42; } + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_dynamic_strip_exe=yes +else $as_nop + zsh_cv_sys_dynamic_strip_exe=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + + LDFLAGS=$save_ldflags +else + zsh_cv_sys_dynamic_strip_exe=no +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_dynamic_strip_exe" >&5 +printf "%s\n" "$zsh_cv_sys_dynamic_strip_exe" >&6; } + + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking whether libraries can be stripped" >&5 +printf %s "checking whether libraries can be stripped... " >&6; } +if test ${zsh_cv_sys_dynamic_strip_lib+y} +then : + printf %s "(cached) " >&6 +else $as_nop + if test "$zsh_cv_func_dlsym_needs_underscore" = yes; then + us=_ +else + us= +fi +echo 'int fred () { return 42; }' > conftest1.c +if { ac_try='$CC -c $CFLAGS $CPPFLAGS $DLCFLAGS conftest1.c 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; } && +{ ac_try='$DLLD -o conftest1.$DL_EXT $LDFLAGS $DLLDFLAGS -s conftest1.o $LIBS 1>&5' + { { eval echo "\"\$as_me\":${as_lineno-$LINENO}: \"$ac_try\""; } >&5 + (eval $ac_try) 2>&5 + ac_status=$? + printf "%s\n" "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5 + test $ac_status = 0; }; }; then + if test "$cross_compiling" = yes +then : + zsh_cv_sys_dynamic_strip_lib=no + +else $as_nop + cat confdefs.h - <<_ACEOF >conftest.$ac_ext +/* end confdefs.h. */ + +#include <stdlib.h> +#ifdef HPUX10DYNAMIC +#include <dl.h> +#define RTLD_LAZY BIND_DEFERRED +#define RTLD_GLOBAL DYNAMIC_PATH + +char *zsh_gl_sym_addr ; + +#define dlopen(file,mode) (void *)shl_load((file), (mode), (long) 0) +#define dlclose(handle) shl_unload((shl_t)(handle)) +#define dlsym(handle,name) (zsh_gl_sym_addr=0,shl_findsym((shl_t *)&(handle),name,TYPE_UNDEFINED,&zsh_gl_sym_addr), (void *)zsh_gl_sym_addr) +#define dlerror() 0 +#else +#ifdef HAVE_DLFCN_H +#include <dlfcn.h> +#else +#include <sys/types.h> +#include <nlist.h> +#include <link.h> +#endif +#endif +#ifndef RTLD_LAZY +#define RTLD_LAZY 1 +#endif +#ifndef RTLD_GLOBAL +#define RTLD_GLOBAL 0 +#endif + +main() +{ + void *handle; + int (*fredsym)(); + handle = dlopen("./conftest1.$DL_EXT", RTLD_LAZY | RTLD_GLOBAL); + if(!handle) exit(1); + fredsym = (int (*)()) dlsym(handle, "${us}fred"); + if(!fredsym) exit(1); + exit((*fredsym)() != 42); +} + +_ACEOF +if ac_fn_c_try_run "$LINENO" +then : + zsh_cv_sys_dynamic_strip_lib=yes +else $as_nop + zsh_cv_sys_dynamic_strip_lib=no +fi +rm -f core *.core core.conftest.* gmon.out bb.out conftest$ac_exeext \ + conftest.$ac_objext conftest.beam conftest.$ac_ext +fi + +else + zsh_cv_sys_dynamic_strip_lib=no +fi + +fi +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $zsh_cv_sys_dynamic_strip_lib" >&5 +printf "%s\n" "$zsh_cv_sys_dynamic_strip_lib" >&6; } + + if $strip_exeldflags && test "$zsh_cv_sys_dynamic_strip_exe" = yes; then + EXELDFLAGS="$EXELDFLAGS -s" + fi + if $strip_libldflags && test "$zsh_cv_sys_dynamic_strip_lib" = yes; then + LIBLDFLAGS="$LIBLDFLAGS -s" + fi + if test "$host_os" = cygwin; then + INSTLIB="install.cygwin-lib" + UNINSTLIB="uninstall.cygwin-lib" + fi +else + $strip_exeldflags && EXELDFLAGS="$EXELDFLAGS -s" + $strip_libldflags && LIBLDFLAGS="$LIBLDFLAGS -s" + RTLD_GLOBAL_OK=no +fi + + +if test "x$dynamic" = xyes; then + D=D + printf "%s\n" "#define DYNAMIC 1" >>confdefs.h +else + D=N +fi + + +if test "x$aixdynamic" = xyes; then + E=E + printf "%s\n" "#define AIXDYNAMIC 1" >>confdefs.h +else + E=N +fi + +if test "x$zsh_cv_sys_dynamic_clash_ok" = xyes; then + SHORTBOOTNAMES=yes +else + SHORTBOOTNAMES=no +fi + + + +if test "$host_os" = cygwin; then + EXTRAZSHOBJS="$EXTRAZSHOBJS zsh.res.o" +fi + + +printf "%s\n" "#define DL_EXT \"$DL_EXT\"" >>confdefs.h + +# Generate config.modules. We look for *.mdd files in first and second +# level subdirectories. Any existing line not containing 'auto=y' will be +# retained, provided the .mdd file itself was found. +CONFIG_MODULES=./config.modules +cat <<EOM > ${CONFIG_MODULES}.sh +srcdir="$srcdir" +dynamic="$dynamic" +CONFIG_MODULES="${CONFIG_MODULES}" +EOM +cat <<\EOM >> ${CONFIG_MODULES}.sh +echo "creating ${CONFIG_MODULES}" +userlist=" " +if test -f ${CONFIG_MODULES}; then + userlist="`sed -e '/^#/d' -e '/auto=y/d' -e 's/ .*/ /' -e 's/^name=/ /' \ + ${CONFIG_MODULES}`" + mv ${CONFIG_MODULES} ${CONFIG_MODULES}.old +else + # Save testing for existence each time. + echo > ${CONFIG_MODULES}.old +fi +(echo "# Edit this file to change the way modules are loaded." +echo "# The format is strict; do not break lines or add extra spaces." +echo "# Run \`make prep' if you change anything here after compiling" +echo "# (there is no need if you change this just after the first time" +echo "# you run \`configure')." +echo "#" +echo "# Values of \`link' are \`static', \`dynamic' or \`no' to compile the" +echo "# module into the shell, link it in at run time, or not use it at all." +echo "# In the final case, no attempt will be made to compile it." +echo "# Use \`static' or \`no' if you do not have dynamic loading." +echo "#" +echo "# Values of \`load' are \`yes' or \`no'; if yes, any builtins etc." +echo "# provided by the module will be autoloaded by the main shell" +echo "# (so long as \`link' is not set to \`no')." +echo "#" +echo "# Values of \`auto' are \`yes' or \`no'. configure sets the value to" +echo "# \`yes'. If you set it by hand to \`no', the line will be retained" +echo "# when the file is regenerated in future." +echo "#" +echo "# Note that the \`functions' entry extends to the end of the line." +echo "# It should not be quoted; it is used verbatim to find files to install." +echo "#" +echo "# You will need to run \`config.status --recheck' if you add a new" +echo "# module." +echo "#" +echo "# You should not change the values for the pseudo-module zsh/main," +echo "# which is the main shell (apart from the functions entry)." +EOM +for modfile in `cd ${srcdir}; echo */*.mdd */*/*.mdd`; do + name= + link= + load= + functions= + result= + . ${srcdir}/$modfile + if test x$name != x && test x"$link" != x; then + case "$link" in + *\ *) eval "link=\`$link\`" + ;; + esac + case "${load}" in + y*) load=" load=yes" + ;; + *) load=" load=no" + ;; + esac + if test "x$functions" != x; then + # N.B. no additional quotes + f=" functions=$functions" + else + f= + fi + case "$link" in + static) result="name=$name modfile=$modfile link=static auto=yes${load}$f" + ;; + dynamic) if test x$dynamic != xno; then + result="name=$name modfile=$modfile link=dynamic\ + auto=yes${load}$f" + else + result="name=$name modfile=$modfile link=no\ + auto=yes load=no$f" + fi + ;; + either) if test x$dynamic != xno; then + result="name=$name modfile=$modfile link=dynamic\ + auto=yes${load}$f" + else + result="name=$name modfile=$modfile link=static\ + auto=yes${load}$f" + fi + ;; + *) result="name=$name modfile=$modfile link=no auto=yes load=no$f" + ;; + esac +cat <<EOM >> ${CONFIG_MODULES}.sh +case "\$userlist" in + *" $name "*) grep "^name=$name " \${CONFIG_MODULES}.old;; + *) echo "$result";; +esac +EOM + fi +done +cat <<\EOM >> ${CONFIG_MODULES}.sh +) >${CONFIG_MODULES} +rm -f ${CONFIG_MODULES}.old +EOM + + + +CLEAN_MK="${srcdir}/Config/clean.mk" +CONFIG_MK="${srcdir}/Config/config.mk" +DEFS_MK="Config/defs.mk" +VERSION_MK="${srcdir}/Config/version.mk" + + +ac_config_files="$ac_config_files Config/defs.mk Makefile Doc/Makefile Etc/Makefile Src/Makefile Test/Makefile" + +ac_config_commands="$ac_config_commands config.modules" + +ac_config_commands="$ac_config_commands stamp-h" + + +cat >confcache <<\_ACEOF +# This file is a shell script that caches the results of configure +# tests run on this system so they can be shared between configure +# scripts and configure runs, see configure's option --config-cache. +# It is not useful on other systems. If it contains results you don't +# want to keep, you may remove or edit it. +# +# config.status only pays attention to the cache file if you give it +# the --recheck option to rerun configure. +# +# `ac_cv_env_foo' variables (set or unset) will be overridden when +# loading this file, other *unset* `ac_cv_foo' will be assigned the +# following values. + +_ACEOF + +# The following way of writing the cache mishandles newlines in values, +# but we know of no workaround that is simple, portable, and efficient. +# So, we kill variables containing newlines. +# Ultrix sh set writes to stderr and can't be redirected directly, +# and sets the high bit in the cache file unless we assign to the vars. +( + for ac_var in `(set) 2>&1 | sed -n 's/^\([a-zA-Z_][a-zA-Z0-9_]*\)=.*/\1/p'`; do + eval ac_val=\$$ac_var + case $ac_val in #( + *${as_nl}*) + case $ac_var in #( + *_cv_*) { printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: cache variable $ac_var contains a newline" >&5 +printf "%s\n" "$as_me: WARNING: cache variable $ac_var contains a newline" >&2;} ;; + esac + case $ac_var in #( + _ | IFS | as_nl) ;; #( + BASH_ARGV | BASH_SOURCE) eval $ac_var= ;; #( + *) { eval $ac_var=; unset $ac_var;} ;; + esac ;; + esac + done + + (set) 2>&1 | + case $as_nl`(ac_space=' '; set) 2>&1` in #( + *${as_nl}ac_space=\ *) + # `set' does not quote correctly, so add quotes: double-quote + # substitution turns \\\\ into \\, and sed turns \\ into \. + sed -n \ + "s/'/'\\\\''/g; + s/^\\([_$as_cr_alnum]*_cv_[_$as_cr_alnum]*\\)=\\(.*\\)/\\1='\\2'/p" + ;; #( + *) + # `set' quotes correctly as required by POSIX, so do not add quotes. + sed -n "/^[_$as_cr_alnum]*_cv_[_$as_cr_alnum]*=/p" + ;; + esac | + sort +) | + sed ' + /^ac_cv_env_/b end + t clear + :clear + s/^\([^=]*\)=\(.*[{}].*\)$/test ${\1+y} || &/ + t end + s/^\([^=]*\)=\(.*\)$/\1=${\1=\2}/ + :end' >>confcache +if diff "$cache_file" confcache >/dev/null 2>&1; then :; else + if test -w "$cache_file"; then + if test "x$cache_file" != "x/dev/null"; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: updating cache $cache_file" >&5 +printf "%s\n" "$as_me: updating cache $cache_file" >&6;} + if test ! -f "$cache_file" || test -h "$cache_file"; then + cat confcache >"$cache_file" + else + case $cache_file in #( + */* | ?:*) + mv -f confcache "$cache_file"$$ && + mv -f "$cache_file"$$ "$cache_file" ;; #( + *) + mv -f confcache "$cache_file" ;; + esac + fi + fi + else + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: not updating unwritable cache $cache_file" >&5 +printf "%s\n" "$as_me: not updating unwritable cache $cache_file" >&6;} + fi +fi +rm -f confcache + +test "x$prefix" = xNONE && prefix=$ac_default_prefix +# Let make expand exec_prefix. +test "x$exec_prefix" = xNONE && exec_prefix='${prefix}' + +DEFS=-DHAVE_CONFIG_H + +ac_libobjs= +ac_ltlibobjs= +U= +for ac_i in : $LIBOBJS; do test "x$ac_i" = x: && continue + # 1. Remove the extension, and $U if already installed. + ac_script='s/\$U\././;s/\.o$//;s/\.obj$//' + ac_i=`printf "%s\n" "$ac_i" | sed "$ac_script"` + # 2. Prepend LIBOBJDIR. When used with automake>=1.10 LIBOBJDIR + # will be set to the directory where LIBOBJS objects are built. + as_fn_append ac_libobjs " \${LIBOBJDIR}$ac_i\$U.$ac_objext" + as_fn_append ac_ltlibobjs " \${LIBOBJDIR}$ac_i"'$U.lo' +done +LIBOBJS=$ac_libobjs + +LTLIBOBJS=$ac_ltlibobjs + + + +: "${CONFIG_STATUS=./config.status}" +ac_write_fail=0 +ac_clean_files_save=$ac_clean_files +ac_clean_files="$ac_clean_files $CONFIG_STATUS" +{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: creating $CONFIG_STATUS" >&5 +printf "%s\n" "$as_me: creating $CONFIG_STATUS" >&6;} +as_write_fail=0 +cat >$CONFIG_STATUS <<_ASEOF || as_write_fail=1 +#! $SHELL +# Generated by $as_me. +# Run this file to recreate the current configuration. +# Compiler output produced by configure, useful for debugging +# configure, is in config.log if it exists. + +debug=false +ac_cs_recheck=false +ac_cs_silent=false + +SHELL=\${CONFIG_SHELL-$SHELL} +export SHELL +_ASEOF +cat >>$CONFIG_STATUS <<\_ASEOF || as_write_fail=1 +## -------------------- ## +## M4sh Initialization. ## +## -------------------- ## + +# Be more Bourne compatible +DUALCASE=1; export DUALCASE # for MKS sh +as_nop=: +if test ${ZSH_VERSION+y} && (emulate sh) >/dev/null 2>&1 +then : + emulate sh + NULLCMD=: + # Pre-4.2 versions of Zsh do word splitting on ${1+"$@"}, which + # is contrary to our usage. Disable this feature. + alias -g '${1+"$@"}'='"$@"' + setopt NO_GLOB_SUBST +else $as_nop + case `(set -o) 2>/dev/null` in #( + *posix*) : + set -o posix ;; #( + *) : + ;; +esac +fi + + + +# Reset variables that may have inherited troublesome values from +# the environment. + +# IFS needs to be set, to space, tab, and newline, in precisely that order. +# (If _AS_PATH_WALK were called with IFS unset, it would have the +# side effect of setting IFS to empty, thus disabling word splitting.) +# Quoting is to prevent editors from complaining about space-tab. +as_nl=' +' +export as_nl +IFS=" "" $as_nl" + +PS1='$ ' +PS2='> ' +PS4='+ ' + +# Ensure predictable behavior from utilities with locale-dependent output. +LC_ALL=C +export LC_ALL +LANGUAGE=C +export LANGUAGE + +# We cannot yet rely on "unset" to work, but we need these variables +# to be unset--not just set to an empty or harmless value--now, to +# avoid bugs in old shells (e.g. pre-3.0 UWIN ksh). This construct +# also avoids known problems related to "unset" and subshell syntax +# in other old shells (e.g. bash 2.01 and pdksh 5.2.14). +for as_var in BASH_ENV ENV MAIL MAILPATH CDPATH +do eval test \${$as_var+y} \ + && ( (unset $as_var) || exit 1) >/dev/null 2>&1 && unset $as_var || : +done + +# Ensure that fds 0, 1, and 2 are open. +if (exec 3>&0) 2>/dev/null; then :; else exec 0</dev/null; fi +if (exec 3>&1) 2>/dev/null; then :; else exec 1>/dev/null; fi +if (exec 3>&2) ; then :; else exec 2>/dev/null; fi + +# The user is always right. +if ${PATH_SEPARATOR+false} :; then + PATH_SEPARATOR=: + (PATH='/bin;/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 && { + (PATH='/bin:/bin'; FPATH=$PATH; sh -c :) >/dev/null 2>&1 || + PATH_SEPARATOR=';' + } +fi + + +# Find who we are. Look in the path if we contain no directory separator. +as_myself= +case $0 in #(( + *[\\/]* ) as_myself=$0 ;; + *) as_save_IFS=$IFS; IFS=$PATH_SEPARATOR +for as_dir in $PATH +do + IFS=$as_save_IFS + case $as_dir in #((( + '') as_dir=./ ;; + */) ;; + *) as_dir=$as_dir/ ;; + esac + test -r "$as_dir$0" && as_myself=$as_dir$0 && break + done +IFS=$as_save_IFS + + ;; +esac +# We did not find ourselves, most probably we were run as `sh COMMAND' +# in which case we are not to be found in the path. +if test "x$as_myself" = x; then + as_myself=$0 +fi +if test ! -f "$as_myself"; then + printf "%s\n" "$as_myself: error: cannot find myself; rerun with an absolute file name" >&2 + exit 1 +fi + + + +# as_fn_error STATUS ERROR [LINENO LOG_FD] +# ---------------------------------------- +# Output "`basename $0`: error: ERROR" to stderr. If LINENO and LOG_FD are +# provided, also output the error to LOG_FD, referencing LINENO. Then exit the +# script with STATUS, using 1 if that was 0. +as_fn_error () +{ + as_status=$1; test $as_status -eq 0 && as_status=1 + if test "$4"; then + as_lineno=${as_lineno-"$3"} as_lineno_stack=as_lineno_stack=$as_lineno_stack + printf "%s\n" "$as_me:${as_lineno-$LINENO}: error: $2" >&$4 + fi + printf "%s\n" "$as_me: error: $2" >&2 + as_fn_exit $as_status +} # as_fn_error + + + +# as_fn_set_status STATUS +# ----------------------- +# Set $? to STATUS, without forking. +as_fn_set_status () +{ + return $1 +} # as_fn_set_status + +# as_fn_exit STATUS +# ----------------- +# Exit the shell with STATUS, even in a "trap 0" or "set -e" context. +as_fn_exit () +{ + set +e + as_fn_set_status $1 + exit $1 +} # as_fn_exit + +# as_fn_unset VAR +# --------------- +# Portably unset VAR. +as_fn_unset () +{ + { eval $1=; unset $1;} +} +as_unset=as_fn_unset + +# as_fn_append VAR VALUE +# ---------------------- +# Append the text in VALUE to the end of the definition contained in VAR. Take +# advantage of any shell optimizations that allow amortized linear growth over +# repeated appends, instead of the typical quadratic growth present in naive +# implementations. +if (eval "as_var=1; as_var+=2; test x\$as_var = x12") 2>/dev/null +then : + eval 'as_fn_append () + { + eval $1+=\$2 + }' +else $as_nop + as_fn_append () + { + eval $1=\$$1\$2 + } +fi # as_fn_append + +# as_fn_arith ARG... +# ------------------ +# Perform arithmetic evaluation on the ARGs, and store the result in the +# global $as_val. Take advantage of shells that can avoid forks. The arguments +# must be portable across $(()) and expr. +if (eval "test \$(( 1 + 1 )) = 2") 2>/dev/null +then : + eval 'as_fn_arith () + { + as_val=$(( $* )) + }' +else $as_nop + as_fn_arith () + { + as_val=`expr "$@" || test $? -eq 1` + } +fi # as_fn_arith + + +if expr a : '\(a\)' >/dev/null 2>&1 && + test "X`expr 00001 : '.*\(...\)'`" = X001; then + as_expr=expr +else + as_expr=false +fi + +if (basename -- /) >/dev/null 2>&1 && test "X`basename -- / 2>&1`" = "X/"; then + as_basename=basename +else + as_basename=false +fi + +if (as_dir=`dirname -- /` && test "X$as_dir" = X/) >/dev/null 2>&1; then + as_dirname=dirname +else + as_dirname=false +fi + +as_me=`$as_basename -- "$0" || +$as_expr X/"$0" : '.*/\([^/][^/]*\)/*$' \| \ + X"$0" : 'X\(//\)$' \| \ + X"$0" : 'X\(/\)' \| . 2>/dev/null || +printf "%s\n" X/"$0" | + sed '/^.*\/\([^/][^/]*\)\/*$/{ + s//\1/ + q + } + /^X\/\(\/\/\)$/{ + s//\1/ + q + } + /^X\/\(\/\).*/{ + s//\1/ + q + } + s/.*/./; q'` + +# Avoid depending upon Character Ranges. +as_cr_letters='abcdefghijklmnopqrstuvwxyz' +as_cr_LETTERS='ABCDEFGHIJKLMNOPQRSTUVWXYZ' +as_cr_Letters=$as_cr_letters$as_cr_LETTERS +as_cr_digits='0123456789' +as_cr_alnum=$as_cr_Letters$as_cr_digits + + +# Determine whether it's possible to make 'echo' print without a newline. +# These variables are no longer used directly by Autoconf, but are AC_SUBSTed +# for compatibility with existing Makefiles. +ECHO_C= ECHO_N= ECHO_T= +case `echo -n x` in #((((( +-n*) + case `echo 'xy\c'` in + *c*) ECHO_T=' ';; # ECHO_T is single tab character. + xy) ECHO_C='\c';; + *) echo `echo ksh88 bug on AIX 6.1` > /dev/null + ECHO_T=' ';; + esac;; +*) + ECHO_N='-n';; +esac + +# For backward compatibility with old third-party macros, we provide +# the shell variables $as_echo and $as_echo_n. New code should use +# AS_ECHO(["message"]) and AS_ECHO_N(["message"]), respectively. +as_echo='printf %s\n' +as_echo_n='printf %s' + +rm -f conf$$ conf$$.exe conf$$.file +if test -d conf$$.dir; then + rm -f conf$$.dir/conf$$.file +else + rm -f conf$$.dir + mkdir conf$$.dir 2>/dev/null +fi +if (echo >conf$$.file) 2>/dev/null; then + if ln -s conf$$.file conf$$ 2>/dev/null; then + as_ln_s='ln -s' + # ... but there are two gotchas: + # 1) On MSYS, both `ln -s file dir' and `ln file dir' fail. + # 2) DJGPP < 2.04 has no symlinks; `ln -s' creates a wrapper executable. + # In both cases, we have to default to `cp -pR'. + ln -s conf$$.file conf$$.dir 2>/dev/null && test ! -f conf$$.exe || + as_ln_s='cp -pR' + elif ln conf$$.file conf$$ 2>/dev/null; then + as_ln_s=ln + else + as_ln_s='cp -pR' + fi +else + as_ln_s='cp -pR' +fi +rm -f conf$$ conf$$.exe conf$$.dir/conf$$.file conf$$.file +rmdir conf$$.dir 2>/dev/null + + +# as_fn_mkdir_p +# ------------- +# Create "$as_dir" as a directory, including parents if necessary. +as_fn_mkdir_p () +{ + + case $as_dir in #( + -*) as_dir=./$as_dir;; + esac + test -d "$as_dir" || eval $as_mkdir_p || { + as_dirs= + while :; do + case $as_dir in #( + *\'*) as_qdir=`printf "%s\n" "$as_dir" | sed "s/'/'\\\\\\\\''/g"`;; #'( + *) as_qdir=$as_dir;; + esac + as_dirs="'$as_qdir' $as_dirs" + as_dir=`$as_dirname -- "$as_dir" || +$as_expr X"$as_dir" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \ + X"$as_dir" : 'X\(//\)[^/]' \| \ + X"$as_dir" : 'X\(//\)$' \| \ + X"$as_dir" : 'X\(/\)' \| . 2>/dev/null || +printf "%s\n" X"$as_dir" | + sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{ + s//\1/ + q + } + /^X\(\/\/\)[^/].*/{ + s//\1/ + q + } + /^X\(\/\/\)$/{ + s//\1/ + q + } + /^X\(\/\).*/{ + s//\1/ + q + } + s/.*/./; q'` + test -d "$as_dir" && break + done + test -z "$as_dirs" || eval "mkdir $as_dirs" + } || test -d "$as_dir" || as_fn_error $? "cannot create directory $as_dir" + + +} # as_fn_mkdir_p +if mkdir -p . 2>/dev/null; then + as_mkdir_p='mkdir -p "$as_dir"' +else + test -d ./-p && rmdir ./-p + as_mkdir_p=false +fi + + +# as_fn_executable_p FILE +# ----------------------- +# Test if FILE is an executable regular file. +as_fn_executable_p () +{ + test -f "$1" && test -x "$1" +} # as_fn_executable_p +as_test_x='test -x' +as_executable_p=as_fn_executable_p + +# Sed expression to map a string onto a valid CPP name. +as_tr_cpp="eval sed 'y%*$as_cr_letters%P$as_cr_LETTERS%;s%[^_$as_cr_alnum]%_%g'" + +# Sed expression to map a string onto a valid variable name. +as_tr_sh="eval sed 'y%*+%pp%;s%[^_$as_cr_alnum]%_%g'" + + +exec 6>&1 +## ----------------------------------- ## +## Main body of $CONFIG_STATUS script. ## +## ----------------------------------- ## +_ASEOF +test $as_write_fail = 0 && chmod +x $CONFIG_STATUS || ac_write_fail=1 + +cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 +# Save the log message, to keep $0 and so on meaningful, and to +# report actual input values of CONFIG_FILES etc. instead of their +# values after options handling. +ac_log=" +This file was extended by $as_me, which was +generated by GNU Autoconf 2.71. Invocation command line was + + CONFIG_FILES = $CONFIG_FILES + CONFIG_HEADERS = $CONFIG_HEADERS + CONFIG_LINKS = $CONFIG_LINKS + CONFIG_COMMANDS = $CONFIG_COMMANDS + $ $0 $@ + +on `(hostname || uname -n) 2>/dev/null | sed 1q` +" + +_ACEOF + +case $ac_config_files in *" +"*) set x $ac_config_files; shift; ac_config_files=$*;; +esac + +case $ac_config_headers in *" +"*) set x $ac_config_headers; shift; ac_config_headers=$*;; +esac + + +cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 +# Files that config.status was made for. +config_files="$ac_config_files" +config_headers="$ac_config_headers" +config_commands="$ac_config_commands" + +_ACEOF + +cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 +ac_cs_usage="\ +\`$as_me' instantiates files and other configuration actions +from templates according to the current configuration. Unless the files +and actions are specified as TAGs, all are instantiated by default. + +Usage: $0 [OPTION]... [TAG]... + + -h, --help print this help, then exit + -V, --version print version number and configuration settings, then exit + --config print configuration, then exit + -q, --quiet, --silent + do not print progress messages + -d, --debug don't remove temporary files + --recheck update $as_me by reconfiguring in the same conditions + --file=FILE[:TEMPLATE] + instantiate the configuration file FILE + --header=FILE[:TEMPLATE] + instantiate the configuration header FILE + +Configuration files: +$config_files + +Configuration headers: +$config_headers + +Configuration commands: +$config_commands + +Report bugs to the package provider." + +_ACEOF +ac_cs_config=`printf "%s\n" "$ac_configure_args" | sed "$ac_safe_unquote"` +ac_cs_config_escaped=`printf "%s\n" "$ac_cs_config" | sed "s/^ //; s/'/'\\\\\\\\''/g"` +cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 +ac_cs_config='$ac_cs_config_escaped' +ac_cs_version="\\ +config.status +configured by $0, generated by GNU Autoconf 2.71, + with options \\"\$ac_cs_config\\" + +Copyright (C) 2021 Free Software Foundation, Inc. +This config.status script is free software; the Free Software Foundation +gives unlimited permission to copy, distribute and modify it." + +ac_pwd='$ac_pwd' +srcdir='$srcdir' +INSTALL='$INSTALL' +AWK='$AWK' +test -n "\$AWK" || AWK=awk +_ACEOF + +cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 +# The default lists apply if the user does not specify any file. +ac_need_defaults=: +while test $# != 0 +do + case $1 in + --*=?*) + ac_option=`expr "X$1" : 'X\([^=]*\)='` + ac_optarg=`expr "X$1" : 'X[^=]*=\(.*\)'` + ac_shift=: + ;; + --*=) + ac_option=`expr "X$1" : 'X\([^=]*\)='` + ac_optarg= + ac_shift=: + ;; + *) + ac_option=$1 + ac_optarg=$2 + ac_shift=shift + ;; + esac + + case $ac_option in + # Handling of the options. + -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) + ac_cs_recheck=: ;; + --version | --versio | --versi | --vers | --ver | --ve | --v | -V ) + printf "%s\n" "$ac_cs_version"; exit ;; + --config | --confi | --conf | --con | --co | --c ) + printf "%s\n" "$ac_cs_config"; exit ;; + --debug | --debu | --deb | --de | --d | -d ) + debug=: ;; + --file | --fil | --fi | --f ) + $ac_shift + case $ac_optarg in + *\'*) ac_optarg=`printf "%s\n" "$ac_optarg" | sed "s/'/'\\\\\\\\''/g"` ;; + '') as_fn_error $? "missing file argument" ;; + esac + as_fn_append CONFIG_FILES " '$ac_optarg'" + ac_need_defaults=false;; + --header | --heade | --head | --hea ) + $ac_shift + case $ac_optarg in + *\'*) ac_optarg=`printf "%s\n" "$ac_optarg" | sed "s/'/'\\\\\\\\''/g"` ;; + esac + as_fn_append CONFIG_HEADERS " '$ac_optarg'" + ac_need_defaults=false;; + --he | --h) + # Conflict between --help and --header + as_fn_error $? "ambiguous option: \`$1' +Try \`$0 --help' for more information.";; + --help | --hel | -h ) + printf "%s\n" "$ac_cs_usage"; exit ;; + -q | -quiet | --quiet | --quie | --qui | --qu | --q \ + | -silent | --silent | --silen | --sile | --sil | --si | --s) + ac_cs_silent=: ;; + + # This is an error. + -*) as_fn_error $? "unrecognized option: \`$1' +Try \`$0 --help' for more information." ;; + + *) as_fn_append ac_config_targets " $1" + ac_need_defaults=false ;; + + esac + shift +done + +ac_configure_extra_args= + +if $ac_cs_silent; then + exec 6>/dev/null + ac_configure_extra_args="$ac_configure_extra_args --silent" +fi + +_ACEOF +cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 +if \$ac_cs_recheck; then + set X $SHELL '$0' $ac_configure_args \$ac_configure_extra_args --no-create --no-recursion + shift + \printf "%s\n" "running CONFIG_SHELL=$SHELL \$*" >&6 + CONFIG_SHELL='$SHELL' + export CONFIG_SHELL + exec "\$@" +fi + +_ACEOF +cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 +exec 5>>config.log +{ + echo + sed 'h;s/./-/g;s/^.../## /;s/...$/ ##/;p;x;p;x' <<_ASBOX +## Running $as_me. ## +_ASBOX + printf "%s\n" "$ac_log" +} >&5 + +_ACEOF +cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 +_ACEOF + +cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 + +# Handling of arguments. +for ac_config_target in $ac_config_targets +do + case $ac_config_target in + "config.h") CONFIG_HEADERS="$CONFIG_HEADERS config.h" ;; + "Config/defs.mk") CONFIG_FILES="$CONFIG_FILES Config/defs.mk" ;; + "Makefile") CONFIG_FILES="$CONFIG_FILES Makefile" ;; + "Doc/Makefile") CONFIG_FILES="$CONFIG_FILES Doc/Makefile" ;; + "Etc/Makefile") CONFIG_FILES="$CONFIG_FILES Etc/Makefile" ;; + "Src/Makefile") CONFIG_FILES="$CONFIG_FILES Src/Makefile" ;; + "Test/Makefile") CONFIG_FILES="$CONFIG_FILES Test/Makefile" ;; + "config.modules") CONFIG_COMMANDS="$CONFIG_COMMANDS config.modules" ;; + "stamp-h") CONFIG_COMMANDS="$CONFIG_COMMANDS stamp-h" ;; + + *) as_fn_error $? "invalid argument: \`$ac_config_target'" "$LINENO" 5;; + esac +done + + +# If the user did not use the arguments to specify the items to instantiate, +# then the envvar interface is used. Set only those that are not. +# We use the long form for the default assignment because of an extremely +# bizarre bug on SunOS 4.1.3. +if $ac_need_defaults; then + test ${CONFIG_FILES+y} || CONFIG_FILES=$config_files + test ${CONFIG_HEADERS+y} || CONFIG_HEADERS=$config_headers + test ${CONFIG_COMMANDS+y} || CONFIG_COMMANDS=$config_commands +fi + +# Have a temporary directory for convenience. Make it in the build tree +# simply because there is no reason against having it here, and in addition, +# creating and moving files from /tmp can sometimes cause problems. +# Hook for its removal unless debugging. +# Note that there is a small window in which the directory will not be cleaned: +# after its creation but before its name has been assigned to `$tmp'. +$debug || +{ + tmp= ac_tmp= + trap 'exit_status=$? + : "${ac_tmp:=$tmp}" + { test ! -d "$ac_tmp" || rm -fr "$ac_tmp"; } && exit $exit_status +' 0 + trap 'as_fn_exit 1' 1 2 13 15 +} +# Create a (secure) tmp directory for tmp files. + +{ + tmp=`(umask 077 && mktemp -d "./confXXXXXX") 2>/dev/null` && + test -d "$tmp" +} || +{ + tmp=./conf$$-$RANDOM + (umask 077 && mkdir "$tmp") +} || as_fn_error $? "cannot create a temporary directory in ." "$LINENO" 5 +ac_tmp=$tmp + +# Set up the scripts for CONFIG_FILES section. +# No need to generate them if there are no CONFIG_FILES. +# This happens for instance with `./config.status config.h'. +if test -n "$CONFIG_FILES"; then + +if $AWK 'BEGIN { getline <"/dev/null" }' </dev/null 2>/dev/null; then + ac_cs_awk_getline=: + ac_cs_awk_pipe_init= + ac_cs_awk_read_file=' + while ((getline aline < (F[key])) > 0) + print(aline) + close(F[key])' + ac_cs_awk_pipe_fini= +else + ac_cs_awk_getline=false + ac_cs_awk_pipe_init="print \"cat <<'|#_!!_#|' &&\"" + ac_cs_awk_read_file=' + print "|#_!!_#|" + print "cat " F[key] " &&" + '$ac_cs_awk_pipe_init + # The final `:' finishes the AND list. + ac_cs_awk_pipe_fini='END { print "|#_!!_#|"; print ":" }' +fi +ac_cr=`echo X | tr X '\015'` +# On cygwin, bash can eat \r inside `` if the user requested igncr. +# But we know of no other shell where ac_cr would be empty at this +# point, so we can use a bashism as a fallback. +if test "x$ac_cr" = x; then + eval ac_cr=\$\'\\r\' +fi +ac_cs_awk_cr=`$AWK 'BEGIN { print "a\rb" }' </dev/null 2>/dev/null` +if test "$ac_cs_awk_cr" = "a${ac_cr}b"; then + ac_cs_awk_cr='\\r' +else + ac_cs_awk_cr=$ac_cr +fi + +echo 'BEGIN {' >"$ac_tmp/subs1.awk" && +_ACEOF + +# Create commands to substitute file output variables. +{ + echo "cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1" && + echo 'cat >>"\$ac_tmp/subs1.awk" <<\\_ACAWK &&' && + echo "$ac_subst_files" | sed 's/.*/F["&"]="$&"/' && + echo "_ACAWK" && + echo "_ACEOF" +} >conf$$files.sh && +. ./conf$$files.sh || + as_fn_error $? "could not make $CONFIG_STATUS" "$LINENO" 5 +rm -f conf$$files.sh + +{ + echo "cat >conf$$subs.awk <<_ACEOF" && + echo "$ac_subst_vars" | sed 's/.*/&!$&$ac_delim/' && + echo "_ACEOF" +} >conf$$subs.sh || + as_fn_error $? "could not make $CONFIG_STATUS" "$LINENO" 5 +ac_delim_num=`echo "$ac_subst_vars" | grep -c '^'` +ac_delim='%!_!# ' +for ac_last_try in false false false false false :; do + . ./conf$$subs.sh || + as_fn_error $? "could not make $CONFIG_STATUS" "$LINENO" 5 + + ac_delim_n=`sed -n "s/.*$ac_delim\$/X/p" conf$$subs.awk | grep -c X` + if test $ac_delim_n = $ac_delim_num; then + break + elif $ac_last_try; then + as_fn_error $? "could not make $CONFIG_STATUS" "$LINENO" 5 + else + ac_delim="$ac_delim!$ac_delim _$ac_delim!! " + fi +done +rm -f conf$$subs.sh + +cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 +cat >>"\$ac_tmp/subs1.awk" <<\\_ACAWK && +_ACEOF +sed -n ' +h +s/^/S["/; s/!.*/"]=/ +p +g +s/^[^!]*!// +:repl +t repl +s/'"$ac_delim"'$// +t delim +:nl +h +s/\(.\{148\}\)..*/\1/ +t more1 +s/["\\]/\\&/g; s/^/"/; s/$/\\n"\\/ +p +n +b repl +:more1 +s/["\\]/\\&/g; s/^/"/; s/$/"\\/ +p +g +s/.\{148\}// +t nl +:delim +h +s/\(.\{148\}\)..*/\1/ +t more2 +s/["\\]/\\&/g; s/^/"/; s/$/"/ +p +b +:more2 +s/["\\]/\\&/g; s/^/"/; s/$/"\\/ +p +g +s/.\{148\}// +t delim +' <conf$$subs.awk | sed ' +/^[^""]/{ + N + s/\n// +} +' >>$CONFIG_STATUS || ac_write_fail=1 +rm -f conf$$subs.awk +cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 +_ACAWK +cat >>"\$ac_tmp/subs1.awk" <<_ACAWK && + for (key in S) S_is_set[key] = 1 + FS = "" + \$ac_cs_awk_pipe_init +} +{ + line = $ 0 + nfields = split(line, field, "@") + substed = 0 + len = length(field[1]) + for (i = 2; i < nfields; i++) { + key = field[i] + keylen = length(key) + if (S_is_set[key]) { + value = S[key] + line = substr(line, 1, len) "" value "" substr(line, len + keylen + 3) + len += length(value) + length(field[++i]) + substed = 1 + } else + len += 1 + keylen + } + if (nfields == 3 && !substed) { + key = field[2] + if (F[key] != "" && line ~ /^[ ]*@.*@[ ]*$/) { + \$ac_cs_awk_read_file + next + } + } + print line +} +\$ac_cs_awk_pipe_fini +_ACAWK +_ACEOF +cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 +if sed "s/$ac_cr//" < /dev/null > /dev/null 2>&1; then + sed "s/$ac_cr\$//; s/$ac_cr/$ac_cs_awk_cr/g" +else + cat +fi < "$ac_tmp/subs1.awk" > "$ac_tmp/subs.awk" \ + || as_fn_error $? "could not setup config files machinery" "$LINENO" 5 +_ACEOF + +# VPATH may cause trouble with some makes, so we remove sole $(srcdir), +# ${srcdir} and @srcdir@ entries from VPATH if srcdir is ".", strip leading and +# trailing colons and then remove the whole line if VPATH becomes empty +# (actually we leave an empty line to preserve line numbers). +if test "x$srcdir" = x.; then + ac_vpsub='/^[ ]*VPATH[ ]*=[ ]*/{ +h +s/// +s/^/:/ +s/[ ]*$/:/ +s/:\$(srcdir):/:/g +s/:\${srcdir}:/:/g +s/:@srcdir@:/:/g +s/^:*// +s/:*$// +x +s/\(=[ ]*\).*/\1/ +G +s/\n// +s/^[^=]*=[ ]*$// +}' +fi + +cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 +fi # test -n "$CONFIG_FILES" + +# Set up the scripts for CONFIG_HEADERS section. +# No need to generate them if there are no CONFIG_HEADERS. +# This happens for instance with `./config.status Makefile'. +if test -n "$CONFIG_HEADERS"; then +cat >"$ac_tmp/defines.awk" <<\_ACAWK || +BEGIN { +_ACEOF + +# Transform confdefs.h into an awk script `defines.awk', embedded as +# here-document in config.status, that substitutes the proper values into +# config.h.in to produce config.h. + +# Create a delimiter string that does not exist in confdefs.h, to ease +# handling of long lines. +ac_delim='%!_!# ' +for ac_last_try in false false :; do + ac_tt=`sed -n "/$ac_delim/p" confdefs.h` + if test -z "$ac_tt"; then + break + elif $ac_last_try; then + as_fn_error $? "could not make $CONFIG_HEADERS" "$LINENO" 5 + else + ac_delim="$ac_delim!$ac_delim _$ac_delim!! " + fi +done + +# For the awk script, D is an array of macro values keyed by name, +# likewise P contains macro parameters if any. Preserve backslash +# newline sequences. + +ac_word_re=[_$as_cr_Letters][_$as_cr_alnum]* +sed -n ' +s/.\{148\}/&'"$ac_delim"'/g +t rset +:rset +s/^[ ]*#[ ]*define[ ][ ]*/ / +t def +d +:def +s/\\$// +t bsnl +s/["\\]/\\&/g +s/^ \('"$ac_word_re"'\)\(([^()]*)\)[ ]*\(.*\)/P["\1"]="\2"\ +D["\1"]=" \3"/p +s/^ \('"$ac_word_re"'\)[ ]*\(.*\)/D["\1"]=" \2"/p +d +:bsnl +s/["\\]/\\&/g +s/^ \('"$ac_word_re"'\)\(([^()]*)\)[ ]*\(.*\)/P["\1"]="\2"\ +D["\1"]=" \3\\\\\\n"\\/p +t cont +s/^ \('"$ac_word_re"'\)[ ]*\(.*\)/D["\1"]=" \2\\\\\\n"\\/p +t cont +d +:cont +n +s/.\{148\}/&'"$ac_delim"'/g +t clear +:clear +s/\\$// +t bsnlc +s/["\\]/\\&/g; s/^/"/; s/$/"/p +d +:bsnlc +s/["\\]/\\&/g; s/^/"/; s/$/\\\\\\n"\\/p +b cont +' <confdefs.h | sed ' +s/'"$ac_delim"'/"\\\ +"/g' >>$CONFIG_STATUS || ac_write_fail=1 + +cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 + for (key in D) D_is_set[key] = 1 + FS = "" +} +/^[\t ]*#[\t ]*(define|undef)[\t ]+$ac_word_re([\t (]|\$)/ { + line = \$ 0 + split(line, arg, " ") + if (arg[1] == "#") { + defundef = arg[2] + mac1 = arg[3] + } else { + defundef = substr(arg[1], 2) + mac1 = arg[2] + } + split(mac1, mac2, "(") #) + macro = mac2[1] + prefix = substr(line, 1, index(line, defundef) - 1) + if (D_is_set[macro]) { + # Preserve the white space surrounding the "#". + print prefix "define", macro P[macro] D[macro] + next + } else { + # Replace #undef with comments. This is necessary, for example, + # in the case of _POSIX_SOURCE, which is predefined and required + # on some systems where configure will not decide to define it. + if (defundef == "undef") { + print "/*", prefix defundef, macro, "*/" + next + } + } +} +{ print } +_ACAWK +_ACEOF +cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 + as_fn_error $? "could not setup config headers machinery" "$LINENO" 5 +fi # test -n "$CONFIG_HEADERS" + + +eval set X " :F $CONFIG_FILES :H $CONFIG_HEADERS :C $CONFIG_COMMANDS" +shift +for ac_tag +do + case $ac_tag in + :[FHLC]) ac_mode=$ac_tag; continue;; + esac + case $ac_mode$ac_tag in + :[FHL]*:*);; + :L* | :C*:*) as_fn_error $? "invalid tag \`$ac_tag'" "$LINENO" 5;; + :[FH]-) ac_tag=-:-;; + :[FH]*) ac_tag=$ac_tag:$ac_tag.in;; + esac + ac_save_IFS=$IFS + IFS=: + set x $ac_tag + IFS=$ac_save_IFS + shift + ac_file=$1 + shift + + case $ac_mode in + :L) ac_source=$1;; + :[FH]) + ac_file_inputs= + for ac_f + do + case $ac_f in + -) ac_f="$ac_tmp/stdin";; + *) # Look for the file first in the build tree, then in the source tree + # (if the path is not absolute). The absolute path cannot be DOS-style, + # because $ac_f cannot contain `:'. + test -f "$ac_f" || + case $ac_f in + [\\/$]*) false;; + *) test -f "$srcdir/$ac_f" && ac_f="$srcdir/$ac_f";; + esac || + as_fn_error 1 "cannot find input file: \`$ac_f'" "$LINENO" 5;; + esac + case $ac_f in *\'*) ac_f=`printf "%s\n" "$ac_f" | sed "s/'/'\\\\\\\\''/g"`;; esac + as_fn_append ac_file_inputs " '$ac_f'" + done + + # Let's still pretend it is `configure' which instantiates (i.e., don't + # use $as_me), people would be surprised to read: + # /* config.h. Generated by config.status. */ + configure_input='Generated from '` + printf "%s\n" "$*" | sed 's|^[^:]*/||;s|:[^:]*/|, |g' + `' by configure.' + if test x"$ac_file" != x-; then + configure_input="$ac_file. $configure_input" + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: creating $ac_file" >&5 +printf "%s\n" "$as_me: creating $ac_file" >&6;} + fi + # Neutralize special characters interpreted by sed in replacement strings. + case $configure_input in #( + *\&* | *\|* | *\\* ) + ac_sed_conf_input=`printf "%s\n" "$configure_input" | + sed 's/[\\\\&|]/\\\\&/g'`;; #( + *) ac_sed_conf_input=$configure_input;; + esac + + case $ac_tag in + *:-:* | *:-) cat >"$ac_tmp/stdin" \ + || as_fn_error $? "could not create $ac_file" "$LINENO" 5 ;; + esac + ;; + esac + + ac_dir=`$as_dirname -- "$ac_file" || +$as_expr X"$ac_file" : 'X\(.*[^/]\)//*[^/][^/]*/*$' \| \ + X"$ac_file" : 'X\(//\)[^/]' \| \ + X"$ac_file" : 'X\(//\)$' \| \ + X"$ac_file" : 'X\(/\)' \| . 2>/dev/null || +printf "%s\n" X"$ac_file" | + sed '/^X\(.*[^/]\)\/\/*[^/][^/]*\/*$/{ + s//\1/ + q + } + /^X\(\/\/\)[^/].*/{ + s//\1/ + q + } + /^X\(\/\/\)$/{ + s//\1/ + q + } + /^X\(\/\).*/{ + s//\1/ + q + } + s/.*/./; q'` + as_dir="$ac_dir"; as_fn_mkdir_p + ac_builddir=. + +case "$ac_dir" in +.) ac_dir_suffix= ac_top_builddir_sub=. ac_top_build_prefix= ;; +*) + ac_dir_suffix=/`printf "%s\n" "$ac_dir" | sed 's|^\.[\\/]||'` + # A ".." for each directory in $ac_dir_suffix. + ac_top_builddir_sub=`printf "%s\n" "$ac_dir_suffix" | sed 's|/[^\\/]*|/..|g;s|/||'` + case $ac_top_builddir_sub in + "") ac_top_builddir_sub=. ac_top_build_prefix= ;; + *) ac_top_build_prefix=$ac_top_builddir_sub/ ;; + esac ;; +esac +ac_abs_top_builddir=$ac_pwd +ac_abs_builddir=$ac_pwd$ac_dir_suffix +# for backward compatibility: +ac_top_builddir=$ac_top_build_prefix + +case $srcdir in + .) # We are building in place. + ac_srcdir=. + ac_top_srcdir=$ac_top_builddir_sub + ac_abs_top_srcdir=$ac_pwd ;; + [\\/]* | ?:[\\/]* ) # Absolute name. + ac_srcdir=$srcdir$ac_dir_suffix; + ac_top_srcdir=$srcdir + ac_abs_top_srcdir=$srcdir ;; + *) # Relative name. + ac_srcdir=$ac_top_build_prefix$srcdir$ac_dir_suffix + ac_top_srcdir=$ac_top_build_prefix$srcdir + ac_abs_top_srcdir=$ac_pwd/$srcdir ;; +esac +ac_abs_srcdir=$ac_abs_top_srcdir$ac_dir_suffix + + + case $ac_mode in + :F) + # + # CONFIG_FILE + # + + case $INSTALL in + [\\/$]* | ?:[\\/]* ) ac_INSTALL=$INSTALL ;; + *) ac_INSTALL=$ac_top_build_prefix$INSTALL ;; + esac +_ACEOF + +cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 +# If the template does not know about datarootdir, expand it. +# FIXME: This hack should be removed a few years after 2.60. +ac_datarootdir_hack=; ac_datarootdir_seen= +ac_sed_dataroot=' +/datarootdir/ { + p + q +} +/@datadir@/p +/@docdir@/p +/@infodir@/p +/@localedir@/p +/@mandir@/p' +case `eval "sed -n \"\$ac_sed_dataroot\" $ac_file_inputs"` in +*datarootdir*) ac_datarootdir_seen=yes;; +*@datadir@*|*@docdir@*|*@infodir@*|*@localedir@*|*@mandir@*) + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: $ac_file_inputs seems to ignore the --datarootdir setting" >&5 +printf "%s\n" "$as_me: WARNING: $ac_file_inputs seems to ignore the --datarootdir setting" >&2;} +_ACEOF +cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 + ac_datarootdir_hack=' + s&@datadir@&$datadir&g + s&@docdir@&$docdir&g + s&@infodir@&$infodir&g + s&@localedir@&$localedir&g + s&@mandir@&$mandir&g + s&\\\${datarootdir}&$datarootdir&g' ;; +esac +_ACEOF + +# Neutralize VPATH when `$srcdir' = `.'. +# Shell code in configure.ac might set extrasub. +# FIXME: do we really want to maintain this feature? +cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 +ac_sed_extra="$ac_vpsub +$extrasub +_ACEOF +cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 +:t +/@[a-zA-Z_][a-zA-Z_0-9]*@/!b +s|@configure_input@|$ac_sed_conf_input|;t t +s&@top_builddir@&$ac_top_builddir_sub&;t t +s&@top_build_prefix@&$ac_top_build_prefix&;t t +s&@srcdir@&$ac_srcdir&;t t +s&@abs_srcdir@&$ac_abs_srcdir&;t t +s&@top_srcdir@&$ac_top_srcdir&;t t +s&@abs_top_srcdir@&$ac_abs_top_srcdir&;t t +s&@builddir@&$ac_builddir&;t t +s&@abs_builddir@&$ac_abs_builddir&;t t +s&@abs_top_builddir@&$ac_abs_top_builddir&;t t +s&@INSTALL@&$ac_INSTALL&;t t +$ac_datarootdir_hack +" +eval sed \"\$ac_sed_extra\" "$ac_file_inputs" | +if $ac_cs_awk_getline; then + $AWK -f "$ac_tmp/subs.awk" +else + $AWK -f "$ac_tmp/subs.awk" | $SHELL +fi \ + >$ac_tmp/out || as_fn_error $? "could not create $ac_file" "$LINENO" 5 + +test -z "$ac_datarootdir_hack$ac_datarootdir_seen" && + { ac_out=`sed -n '/\${datarootdir}/p' "$ac_tmp/out"`; test -n "$ac_out"; } && + { ac_out=`sed -n '/^[ ]*datarootdir[ ]*:*=/p' \ + "$ac_tmp/out"`; test -z "$ac_out"; } && + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: $ac_file contains a reference to the variable \`datarootdir' +which seems to be undefined. Please make sure it is defined" >&5 +printf "%s\n" "$as_me: WARNING: $ac_file contains a reference to the variable \`datarootdir' +which seems to be undefined. Please make sure it is defined" >&2;} + + rm -f "$ac_tmp/stdin" + case $ac_file in + -) cat "$ac_tmp/out" && rm -f "$ac_tmp/out";; + *) rm -f "$ac_file" && mv "$ac_tmp/out" "$ac_file";; + esac \ + || as_fn_error $? "could not create $ac_file" "$LINENO" 5 + ;; + :H) + # + # CONFIG_HEADER + # + if test x"$ac_file" != x-; then + { + printf "%s\n" "/* $configure_input */" >&1 \ + && eval '$AWK -f "$ac_tmp/defines.awk"' "$ac_file_inputs" + } >"$ac_tmp/config.h" \ + || as_fn_error $? "could not create $ac_file" "$LINENO" 5 + if diff "$ac_file" "$ac_tmp/config.h" >/dev/null 2>&1; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: $ac_file is unchanged" >&5 +printf "%s\n" "$as_me: $ac_file is unchanged" >&6;} + else + rm -f "$ac_file" + mv "$ac_tmp/config.h" "$ac_file" \ + || as_fn_error $? "could not create $ac_file" "$LINENO" 5 + fi + else + printf "%s\n" "/* $configure_input */" >&1 \ + && eval '$AWK -f "$ac_tmp/defines.awk"' "$ac_file_inputs" \ + || as_fn_error $? "could not create -" "$LINENO" 5 + fi + ;; + + :C) { printf "%s\n" "$as_me:${as_lineno-$LINENO}: executing $ac_file commands" >&5 +printf "%s\n" "$as_me: executing $ac_file commands" >&6;} + ;; + esac + + + case $ac_file$ac_mode in + "config.modules":C) . ./config.modules.sh ;; + "stamp-h":C) echo >stamp-h ;; + + esac +done # for ac_tag + + +as_fn_exit 0 +_ACEOF +ac_clean_files=$ac_clean_files_save + +test $ac_write_fail = 0 || + as_fn_error $? "write failure creating $CONFIG_STATUS" "$LINENO" 5 + + +# configure is writing to config.log, and then calls config.status. +# config.status does its own redirection, appending to config.log. +# Unfortunately, on DOS this fails, as config.log is still kept open +# by configure, so config.status won't be able to write to it; its +# output is simply discarded. So we exec the FD to /dev/null, +# effectively closing config.log, so it can be properly (re)opened and +# appended to by config.status. When coming back to configure, we +# need to make the FD available again. +if test "$no_create" != yes; then + ac_cs_success=: + ac_config_status_args= + test "$silent" = yes && + ac_config_status_args="$ac_config_status_args --quiet" + exec 5>/dev/null + $SHELL $CONFIG_STATUS $ac_config_status_args || ac_cs_success=false + exec 5>>config.log + # Use ||, not &&, to avoid exiting from the if with $? = 1, which + # would make configure fail if this is the last instruction. + $ac_cs_success || as_fn_exit 1 +fi +if test -n "$ac_unrecognized_opts" && test "$enable_option_checking" != no; then + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: unrecognized options: $ac_unrecognized_opts" >&5 +printf "%s\n" "$as_me: WARNING: unrecognized options: $ac_unrecognized_opts" >&2;} +fi + + +for manpage in `cd ${srcdir} && echo Doc/*.1`; do + if test x"$manpage" != x"Doc/*.1" && ! test -e "${manpage}"; then + cp ${srcdir}/${manpage} ./Doc/ + fi +done +if ! test -e Doc/help.txt; then + cp ${srcdir}/Doc/help.txt ./Doc/ +fi +mkdir -p ./Doc/help +for helpfile in `cd ${srcdir} && echo Doc/help/*`; do + if test x"$helpfile" != x"Doc/help/*" && ! test -e "${helpfile}"; then + cp ${srcdir}/${helpfile} ./Doc/help/ + fi +done + +eval "zshbin1=${bindir}" +eval "zshbin2=${zshbin1}" +eval "zshman1=${mandir}" +eval "zshman2=${zshman1}" +eval "zshinfo1=${infodir}" +eval "zshinfo2=${zshinfo1}" +eval "zshfndir1=${fndir}" +eval "zshfndir2=${zshfndir1}" + +echo " +zsh configuration +----------------- +zsh version : ${VERSION} +host operating system : ${host_cpu}-${host_vendor}-${host_os} +source code location : ${srcdir} +compiler : ${CC} +preprocessor flags : ${CPPFLAGS} +executable compiler flags : ${CFLAGS}" +if test "x$dynamic" = xyes; then + echo "\ +module compiler flags : ${CFLAGS} ${DLCFLAGS}" +fi +echo "\ +executable linker flags : ${LDFLAGS} ${EXELDFLAGS} ${EXTRA_LDFLAGS}" +if test "x$dynamic" = xyes; then + echo "\ +module linker flags : ${LDFLAGS} ${LIBLDFLAGS} ${DLLDFLAGS}" +fi +echo "\ +library flags : ${LIBS} +installation basename : ${tzsh_name} +binary install path : ${zshbin2} +man page install path : ${zshman2} +info install path : ${zshinfo2}" +if test "$zshfndir2" != no; then + echo "functions install path : ${zshfndir2}" +fi +if test "x$additionalfpath" != x; then + echo "additional fpath entries : ${additionalfpath}" +fi +echo "See config.modules for installed modules and functions. +" + +if test x$zsh_cv_c_unicode_support != xyes; then + if test "x$zfuncs_absent" = x; then + # The user opted out. + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: You have chosen to build without multibyte support." >&5 +printf "%s\n" "$as_me: WARNING: You have chosen to build without multibyte support." >&2;} + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: This configuration may not be suitable for production use. It is known to cause errors in 'make test'. We strongly recommend to re-run configure with --enable-multibyte." >&5 +printf "%s\n" "$as_me: WARNING: This configuration may not be suitable for production use. It is known to cause errors in 'make test'. We strongly recommend to re-run configure with --enable-multibyte." >&2;} + else + # Some requisite functions are missing. + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: Multibyte support cannot be enabled: some standard library functions are missing: $zfuncs_absent" >&5 +printf "%s\n" "$as_me: WARNING: Multibyte support cannot be enabled: some standard library functions are missing: $zfuncs_absent" >&2;} + { printf "%s\n" "$as_me:${as_lineno-$LINENO}: WARNING: This configuration may not be suitable for production use. It is known to cause errors in 'make test'. If your system provides those functions, we recommend to re-run configure appropriately." >&5 +printf "%s\n" "$as_me: WARNING: This configuration may not be suitable for production use. It is known to cause errors in 'make test'. If your system provides those functions, we recommend to re-run configure appropriately." >&2;} + # If your system doesn't have those functions, consider patching the + # test suite and sending the patch to zsh-workers@ for inclusion. + fi +fi + +exit 0 + diff --git a/stamp-h.in b/stamp-h.in new file mode 100644 index 000000000..8b1378917 --- /dev/null +++ b/stamp-h.in @@ -0,0 +1 @@ + |