diff options
| author | Craig Jennings <c@cjennings.net> | 2025-10-12 11:47:26 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2025-10-12 11:47:26 -0500 |
| commit | 092304d9e0ccc37cc0ddaa9b136457e56a1cac20 (patch) | |
| tree | ea81999b8442246c978b364dd90e8c752af50db5 /assets/info/zsh.info-2 | |
changing repositories
Diffstat (limited to 'assets/info/zsh.info-2')
| -rw-r--r-- | assets/info/zsh.info-2 | 6945 |
1 files changed, 6945 insertions, 0 deletions
diff --git a/assets/info/zsh.info-2 b/assets/info/zsh.info-2 new file mode 100644 index 00000000..efadefa0 --- /dev/null +++ b/assets/info/zsh.info-2 @@ -0,0 +1,6945 @@ +This is zsh.info, produced by makeinfo version 4.8 from ./zsh.texi. + +INFO-DIR-SECTION Utilities +START-INFO-DIR-ENTRY +* ZSH: (zsh). The Z Shell Manual. +END-INFO-DIR-ENTRY + + +File: zsh.info, Node: Parameters Used By The Shell, Prev: Parameters Set By The Shell, Up: Parameters + +15.6 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 sh or ksh emulation mode. + +In cases where there are two parameters with an upper- and lowercase +form of the same name, such as path and 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 `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. + + +ARGV0 + If exported, its value is used as the argv[0] of external commands. + Usually used in constructs like `ARGV0=emacs nethack'. + +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. + + 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. + +cdpath <S> <Z> (CDPATH <S>) + An array (colon-separated list) of directories specifying the + search path for the cd command. + +COLUMNS <S> + The number of columns for this terminal session. Used for + printing select lists and for the line editor. + +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 `_*' then completion functions (which, by + convention, have names beginning with `_') will never be offered + as spelling corrections. The pattern does not apply to the + correction of file names, as applied by the CORRECT_ALL option (so + with the example just given files beginning with `_' in the current + directory would still be completed). + +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 `.*' then dot file + names will never be offered as spelling corrections. This is + useful with the CORRECT_ALL option. + +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 AUTO_PUSHD option. + +ENV + If the ENV environment variable is set when zsh is invoked as sh + or ksh, $ENV is sourced after the profile scripts. The value of + ENV is subjected to parameter expansion, command substitution, and + arithmetic expansion before being interpreted as a pathname. Note + that ENV is _not_ used unless the shell is interactive and zsh is + emulating `sh' or `ksh'. + +FCEDIT + The default editor for the fc builtin. If FCEDIT is not set, the + parameter EDITOR is used; if that is not set either, a builtin + default, usually vi, is used. + +fignore <S> <Z> (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. + +fpath <S> <Z> (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 -u attribute is referenced. If an executable + file is found, then it is read and executed in the current + environment. + +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 `!'). The second character signals the start + of a quick history substitution (default `^'). The third + character is the comment character (default `#'). + + The characters must be in the ASCII character set; any attempt to + set histchars to characters with a locale-dependent meaning will be + rejected with an error message. + +HISTCHARS <S> <Z> + Same as histchars. (Deprecated.) + +HISTFILE + The file to save the history in when an interactive shell exits. + If unset, the history is not saved. + +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 `fc *' then commands that + invoke the interactive history editor are never written to the + history file. + + Note that HISTORY_IGNORE defines a single pattern: to specify + alternatives use the `(FIRST|SECOND|...)' syntax. + + Compare the HIST_NO_STORE option or the zshaddhistory hook, either + of which would prevent such commands from being added to the + interactive history at all. If you wish to use HISTORY_IGNORE to + stop history being added in the first place, you can define the + following hook: + + + zshaddhistory() { + emulate -L zsh + ## uncomment if HISTORY_IGNORE + ## should use EXTENDED_GLOB syntax + # setopt extendedglob + [[ $1 != ${~HISTORY_IGNORE} ]] + } + +HISTSIZE <S> + The maximum number of events stored in the internal history list. + If you use the HIST_EXPIRE_DUPS_FIRST option, setting this value + larger than the SAVEHIST size will give you the difference as a + cushion for saving duplicated history events. + + If this is made local, it is not implicitly set to 0, but may be + explicitly set locally. + +HOME <S> + The default argument for the cd command. This is not set + automatically by the shell in sh, ksh or csh emulation, but it is + typically present in the environment anyway, and if it becomes set + it has its usual special behaviour. + +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 read builtin. Any + characters from the set space, tab and newline that appear in the + IFS are called _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. + + If the parameter is unset, the default is used. Note this has a + different effect from setting the parameter to an empty string. + +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 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. + + For backward compatibility, if the SUNKEYBOARDHACK option is + explicitly set, the value of KEYBOARD_HACK reverts to backquote. + If the option is explicitly unset, this variable is set to empty. + +KEYTIMEOUT + The time the shell waits, in hundredths of seconds, for another + key to be pressed when reading bound multi-character sequences. + +LANG <S> + This variable determines the locale category for any category not + specifically selected via a variable starting with `LC_'. + +LC_ALL <S> + This variable overrides the value of the `LANG' variable and the + value of any of the other variables starting with `LC_'. + +LC_COLLATE <S> + This variable determines the locale category for character + collation information within ranges in glob brackets and for + sorting. + +LC_CTYPE <S> + This variable determines the locale category for character handling + functions. If the MULTIBYTE option is in effect this variable or + 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 en_US.iso88591 (certain + Linux distributions) or en_US.ISO8859-1 (MacOS). + +LC_MESSAGES <S> + This variable determines the language in which messages should be + written. Note that zsh does not use message catalogs. + +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. + +LC_TIME <S> + This variable determines the locale category for date and time + formatting in prompt escape sequences. + +LINES <S> + The number of lines for this terminal session. Used for printing + select lists and for the line editor. + +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. + +LOGCHECK + The interval in seconds between checks for login/logout activity + using the watch parameter. + +MAIL + If this parameter is set and mailpath is not set, the shell looks + for mail in the specified file. + +MAILCHECK + The interval in seconds between checks for new mail. + +mailpath <S> <Z> (MAILPATH <S>) + An array (colon-separated list) of filenames to check for new + mail. Each filename can be followed by a `?' and a message that + will be printed. The message will undergo parameter expansion, + command substitution and arithmetic expansion with the variable $_ + defined as the name of the file that has changed. The default + message is `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. + +manpath <S> <Z> (MANPATH <S> <Z>) + An array (colon-separated list) whose value is not used by the + shell. The manpath array can be useful, however, since setting it + also sets MANPATH, and vice versa. + +match +mbegin +mend + Arrays set by the shell when the b globbing flag is used in pattern + matches. See the subsection _Globbing flags_ in *Note Filename + Generation::. + +MATCH +MBEGIN +MEND + Set by the shell when the m globbing flag is used in pattern + matches. See the subsection _Globbing flags_ in *Note Filename + Generation::. + +module_path <S> <Z> (MODULE_PATH <S>) + An array (colon-separated list) of directories that zmodload + searches for dynamically loadable modules. This is initialized to + a standard pathname, usually `/usr/local/lib/zsh/$ZSH_VERSION'. + (The `/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. + + These parameters only exist if the installation supports dynamic + module loading. + +NULLCMD <S> + The command name to assume if a redirection is specified with no + command. Defaults to cat. For `sh'/`ksh' behavior, change this + to :. For `csh'-like behavior, unset this parameter; the shell + will print an error message if null commands are entered. + +path <S> <Z> (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. + +POSTEDIT <S> + This string is output whenever the line editor exits. It usually + contains termcap strings to reset the terminal. + +PROMPT <S> <Z> +PROMPT2 <S> <Z> +PROMPT3 <S> <Z> +PROMPT4 <S> <Z> + Same as PS1, PS2, PS3 and PS4, respectively. + +prompt <S> <Z> + Same as PS1. + +PROMPT_EOL_MARK + When the PROMPT_CR and PROMPT_SP options are set, the + PROMPT_EOL_MARK parameter can be used to customize how the end of + partial lines are shown. This parameter undergoes prompt + expansion, with the PROMPT_PERCENT option set. If not set, the + default behavior is equivalent to the value `%B%S%#%s%b'. + +PS1 <S> + The primary prompt string, printed before a command is read. It + undergoes a special form of expansion before being displayed; see + *Note Prompt Expansion::. The default is `%m%# '. + +PS2 <S> + The secondary prompt, printed when the shell needs more information + to complete a command. It is expanded in the same way as PS1. + The default is `%_> ', which displays any shell constructs or + quotation marks which are currently being processed. + +PS3 <S> + Selection prompt used within a select loop. It is expanded in the + same way as PS1. The default is `?# '. + +PS4 <S> + The execution trace prompt. Default is `+%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 `+ '. + +psvar <S> <Z> (PSVAR <S>) + An array (colon-separated list) whose elements can be used in + PROMPT strings. Setting psvar also sets PSVAR, and vice versa. + +READNULLCMD <S> + The command name to assume if a single input redirection is + specified with no command. Defaults to more. + +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 TIMEFMT parameter, which is the same + as for the REPORTTIME variable and the time builtin; note that by + default this does not output memory usage. Appending " max RSS + %M" to the value of TIMEFMT causes it to output the value that + triggered the report. If REPORTTIME is also in use, at most a + single report is printed for both triggers. This feature requires + the getrusage() system call, commonly supported by modern + Unix-like systems. + +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 time keyword still cause the summary to + be printed in this case. + +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 + read builtin and the select complex command may set REPLY, and + filename generation both sets and examines its value when + evaluating certain expressions. Some modules also employ REPLY + for similar purposes. + +reply + As REPLY, but for array values rather than strings. + +RPROMPT <S> +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 SINGLE_LINE_ZLE option is set. It is expanded in the + same way as PS1. + +RPROMPT2 <S> +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 SINGLE_LINE_ZLE option is set. It is expanded in + the same way as PS2. + +SAVEHIST + The maximum number of history events to save in the history file. + + If this is made local, it is not implicitly set to 0, but may be + explicitly set locally. + +SPROMPT <S> + The prompt used for spelling correction. The sequence `%R' + expands to the string which presumably needs spelling correction, + and `%r' expands to the proposed correction. All other prompt + escapes are also allowed. + + The actions available at the prompt are [nyae]: + n (`no') (default) + Discard the correction and run the command. + + y (`yes') + Make the correction and run the command. + + a (`abort') + Discard the entire command line without running it. + + e (`edit') + Resume editing the command line. + +STTY + If this parameter is set in a command's environment, the shell + runs the 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 fg or wait builtins it will see the modes + specified by STTY, as if it were not suspended. This + (intentionally) does not apply if the command is continued via + `kill -CONT'. 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 STTY should not be used for window size specifications; these + will not be local to the command. + +TERM <S> + The type of terminal in use. This is used when looking up termcap + sequences. An assignment to TERM causes zsh to re-initialize the + terminal, even if the value does not change (e.g., `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. + +TERMINFO <S> + A reference to your terminfo database, used by the `terminfo' + library when the system has it; see man page terminfo(5). If set, + this causes the shell to reinitialise the terminal, making the + workaround `TERM=$TERM' unnecessary. + +TERMINFO_DIRS <S> + A colon-seprarated list of terminfo databases, used by the + `terminfo' library when the system has it; see man page + terminfo(5). This variable is only used by certain terminal + libraries, in particular ncurses; see man page terminfo(5) to + check support on your system. If set, this causes the shell to + reinitialise the terminal, making the workaround `TERM=$TERM' + unnecessary. Note that unlike other colon-separated arrays this + is not tied to a zsh array. + +TIMEFMT + The format of process time reports with the time keyword. The + default is `%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: + + + %% + A `%'. + + %U + CPU seconds spent in user mode. + + %S + CPU seconds spent in kernel mode. + + %E + Elapsed time in seconds. + + %P + The CPU percentage, computed as 100*(%U+%S)/%E. + + %W + Number of times the process was swapped. + + %X + The average amount in (shared) text space used in kilobytes. + + %D + The average amount in (unshared) data/stack space used in + kilobytes. + + %K + The total space used (%X+%D) in kilobytes. + + %M + The maximum memory the process had in use at any time in + kilobytes. + + %F + The number of major page faults (page needed to be brought + from disk). + + %R + The number of minor page faults. + + %I + The number of input operations. + + %O + The number of output operations. + + %r + The number of socket messages received. + + %s + The number of socket messages sent. + + %k + The number of signals received. + + %w + Number of voluntary context switches (waits). + + %c + Number of involuntary context switches. + + %J + The name of this job. + + A star may be inserted between the percent sign and flags printing + time (e.g., `%*E'); this causes the time to be printed in + `HH:MM:SS.TTT' format (hours and minutes are only printed if they + are not zero). Alternatively, `m' or `u' may be used (e.g., + `%mE') to produce time output in milliseconds or microseconds, + respectively. + +TMOUT + If this parameter is nonzero, the shell will receive an ALRM + signal if a command is not entered within the specified number of + seconds after issuing a prompt. If there is a trap on SIGALRM, it + will be executed and a new alarm is scheduled using the value of + the 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 + TMOUT parameter, zsh terminates. Otherwise a new alarm is + scheduled to TMOUT seconds after the last keypress. + +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 `/tmp/zsh'. + +TMPSUFFIX + A filename suffix which the shell will use for temporary files + created by process substitutions (e.g., `=(LIST)'). Note that the + value should include a leading dot `.' 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. + +watch <S> <Z> (WATCH <S>) + An array (colon-separated list) of login/logout events to report. + + If it contains the single word `all', then all login/logout events + are reported. If it contains the single word `notme', then all + events are reported as with `all' except $USERNAME. + + An entry in this list may consist of a username, an `@' followed + by a remote hostname, and a `%' followed by a line (tty). Any of + these may be a pattern (be sure to quote this during the + assignment to watch so that it does not immediately perform file + generation); the setting of the 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. + + For example, with the EXTENDED_GLOB option set, the following: + + + watch=('^(pws|barts)') + + causes reports for activity associated with any user other than pws + or barts. + +WATCHFMT + The format of login/logout reports if the watch parameter is set. + Default is `%n has %a %l from %m'. Recognizes the following + escape sequences: + + + %n + The name of the user that logged in/out. + + %a + The observed action, i.e. "logged on" or "logged off". + + %l + The line (tty) the user is logged in on. + + %M + The full hostname of the remote host. + + %m + The hostname up to the first `.'. If only the IP address is + available or the utmp field contains the name of an X-windows + display, the whole name is printed. + + _NOTE:_ The `%m' and `%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. + + %S (%s) + Start (stop) standout mode. + + %U (%u) + Start (stop) underline mode. + + %B (%b) + Start (stop) boldface mode. + + %t + %@ + The time, in 12-hour, am/pm format. + + %T + The time, in 24-hour format. + + %w + The date in `DAY-DD' format. + + %W + The date in `MM/DD/YY' format. + + %D + The date in `YY-MM-DD' format. + + %D{STRING} + The date formatted as STRING using the strftime function, with + zsh extensions as described by *Note Prompt Expansion::. + + %(X:TRUE-TEXT:FALSE-TEXT) + Specifies a ternary expression. The character following the + X is arbitrary; the same character is used to separate the + text for the "true" result from that for the "false" result. + Both the separator and the right parenthesis may be escaped + with a backslash. Ternary expressions may be nested. + + The test character X may be any one of `l', `n', `m' or `M', + which indicate a `true' result if the corresponding escape + sequence would return a non-empty value; or it may be `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. + + If the result is `true', then the TRUE-TEXT is formatted + according to the rules above and printed, and the FALSE-TEXT + is skipped. If `false', the TRUE-TEXT is skipped and the + FALSE-TEXT is formatted and printed. Either or both of the + branches may be empty, but both separators must be present in + any case. + + +WORDCHARS <S> + A list of non-alphanumeric characters considered part of a word by + the line editor. + +ZBEEP + If set, this gives a string of characters, which can use all the + same codes as the bindkey command as described in *Note 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 `\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 + `\e[?5l\e[?5h' instead). This takes precedence over the NOBEEP + option. + +ZDOTDIR + The directory to search for shell startup files (.zshrc, etc), if + not $HOME. + +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. + + 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. + +zle_highlight + An array describing contexts in which ZLE should highlight the + input text. See *Note Character Highlighting::. + +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. + `print -zr - $ZLE_LINE_ABORTED' can be used to recover the line. + Only the most recent line of this kind is remembered. + +ZLE_REMOVE_SUFFIX_CHARS +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. + + These variables can contain the sets of characters that will cause + the suffix to be removed. If ZLE_REMOVE_SUFFIX_CHARS is set, those + characters will cause the suffix to be removed; if + ZLE_SPACE_SUFFIX_CHARS is set, those characters will cause the + suffix to be removed and replaced by a space. + + If ZLE_REMOVE_SUFFIX_CHARS is not set, the default behaviour is + equivalent to: + + + ZLE_REMOVE_SUFFIX_CHARS=$' \t\n;&|' + + If ZLE_REMOVE_SUFFIX_CHARS is set but is empty, no characters have + this behaviour. ZLE_SPACE_SUFFIX_CHARS takes precedence, so that + the following: + + + ZLE_SPACE_SUFFIX_CHARS=$'&|' + + causes the characters `&' and `|' to remove the suffix but to + replace it with a space. + + To illustrate the difference, suppose that the option + AUTO_REMOVE_SLASH is in effect and the directory DIR has just been + completed, with an appended /, following which the user types `&'. + The default result is `DIR&'. With ZLE_REMOVE_SUFFIX_CHARS set + but without including `&' the result is `DIR/&'. With + ZLE_SPACE_SUFFIX_CHARS set to include `&' the result is `DIR &'. + + 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 *Note Completion + System::. + +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 RPS1 or RPROMPT + and the right hand side of the screen. If not set, the value 1 is + used. + + 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. + + + +File: zsh.info, Node: Options, Next: Shell Builtin Commands, Prev: Parameters, Up: Top + +16 Options +********** + + + +* Menu: + +* Specifying Options:: +* Description of Options:: +* Option Aliases:: +* Single Letter Options:: + + +File: zsh.info, Node: Specifying Options, Next: Description of Options, Up: Options + +16.1 Specifying Options +======================= + +Options are primarily referred to by name. These names are case +insensitive and underscores are ignored. For example, `allexport' is +equivalent to `A__lleXP_ort'. + +The sense of an option name may be inverted by preceding it with `no', +so `setopt No_Beep' is equivalent to `unsetopt beep'. This inversion +can only be done once, so `nonobeep' is _not_ a synonym for `beep'. +Similarly, `tify' is not a synonym for `nonotify' (the inversion of +`notify'). + +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 `sh'/`ksh' (used when the SH_OPTION_LETTERS option is set). +The single letter options can be used on the shell command line, or +with the set, setopt and unsetopt builtins, as normal Unix options +preceded by `-'. + +The sense of the single letter options may be inverted by using `+' +instead of `-'. 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, `+n' is the short name of `exec', and +`-n' is the short name of its inversion, `noexec'. + +In strings of single letter options supplied to the shell at startup, +trailing whitespace will be ignored; for example the string `-f ' +will be treated just as `-f', but the string `-f i' is an error. This +is because many systems which implement the `#!' mechanism for calling +scripts do not strip trailing whitespace. + + + + +File: zsh.info, Node: Description of Options, Next: Option Aliases, Prev: Specifying Options, Up: Options + +16.2 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 `setopt', `unsetopt', `set -o' or `set +o'), those turned +on by default appear in the list prefixed with `no'. Hence (unless +KSH_OPTION_PRINT is set), `setopt' shows all options whose settings are +changed from the default. + + + +16.2.1 Changing Directories +--------------------------- + + +AUTO_CD (-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 cd command + to that directory. This option is only applicable if the option + 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 cd be used explicitly in scripts to avoid + ambiguity. + +AUTO_PUSHD (-N) + Make cd push the old directory onto the directory stack. + +CDABLE_VARS (-T) + If the argument to a cd command (or an implied cd with the 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 `~' (see + *Note Filename Expansion::). + +CD_SILENT + Never print the working directory after a cd (whether explicit or + implied with the AUTO_CD option set). cd normally prints the + working directory when the argument given to it was -, a stack + entry, or the name of a directory found under CDPATH. Note that + this is distinct from pushd's stack-printing behaviour, which is + controlled by PUSHD_SILENT. This option overrides the + printing-related effects of POSIX_CD. + +CHASE_DOTS + When changing to a directory containing a path segment `..' which + would otherwise be treated as canceling the previous segment in + the path (in other words, `foo/..' would be removed from the path, + or if `..' 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 + CHASE_LINKS. + + For example, suppose /foo/bar is a link to the directory /alt/rod. + Without this option set, `cd /foo/bar/..' changes to /foo; with it + set, it changes to /alt. The same applies if the current directory + is /foo/bar and `cd ..' is used. Note that all other symbolic + links in the path will also be resolved. + +CHASE_LINKS (-w) + Resolve symbolic links to their true values when changing + directory. This also has the effect of CHASE_DOTS, i.e. a `..' + path segment will be treated as referring to the physical parent, + even if the preceding path segment is a symbolic link. + +POSIX_CD <K> <S> + Modifies the behaviour of cd, chdir and pushd commands to make + them more compatible with the POSIX standard. The behaviour with + the option unset is described in the documentation for the cd + builtin in *Note Shell Builtin Commands::. If the option is set, + the shell does not test for directories beneath the local + directory (`.') until after all directories in cdpath have been + tested, and the cd and chdir commands do not recognise arguments + of the form `{+|-}N' as directory stack entries. + + 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 pushd is still limited to interactive + shells); and any use of a component of CDPATH, including a `.' but + excluding an empty component that is otherwise treated as `.', + causes the directory to be printed. + +PUSHD_IGNORE_DUPS + Don't push multiple copies of the same directory onto the + directory stack. + +PUSHD_MINUS + Exchanges the meanings of `+' and `-' when used with a number to + specify a directory in the stack. + +PUSHD_SILENT (-E) + Do not print the directory stack after pushd or popd. + +PUSHD_TO_HOME (-D) + Have pushd with no arguments act like `pushd $HOME'. + + + +16.2.2 Completion +----------------- + + +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 _no_ numeric argument. + +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. + +AUTO_LIST (-9) <D> + Automatically list choices on an ambiguous completion. + +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 MENU_COMPLETE. + +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 `%~' and related prompt sequences, and will be available + when completion is performed on a word starting with `~'. + (Otherwise, the parameter must be used in the form `~PARAM' first.) + +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 `}', `:', 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 `,', which will be removed if + `}' is typed next. + +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. + +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. + +BASH_AUTO_LIST + On an ambiguous completion, automatically list choices when the + completion function is called twice in succession. This takes + precedence over AUTO_LIST. The setting of LIST_AMBIGUOUS is + respected. If AUTO_MENU is set, the menu behaviour will then start + with the third press. Note that this will not work with + MENU_COMPLETE, since repeated completion calls immediately cycle + through the list in that case. + +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. + +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. + +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 MENU_COMPLETE. The matches + are generated as if a `*' was added to the end of the word, or + inserted at the cursor when 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. + + 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 GLOB_COMPLETE option does not have + this effect. + +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. + +LIST_AMBIGUOUS <D> + This option works when AUTO_LIST or 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 BASH_AUTO_LIST, this means that the + list will be delayed to the third call of the function. + +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 BEEP is also set; + this may be modified if completion is called from a user-defined + widget. + +LIST_PACKED + Try to make the completion list smaller (occupying less lines) by + printing the matches in columns with different widths. + +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. + +LIST_TYPES (-X) <D> + When listing files that are possible completions, show the type of + each file with a trailing identifying mark. + +MENU_COMPLETE (-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. reverse-menu-complete may be used to loop through the + list in the other direction. This option overrides AUTO_MENU. + +REC_EXACT (-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. + + + +16.2.3 Expansion and Globbing +----------------------------- + + +BAD_PATTERN (+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.) + +BARE_GLOB_QUAL <Z> + In a glob pattern, treat a trailing set of parentheses as a + qualifier list, if it contains no `|', `(' or (if special) `~' + characters. See *Note Filename Generation::. + +BRACE_CCL + Expand expressions in braces which would not otherwise undergo + brace expansion to a lexically ordered list of all the characters. + See *Note Brace Expansion::. + +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, cvs(/) can match the directory CVS owing to the presence + of the globbing flag (unless the option BARE_GLOB_QUAL is unset). + +CASE_MATCH <D> + Make regular expressions using the zsh/regex module (including + matches with =~) sensitive to case. + +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 NOMATCH. + +EQUALS <Z> + Perform = filename expansion. (See *Note Filename Expansion::.) + +EXTENDED_GLOB + Treat the `#', `~' and `^' characters as part of patterns for + filename generation, etc. (An initial unquoted `~' always + produces named directory expansion.) + +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. + +GLOB (+F, ksh: +f) <D> + Perform filename generation (globbing). (See *Note Filename + Generation::.) + +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 + `NAME=PATTERN (e.g. `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 `NAME=(VALUE)' (e.g. `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. + +GLOB_DOTS (-4) + Do not require a leading `.' in a filename to be matched + explicitly. + +GLOB_STAR_SHORT + When this option is set and the default zsh-style globbing is in + effect, the pattern `**/*' can be abbreviated to `**' and the + pattern `***/*' can be abbreviated to ***. Hence `**.c' finds a + file ending in .c in any subdirectory, and `***.c' does the same + while also following symbolic links. A / immediately after the + `**' or `***' forces the pattern to be treated as the + unabbreviated form. + +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. + +HIST_SUBST_PATTERN + Substitutions using the :s and :& history modifiers are performed + with pattern matching instead of string matching. This occurs + wherever history modifiers are valid, including glob qualifiers + and parameters. See *Note Modifiers::. + +IGNORE_BRACES (-I) <S> + Do not perform brace expansion. For historical reasons this also + includes the effect of the IGNORE_CLOSE_BRACES option. + +IGNORE_CLOSE_BRACES + When neither this option nor IGNORE_BRACES is set, a sole close + brace character `}' 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 + IGNORE_BRACES, this option does not disable brace expansion. + + For example, with both options unset a function may be defined in + the following fashion: + + + args() { echo $# } + + while if either option is set, this does not work and something + equivalent to the following is required: + + + args() { echo $#; } + + +KSH_GLOB <K> + In pattern matching, the interpretation of parentheses is affected + by a preceding `@', `*', `+', `?' or `!'. See *Note Filename + Generation::. + +MAGIC_EQUAL_SUBST + All unquoted arguments of the form `ANYTHING=EXPRESSION' appearing + after the command name have filename expansion (that is, where + EXPRESSION has a leading `~' or `=') performed on 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 echo foo=~/bar:~/rod, both occurrences of ~ would be + replaced. Note that this happens anyway with typeset and similar + statements. + + This option respects the setting of the KSH_TYPESET option. In + other words, if both options are in effect, arguments looking like + assignments will not undergo word splitting. + +MARK_DIRS (-8, ksh: -X) + Append a trailing `/' to all directory names resulting from + filename generation (globbing). + +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. + + The option is on by default if the shell was compiled with + MULTIBYTE_SUPPORT; otherwise it is off by default and has no effect + if turned on. + + 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. + + 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. + +NOMATCH (+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 `~' or `='. + +NULL_GLOB (-G) + If a pattern for filename generation has no matches, delete the + pattern from the argument list instead of reporting an error. + Overrides NOMATCH. + +NUMERIC_GLOB_SORT + If numeric filenames are matched by a filename generation pattern, + sort the filenames numerically rather than lexicographically. + +RC_EXPAND_PARAM (-P) + Array expansions of the form `FOO${XX}BAR', where the parameter XX + is set to (A B C), are substituted with `FOOABAR FOOBBAR FOOCBAR' + instead of the default `FOOA B CBAR'. Note that an empty array + will therefore cause all arguments to be removed. + +REMATCH_PCRE + If set, regular expression matching with the =~ operator will use + Perl-Compatible Regular Expressions from the PCRE library. (The + zsh/pcre module must be available.) If not set, regular + expressions will use the extended regexp syntax provided by the + system libraries. + +SH_GLOB <K> <S> + Disables the special meaning of `(', `|', `)' and '<' for globbing + the result of parameter and command substitutions, and in some + other places where the shell accepts patterns. If SH_GLOB is set + but 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. !(true) is + interpreted as if there were a space after the !. This option is + set by default if zsh is invoked as sh or ksh. + +UNSET (+u, ksh: +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. + +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 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. + +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 + WARN_CREATE_GLOBAL as in this case the warning is only printed + when a parameter is _not_ created. Where possible, use of 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 `functions + -W'. + + For example, the following code produces a warning for the + assignment inside the function nested as that overrides the value + within toplevel + + + toplevel() { + local foo="in fn" + nested + } + nested() { + foo="in nested" + } + setopt warn_nested_var + toplevel + + + +16.2.4 History +-------------- + + +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 $SAVEHIST (see + also the HIST_SAVE_BY_COPY option). + +BANG_HIST (+K) <C> <Z> + Perform textual history expansion, `csh'-style, treating the + character `!' specially. + +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: + + `: <BEGINNING TIME>:<ELAPSED SECONDS>;<COMMAND>'. + +HIST_ALLOW_CLOBBER + Add `|' to output redirections in the history. This allows history + references to clobber files even when CLOBBER is unset. + +HIST_BEEP <D> + Beep in ZLE when a widget attempts to access a history entry which + isn't there. + +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 HISTSIZE to + a larger number than SAVEHIST in order to give you some room for + the duplicated events, otherwise this option will behave just like + HIST_IGNORE_ALL_DUPS once the history fills up with unique events. + +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 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. + +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. + +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). + +HIST_IGNORE_DUPS (-h) + Do not enter command lines into the history list if they are + duplicates of the previous event. + +HIST_IGNORE_SPACE (-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. + +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. + +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. + +HIST_NO_STORE + Remove the history (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. + +HIST_REDUCE_BLANKS + Remove superfluous blanks from each command line being added to + the history list. + +HIST_SAVE_BY_COPY <D> + When the history file is re-written, we normally write out a copy + of the file named $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. + + 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. + +HIST_SAVE_NO_DUPS + When writing out the history file, older commands that duplicate + newer ones are omitted. + +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. + +INC_APPEND_HISTORY + This option works like APPEND_HISTORY except that new history lines + are added to the $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 $SAVEHIST (see + also the HIST_SAVE_BY_COPY option). + +INC_APPEND_HISTORY_TIME + This option is a variant of 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 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. + + This option is only useful if INC_APPEND_HISTORY and SHARE_HISTORY + are turned off. The three options should be considered mutually + exclusive. + +SHARE_HISTORY <K> + 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 INC_APPEND_HISTORY, which should be + turned off if this option is in effect). The history lines are + also output with timestamps ala EXTENDED_HISTORY (which makes it + easier to find the spot where we left off reading the file after + it gets re-written). + + 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. + + If you find that you want more control over when commands get + imported, you may wish to turn SHARE_HISTORY off, + INC_APPEND_HISTORY or INC_APPEND_HISTORY_TIME (see above) on, and + then manually import commands whenever you need them using `fc + -RI'. + + + +16.2.5 Initialisation +--------------------- + + +ALL_EXPORT (-a, ksh: -a) + All parameters subsequently defined are automatically exported. + +GLOBAL_EXPORT <Z> + If this option is set, passing the -x flag to the builtins declare, + float, integer, readonly and typeset (but not local) will also set + the -g flag; hence parameters exported to the environment will + not be made local to the enclosing function, unless they were + already or the flag +g is given explicitly. If the option is + unset, exported parameters will be made local in just the same way + as any other parameter. + + This option is set by default for backward compatibility; it is not + recommended that its behaviour be relied upon. Note that the + builtin export always sets both the -x and -g flags, and hence its + effect extends beyond the scope of the enclosing function; this is + the most portable way to achieve this behaviour. + +GLOBAL_RCS (-d) <D> + If this option is unset, the startup files /etc/zprofile, + /etc/zshrc, /etc/zlogin and /etc/zlogout will not be run. It can + be disabled and re-enabled at any time, including inside local + startup files (.zshrc, etc.). + +RCS (+f) <D> + After /etc/zshenv is sourced on startup, source the .zshenv, + /etc/zprofile, .zprofile, /etc/zshrc, .zshrc, /etc/zlogin, + .zlogin, and .zlogout files, as described in *Note Files::. If + this option is unset, the /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. + + + +16.2.6 Input/Output +------------------- + + +ALIASES <D> + Expand aliases. + +CLOBBER (+C, ksh: +C) <D> + Allows `>' redirection to truncate existing files. Otherwise `>!' + or `>|' must be used to truncate a file. + + If the option is not set, and the option APPEND_CREATE is also not + set, `>>!' or `>>|' must be used to create a file. If either + option is set, `>>' may be used. + +CORRECT (-0) + Try to correct the spelling of commands. Note that, when the + 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. + + The shell variable CORRECT_IGNORE may be set to a pattern to match + words that will never be offered as corrections. + +CORRECT_ALL (-O) + Try to correct the spelling of all arguments in a line. + + The shell variable CORRECT_IGNORE_FILE may be set to a pattern to + match file names that will never be offered as corrections. + +DVORAK + Use the Dvorak keyboard instead of the standard qwerty keyboard as + a basis for examining spelling mistakes for the CORRECT and + CORRECT_ALL options and the spell-word editor command. + +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. + +IGNORE_EOF (-7) + Do not exit on end-of-file. Require the use of exit or logout + instead. However, ten consecutive EOFs will cause the shell to + exit anyway, to avoid the shell hanging if its tty goes away. + + 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. + +INTERACTIVE_COMMENTS (-k) <K> <S> + Allow comments even in interactive shells. + +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 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. + +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 HASH_CMDS nor CORRECT is set. + +HASH_EXECUTABLES_ONLY + When hashing commands because of 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. + +MAIL_WARNING (-U) + Print a warning message if a mail file has been accessed since the + shell last checked. + +PATH_DIRS (-Q) + Perform a path search even on command names with slashes in them. + Thus if `/usr/local/bin' is in the user's path, and he or she types + `X11/xinit', the command `/usr/local/bin/X11/xinit' will be + executed (assuming it exists). Commands explicitly beginning with + `/', `./' or `../' are not subject to the path search. This also + applies to the `.' and source builtins. + + 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 `.' or the current directory appear in the command search + path. + +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 *Note Invocation::. + +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 man page ctype(3)). + +PRINT_EXIT_VALUE (-1) + Print the exit value of programs with non-zero exit status. This + is only available at the command line in interactive shells. + +RC_QUOTES + Allow the character sequence `''' to signify a single quote within + singly quoted strings. Note this does not apply in quoted strings + using the format $'...', where a backslashed single quote can be + used. + +RM_STAR_SILENT (-H) <K> <S> + Do not query the user before executing `rm *' or `rm path/*'. + +RM_STAR_WAIT + If querying the user before executing `rm *' or `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 `*' in ZLE (with tab). + +SHORT_LOOPS <C> <Z> + Allow the short forms of for, repeat, select, if, and function + constructs. + +SUN_KEYBOARD_HACK (-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 KEYBOARD_HACK lets you choose the character to be + removed. + + + +16.2.7 Job Control +------------------ + + +AUTO_CONTINUE + With this option set, stopped jobs that are removed from the job + table with the disown builtin command are automatically sent a CONT + signal to make them running. + +AUTO_RESUME (-W) + Treat single word simple commands without redirection as + candidates for resumption of an existing job. + +BG_NICE (-6) <C> <Z> + Run all background jobs at a lower priority. This option is set + by default. + +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. NO_CHECK_JOBS is best used only in combination with + NO_HUP, else such jobs will be killed automatically. + + The check is omitted if the commands run from the previous command + line included a `jobs' command, since it is assumed the user is + aware that there are background or suspended jobs. A `jobs' + command run from one of the hook functions defined in the section + Special Functions in *Note Functions:: is not counted for this + purpose. + +CHECK_RUNNING_JOBS <Z> + Check for both running and suspended jobs when CHECK_JOBS is + enabled. When this option is disabled, zsh checks only for + suspended jobs, which matches the default behavior of bash. + + This option has no effect unless CHECK_JOBS is set. + +HUP <Z> + Send the HUP signal to running jobs when the shell exits. + +LONG_LIST_JOBS (-R) + Print job notifications in the long format by default. + +MONITOR (-m, ksh: -m) + Allow job control. Set by default in interactive shells. + +NOTIFY (-5, ksh: -b) <Z> + Report the status of background jobs immediately, rather than + waiting until just before printing a prompt. + +POSIX_JOBS <K> <S> + This option makes job control more compliant with the POSIX + standard. + + When the option is not set, the MONITOR option is unset on entry to + subshells, so that job control is no longer active. When the + option is set, the MONITOR option and job control remain active in + the subshell, but note that the subshell has no access to jobs in + the parent shell. + + When the option is not set, jobs put in the background or + foreground with bg or fg are displayed with the same information + that would be reported by jobs. When the option is set, only the + text is printed. The output from jobs itself is not affected by + the option. + + 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 jobs is empty + until a job is started within the subshell. + + In previous versions of the shell, it was necessary to enable + POSIX_JOBS in order for the builtin command wait to return the + status of background jobs that had already exited. This is no + longer the case. + + + +16.2.8 Prompting +---------------- + + +PROMPT_BANG <K> + If set, `!' is treated specially in prompt expansion. See *Note + Prompt Expansion::. + +PROMPT_CR (+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. + +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 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). + + When a partial line is preserved, by default you will see an + inverse+bold character at the end of the partial line: a `%' for + a normal user or a `#' for root. If set, the shell parameter + PROMPT_EOL_MARK can be used to customize how the end of partial + lines are shown. + + NOTE: if the PROMPT_CR option is not set, enabling this option will + have no effect. This option is on by default. + +PROMPT_PERCENT <C> <Z> + If set, `%' is treated specially in prompt expansion. See *Note + Prompt Expansion::. + +PROMPT_SUBST <K> <S> + If set, _parameter expansion_, _command substitution_ and + _arithmetic expansion_ are performed in prompts. Substitutions + within prompts do not affect the command status. + +TRANSIENT_RPROMPT + Remove any right prompt from display when accepting a command + line. This may be useful with terminals with other cut/paste + methods. + + + +16.2.9 Scripts and Functions +---------------------------- + + +ALIAS_FUNC_DEF <S> + By default, zsh does not allow the definition of functions using + the `NAME ()' syntax if 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. + + When this option is set, aliases can be used for defining + functions. + + For example, consider the following definitions as they might + occur in a startup file. + + + alias foo=bar + foo() { + print This probably does not do what you expect. + } + + Here, foo is expanded as an alias to bar before the () is + encountered, so the function defined would be named bar. By + default this is instead an error in native mode. Note that + quoting any part of the function name, or using the keyword + function, avoids the problem, so is recommended when the function + name can also be an alias. + +C_BASES + Output hexadecimal numbers in the standard C format, for example + `0xFF' instead of the usual `16#FF'. If the option OCTAL_ZEROES + is also set (it is not by default), octal numbers will be treated + similarly and hence appear as `077' instead of `8#77'. This + option has no effect on the 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 + C_BASES. + +C_PRECEDENCES + This alters the precedence of arithmetic operators to be more like + C and other programming languages; *Note Arithmetic Evaluation:: + has an explicit list. + +DEBUG_BEFORE_CMD <D> + Run the 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. + +ERR_EXIT (-e, ksh: -e) + If a command has a non-zero exit status, execute the ZERR trap, if + set, and exit. This is disabled while running initialization + scripts. + + The behaviour is also disabled inside DEBUG traps. In this case + the option is handled specially: it is unset on entry to the trap. + If the option DEBUG_BEFORE_CMD is set, as it is by default, and + the option ERR_EXIT is found to have been set on exit, then the + command for which the DEBUG trap is being executed is skipped. + The option is restored after the trap exits. + + Non-zero status in a command list containing && or || is ignored + for commands not at the end of the list. Hence + + + false && true + + does not trigger exit. + + Exiting due to ERR_EXIT has certain interactions with asynchronous + jobs noted in *Note Jobs & Signals::. + +ERR_RETURN + If a command has a non-zero exit status, return immediately from + the enclosing function. The logic is similar to that for ERR_EXIT, + except that an implicit return statement is executed instead of an + exit. This will trigger an exit at the outermost level of a + non-interactive script. + + Normally this option inherits the behaviour of ERR_EXIT that code + followed by `&&' `||' does not trigger a return. Hence in the + following: + + + summit || true + + no return is forced as the combined effect always has a zero return + status. + + Note. however, that if summit in the above example is itself a + function, code inside it is considered separately: it may force a + return from summit (assuming the option remains set within + summit), but not from the enclosing context. This behaviour is + different from ERR_EXIT which is unaffected by function scope. + +EVAL_LINENO <Z> + If set, line numbers of expressions evaluated using the builtin + eval are tracked separately of the enclosing environment. This + applies both to the parameter LINENO and the line number output by + the prompt escape %i. If the option is set, the prompt escape %N + will output the string `(eval)' instead of the script or function + name as an indication. (The two prompt escapes are typically + used in the parameter PS4 to be output when the option XTRACE is + set.) If EVAL_LINENO is unset, the line number of the surrounding + script or function is retained during the evaluation. + +EXEC (+n, ksh: +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 `-n' is + supplied to the shell at startup. + +FUNCTION_ARGZERO <C> <Z> + When executing a shell function or sourcing a script, set $0 + temporarily to the name of the function/script. Note that toggling + FUNCTION_ARGZERO from on to off (or off to on) does not change the + current value of $0. Only the state upon entry to the function or + script has an effect. Compare POSIX_ARGZERO. + +LOCAL_LOOPS + When this option is not set, the effect of break and continue + commands may propagate outside function scope, affecting loops in + calling functions. When the option is set in a calling function, a + break or a 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. + +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 + PRIVILEGED and RESTRICTED. Otherwise, only this option, and the + LOCAL_LOOPS, XTRACE and 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 `emulate -L zsh'; the -L activates + LOCAL_OPTIONS. + +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 + `disable -p', is restored to what it was when the function was + entered. The behaviour of this option is similar to the effect of + LOCAL_OPTIONS on options; hence `emulate -L sh' (or indeed any + other emulation with the -L option) activates LOCAL_PATTERNS. + +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 _prior_ to altering the trap behaviour in a function; unlike + 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, + + + unsetopt localtraps + trap - INT + fn() { setopt localtraps; trap '' INT; sleep 3; } + + will restore normal handling of SIGINT after the function exits. + +MULTI_FUNC_DEF <Z> + Allow definitions of multiple functions at once in the form `fn1 + fn2...()'; if the option is not set, this causes a parse error. + Definition of multiple functions with the function keyword is + always allowed. Multiple function definitions are not often used + and can cause obscure errors. + +MULTIOS <Z> + Perform implicit `tee's or `cat's when multiple redirections are + attempted (see *Note Redirection::). + +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. + + Sequences of digits indicating a numeric base such as the `08' + component in `08#77' are always interpreted as decimal, regardless + of leading zeroes. + +PIPE_FAIL + By default, when a pipeline exits the exit status recorded by the + shell and returned by the shell variable $? 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. + +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 XTRACE option, with the message <sourcetrace>. A + file may be loaded by the shell itself when it starts up and shuts + down (Startup/Shutdown Files) or by the use of the `source' and + `dot' builtin commands. + +TYPESET_SILENT + If this is unset, executing any of the `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 `-m' option. The option `-p' is + available whether or not the option is set. + +VERBOSE (-v, ksh: -v) + Print shell input lines as they are read. + +XTRACE (-x, ksh: -x) + Print commands and their arguments as they are executed. The + output is preceded by the value of $PS4, formatted as described in + *Note Prompt Expansion::. + + + +16.2.10 Shell Emulation +----------------------- + + +APPEND_CREATE <K> <S> + This option only applies when NO_CLOBBER (-C) is in effect. + + If this option is not set, the shell will report an error when a + append redirection (>>) is used on a file that does not already + exists (the traditional zsh behaviour of NO_CLOBBER). If the + option is set, no error is reported (POSIX behaviour). + +BASH_REMATCH + When set, matches performed with the =~ operator will set the + BASH_REMATCH array variable, instead of the default MATCH and + match variables. The first element of the BASH_REMATCH array will + contain the entire matched text and subsequent elements will + contain extracted substrings. This option makes more sense when + 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 MATCH variable contains the entire matched text + and the match array variable contains substrings. + +BSD_ECHO <S> + Make the echo builtin compatible with the BSD man page echo(1) + command. This disables backslashed escape sequences in echo + strings unless the -e option is specified. + +CONTINUE_ON_ERROR + If a fatal error is encountered (see *Note 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. + +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. + +CSH_JUNKIE_LOOPS <C> + Allow loop bodies to take the form `LIST; end' instead of `do + LIST; done'. + +CSH_JUNKIE_QUOTES <C> + Changes the rules for single- and double-quoted text to match that + of `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 `$', ``' or + `"' (and `\' itself no longer needs escaping). Command + substitutions are only expanded once, and cannot be nested. + +CSH_NULLCMD <C> + Do not use the values of NULLCMD and READNULLCMD when running + redirections with no command. This make such redirections fail + (see *Note Redirection::). + +KSH_ARRAYS <K> <S> + Emulate `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 + (`${path[2]}' rather than just `$path[2]') or to apply modifiers + to any parameter (`${PWD:h}' rather than `$PWD:h'). + +KSH_AUTOLOAD <K> <S> + Emulate `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 + `ksh'-style case - of the file containing only a simple definition + of the function - is always handled in the `ksh'-compatible + manner.) + +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. + +KSH_TYPESET + This option is now obsolete: a better appropximation to the + behaviour of other shells is obtained with the reserved word + interface to declare, export, float, integer, local, readonly and + typeset. Note that the option is only applied when the reserved + word interface is _not_ in use. + + Alters the way arguments to the typeset family of commands, + including declare, export, float, integer, local and 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. + +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 KSH_ARRAYS is also + set. + + If neither this option nor 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 KSH_ZERO_SUBSCRIPT is not set, + + + array[0]=(element) + + is an error, while + + + array[0,1]=(element) + + is not and will replace the first element of the array. + + This option is for compatibility with older versions of the shell + and is not recommended in new code. + +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 *Note Reserved Words::. + + 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 `zsh -c', + or even `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. + +POSIX_ARGZERO + This option may be used to temporarily disable FUNCTION_ARGZERO and + thereby restore the value of $0 to the name used to invoke the + shell (or as set by the -c command line option). For + compatibility with previous versions of the shell, emulations use + NO_FUNCTION_ARGZERO instead of POSIX_ARGZERO, which may result in + unexpected scoping of $0 if the emulation mode is changed inside a + function or script. To avoid this, explicitly enable + POSIX_ARGZERO in the emulate command: + + + emulate sh -o POSIX_ARGZERO + + Note that NO_POSIX_ARGZERO has no effect unless FUNCTION_ARGZERO + was already enabled upon entry to the function or script. + +POSIX_BUILTINS <K> <S> + When this option is set the 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 command + builtin. Special builtins are ., :, break, continue, declare, + eval, exit, export, integer, local, readonly, return, set, shift, + source, times, trap and unset. + + In addition, various error conditions associated with the above + builtins or exec cause a non-interactive shell to exit and an + interactive shell to return to its top-level processing. + + Furthermore, functions and shell builtins are not executed after + an exec prefix; the command to be executed must be an external + command found in the path. + + Furthermore, the getopts builtin behaves in a POSIX-compatible + fashion in that the associated variable OPTIND is not made local + to functions. + + Moreover, the warning and special exit code from [[ -o + NON_EXISTENT_OPTION ]] are suppressed. + +POSIX_IDENTIFIERS <K> <S> + When this option is set, only the ASCII characters a to z, A to Z, + 0 to 9 and _ may be used in identifiers (names of shell parameters + and modules). + + In addition, setting this option limits the effect of parameter + substitution with no braces, so that the expression $# is treated + as the parameter $# even if followed by a valid parameter name. + When it is unset, zsh allows expressions of the form $#NAME to + refer to the length of $NAME, even for special variables, for + example in expressions such as $#- and $#*. + + 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 `unset + t; (( t = 3 ))'. without POSIX_IDENTIFIERS set t has integer type, + while with it set it has scalar type. + + When the option is unset and multibyte character support is + enabled (i.e. it is compiled in and the option 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 VARIABLE=VALUE has already been parsed as a command rather + than an assignment. + + 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. + +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. + + When this option is not set, null characters embedded within + strings of the form $'...' 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. + + When this option is set, the $'...' expression is truncated at the + null character. Note that remaining parts of the same string + beyond the termination of the quotes are not truncated. + + For example, the command line argument a$'b\0c'd is treated with + the option off as the characters a, b, null, c, d, and with the + option on as the characters a, b, d. + +POSIX_TRAPS <K> <S> + When this option is set, the usual zsh behaviour of executing + traps for EXIT on exit from shell functions is suppressed. In + that case, manipulating EXIT traps always alters the global trap + for exiting the shell; the LOCAL_TRAPS option is ignored for the + EXIT trap. Furthermore, a 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. + +SH_FILE_EXPANSION <K> <S> + Perform filename expansion (e.g., ~ expansion) _before_ parameter + expansion, command substitution, arithmetic expansion and brace + expansion. If this option is unset, it is performed _after_ brace + expansion, so things like `~$USERNAME' and `~{pfalstad,rc}' will + work. + +SH_NULLCMD <K> <S> + Do not use the values of NULLCMD and READNULLCMD when doing + redirections, use `:' instead (see *Note Redirection::). + +SH_OPTION_LETTERS <K> <S> + If this option is set the shell tries to interpret single letter + options (which are used with set and setopt) like `ksh' does. + This also affects the value of the - special parameter. + +SH_WORD_SPLIT (-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 *Note Parameter Expansion::.) + +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. + + + +16.2.11 Shell State +------------------- + + +INTERACTIVE (-i, ksh: -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 + 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. + +LOGIN (-l, ksh: -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 argv[0] + passed to the shell is a `-'. + +PRIVILEGED (-p, ksh: -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 -p option to zsh so that it takes effect during + startup. + + + #!/bin/zsh -p + + 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: + + + unsetopt privileged || exit + + The PRIVILEGED option disables sourcing user startup files. If + zsh is invoked as `sh' or `ksh' with this option set, + /etc/suid_profile is sourced (after /etc/profile on interactive + shells). Sourcing ~/.profile is disabled and the contents of the + ENV variable is ignored. This option cannot be changed using the + -m option of setopt and unsetopt, and changing it inside a + function always changes it globally regardless of the LOCAL_OPTIONS + option. + +RESTRICTED (-r) + Enables restricted mode. This option cannot be changed using + unsetopt, and setting it inside a function always changes it + globally regardless of the LOCAL_OPTIONS option. See *Note + Restricted Shell::. + +SHIN_STDIN (-s, ksh: -s) + Commands are being read from the standard input. Commands are + read from standard input if no command is specified with -c and no + file of commands is specified. If 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 _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. + +SINGLE_COMMAND (-t, ksh: -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 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. + + + +16.2.12 Zle +----------- + + +BEEP (+B) <D> + Beep on error in ZLE. + +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. + + If this option is set, the pattern test [[: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. + +EMACS + If ZLE is loaded, turning on this option has the equivalent effect + of `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; bindkey is the recommended interface. + +OVERSTRIKE + Start up the line editor in overstrike mode. + +SINGLE_LINE_ZLE (-M) <K> + Use single-line command line editing instead of multi-line. + + 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. + +VI + If ZLE is loaded, turning on this option has the equivalent effect + of `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; bindkey is the recommended interface. + +ZLE (-Z) + Use the zsh line editor. Set by default in interactive shells + connected to a terminal. + + + + +File: zsh.info, Node: Option Aliases, Next: Single Letter Options, Prev: Description of Options, Up: Options + +16.3 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. + + +BRACE_EXPAND + _NO__IGNORE_BRACES (ksh and bash compatibility) + +DOT_GLOB + GLOB_DOTS (bash compatibility) + +HASH_ALL + HASH_CMDS (bash compatibility) + +HIST_APPEND + APPEND_HISTORY (bash compatibility) + +HIST_EXPAND + BANG_HIST (bash compatibility) + +LOG + _NO__HIST_NO_FUNCTIONS (ksh compatibility) + +MAIL_WARN + MAIL_WARNING (bash compatibility) + +ONE_CMD + SINGLE_COMMAND (bash compatibility) + +PHYSICAL + CHASE_LINKS (ksh and bash compatibility) + +PROMPT_VARS + PROMPT_SUBST (bash compatibility) + +STDIN + SHIN_STDIN (ksh compatibility) + +TRACK_ALL + HASH_CMDS (ksh compatibility) + + + +File: zsh.info, Node: Single Letter Options, Prev: Option Aliases, Up: Options + +16.4 Single Letter Options +========================== + + + +16.4.1 Default set +------------------ + + +-0 + CORRECT + +-1 + PRINT_EXIT_VALUE + +-2 + _NO__BAD_PATTERN + +-3 + _NO__NOMATCH + +-4 + GLOB_DOTS + +-5 + NOTIFY + +-6 + BG_NICE + +-7 + IGNORE_EOF + +-8 + MARK_DIRS + +-9 + AUTO_LIST + +-B + _NO__BEEP + +-C + _NO__CLOBBER + +-D + PUSHD_TO_HOME + +-E + PUSHD_SILENT + +-F + _NO__GLOB + +-G + NULL_GLOB + +-H + RM_STAR_SILENT + +-I + IGNORE_BRACES + +-J + AUTO_CD + +-K + _NO__BANG_HIST + +-L + SUN_KEYBOARD_HACK + +-M + SINGLE_LINE_ZLE + +-N + AUTO_PUSHD + +-O + CORRECT_ALL + +-P + RC_EXPAND_PARAM + +-Q + PATH_DIRS + +-R + LONG_LIST_JOBS + +-S + REC_EXACT + +-T + CDABLE_VARS + +-U + MAIL_WARNING + +-V + _NO__PROMPT_CR + +-W + AUTO_RESUME + +-X + LIST_TYPES + +-Y + MENU_COMPLETE + +-Z + ZLE + +-a + ALL_EXPORT + +-e + ERR_EXIT + +-f + _NO__RCS + +-g + HIST_IGNORE_SPACE + +-h + HIST_IGNORE_DUPS + +-i + INTERACTIVE + +-k + INTERACTIVE_COMMENTS + +-l + LOGIN + +-m + MONITOR + +-n + _NO__EXEC + +-p + PRIVILEGED + +-r + RESTRICTED + +-s + SHIN_STDIN + +-t + SINGLE_COMMAND + +-u + _NO__UNSET + +-v + VERBOSE + +-w + CHASE_LINKS + +-x + XTRACE + +-y + SH_WORD_SPLIT + +16.4.2 sh/ksh emulation set +--------------------------- + + +-C + _NO__CLOBBER + +-T + TRAPS_ASYNC + +-X + MARK_DIRS + +-a + ALL_EXPORT + +-b + NOTIFY + +-e + ERR_EXIT + +-f + _NO__GLOB + +-i + INTERACTIVE + +-l + LOGIN + +-m + MONITOR + +-n + _NO__EXEC + +-p + PRIVILEGED + +-r + RESTRICTED + +-s + SHIN_STDIN + +-t + SINGLE_COMMAND + +-u + _NO__UNSET + +-v + VERBOSE + +-x + XTRACE + +16.4.3 Also note +---------------- + + +-A + Used by set for setting arrays + +-b + Used on the command line to specify end of option processing + +-c + Used on the command line to specify a single command + +-m + Used by setopt for pattern-matching option setting + +-o + Used in all places to allow use of long option names + +-s + Used by set to sort positional parameters + + +File: zsh.info, Node: Shell Builtin Commands, Next: Zsh Line Editor, Prev: Options, Up: Top + +17 Shell Builtin Commands +************************* + +Some shell builtin commands take options as described in individual +entries; these are often referred to in the list below as `flags' to +avoid confusion with shell options, which may also have an effect on the +behaviour of builtin commands. In this introductory section, `option' +always has the meaning of an option to a command that should be +familiar to most command line users. + +Typically, options are single letters preceded by a hyphen (-). +Options that take an argument accept it either immediately following the +option letter or after white space, for example `print -C3 {1..9}' or +`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 `print -rca - *' and `print -r -c -a - *' are +equivalent. + +Some shell builtin commands also take options that begin with `+' +instead of `-'. The list below makes clear which commands these are. + +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. + +All builtin commands other than `echo' and precommand modifiers, even +those that have no options, can be given the argument `--' 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 `-'. For +historical reasons, most builtin commands (including `echo') also +recognize a single `-' in a separate word for this purpose; note that +this is less standard and use of `--' is recommended. + + +- SIMPLE COMMAND + See *Note Precommand Modifiers::. + +. 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 + parameters; 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. + +: [ ARG ... ] + This command does nothing, although normal argument expansions is + performed which may have effects on shell parameters. A zero exit + status is returned. + +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, define a + global alias; global aliases are expanded even if they do not + occur in command position. + + 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 different 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 *Note Aliasing::. + +autoload [ {+|-}RTUXdkmrtWz ] [ -w ] [ NAME ... ] + See the section `Autoloading Functions' in *Note Functions:: for + full details. The fpath parameter will be searched to find the + function 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 + 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 + -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 function, + but does _not_ execute it. The exit status is zero (success) if + the function was not previously defined _and_ a definition for it + was found. This does _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 -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 function + 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 + emulation, 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 interface. + +bg [ JOB ... ] +JOB ... & + Put each specified JOB in the background, or the current job if + none is specified. + +bindkey + See *Note Zle Builtins::. + +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. + +builtin NAME [ ARGS ... ] + Executes the builtin NAME, with the given ARGS. + +bye + Same as exit. + +cap + See *Note The zsh/cap Module::. + +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 + directories 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 + `.' occurs 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 environment 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. + +clone + See *Note The zsh/clone Module::. + +command [ -pvV ] SIMPLE COMMAND + The simple command argument is taken as an external command + instead 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 *Note Precommand Modifiers::. + +comparguments + See *Note The zsh/computil Module::. + +compcall + See *Note The zsh/compctl Module::. + +compctl + See *Note The zsh/compctl Module::. + +compdescribe + See *Note The zsh/computil Module::. + +compfiles + See *Note The zsh/computil Module::. + +compgroups + See *Note The zsh/computil Module::. + +compquote + See *Note The zsh/computil Module::. + +comptags + See *Note The zsh/computil Module::. + +comptry + See *Note The zsh/computil Module::. + +compvalues + See *Note The zsh/computil Module::. + +continue [ N ] + Resume the next iteration of the enclosing for, while, until, + select or repeat loop. If an arithmetic expression N is specified, + break out of N-1 loops and resume at the Nth enclosing loop. + +declare + Same as typeset. + +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 specified, + 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 (*Note Filename Expansion::). + + -p + print directory entries one per line. + + -v + number the directories in the stack when printing. + + + +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 arguments 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 disabled. 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 *Note Filename Generation::. + 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 disabling patterns + as certain expressions, in particular those involving parentheses, + are parsed differently. + + 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. + + + '?' + The pattern character ? wherever it occurs, including when + preceding a parenthesis with KSH_GLOB. + + '*' + The pattern character * wherever it occurs, including + recursive 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 + repetition 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 @(...). + + +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. + +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 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 printf, and for a more controllable way of + printing text within zsh, see print. + +echotc + See *Note The zsh/termcap Module::. + +echoti + See *Note The zsh/terminfo Module::. + +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 *Note 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 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 directly + 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 environment; + otherwise, only those options likely to cause portability 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 emulate command and any + setopt, disable -p or enable -p, and trap commands to be local to + the immediately surrounding shell function, if any; normally these + options are turned off in all emulation 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 + *Note Invocation::, 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 before + emulate returns. The -R switch may precede the name of the shell + to emulate; note this has a meaning distinct from including -R in + FLAGS. + + Use of -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 -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 + emulation. fno is then executed, causing options associated with + emulations 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 option + 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 suitable + 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 example, 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 + corresponds to different sticky emulation modes, so for + example `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 different, so + for example `emulate zsh -c' and `emulate zsh -o cbases -c' + are treated as distinct sticky emulations. + +enable [ -afmprs ] NAME ... + Enable the NAMEd hash table elements, presumably disabled earlier + 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 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 disable builtin command. + + 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 unless + the EXTENDED_GLOB option is also set. To enable all possible + patterns (so that they may be individually disabled with disable + -p), use `setopt EXTENDED_GLOB KSH_GLOB NO_SH_GLOB'. + +eval [ 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 ARGS or they contain no commands (i.e. are an + empty string or whitespace) the return status is zero. + +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 + *Note Precommand Modifiers::. + + If the option POSIX_BUILTINS is set, COMMAND is never interpreted + 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. + +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 *Note Jobs & Signals:: for some possibly + unexpected interactions of the exit command with jobs. + +export [ NAME[=VALUE] ... ] + The specified NAMEs are marked for automatic export to the + environment of subsequently executed commands. Equivalent to + typeset -gx. If a parameter specified does not already exist, it + is created in the global scope. + +false [ ARG ... ] + Do nothing and return an exit status of 1. + +fc [ -e ENAME ] [ -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 automatically, + 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 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 OLD=NEW, if any, are then performed on the text + of the events. + + In addition to the number range, + -I + restricts to only internal events (not from $HISTFILE) + + -L + restricts to only local events (not from other shells, see + SHARE_HISTORY in *Note Description of Options:: - note that + $HISTFILE is considered local when read at startup) + + -m + takes the first argument as a pattern (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 + specified, 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 -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 extensions + described for the %D{STRING} prompt format in *Note Prompt + Expansion::. The resulting formatted string must be no more + than 256 characters or will not be printed + + -D + prints elapsed times; may be combined with one of the options + above + + `fc -p' pushes the current history list onto a stack and switches + to a new history list. If the -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 `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 + appropriately, 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 declarations + 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 history 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 append/write to the history + file are appended/written. In any case, the created file will + have no more than $SAVEHIST entries. + +fg [ JOB ... ] +JOB ... + Bring each specified JOB in turn to the foreground. If no JOB is + specified, resume the current job. + +float [ {+|-}Hghlprtux ] [ {+|-}EFLRZ [ N ] ] [ NAME[=VALUE] ... ] + Equivalent to typeset -E, except that options irrelevant to + floating point numbers are not permitted. + +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 autoload, + 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 syntactic + 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) unless 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 without + 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. + + 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 + *Note Arithmetic Evaluation::. By default 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 + mathematical function call. The result of the last arithmetical + expression evaluated inside the shell function (even if it is a + form that normally only returns a status) gives the result of the + mathematical function. + + If the additional option -s is given to 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. + + functions -M with no arguments lists all such user-defined + functions in the same form as a definition. With the additional + option -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). + + For example, the following prints the cube of 3: + + + zmath_cube() { (( $1 * $1 * $1 )) } + functions -M cube 1 1 zmath_cube + print $(( cube(3) )) + + The following string function takes a single argument, including + the commas, so prints 11: + + + stringfn() { (( $#1 )) } + functions -Ms stringfn + print $(( stringfn(foo,bar,rod) )) + +getcap + See *Note The zsh/cap Module::. + +getln [ -AclneE ] NAME ... + Read the top value from the buffer stack and put it in the shell + parameter NAME. Equivalent to read -zr. + +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 + assigning 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 (this is disabled by the POSIX_BUILTINS option). 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 + unknown 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. + +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 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 -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 + explicit 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 selected + 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 option + causes the selected hash table to be fully rebuilt immediately. + 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 + selected 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. + +history + Same as fc -l. + +integer [ {+|-}Hghlprtux ] [ {+|-}LRZi [ N ] ] [ NAME[=VALUE] ... ] + Equivalent to typeset -i, except that options irrelevant to + integers are not permitted. + +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 (man page ps(1)) listings. This feature + is typically used by daemons, to indicate their state. + +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. + +let ARG ... + Evaluate each ARG as an arithmetic expression. See *Note + 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. + +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 current shell + is set to the previously set resource limits of the children. + + If LIMIT is not specified, print the current limit placed on + RESOURCE, 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 + 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. + + RESOURCE can be one of: + + + addressspace + Maximum amount of address space used. + + aiomemorylocked + Maximum amount of memory locked in RAM for AIO operations. + + 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 system. + 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'. + +local [ {+|-}AHUahlprtux ] [ {+|-}EFLRZi [ N ] ] [ NAME[=VALUE] ... ] + Same as typeset, except that the options -g, and -f are not + permitted. In this case the -x option does not force the use of + -g, i.e. exported variables will be local to functions. + +log + List all users currently logged in who are affected by the current + setting of the watch parameter. + +logout [ N ] + Same as exit, except that it only works in a login shell. + +noglob SIMPLE COMMAND + See *Note Precommand Modifiers::. + +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 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 -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 interactive + user. + +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 + represented 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 bindkey + command, see *Note Zle Builtins::. + + -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 prefixes + 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 spaces. + Note: if the list of arguments is empty, print -l will still + output one empty line. To print a possibly-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 subsequent + 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 *Note Prompt Expansion::). In + combination with `-f', prompt escape sequences are parsed + only within interpolated arguments, not within the format + string. + + -r + Ignore the escape conventions of echo. + + -R + Emulate the BSD echo command, which does not process escape + 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 indented 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 characters + 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 format. + + -z + Push the arguments onto the editing buffer stack, separated + 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. + +printf [ -v NAME ] FORMAT [ ARG ... ] + Print the arguments according to the format specification. + Formatting rules are the same as used in C. The same escape + sequences as for echo are recognised in the format. All C + conversion 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 *Note Arithmetic Evaluation:: 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 + 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. + + 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 specified 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. + +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 interpreted 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 + directory list. 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 -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 interactive + user. + + If the option -q is not specified and the shell option PUSHD_SILENT + is not set, the directory stack will be printed after a pushd is + performed. + + The options -s, -L and -P have the same meanings as for the cd + builtin. + +pushln [ ARG ... ] + Equivalent to print -nz. + +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. + +r + Same as fc -e -. + +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' otherwise. 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 encounters 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 ignored + when -q is present. Input is read from the terminal 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 *Note Zsh Line Editor::). This flag is ignored + when the -k or -q flags are present. + + -e + -E + The input read is printed (echoed) to the standard output. + 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 compctl). 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 instead 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 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 -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 processing + 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 character. 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 + interactive. + + The value (exit status) of read is 1 when an end-of-file is + encountered, or when -c or -l is present and the command is not + called from a compctl function, or as described for -q. Otherwise + 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. + +readonly + Same as typeset -r. With the POSIX_BUILTINS option set, same as + typeset -gr. + +rehash + Same as hash -r. + +return [ N ] + Causes a shell function or `.' script to return to the invoking + script with the return status specified by an arithmetic + expression N. 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 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 `return $((128+$1))' will return the + same status as if the signal had not been trapped. + +sched + See *Note The zsh/sched Module::. + +set [ {+|-}OPTIONS | {+|-}o [ OPTION_NAME ] ] ... [ {+|-}A [ NAME ] ] + [ ARG ... ] + Set the options for the shell and/or set the positional + parameters, 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 *Note Options::. Flags may be + specified by name using the -o option. If no option name is + supplied 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 + replace the initial elements of that array; if no NAME is + specified, 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 + arguments following 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 + + + 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. + +setcap + See *Note The zsh/cap Module::. + +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 + differences from the default options for the current emulation + (the default emulation being native zsh, shown as <Z> in *Note + Description of Options::). Options that are on by default for the + emulation are shown with the prefix no only if they are off, while + other options 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 + example, 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 expansion), and all + options with names matching these patterns are set. + + 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 `set -o'. This is because set is regarded as a special builtin + by the POSIX standard, but setopt is not. + +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 instead 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. + +source FILE [ ARG ... ] + Same as `.', except that the current directory is always searched + and is always searched first, before directories in $path. + +stat + See *Note The zsh/stat Module::. + +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. + +test [ ARG ... ] +[ [ ARG ... ] ] + Like the system version of test. Added for compatibility; use + conditional expressions instead (see *Note Conditional + Expressions::). The main differences between the conditional + expression 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 arithmetic + expressions. + + 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 `[[' test + syntax which does not have these ambiguities. + +times + Print the accumulated user and system times for the shell and for + processes run from the shell. + +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 + defaults, or, if no SIG args are present, all traps are reset. + + If ARG is an empty string, then the specified signals are ignored + 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 + associated 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 *Note Simple Commands & + Pipelines::. 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 *Note Description of Options::. 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 parameter 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 execution 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 + different from those defined as `TRAPNAL () { ... }', 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, + + + 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 another. + +true [ ARG ... ] + Do nothing and return an exit status of 0. + +ttyctl [ -fu ] + The -f option freezes the tty (i.e. terminal or terminal + emulator), 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 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. + + 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. + +type [ -wfpamsS ] NAME ... + Equivalent to whence -v. + +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 behavior, + a parameter is created for each NAME that does not already refer + to one. When inside a function, a new parameter is created for + every NAME (even those that already exist), and is unset again + when the function completes. See *Note Local Parameters::. The + same rules apply to special shell parameters, which retain their + special attributes when made local. + + For each NAME=VALUE assignment, the parameter NAME is set to VALUE. + + If the shell option TYPESET_SILENT is not set, for each remaining + 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 display to + only those parameters that have the specified attributes, 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 + assignment is possible if any of the reserved words declare, + export, 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 + expanded (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 parameter 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. + + Arbitrary arguments are allowed if they take the form of + assignments 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 setting + 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 my be disabled + separately. For example, `disable -r typeset' disables the + reserved word interface to typeset, exposing the builtin + interface, 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 + reserved 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 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: + + + # 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 + parameter 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 parameter (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 values 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 equivalent to + `typeset +U' and displays the names of all arrays 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 effect when listing + existing parameters, nor does the flag +g have any effect + except in combination with -m (see below). + + -m + If the -m flag is given the 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 -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 already + local. Otherwise -m applies all other flags or assignments + 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 ignored 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 assignment, + 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. Currently + only the value 1 is supported. In this case arrays and + associative arrays are printed with newlines between 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 assigned + an initial value (the restrictions on assignment forms + described above also apply). + + 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 + 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 possible to apply + -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. + + 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 + parameter 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 *Note + Array Parameters::. + + -L [ N ] + Left justify and remove leading blanks from the value when + the parameter is expanded. If N is nonzero, it defines the + width of the field. If 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. + + The width is the count of characters, which may be multibyte + 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 parameter expansion + flags ${(ml...)...} as described in `Parameter Expansion + Flags' in *Note Parameter Expansion::. + + 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 -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 combined 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-separated 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 variables 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. Otherwise, + 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 zeroes, 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 typeset 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 execution + 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 function 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 extra + 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 *Note 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 `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 altered 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 regardless of having the -h attribute. + Global special parameters 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 display 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/parameter and zsh/mapfile modules. + Note, however, that unlike the -h flag this is also useful + for non-special parameters. + + -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 + representation. On output the variable will be converted to + scientific 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 + representation. 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 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. + + 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 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. + + -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 subsequently + executed commands. If the option GLOBAL_EXPORT is set, this + implies the option -g, unless +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. + + +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 + removes the limit on the resource, or `hard', which uses the + current 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 + 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. + + 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 effect 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 + RESOURCE', 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 correspond 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 + compiled into the shell. The shell will try to read or write the + limit anyway, and will report an error if this fails. + +umask [ -S ] [ MASK ] + The umask is set to MASK. MASK can be either an octal number or a + symbolic value as described in man page chmod(1). 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. + +unalias [ -ams ] NAME ... + Removes aliases. This command works the same as unhash -a, except + 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. + +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. + +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 privileges, 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'. + +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 subscript 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. + +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 patterns), + and all options with names matching these patterns are unset. + +vared + See *Note Zle Builtins::. + +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 processes + are not recorded, and that the user is potentially interested in + both, so this problem is intrinsic to process IDs. + +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 different from other + shells that write that message to standard error.) + + whence is most useful when NAME is only the last path component of + a command, i.e. does not include a `/'; in particular, pattern + 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, reserved + 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 following + 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. + + +where [ -wpmsS ] [ -x NUM ] NAME ... + Equivalent to whence -ca. + +which [ -wpamsS ] [ -x NUM ] NAME ... + Equivalent to whence -c. + +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 autoloading of + functions and sourcing of scripts by avoiding parsing of the text + when the files are read. + + The first form (without the -c, -a or -t options) creates a + compiled 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 *Note Functions:: for a description 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 + appended. 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 definition files for + those functions, if found, are compiled into FILE. If both -c and + -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 -c or -a option will be autoloaded as if the + KSH_AUTOLOAD option were unset. + + 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 additional + functions defined in the file, and any other initialization 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 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 _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, consequently + 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 compiled 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 compiled 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 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). + +zformat + See *Note The zsh/zutil Module::. + +zftp + See *Note The zsh/zftp Module::. + +zle + See *Note Zle Builtins::. + +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 modules + 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 already + loaded the duplicate module is ignored. If 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 -i is accepted for compatibility but has no effect. + + The NAMEd module is searched for in the same way a command + 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 status indicates if + the module was loaded. This is appropriate 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 system. 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 module + will not be loaded if its boot function fails. Similarly a + module can only be unloaded if its cleanup function runs + successfully. + + zmodload -F [ -almLe -P PARAM ] MODULE [ [+-]FEATURE ... ] + zmodload -F allows more selective control over the features + provided by modules. With no options apart from -F, the + module named MODULE is loaded, if it was not already loaded, + and the list of FEATUREs is set to the required 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 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. + + The standard features are builtins, conditions, parameters + and math functions; these are indicated by the prefix `b:', + `c:' (`C:' for an infix condition), `p:' and `f:', + respectively, followed by the name that the corresponding + 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 prefix. + + 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 features 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 disabled 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 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 + or - 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. + + With -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 + 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 autoload + 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 autoload 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 options + for listing and testing the existence of autoloadable + features. In this case -l is ignored if -L is specified. + 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 argument. + + With -d and one argument, all dependencies for that module + are listed. With -d and no arguments, all module + dependencies 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 defined, with the same name as the + module. -i suppresses the error if the builtin is already + defined or autoloaded, 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 possible if the + builtin is not yet loaded. -i suppresses the error if the + builtin is already removed (or never existed). + + Autoload requests are retained if the module is subsequently + 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 conditions. + + 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 corresponding 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, either 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 + 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 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 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. + + 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 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. + +zparseopts + See *Note The zsh/zutil Module::. + +zprof + See *Note The zsh/zprof Module::. + +zpty + See *Note The zsh/zpty Module::. + +zregexparse + See *Note The zsh/zutil Module::. + +zsocket + See *Note The zsh/net/socket Module::. + +zstyle + See *Note The zsh/zutil Module::. + +ztcp + See *Note The zsh/net/tcp Module::. + + + +File: zsh.info, Node: Zsh Line Editor, Next: Completion Widgets, Prev: Shell Builtin Commands, Up: Top + +18 Zsh Line Editor +****************** + + + +18.1 Description +================ + +If the 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. + +There are two display modes. The first, multiline mode, is the +default. It only works if the TERM parameter is set to a valid +terminal type that can move the cursor up. The second, single line +mode, is used if TERM is invalid or incapable of moving the cursor up, +or if the SINGLE_LINE_ZLE option is set. This mode is similar to +`ksh', and uses no termcap sequences. If TERM is "emacs", the ZLE +option will be unset by default. + +The parameters BAUD, COLUMNS, and LINES are also used by the line +editor. See *Note Parameters Used By The Shell::. + +The parameter zle_highlight is also used by the line editor; see *Note +Character Highlighting::. Highlighting of special characters and the +region between the cursor and the mark (as set with set-mark-command in +Emacs mode, or by 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: + + + zle_highlight=(none) + +In many places, references are made to the 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 digit-argument widget. See also *Note Arguments:: for some other +ways the numeric argument can be modified. + + + +* Menu: + +* Keymaps:: +* Zle Builtins:: +* Zle Widgets:: +* Character Highlighting:: + + + +File: zsh.info, Node: Keymaps, Next: Zle Builtins, Up: Zsh Line Editor + +18.2 Keymaps +============ + +A keymap in ZLE contains a set of bindings between key sequences and +ZLE commands. The empty key sequence cannot be bound. + +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. bindkey +can be used to manipulate keymap names. + +Initially, there are eight keymaps: + + +emacs + EMACS emulation + +viins + vi emulation - insert mode + +vicmd + vi emulation - command mode + +viopp + vi emulation - operator pending + +visual + vi emulation - selection active + +isearch + incremental search mode + +command + read a command name + +.safe + fallback keymap + +The `.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 `.' for their own keymaps. + +In addition to these names, either `emacs' or `viins' is also linked to +the name `main'. If one of the VISUAL or EDITOR environment variables +contain the string `vi' when the shell starts up then it will be +`viins', otherwise it will be `emacs'. bindkey's -e and -v options +provide a convenient way to override this default choice. + +When the editor starts up, it will select the `main' keymap. If that +keymap doesn't exist, it will use `.safe' instead. + +In the `.safe' keymap, each single key is bound to self-insert, except +for ^J (line feed) and ^M (return) which are bound to 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. + +18.2.1 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 +KEYTIMEOUT parameter; its default is 0.4 sec. There is no timeout if +the prefix string is not itself bound to a command. + +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 ? were typed and resets the input +state. + +As well as ZLE commands, key sequences can be bound to other strings, +by using `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. + +A key sequence typed by the user can be turned into a command name for +use in user-defined widgets with the read-command widget, described in +*Note Miscellaneous:: below. + +18.2.2 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 isearch keymap will +override a binding in the main keymap but all keys that are not +overridden can still be used. + +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 iw in viopp as this hides +the binding of i in vicmd. However, a longer sequence in the global +keymap that shares the same prefix can still apply so for example the +binding of ^Xa in the global keymap will be unaffected by the binding +of ^Xb in the local keymap. + + + + +File: zsh.info, Node: Zle Builtins, Next: Zle Widgets, Prev: Keymaps, Up: Zsh Line Editor + +18.3 Zle Builtins +================= + +The ZLE module contains three related builtin commands. The bindkey +command manipulates keymaps and key bindings; the vared command invokes +ZLE on the value of a shell parameter; and the zle command manipulates +editing widgets and allows command line access to ZLE commands from +within shell functions. + + +bindkey [ OPTIONS ] -l [ -L ] [ KEYMAP ... ] +bindkey [ OPTIONS ] -d +bindkey [ OPTIONS ] -D KEYMAP ... +bindkey [ OPTIONS ] -A OLD-KEYMAP NEW-KEYMAP +bindkey [ OPTIONS ] -N NEW-KEYMAP [ OLD-KEYMAP ] +bindkey [ OPTIONS ] -m +bindkey [ OPTIONS ] -r IN-STRING ... +bindkey [ OPTIONS ] -s IN-STRING OUT-STRING ... +bindkey [ OPTIONS ] IN-STRING COMMAND ... +bindkey [ OPTIONS ] [ IN-STRING ] + bindkey's options can be divided into three categories: keymap + selection for the current command, operation selection, and + others. The keymap selection options are: + + + -e + Selects keymap `emacs' for any operations by the current + command, and also links `emacs' to `main' so that it is + selected by default the next time the editor starts. + + -v + Selects keymap `viins' for any operations by the current + command, and also links `viins' to `main' so that it is + selected by default the next time the editor starts. + + -a + Selects keymap `vicmd' for any operations by the current + command. + + -M KEYMAP + The KEYMAP specifies a keymap name that is selected for any + operations by the current command. + + + If a keymap selection is required and none of the options above + are used, the `main' keymap is used. Some operations do not + permit a keymap to be selected, namely: + + + -l + List all existing keymap names; if any arguments are given, + list just those keymaps. + + If the -L option is also used, list in the form of bindkey + commands to create or link the keymaps. `bindkey -lL main' + shows which keymap is linked to `main', if any, and hence if + the standard emacs or vi emulation is in effect. This option + does not show the .safe keymap because it cannot be created + in that fashion; however, neither is `bindkey -lL .safe' + reported as an error, it simply outputs nothing. + + -d + Delete all existing keymaps and reset to the default state. + + -D KEYMAP ... + Delete the named KEYMAPs. + + -A OLD-KEYMAP NEW-KEYMAP + Make the NEW-KEYMAP name an alias for 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 NEW-KEYMAP name, it is deleted. + + -N NEW-KEYMAP [ OLD-KEYMAP ] + Create a new keymap, named NEW-KEYMAP. If a keymap already + has that name, it is deleted. If an OLD-KEYMAP name is + given, the new keymap is initialized to be a duplicate of it, + otherwise the new keymap will be empty. + + + To use a newly created keymap, it should be linked to main. Hence + the sequence of commands to create and use a new keymap `mymap' + initialized from the emacs keymap (which remains unchanged) is: + + + bindkey -N mymap emacs + bindkey -A mymap main + + Note that while `bindkey -A NEWMAP main' will work when NEWMAP is + emacs or viins, it will not work for vicmd, as switching from vi + insert to command mode becomes impossible. + + The following operations act on the `main' keymap if no keymap + selection option was given: + + + -m + Add the built-in set of meta-key bindings to the selected + keymap. Only keys that are unbound or bound to self-insert + are affected. + + -r IN-STRING ... + Unbind the specified IN-STRINGs in the selected keymap. This + is exactly equivalent to binding the strings to undefined-key. + + When -R is also used, interpret the IN-STRINGs as ranges. + + When -p is also used, the IN-STRINGs specify prefixes. Any + binding that has the given IN-STRING as a prefix, not + including the binding for the IN-STRING itself, if any, will + be removed. For example, + + + bindkey -rpM viins '^[' + + 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 + vi-cmd-mode). This is incompatible with the option -R. + + -s IN-STRING OUT-STRING ... + Bind each IN-STRING to each OUT-STRING. When IN-STRING is + typed, OUT-STRING will be pushed back and treated as input to + the line editor. When -R is also used, interpret the + IN-STRINGs as ranges. + + Note that both IN-STRING and OUT-STRING are subject to the + same form of interpretation, as described below. + + IN-STRING COMMAND ... + Bind each IN-STRING to each COMMAND. When -R is used, + interpret the IN-STRINGs as ranges. + + [ IN-STRING ] + List key bindings. If an 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 -e or -v option is + used alone, the keymap is _not_ displayed - the implicit + linking of keymaps is the only thing that happens.) + + When the option -p is used, the 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. + + When the -L option is used, the list is in the form of bindkey + commands to create the key bindings. + + + When the -R option is used as noted above, a valid range consists + of two characters, with an optional `-' between them. All + characters between the two specified, inclusive, are bound as + specified. + + For either IN-STRING or OUT-STRING, the following escape sequences + are recognised: + + + \a + bell character + + \b + backspace + + \e, \E + escape + + \f + form feed + + \n + linefeed (newline) + + \r + carriage return + + \t + horizontal tab + + \v + vertical tab + + \NNN + character code in octal + + \xNN + character code in hexadecimal + + \uNNNN + unicode character code in hexadecimal + + \UNNNNNNNN + unicode character code in hexadecimal + + \M[-]X + character with meta bit set + + \C[-]X + control character + + ^X + control character + + In all other cases, `\' escapes the following character. Delete is + written as `^?'. Note that `\M^?' and `^\M?' are not the same, + and that (unlike emacs), the bindings `\M-X' and `\eX' are + entirely distinct, although they are initialized to the same + bindings by `bindkey -m'. + +vared [ -Aacghe ] [ -p PROMPT ] [ -r RPROMPT ] + [ -M MAIN-KEYMAP ] [ -m VICMD-KEYMAP ] + [ -i INIT-WIDGET ] [ -f FINISH-WIDGET ] + [ -t TTY ] NAME + The value of the parameter NAME is loaded into the edit buffer, + and the line editor is invoked. When the editor exits, NAME is + set to the string value returned by the editor. When the -c flag + is given, the parameter is created if it doesn't already exist. + The -a flag may be given with -c to create an array parameter, or + the -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 -g flag may be given to + suppress warnings from the WARN_CREATE_GLOBAL and WARN_NESTED_VAR + options. + + If an array or array slice is being edited, separator characters + as defined in $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. + + Individual elements of existing array or associative array + parameters may be edited by using subscript syntax on NAME. New + elements are created automatically, even without -c. + + If the -p flag is given, the following string will be taken as the + prompt to display at the left. If the -r flag is given, the + following string gives the prompt to display at the right. If the + -h flag is specified, the history can be accessed from ZLE. If the + -e flag is given, typing ^D (Control-D) on an empty line causes + vared to exit immediately with a non-zero return value. + + The -M option gives a keymap to link to the main keymap during + editing, and the -m option gives a keymap to link to the vicmd + keymap during editing. For vi-style editing, this allows a pair + of keymaps to override viins and vicmd. For emacs-style editing, + only -M is normally needed but the -m option may still be used. + On exit, the previous keymaps will be restored. + + Vared calls the usual `zle-line-init' and `zle-line-finish' hooks + before and after it takes control. Using the -i and -f options, it + is possible to replace these with other custom widgets. + + If `-t TTY' is given, TTY is the name of a terminal device to be + used instead of the default /dev/tty. If TTY does not refer to a + terminal an error is reported. + +zle +zle -l [ -L | -a ] [ STRING ... ] +zle -D WIDGET ... +zle -A OLD-WIDGET NEW-WIDGET +zle -N WIDGET [ FUNCTION ] +zle -f FLAG [ FLAG... ] +zle -C WIDGET COMPLETION-WIDGET FUNCTION +zle -R [ -c ] [ DISPLAY-STRING ] [ STRING ... ] +zle -M STRING +zle -U STRING +zle -K KEYMAP +zle -F [ -L | -w ] [ FD [ HANDLER ] ] +zle -I +zle -T [ tc FUNCTION | -r tc | -L ] +zle WIDGET [ -n NUM ] [ -Nw ] [ -K KEYMAP ] ARGS ... + The zle builtin performs a number of different actions concerning + ZLE. + + 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. + + Otherwise, which operation it performs depends on its options: + + + -l [ -L | -a ] [ STRING ] + List all existing user-defined widgets. If the -L option is + used, list in the form of zle commands to create the widgets. + + When combined with the -a option, all widget names are listed, + including the builtin ones. In this case the -L option is + ignored. + + If at least one STRING is given, and -a is present or -L is + not used, nothing will be printed. The return status will be + zero if all STRINGs are names of existing widgets and + non-zero if at least one STRING is not a name of a defined + widget. If -a is also present, all widget names are used for + the comparison including builtin widgets, else only + user-defined widgets are used. + + If at least one STRING is present and the -L option is used, + user-defined widgets matching any STRING are listed in the + form of zle commands to create the widgets. + + -D WIDGET ... + Delete the named WIDGETs. + + -A OLD-WIDGET NEW-WIDGET + Make the NEW-WIDGET name an alias for 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 NEW-WIDGET name, it is deleted. + + -N WIDGET [ 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 + FUNCTION is called. If no function name is specified, it + defaults to the same name as the widget. For further + information, see *Note Zle Widgets::. + + -f FLAG [ FLAG... ] + Set various flags on the running widget. Possible values for + FLAG are: + + 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 YANK_START and YANK_END correctly. yankbefore does the + same but is used when the yanked text appears after the + cursor. + + 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 `zle -f kill' + to retain this effect. + + vichange for indicating that the widget represents a vi + change that can be repeated as a whole with + `vi-repeat-change'. The flag should be set early in the + function before inspecting the value of 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. + + -C WIDGET COMPLETION-WIDGET FUNCTION + Create a user-defined completion widget named WIDGET. The + completion widget will behave like the built-in + completion-widget whose name is given as COMPLETION-WIDGET. + To generate the completions, the shell function FUNCTION will + be called. For further information, see *Note Completion + Widgets::. + + -R [ -c ] [ DISPLAY-STRING ] [ STRING ... ] + Redisplay the command line; this is to be called from within + a user-defined widget to allow changes to become visible. If + a DISPLAY-STRING is given and not empty, this is shown in the + status line (immediately below the line being edited). + + If the optional STRINGs are given they are listed below the + prompt in the same way as completion lists are printed. If no + STRINGs are given but the -c option is used such a list is + cleared. + + Note that this option is only useful for widgets that do not + exit immediately after using it because the strings displayed + will be erased immediately after return from the widget. + + 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. + + The status is zero if zle was active, else one. + + -M STRING + As with the -R option, the STRING will be displayed below the + command line; unlike the -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 STRING will still be + displayed after the widget returns (until it is overwritten + by subsequent commands). + + -U STRING + This pushes the characters in the STRING onto the input stack + of ZLE. After the widget currently executed finishes ZLE + will behave as if the characters in the STRING were typed by + the user. + + 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 STRING will be processed in + the order in which they appear in the string. + + -K KEYMAP + Selects the keymap named KEYMAP. An error message will be + displayed if there is no such keymap. + + 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 `main' keymap selected. + + -F [ -L | -w ] [ FD [ HANDLER ] ] + Only available if your system supports one of the `poll' or + `select' system calls; most modern systems do. + + Installs HANDLER (the name of a shell function) to handle + input from file descriptor FD. Installing a handler for an + 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 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. + + When zle is attempting to read data, it will examine both the + terminal and the list of handled FD's. If data becomes + available on a handled FD, zle calls 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: `hup' + for a disconnect, `nval' for a closed or otherwise invalid + descriptor, or `err' for any other condition. Systems that + support only the `select' system call always use `err'. + + If the option -w is also given, the HANDLER is instead a line + editor widget, typically a shell function made into a widget + using `zle -N'. In that case HANDLER can use all the + facilities of zle to update the current editing line. Note, + however, that as handling FD takes place at a low level + changes to the display will not automatically appear; the + widget should call `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. + + If either type of handler produces output to the terminal, it + should call `zle -I' before doing so (see below). Handlers + should not attempt to read from the terminal. + + If no HANDLER is given, but an FD is present, any handler for + that FD is removed. If there is none, an error message is + printed and status 1 is returned. + + If no arguments are given, or the -L option is supplied, a + list of handlers is printed in a form which can be stored for + later execution. + + An FD (but not a HANDLER) may optionally be given with the -L + option; in this case, the function will list the handler if + any, else silently return status 1. + + Note that this feature should be used with care. Activity on + one of the FD's which is not properly handled can cause the + terminal to become unusable. Removing an FD handler from + within a signal trap may cause unpredictable behavior. + + Here is a simple example of using this feature. A connection + to a remote TCP port is created using the ztcp command; see + *Note 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. + + + 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 + + -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: + + + TRAPUSR1() { + # Invalidate zle display + [[ -o zle ]] && zle -I + # Show output + print Hello + } + + In general, the trap function may need to test whether zle is + active before using this method (as shown in the example), + since the zsh/zle module may not even be loaded; if it is + not, the command can be skipped. + + It is possible to call `zle -I' several times before control + is returned to the editor; the display will only be + invalidated the first time to minimise disruption. + + Note that there are normally better ways of manipulating the + display from within zle widgets; see, for example, `zle -R' + above. + + The returned status is zero if zle was invalidated, even + though this may have been by a previous call to `zle -I' or + by a system notification. To test if a zle widget may be + called at this point, execute zle with no arguments and + examine the return status. + + -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. + + `zle -T TRANSFORMATION FUNC' specifies that the given + TRANSFORMATION (see below) is effected by shell function FUNC. + + `zle -Tr TRANSFORMATION' removes the given TRANSFORMATION if + it was present (it is not an error if none was). + + `zle -TL' can be used to list all transformations currently in + operation. + + Currently the only transformation is 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 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. + + WIDGET [ -n NUM ] [ -Nw ] [ -K KEYMAP ] ARGS ... + Invoke the specified WIDGET. This can only be done when ZLE + is active; normally this will be within a user-defined widget. + + With the options -n and -N, the current numeric argument will + be saved and then restored after the call to WIDGET; `-n NUM' + sets the numeric argument temporarily to NUM, while `-N' sets + it to the default, i.e. as if there were none. + + With the option -K, KEYMAP will be used as the current keymap + during the execution of the widget. The previous keymap will + be restored when the widget exits. + + Normally, calling a widget in this way does not set the + special parameter 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 -w, WIDGET and + related parameters are set to reflect the widget being + executed by the zle call. + + 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 --. 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 history-search-forward and + -backward and the corresponding functions prefixed by vi-, + and by universal-argument. No error is flagged if the + command does not use the arguments, or only uses some of them. + + 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. + + A non-zero return status causes the shell to beep when the + widget exits, unless the BEEP options was unset or the widget + was called via the zle command. Thus if a user defined + widget requires an immediate beep, it should call the beep + widget directly. + + + + + +File: zsh.info, Node: Zle Widgets, Next: Character Highlighting, Prev: Zle Builtins, Up: Zsh Line Editor + +18.4 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. + +The standard widgets built into ZLE are listed in Standard Widgets +below. Other built-in widgets can be defined by other modules (see +*Note Zsh Modules::). Each built-in widget has two names: its normal +canonical name, and the same name preceded by a `.'. The `.' 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. + +User-defined widgets are defined using `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 `.'. + +18.5 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 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 read -k or 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. + +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 local. + +Inside completion widgets and traps called while ZLE is active, these +parameters are available read-only. + +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: + + + 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 + } + } + + +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. + +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. + +CONTEXT (scalar) + The context in which zle was called to read a line; read-only. + One of the values: + + + start + The start of a command line (at prompt PS1). + + cont + A continuation to a command line (at prompt PS2). + + select + In a select loop (at prompt PS3). + + vared + Editing a variable in vared. + + +CURSOR (integer) + The offset of the cursor, within the edit buffer. This is in the + range 0 to $#BUFFER, and is by definition equal to $#LBUFFER. + Attempts to move the cursor outside the buffer will result in the + cursor being moved to the appropriate end of the buffer. + +CUTBUFFER (scalar) + The last item cut using one of the `kill-' commands; the string + which the next yank would insert in the line. Later entries in + the kill ring are in the array killring. Note that the command + `zle copy-region-as-kill 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. + +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 HISTCMD, + which always gives the number of the history line being added to + the main shell's history. HISTNO refers to the line being + retrieved within zle. + +ISEARCHMATCH_ACTIVE (integer) +ISEARCHMATCH_START (integer) +ISEARCHMATCH_END (integer) + ISEARCHMATCH_ACTIVE indicates whether a part of the BUFFER is + currently matched by an incremental search pattern. + ISEARCHMATCH_START and ISEARCHMATCH_END give the location of the + matched part and are in the same units as CURSOR. They are only + valid for reading when ISEARCHMATCH_ACTIVE is non-zero. + + All parameters are read-only. + +KEYMAP (scalar) + The name of the currently selected keymap; read-only. + +KEYS (scalar) + The keys typed to invoke this widget, as a literal string; + read-only. + +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 PENDING; the two values are distinct. + +killring (array) + The array of previously killed items, with the most recently + killed first. This gives the items that would be retrieved by a + yank-pop in the same order. Note, however, that the most recently + killed item is in $CUTBUFFER; $killring shows the array of + previous entries. + + 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 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. + +LASTABORTEDSEARCH (scalar) + The last search string used by an interactive search that was + aborted by the user (status 3 returned by the search widget). + +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. + +LASTWIDGET (scalar) + The name of the last widget that was executed; read-only. + +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 $LBUFFER and the + old $RBUFFER. + +MARK (integer) + Like CURSOR, but for the mark. With vi-mode operators that wait for + a movement command to select a region of text, setting MARK allows + the selection to extend in both directions from the initial cursor + position. + +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 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. + +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 + KEYS_QUEUED_COUNT; the two values are distinct. + +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. + +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. + +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. + +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 $LBUFFER and the + new $RBUFFER. + +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 *Note Character + Highlighting::. + +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 + PREDISPLAY and POSTDISPLAY are possible, but note that the P flag + is needed for character indexing to include PREDISPLAY. + + Each string consists of the following parts: + + + * Optionally, a `P' to signify that the start and end offset + that follow include any string set by the PREDISPLAY special + parameter; this is needed if the predisplay string itself is + to be highlighted. Whitespace may follow the `P'. + + * A start offset in the same units as CURSOR, terminated by + whitespace. + + * An end offset in the same units as CURSOR, terminated by + whitespace. + + * A highlight specification in the same format as used for + contexts in the parameter zle_highlight, see *Note Character + Highlighting::; for example, standout or fg=red,bold. + + For example, + + + region_highlight=("P0 20 bold") + + specifies that the first twenty characters of the text including + any predisplay string should be highlighted in bold. + + Note that the effect of region_highlight is not saved and + disappears as soon as the line is accepted. + + The final highlighting on the command line depends on both + region_highlight and zle_highlight; see *Note Character + Highlighting:: for details. + +registers (associative array) + The contents of each of the vi register buffers. These are + typically set using vi-set-buffer followed by a delete, change or + yank command. + +SUFFIX_ACTIVE (integer) +SUFFIX_START (integer) +SUFFIX_END (integer) + SUFFIX_ACTIVE indicates whether an auto-removable completion suffix + is currently active. SUFFIX_START and SUFFIX_END give the location + of the suffix and are in the same units as CURSOR. They are only + valid for reading when SUFFIX_ACTIVE is non-zero. + + All parameters are read-only. + +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 undo widget in order to + undo back to the recorded point. Read-only. + +UNDO_LIMIT_NO (integer) + A number corresponding to an existing change in the undo history; + compare UNDO_CHANGE_NO. If this is set to a value greater than + zero, the undo command will not allow the line to be undone beyond + the given change number. It is still possible to use `zle undo + CHANGE' in a widget to undo beyond that point; in that case, it + will not be possible to undo at all until UNDO_LIMIT_NO is + reduced. Set to 0 to disable the limit. + + A typical use of this variable in a widget function is as follows + (note the additional function scope is required): + + + () { + local UNDO_LIMIT_NO=$UNDO_CHANGE_NO + # Perform some form of recursive edit. + } + +WIDGET (scalar) + The name of the widget currently being executed; read-only. + +WIDGETFUNC (scalar) + The name of the shell function that implements a widget defined + with either zle -N or zle -C. In the former case, this is the + second argument to the 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 zle -C command that defined + the widget. Read-only. + +WIDGETSTYLE (scalar) + Describes the implementation behind the completion widget + currently being executed; the second argument that followed zle -C + when the widget was defined. This is the name of a builtin + completion widget. For widgets defined with zle -N this is set to + the empty string. Read-only. + +YANK_ACTIVE (integer) +YANK_START (integer) +YANK_END (integer) + YANK_ACTIVE indicates whether text has just been yanked (pasted) + into the buffer. YANK_START and YANK_END give the location of the + pasted text and are in the same units as CURSOR. They are only + valid for reading when YANK_ACTIVE is non-zero. They can also be + assigned by widgets that insert text in a yank-like fashion, for + example wrappers of bracketed-paste. See also zle -f. + + YANK_ACTIVE is read-only. + +ZLE_RECURSIVE (integer) + Usually zero, but incremented inside any instance of + recursive-edit. Hence indicates the current recursion level. + + ZLE_RECURSIVE is read-only. + +ZLE_STATE (scalar) + Contains a set of space-separated words that describe the current + zle state. + + Currently, the states shown are the insert mode as set by the + overwrite-mode or vi-replace widgets and whether history commands + will visit imported entries as controlled by the set-local-history + widget. The string contains `insert' if characters to be inserted + on the command line move existing characters to the right or + `overwrite' if characters to be inserted overwrite existing + characters. It contains `localhistory' if only local history + commands will be visited or `globalhistory' if imported history + commands will also be visited. + + 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: + + + if [[ $ZLE_STATE == *globalhistory*insert* ]]; then ...; fi + + + +18.5.1 Special Widgets +---------------------- + +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. + + +zle-isearch-exit + Executed at the end of incremental search at the point where the + isearch prompt is removed from the display. See + zle-isearch-update for an example. + +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 `zle -M' within the widget. For example, + + + zle-isearch-update() { zle -M "Line $HISTNO"; } + zle -N zle-isearch-update + + Note the line output by `zle -M' is not deleted on exit from + incremental search. This can be done from a zle-isearch-exit + widget: + + + zle-isearch-exit() { zle -M ""; } + zle -N zle-isearch-exit + +zle-line-pre-redraw + Executed whenever the input line is about to be redrawn, providing + an opportunity to update the region_highlight array. + +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. + + + zle-line-init() { zle -K vicmd; } + zle -N zle-line-init + + (The command inside the function sets the keymap directly; it is + equivalent to zle vi-cmd-mode.) + +zle-line-finish + This is similar to zle-line-init but is executed every time the + line editor has finished reading a line of input. + +zle-history-line-set + Executed when the history line changes. + +zle-keymap-select + Executed every time the keymap changes, i.e. the special parameter + 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. + + The value $KEYMAP within the function reflects the new keymap. The + old keymap is passed as the sole argument. + + This can be used for detecting switches between the vi command + (vicmd) and insert (usually main) keymaps. + + + +18.6 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 +`emacs', `vicmd' and `viins' keymaps, respectively). + +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 viins keymap, the initial escape character of the +sequences serves also to return to the vicmd keymap: whether this +happens is determined by the KEYTIMEOUT parameter, see *Note +Parameters::. + +* Menu: + +* Movement:: +* History Control:: +* Modifying Text:: +* Arguments:: +* Completion:: +* Miscellaneous:: +* Text Objects:: + + +File: zsh.info, Node: Movement, Next: History Control, Up: Zle Widgets + +18.6.1 Movement +--------------- + + +vi-backward-blank-word (unbound) (B) (unbound) + Move backward one word, where a word is defined as a series of + non-blank characters. + +vi-backward-blank-word-end (unbound) (gE) (unbound) + Move to the end of the previous word, where a word is defined as a + series of non-blank characters. + +backward-char (^B ESC-[D) (unbound) (unbound) + Move backward one character. + +vi-backward-char (unbound) (^H h ^?) (ESC-[D) + Move backward one character, without changing lines. + +backward-word (ESC-B ESC-b) (unbound) (unbound) + Move to the beginning of the previous word. + +emacs-backward-word + Move to the beginning of the previous word. + +vi-backward-word (unbound) (b) (unbound) + Move to the beginning of the previous word, vi-style. + +vi-backward-word-end (unbound) (ge) (unbound) + Move to the end of the previous word, vi-style. + +beginning-of-line (^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. + +vi-beginning-of-line + Move to the beginning of the line, without changing lines. + +down-line (unbound) (unbound) (unbound) + Move down a line in the buffer. + +end-of-line (^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. + +vi-end-of-line (unbound) ($) (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. + +vi-forward-blank-word (unbound) (W) (unbound) + Move forward one word, where a word is defined as a series of + non-blank characters. + +vi-forward-blank-word-end (unbound) (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. + +forward-char (^F ESC-[C) (unbound) (unbound) + Move forward one character. + +vi-forward-char (unbound) (space l) (ESC-[C) + Move forward one character. + +vi-find-next-char (^X^F) (f) (unbound) + Read a character from the keyboard, and move to the next + occurrence of it in the line. + +vi-find-next-char-skip (unbound) (t) (unbound) + Read a character from the keyboard, and move to the position just + before the next occurrence of it in the line. + +vi-find-prev-char (unbound) (F) (unbound) + Read a character from the keyboard, and move to the previous + occurrence of it in the line. + +vi-find-prev-char-skip (unbound) (T) (unbound) + Read a character from the keyboard, and move to the position just + after the previous occurrence of it in the line. + +vi-first-non-blank (unbound) (^) (unbound) + Move to the first non-blank character in the line. + +vi-forward-word (unbound) (w) (unbound) + Move forward one word, vi-style. + +forward-word (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 WORDCHARS parameter. + +emacs-forward-word + Move to the end of the next word. + +vi-forward-word-end (unbound) (e) (unbound) + Move to the end of the next word. + +vi-goto-column (ESC-|) (|) (unbound) + Move to the column specified by the numeric argument. + +vi-goto-mark (unbound) (`) (unbound) + Move to the specified mark. + +vi-goto-mark-line (unbound) (') (unbound) + Move to beginning of the line containing the specified mark. + +vi-repeat-find (unbound) (;) (unbound) + Repeat the last vi-find command. + +vi-rev-repeat-find (unbound) (,) (unbound) + Repeat the last vi-find command in the opposite direction. + +up-line (unbound) (unbound) (unbound) + Move up a line in the buffer. + + |