From c175751b501a3a4cb40ad4787340a597ea769be4 Mon Sep 17 00:00:00 2001 From: Tanaka Akira Date: Thu, 15 Apr 1999 18:05:35 +0000 Subject: Initial revision --- Doc/Zsh/.distfiles | 9 + Doc/Zsh/.lastloc | 1 + Doc/Zsh/arith.yo | 73 +++ Doc/Zsh/builtins.yo | 1184 ++++++++++++++++++++++++++++++++++++++++++++++ Doc/Zsh/compat.yo | 69 +++ Doc/Zsh/compctl.yo | 526 ++++++++++++++++++++ Doc/Zsh/cond.yo | 158 +++++++ Doc/Zsh/exec.yo | 25 + Doc/Zsh/expn.yo | 1052 ++++++++++++++++++++++++++++++++++++++++ Doc/Zsh/filelist.yo | 15 + Doc/Zsh/files.yo | 26 + Doc/Zsh/func.yo | 107 +++++ Doc/Zsh/grammar.yo | 335 +++++++++++++ Doc/Zsh/guide.yo | 149 ++++++ Doc/Zsh/index.yo | 24 + Doc/Zsh/intro.yo | 38 ++ Doc/Zsh/invoke.yo | 23 + Doc/Zsh/jobs.yo | 91 ++++ Doc/Zsh/metafaq.yo | 142 ++++++ Doc/Zsh/mod_cap.yo | 28 ++ Doc/Zsh/mod_clone.yo | 19 + Doc/Zsh/mod_comp1.yo | 11 + Doc/Zsh/mod_compctl.yo | 7 + Doc/Zsh/mod_deltochar.yo | 12 + Doc/Zsh/mod_example.yo | 16 + Doc/Zsh/mod_files.yo | 100 ++++ Doc/Zsh/mod_sched.yo | 17 + Doc/Zsh/mod_stat.yo | 145 ++++++ Doc/Zsh/mod_zftp.yo | 421 +++++++++++++++++ Doc/Zsh/mod_zle.yo | 193 ++++++++ Doc/Zsh/modules.yo | 64 +++ Doc/Zsh/options.yo | 1039 ++++++++++++++++++++++++++++++++++++++++ Doc/Zsh/params.yo | 812 +++++++++++++++++++++++++++++++ Doc/Zsh/prompt.yo | 209 ++++++++ Doc/Zsh/redirect.yo | 183 +++++++ Doc/Zsh/restricted.yo | 44 ++ Doc/Zsh/seealso.yo | 25 + Doc/Zsh/zle.yo | 1076 +++++++++++++++++++++++++++++++++++++++++ 38 files changed, 8468 insertions(+) create mode 100644 Doc/Zsh/.distfiles create mode 100644 Doc/Zsh/.lastloc create mode 100644 Doc/Zsh/arith.yo create mode 100644 Doc/Zsh/builtins.yo create mode 100644 Doc/Zsh/compat.yo create mode 100644 Doc/Zsh/compctl.yo create mode 100644 Doc/Zsh/cond.yo create mode 100644 Doc/Zsh/exec.yo create mode 100644 Doc/Zsh/expn.yo create mode 100644 Doc/Zsh/filelist.yo create mode 100644 Doc/Zsh/files.yo create mode 100644 Doc/Zsh/func.yo create mode 100644 Doc/Zsh/grammar.yo create mode 100644 Doc/Zsh/guide.yo create mode 100644 Doc/Zsh/index.yo create mode 100644 Doc/Zsh/intro.yo create mode 100644 Doc/Zsh/invoke.yo create mode 100644 Doc/Zsh/jobs.yo create mode 100644 Doc/Zsh/metafaq.yo create mode 100644 Doc/Zsh/mod_cap.yo create mode 100644 Doc/Zsh/mod_clone.yo create mode 100644 Doc/Zsh/mod_comp1.yo create mode 100644 Doc/Zsh/mod_compctl.yo create mode 100644 Doc/Zsh/mod_deltochar.yo create mode 100644 Doc/Zsh/mod_example.yo create mode 100644 Doc/Zsh/mod_files.yo create mode 100644 Doc/Zsh/mod_sched.yo create mode 100644 Doc/Zsh/mod_stat.yo create mode 100644 Doc/Zsh/mod_zftp.yo create mode 100644 Doc/Zsh/mod_zle.yo create mode 100644 Doc/Zsh/modules.yo create mode 100644 Doc/Zsh/options.yo create mode 100644 Doc/Zsh/params.yo create mode 100644 Doc/Zsh/prompt.yo create mode 100644 Doc/Zsh/redirect.yo create mode 100644 Doc/Zsh/restricted.yo create mode 100644 Doc/Zsh/seealso.yo create mode 100644 Doc/Zsh/zle.yo (limited to 'Doc/Zsh') diff --git a/Doc/Zsh/.distfiles b/Doc/Zsh/.distfiles new file mode 100644 index 000000000..42517f507 --- /dev/null +++ b/Doc/Zsh/.distfiles @@ -0,0 +1,9 @@ +DISTFILES_SRC=' + .distfiles + arith.yo builtins.yo compat.yo compctl.yo cond.yo exec.yo expn.yo + filelist.yo files.yo func.yo grammar.yo guide.yo index.yo intro.yo + invoke.yo jobs.yo metafaq.yo mod_cap.yo mod_clone.yo mod_comp1.yo + mod_compctl.yo mod_deltochar.yo mod_example.yo mod_files.yo mod_sched.yo + mod_stat.yo mod_zle.yo modules.yo options.yo params.yo prompt.yo + redirect.yo restricted.yo seealso.yo zle.yo +' diff --git a/Doc/Zsh/.lastloc b/Doc/Zsh/.lastloc new file mode 100644 index 000000000..8b1a784a8 --- /dev/null +++ b/Doc/Zsh/.lastloc @@ -0,0 +1 @@ +(("/home/user2/pws/src/zsh-3.1.5/Doc/Zsh/expn.yo" . 33735)) diff --git a/Doc/Zsh/arith.yo b/Doc/Zsh/arith.yo new file mode 100644 index 000000000..1560c81d3 --- /dev/null +++ b/Doc/Zsh/arith.yo @@ -0,0 +1,73 @@ +texinode(Arithmetic Evaluation)(Conditional Expressions)(Jobs & Signals)(Top) +chapter(Arithmetic Evaluation) +ifzman(\ +sect(Arithmetic Evaluation) +)\ +cindex(arithmetic evaluation) +cindex(evaluation, arithmetic) +An ability to perform integer arithmetic is provided with the builtin tt(let). +findex(let, use of) +Evaluations are performed using em(long) arithmetic. +A leading `tt(0x)' or `tt(0X)' denotes hexadecimal. +Otherwise, numbers are of the form `[var(base)tt(#)]var(n)', +where var(base) is a decimal number between two and thirty-six +representing the arithmetic base and var(n) +is a number in that base (for example, `tt(16#ff)' is 255 in hexadecimal). +If var(base) is omitted +then base 10 is used. For backwards compatibility the form +`tt([)var(base)tt(])var(n)' is also accepted. + +cindex(arithmetic operators) +cindex(operators, arithmetic) +An arithmetic expression uses nearly the same syntax, precedence, and +associativity of expressions in C. +The following operators are supported (listed in decreasing order +of precedence): + +startsitem() +sitem(tt(PLUS() - ! ~ PLUS()PLUS() --))(unary plus/minus, logical NOT, complement, {pre,post}{in,de}crement) +sitem(tt(<< >>))(bitwise shift left, right) +sitem(tt(&))(bitwise AND) +sitem(tt(^))(bitwise XOR) +sitem(tt(|))(bitwise OR) +sitem(tt(**))(exponentiation) +sitem(tt(* / %))(multiplication, division, modulus (remainder)) +sitem(tt(PLUS() -))(addition, subtraction) +sitem(tt(< > <= >=))(comparison) +sitem(tt(== !=))(equality and inequality) +sitem(tt(&&))(logical AND) +sitem(tt(|| ^^))(logical OR, XOR) +sitem(tt(? :))(ternary operator) +sitem(tt(= PLUS()= -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=))(assignment) +sitem(tt(,))(comma operator) +endsitem() + +The operators `tt(&&)', `tt(||)', `tt(&&=)', and `tt(||=)' are short-circuiting, +and only one of the latter two expressions in a ternary operator +is evaluated. Note the precedence of the bitwise AND, OR, +and XOR operators. + +An expression of the form `tt(#\)var(x)' where var(x) is any character +gives the ascii value of this character and an expression of the form +`tt(#)var(foo)' gives the ascii value of the first character of the value +of the parameter var(foo). + +Named parameters and subscripted arrays can be referenced by name within an +arithmetic expression without using the parameter substitution syntax. + +An internal integer representation of a named parameter +can be specified with the tt(integer) builtin. +cindex(parameters, integer) +cindex(integer parameters) +findex(integer, use of) +Arithmetic evaluation is performed on the value of each +assignment to a named parameter declared integer +in this manner. + +Since many of the arithmetic operators require +quoting, an alternative form of the tt(let) command is provided. +For any command which begins with a tt(LPAR()LPAR()), +all the characters until a matching tt(RPAR()RPAR()) +are treated as a quoted expression. +More precisely, `tt(LPAR()LPAR()) ... tt(RPAR()RPAR())' +is equivalent to `tt(let ")...tt(")'. diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo new file mode 100644 index 000000000..8959543c5 --- /dev/null +++ b/Doc/Zsh/builtins.yo @@ -0,0 +1,1184 @@ +texinode(Shell Builtin Commands)(Zsh Line Editor)(Options)(Top) +chapter(Shell Builtin Commands) +ifzman(\ +sect(Shell Builtin Commands) +)\ +cindex(builtin commands) +cindex(commands, builtin) +def(prefix)(1)(\ +findex(ARG1) +item(tt(ARG1) var(simple command))( +See noderef(Precommand Modifiers). +)\ +)\ +def(alias)(2)(\ +findex(ARG1) +item(tt(ARG1))( +Same as tt(ARG2). +)\ +)\ +startitem() +prefix(-) +findex(.) +item(tt(.) var(file) [ var(arg) ... ])( +Read commands from var(file) and execute them in the current shell +environment. +If var(file) does not contain a slash, or if tt(PATH_DIRS) +is set, the shell looks in the components of tt($path) to find the +directory containing var(file). +Files in the current directory are not read unless `tt(.)' appears +somewhere in tt($path). + +If any arguments var(arg) are given, +they become the positional parameters; the old positional +parameters are restored when the var(file) is done executing. +The exit status is the exit status of the last command executed. +) +findex(NOTRANS(:)) +cindex(expanding parameters) +cindex(parameters, expanding) +cindex(doing nothing) +item(tt(:) [ var(arg) ... ])( +This command only expands parameters. A zero exit code is returned. +) +findex(alias) +cindex(aliases, defining) +cindex(aliases, listing) +item(tt(alias) [ tt(-gmrL) ] [ var(name)[tt(=)var(value)] ... ])( +For each var(name) with a corresponding var(value), define an alias +with that value. A trailing space in var(value) causes the next word +to be checked for alias substitution. If the tt(-g) flag is present, +define a global alias; global aliases are expanded even if they do not +occur in command position. + +For each var(name) with no var(value), +print the value of var(name), if any. With no arguments, print all +currently defined aliases. If the tt(-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 the tt(-g) or tt(-r) flags +are present, then restrict the printing to global or regular +aliases, respectively. + +If the tt(-L) flag is present, then print each +alias in a manner suitable for putting in a startup script. The exit +status is nonzero if a var(name) (with no var(value)) is given for +which no alias has been defined. +) +findex(autoload) +cindex(functions, autoloading) +cindex(autoloading functions) +alias(autoload)(functions -u) +findex(bg) +cindex(jobs, backgrounding) +xitem(tt(bg) [ var(job) ... ]) +item(var(job) ... tt(&))( +Put each specified var(job) in the background, +or the current job if none is specified. +) +findex(break) +cindex(exiting loops) +cindex(loops, exiting) +item(tt(break) [ var(n) ])( +Exit from an enclosing tt(for), tt(while), +tt(until), tt(select) or tt(repeat) loop. If var(n) +is specified, then break var(n) levels instead of just one. +) +findex(builtin) +item(tt(builtin) var(name) [ var(args) ... ])( +Executes the builtin var(name), with the given var(args). +) +alias(bye)(exit) +findex(cd) +cindex(directories, changing) +xitem(tt(cd) [ tt(-sLP) ] [ var(arg) ]) +xitem(tt(cd) [ tt(-sLP) ] var(old) var(new)) +item(tt(cd) [ tt(-sLP) ] {tt(PLUS())|tt(-)}var(n))( +Change the current directory. In the first form, change the +current directory to var(arg), or to the value of tt($HOME) if +var(arg) is not specified. If var(arg) is `tt(-)', change to the +value of tt($OLDPWD), the previous directory. +If a directory named var(arg) is not found in the current directory +and var(arg) does not begin with a slash, +search each component of the shell parameter tt(cdpath). +If the option tt(CDABLE_VARS) is set, and a parameter named var(arg) +exists whose value begins with a slash, treat its value as +the directory. + +The second form of tt(cd) substitutes the string var(new) +for the string var(old) in the name of the current directory, +and tries to change to this new directory. + +The third form of tt(cd) extracts an entry from the directory +stack, and changes to that directory. An argument of the form +`tt(PLUS())var(n)' identifies a stack entry by counting from the left +of the list shown by the tt(dirs) command, starting with zero. +An argument of the form `tt(-)var(n)' counts from the right. +If the tt(PUSHD_MINUS) option is set, the meanings of `tt(PLUS())' +and `tt(-)' in this context are swapped. + +If the tt(-s) option is specified, tt(cd) refuses to change the current +directory if the given pathname contains symlinks. If the tt(-P) option +is given or the tt(CHASE_LINKS) option is set, symbolic links are resolved +to their true values. If the tt(-L) option is given symbolic links are +followed regardless of the state of the tt(CHASE_LINKS) option. +) +alias(chdir)(cd) +prefix(command) +findex(continue) +cindex(loops, continuing) +cindex(continuing loops) +item(tt(continue) [ var(n) ])( +Resume the next iteration of the enclosing +tt(for), tt(while), tt(until), tt(select) or +tt(repeat) loop. If var(n) is specified, break out of +var(n)-1 loops and resume at the var(n)th enclosing loop. +) +alias(declare)(typeset) +findex(dirs) +cindex(directory stack, printing) +item(tt(dirs) [ tt(-v) ] [ var(arg) ... ])( +With no arguments, print the contents of the directory stack. +If the tt(-v) option is given, number the directories +in the stack when printing. +Directories are added to this stack with the tt(pushd) command, +and removed with the tt(cd) or tt(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. +) +findex(disable) +cindex(disabling commands) +cindex(commands, disabling) +item(tt(disable) [ tt(-afmr) ] var(name) ...)( +Temporarily disable the var(name)d hash table elements. The default +is to disable builtin commands. This allows you to use an external +command with the same name as a builtin command. The tt(-a) option +causes tt(disable) to act on aliases. The tt(-f) option causes +tt(disable) to act on shell functions. The tt(-r) options causes +tt(disable) to act on reserved words. Without arguments all disabled +hash table elements from the corresponding hash table are printed. +With the tt(-m) flag the arguments are taken as patterns (should be +quoted to preserve them from being taken as glob patterns), and all hash +table elements from the corresponding hash table matching these patterns +are disabled. Disabled objects can be enabled with the tt(enable) +command. +) +findex(disown) +cindex(jobs, disowning) +xitem(tt(disown) [ var(job) ... ]) +xitem(var(job) ... tt(&|)) +item(var(job) ... tt(&!))( +Remove the specified var(job)s from the job table; the shell will +no longer report their status, and will not complain if you +try to exit an interactive shell with them running or stopped. +If no var(job) is specified, disown the current job. +) +findex(echo) +item(tt(echo) [ tt(-neE) ] [ var(arg) ... ])( +Write each var(arg) on the standard output, with a space separating +each one. +If the tt(-n) flag is not present, print a newline at the end. +tt(echo) recognizes the following escape sequences: + +startsitem() +sitem(tt(\a))(bell character) +sitem(tt(\b))(backspace) +sitem(tt(\c))(suppress final newline) +sitem(tt(\e))(escape) +sitem(tt(\f))(form feed) +sitem(tt(\n))(linefeed (newline)) +sitem(tt(\r))(carriage return) +sitem(tt(\t))(horizontal tab) +sitem(tt(\v))(vertical tab) +sitem(tt(\\))(backslash) +sitem(tt(\0)var(NNN))(character code in octal) +sitem(tt(\x)var(NN))(character code in hexadecimal) +endsitem() + +pindex(BSD_ECHO, use of) +The tt(-E) flag, or the tt(BSD_ECHO) option, can be used to disable +these escape sequences. In the latter case, tt(-e) flag can be used to +enable them. +) +findex(echotc) +cindex(termcap string, printing) +item(tt(echotc) var(cap) [ var(arg) ... ])( +Output the termcap string corresponding to the capability +var(cap), with optional arguments. +) +findex(emulate) +cindex(compatibility, sh) +cindex(compatibility, ksh) +cindex(compatibility, csh) +cindex(sh, compatibility) +cindex(ksh, compatibility) +cindex(csh, compatibility) +item(tt(emulate) [ tt(-R) ] {tt(zsh)|tt(sh)|tt(ksh)|tt(csh)})( +Set up zsh options to emulate the specified shell as much as possible. +bf(csh) will never be fully emulated. +If the argument is not one of the shells listed above, tt(zsh) +will be used as a default. If the tt(-R) option is given, all options +are reset to their default value corresponding to the specified emulation +mode. +) +findex(enable) +cindex(enabling commands) +cindex(commands, enabling) +item(tt(enable) [ tt(-afmr) ] var(name) ...)( +Enable the var(name)d hash table elements, presumably disabled +earlier with tt(disable). The default is to enable builtin commands. +The tt(-a) option causes tt(enable) to act on aliases. The tt(-f) +option causes tt(enable) to act on shell functions. The tt(-r) +option causes tt(enable) to act on reserved words. Without arguments +all enabled hash table elements from the corresponding hash table are +printed. With the tt(-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 tt(disable) builtin command. +) +findex(eval) +cindex(evaluating arguments as commands) +item(tt(eval) [ var(arg) ... ])( +Read the arguments as input to the shell and execute the resulting +command in the current shell process. +) +prefix(exec) +findex(exit) +item(tt(exit) [ var(n) ])( +Exit the shell with the exit code specified by var(n); if none +is specified, use the exit code from the last command executed. +pindex(IGNORE_EOF, use of) +An EOF condition will also cause the shell to exit, unless +the tt(IGNORE_EOF) option is set. +) +findex(export) +item(tt(export) [ var(name)[tt(=)var(value)] ... ])( +The specified var(name)s are marked for automatic export +to the environment of subsequently executed commands. +Equivalent to tt(typeset -x), except that no parameter will be created +to hide an existing one in an outer scope. +If a parameter specified does not +already exist, it is created in the global scope. +) +findex(false) +cindex(doing nothing, unsuccessfully) +item(tt(false) [ var(arg) ... ])( +Do nothing and return an exit code of 1. +) +findex(fc) +cindex(history, editing) +cindex(editing history) +xitem(tt(fc) [ tt(-e) var(ename) ] [ tt(-nlrdDfEim) ] [ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ]) +item(tt(fc) tt(-ARWI) [ var(filename) ])( +Select a range of commands from var(first) to var(last) from the +history list. +The arguments var(first) and var(last) may be specified as a +number or as a string. A negative number is used as an offset +to the current history event number. +A string specifies the most recent event beginning with the given string. +All substitutions var(old)tt(=)var(new), if any, are then performed +on the commands. + +If the tt(-l) flag is given, the resulting commands are listed on +standard output. +If the tt(-m) flag is also given the first argument is taken as a +pattern (should be quoted) and only the history events matching this +pattern will be shown. +Otherwise the editor program var(ename) is invoked on a file containing +these history events. If var(ename) is not given, the value +of the parameter tt(FCEDIT) is used. If var(ename) is `tt(-)', +no editor is invoked. When editing is complete, the edited +command is executed. + +If var(first) is not specified, it will be set to -1 (the most recent +event), or to -16 if the tt(-l) flag is given. +If var(last) is not specified, it will be set to var(first), +or to -1 if the tt(-l) flag is given. + +The flag tt(-r) reverses the order of the commands and the +flag tt(-n) suppresses command numbers when listing. +Also when listing, tt(-d) prints timestamps for each command, and +tt(-f) prints full time-date stamps. Adding the tt(-E) flag +causes the dates to be printed as `var(dd)tt(.)var(mm)tt(.)var(yyyy)', +instead of the default `var(mm)tt(/)var(dd)tt(/)var(yyyy)'. +Adding the tt(-i) flag causes the dates to be printed in ISO8601 +`var(yyyy)tt(-)var(mm)tt(-)var(dd)' format. +With the tt(-D) flag, tt(fc) prints elapsed times. + +cindex(history, file) +cindex(file, history) +tt(fc -R) reads the history from the given file, +tt(fc -W) writes the history out to the given file, +and tt(fc -A) appends the history out to the given file. +If the tt(-I) option is added, only those +events that are new since last incremental append (write) to +the history file are appended (written). +In any case the file will have no more than tt($SAVEHIST) +entries. +) +findex(fg) +cindex(jobs, foregrounding) +cindex(jobs, resuming) +xitem(tt(fg) [ var(job) ... ]) +item(var(job) ...)( +Bring each specified var(job) in turn to the foreground. +If no var(job) is specified, resume the current job. +) +findex(functions) +item(tt(functions) [ {tt(PLUS())|tt(-)}tt(tum) ] [ var(name) ... ])( +Equivalent to tt(typeset -f). +) +findex(getln) +cindex(line, reading) +cindex(reading a line) +item(tt(getln) [ tt(-AclneE) ] var(name) ...)( +Read the top value from the buffer stack and put it in +the shell parameter tt(name). Equivalent to +tt(read -zr). +) +findex(getopts) +cindex(options, processing) +item(tt(getopts) var(optstring) var(name) [ var(arg) ... ])( +Checks the var(arg)s for legal options. If the var(arg)s are omitted, +use the positional parameters. A valid option argument +begins with a `tt(PLUS())' or a `tt(-)'. An argument not beginning with +a `tt(PLUS())' or a `tt(-)', or the argument `tt(--)', ends the options. +var(optstring) contains the letters that tt(getopts) +recognizes. If a letter is followed by a `tt(:)', that option +is expected to have an argument. The options can be +separated from the argument by blanks. + +Each time it is invoked, tt(getopts) places the option letter it finds +in the shell parameter var(name), prepended with a `tt(PLUS())' when +var(arg) begins with a `tt(PLUS())'. The index of the next var(arg) +is stored in tt(OPTIND). The option argument, if any, +is stored in tt(OPTARG). +vindex(OPTIND, use of) +vindex(OPTARG, use of) + +A leading `tt(:)' in var(optstring) causes tt(getopts) to store the +letter of the invalid option in tt(OPTARG), and to set var(name) +to `tt(?)' for an unknown option and to `tt(:)' when a required option +is missing. Otherwise, tt(getopts) prints an error +message. The exit status is nonzero when there are no more options. +) +findex(hash) +item(tt(hash) [ tt(-dfmrv) ] [ var(name)[tt(=)var(value)] ] ...)( +tt(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 tt(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 tt(-d) option; +without the option the command hash table is used, and with the option the +named directory hash table is used. + +Given no arguments, and neither the tt(-r) or tt(-f) options, +the selected hash table will be listed in full. + +The tt(-r) option causes the selected hash table to be emptied. +It will be subsequently rebuilt in the normal fashion. +The tt(-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 tt(PATH), +and for the named directory hash table this adds all users' home directories. +These two options cannot be used with any arguments. + +The tt(-m) option causes the arguments to be taken as patterns +(they 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 var(name) with a corresponding var(value), put `var(name)' in +the selected hash table, associating it with the pathname `var(value)'. +In the command hash table, this means that +whenever `var(name)' is used as a command argument, the shell will try +to execute the file given by `var(value)'. +In the named directory hash table, this means +that `var(value)' may be referred to as `tt(~)var(name)'. + +For each var(name) with no +corresponding var(value), attempt to add var(name) to the hash table, +checking what the appropriate tt(value) is in the normal manner for +that hash table. If an appropriate tt(value) can't be found, then +the hash table will be unchanged. + +The tt(-v) option causes hash table entries to be listed as they are +added by explicit specification. If has no effect if used with tt(-f). +) +alias(history)(fc -l) +findex(integer) +item(tt(integer) [ {tt(PLUS())|tt(-)}tt(lrtux) ] [ var(name)[tt(=)var(value)] ... ])( +Equivalent to tt(typeset -i), except that options irrelevant to +integers are not permitted. +) +findex(jobs) +xitem(tt(jobs) [ tt(-dlprs) ] [ var(job) ... ]) +item(tt(jobs -Z) var(string))( +Lists information about each given job, or all jobs +if var(job) is omitted. The tt(-l) flag lists process +IDs, and the tt(-p) flag lists process groups. +If the tt(-r) flag is specified only running jobs will be listed +and if the tt(-s) flag is given only stopped jobs are shown. +If the tt(-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 tt(-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 tt(ps) (manref(ps)(1)) listings. This feature is typically +used by daemons, to indicate their state. +) +findex(kill) +cindex(killing jobs) +cindex(jobs, killing) +xitem(tt(kill) [ tt(-s) var(signal_name) ] var(job) ...) +xitem(tt(kill) [ tt(-)var(sig) ] var(job) ...) +item(tt(kill) tt(-l) [ var(sig) ... ])( +Sends either tt(SIGTERM) or the specified signal to the given +jobs or processes. +Signals are given by number or by names, without the `tt(SIG)' prefix. +If the signal being sent is not `tt(KILL)' or `tt(CONT)', then the job +will be sent a `tt(CONT)' signal if it is stopped. +The argument var(job) can be the process ID of a job +not in the job list. +In the third form, tt(kill -l), if var(sig) is not +specified the signal names are listed. Otherwise, for each +var(sig) that is a name, the corresponding signal number is +listed. For each var(sig) that is a signal number or a number +representing the exit status of a process which was terminated or +stopped by a signal the name of the signal is printed. +) +findex(let) +item(tt(let) var(arg) ...)( +Evaluate each var(arg) as an arithmetic expression. +See noderef(Arithmetic Evaluation) for a description +of arithmetic expressions. The exit status is 0 if the +value of the last expression is nonzero, and 1 otherwise. +) +findex(limit) +cindex(resource limits) +cindex(limits, resource) +item(tt(limit) [ tt(-hs) ] [ var(resource) [ var(limit) ] ] ...)( +Set or display resource limits. Unless the tt(-s) flag is given, +the limit applies only the children of the shell. If tt(-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 var(limit) is not specified, print the current limit placed +on var(resource), otherwise +set the limit to the specified value. If the tt(-h) flag +is given, use hard limits instead of soft limits. +If no var(resource) is given, print all limits. + +var(resource) can be one of: + +startsitem() +sitem(tt(memorylocked))(Maximum amount of memory locked in RAM.) +sitem(tt(resident))(Maximum resident set size.) +sitem(tt(vmemorysize))(Maximum amount of virtual memory.) +sitem(tt(descriptors))(Maximum value for a file descriptor.) +sitem(tt(coredumpsize))(Maximum size of a core dump.) +sitem(tt(stacksize))(Maximum stack size for each process.) +sitem(tt(datasize))(Maximum data size (including stack) for each process.) +sitem(tt(filesize))(Largest single file allowed.) +sitem(tt(cputime))(Maximum CPU seconds per process.) +sitem(tt(maxproc))(Maximum number of processes.) +sitem(tt(addressspace))(Maximum amount of address space used.) +sitem(tt(cachedthreads))(Maximum number of cached threads.) +endsitem() + +Which of these resource limits are available depends on the system. +var(resource) can be abbreviated to any unambiguous prefix. + +var(limit) is a number, with an optional scaling factor, as follows: + +startsitem() +sitem(var(n)tt(h))(hours) +sitem(var(n)tt(k))(kilobytes (default)) +sitem(var(n)tt(m))(megabytes or minutes) +sitem([var(mm)tt(:)]var(ss))(minutes and seconds) +endsitem() +) +findex(local) +item(tt(local) [ {tt(PLUS())|tt(-)}tt(LRZilrtu) [var(n)]] [ var(name)[tt(=)var(value)] ] ...)( +Same as tt(typeset), except that the options tt(-x) and +tt(-f) are not permitted. +) +findex(log) +vindex(watch, use of) +cindex(watching users) +cindex(users, watching) +item(tt(log))( +List all users currently logged in who are affected by +the current setting of the tt(watch) parameter. +) +findex(logout) +item(tt(logout) [ var(n) ])( +Same as tt(exit), except that it only works in a login shell. +) +prefix(noglob) +findex(popd) +item(tt(popd) [ {tt(PLUS())|tt(-)}var(n) ])( +Removes a entry from the directory stack, and perform a tt(cd) to +the new top directory. With no argument, the current top entry is +removed. An argument of the form `tt(PLUS())var(n)' identifies a stack +entry by counting from the left of the list shown by the tt(dirs) command, +starting with zero. An argument of the form tt(-n) counts from the right. +pindex(PUSHD_MINUS, use of) +If the tt(PUSHD_MINUS) option is set, the meanings of `tt(PLUS())' and +`tt(-)' in this context are swapped. +) +findex(print) +item(tt(print) [ tt(-nrslzpNDPoOicm) ] [ tt(-u)var(n) ] [ tt(-R) [ tt(-en) ]] [ var(arg) ... ])( +With no flags or with flag `tt(-)', the arguments are printed on +the standard output as described by tt(echo), with the following differences: +the escape sequence `tt(\M-)var(x)' metafies the character +var(x) (sets the highest bit), +`tt(\C-)var(x)' produces a control character (`tt(\C-@)' and `tt(\C-?)' give the +characters NUL and delete), and `tt(\E)' is a synonym for `tt(\e)'. +Finally, if not in an escape +sequence, `tt(\)' escapes the following character and is not printed. + +startitem() +item(tt(-r))( +Ignore the escape conventions of tt(echo). +) +item(tt(-R))( +Emulate the BSD tt(echo) command, which does not process escape sequences +unless the tt(-e) flag is given. The tt(-n) flag suppresses the trailing +newline. Only the tt(-e) and tt(-n) flags are recognized after +tt(-R); all other arguments and options are printed. +) +item(tt(-m))( +Take the first argument as a pattern (should be quoted), and remove +it from the argument list together with subsequent arguments that +do not match this pattern. +) +item(tt(-s))( +Place the results in the history list instead of on the standard output. +) +item(tt(-n))( +Do not add a newline to the output. +) +item(tt(-l))( +Print the arguments separated by newlines instead of spaces. +) +item(tt(-N))( +Print the arguments separated and terminated by nulls. +) +item(tt(-o))( +Print the arguments sorted in ascending order. +) +item(tt(-O))( +Print the arguments sorted in descending order. +) +item(tt(-i))( +If given together with tt(-o) or tt(-O), makes them work case +independently. +) +item(tt(-c))( +Print the arguments in columns. +) +item(tt(-u)var(n))( +Print the arguments to file descriptor var(n). +) +item(tt(-p))( +Print the arguments to the input of the coprocess. +) +item(tt(-z))( +Push the arguments onto the editing buffer stack, separated by spaces; +no escape sequences are recognized. +) +item(tt(-D))( +Treat the arguments as directory names, replacing prefixes with tt(~) +expressions, as appropriate. +) +item(tt(-P))( +Perform prompt expansion (see noderef(Prompt Expansion)). +) +enditem() +) +findex(pushd) +pindex(PUSHD_TO_HOME, use of) +pindex(PUSHD_MINUS, use of) +pindex(CDABLE_VARS, use of) +pindex(PUSHD_SILENT, use of) +xitem(tt(pushd) [ var(arg) ]) +xitem(tt(pushd) var(old) var(new)) +item(tt(pushd) {tt(PLUS())|tt(-)}var(n))( +Change the current directory, and push the old current directory +onto the directory stack. In the first form, change the +current directory to var(arg). +If var(arg) is not specified, change to the second directory +on the stack (that is, exchange the top two entries), or +change to tt($HOME) if the tt(PUSHD_TO_HOME) +option is set or if there is only one entry on the stack. + +If var(arg) is `tt(-)', change to tt($OLDPWD), the previous directory. +If a directory named var(arg) is not found in the current directory +and var(arg) does not contain a slash, +search each component of the shell parameter tt(cdpath). +If the option tt(CDABLE_VARS) is set, and a parameter named var(arg) +exists whose value begins with a slash, treat its value as +the directory. + +If the option tt(PUSHD_SILENT) is not set, the directory +stack will be printed after a tt(pushd) is performed. + +The second form of tt(pushd) substitutes the string var(new) +for the string var(old) in the name of the current directory, +and tries to change to this new directory. + +The third form of tt(pushd) changes directory by rotating the +directory list. An argument of the form `tt(PLUS())var(n)' identifies a stack +entry by counting from the left of the list shown by the tt(dirs) +command, starting with zero. An argument of the form `tt(-)var(n)' counts +from the right. If the tt(PUSHD_MINUS) option is set, the meanings +of `tt(PLUS())' and `tt(-)' in this context are swapped. +) +findex(pushln) +item(tt(pushln) [ var(arg) ... ])( +Equivalent to tt(print -nz). +) +findex(pwd) +pindex(CHASE_LINKS, use of) +item(tt(pwd) [ tt(-rLP) ])( +Print the absolute pathname of the current working directory. +If the tt(-r) or the tt(-P) flag is specified, or the tt(CHASE_LINKS) +option is set and the tt(-L) flag is not given, the printed path will not +contain symbolic links. +) +alias(r)(fc -e -) +findex(read) +vindex(IFS, use of) +item(tt(read) [ tt(-rzpqAclneE) ] [ tt(-k) [ var(num) ] ] \ +[ tt(-u)var(n) ] [ var(name)[tt(?)var(prompt)] ] [ var(name) ... ])( +Read one line and break it into fields using the characters +in tt($IFS) as separators, except as noted below. +The first field is assigned to the first var(name), the second field +to the second var(name), etc., with leftover +fields assigned to the last var(name). + +startitem() +item(tt(-r))( +Raw mode: a `tt(\)' at the end of a line does not signify line +continuation. +) +item(tt(-q))( +Read only one character from the terminal and set var(name) to +`tt(y)' if this character was `tt(y)' or `tt(Y)' and to `tt(n)' otherwise. +With this flag set the return value is zero only if the character was +`tt(y)' or `tt(Y)'. Note that this always reads from the terminal, even +if used with the tt(-p) or tt(-u) or tt(-z) flags or with redirected input. +) +item(tt(-k) [ var(num) ])( +Read only one (or var(num)) characters. All are assigned to the first +var(name), without word splitting. This flag is ignored when tt(-q) is +present. Input is read from the terminal unless one of tt(-u) or tt(-p) +is present. +) +item(tt(-z))( +Read one entry from the editor buffer stack and assign it to the first +var(name), without word splitting. Text is pushed onto the stack with +`tt(print -z)' or with tt(push-line) from the line editor (see +ifzman(zmanref(zshzle))\ +ifnzman(noderef(Zsh Line Editor))\ +). This flag is ignored when the tt(-k) or tt(-q) flags are present. +) +xitem(tt(-e)) +item(tt(-E))( +The input read is printed (echoed) to the standard output. If the tt(-e) +flag is used, no input is assigned to the parameters. +) +item(tt(-A))( +The first var(name) is taken as the name of an array and all words are +assigned to it. +) +xitem(tt(-c)) +item(tt(-l))( +These flags are allowed only if called inside a +function used for completion (specified with the tt(-K) flag to +tt(compctl)). If the tt(-c) flag is given, the words of the +current command are read. If the tt(-l) flag is given, the whole +line is assigned as a scalar. If both flags are present, tt(-l) +is used and tt(-c) is ignored. If var(name) is omitted then +tt(REPLY) is used for scalars and tt(reply) for arrays. +) +item(tt(-n))( +Together with tt(-c), the number of the word the cursor is on is +read. With tt(-l), the index of the character the cursor is on is +read. Note that the command name is word number 1, not word 0, +and that when the cursor is at the end of the line, its character +index is the length of the line plus one. +) +item(tt(-u)var(n))( +Input is read from file descriptor var(n). +) +item(tt(-p))( +Input is read from the coprocess. +) +enditem() + +If the first argument contains a `tt(?)', the remainder of this +word is used as a var(prompt) on standard error when the shell +is interactive. + +The value (exit status) of tt(read) is 1 when an end-of-file is +encountered, or when tt(-c) or tt(-l) is present and the command is +not called from a tt(compctl) function. Otherwise the value is 0. + +The behavior of some combinations of the tt(-k), tt(-p), tt(-q), tt(-u) +and tt(-z) flags is undefined. Presently tt(-q) cancels all the others, +tt(-p) cancels tt(-u), tt(-k) cancels tt(-z), and otherwise tt(-z) +cancels both tt(-p) and tt(-u). + +The tt(-c) or tt(-l) flags cancel any and all of tt(-kpquz). +) +cindex(parameters, marking readonly) +alias(readonly)(typeset -r) +alias(rehash)(hash -r) +findex(return) +cindex(functions, returning from) +item(tt(return) [ var(n) ])( +Causes a shell function or tt(.) script to return to +the invoking script with the return status specified by var(n). If var(n) +is omitted, the return status is that of the last command +executed. + +If tt(return) was executed from a trap in a tt(TRAP)var(NAL) function, +the effect is different for zero and non-zero return status. With zero +status (or after an implicit return at the end of the trap), the shell +will return to whatever it was previously processing; with a non-zero +status, the shell will behave as interrupted except that the return +status of the trap is retained. Note that the signal which caused the +trap is passed as the first argument, so the statement `tt(return +$((128PLUS()$1)))' will return the same status as if the signal had not +been trapped. +) +findex(set) +cindex(parameters, listing) +cindex(parameters, positional) +cindex(parameters, setting array) +cindex(array parameters, setting) +item(tt(set) [ {tt(PLUS())|tt(-)}var(options) | {tt(PLUS())|tt(-)}tt(o) var(option_name) ] ... [ {tt(PLUS())|tt(-)}tt(A) [ var(name) ] ] [ var(arg) ... ])( +Set the options for the shell and/or set the positional parameters, or +declare and set an array. If the tt(-s) option is given, it causes the +specified arguments to be sorted before assigning them to the positional +parameters (or to the array var(name) if tt(-A) is used). With tt(PLUS()s) +sort arguments in descending order. For the meaning of the other flags, see +ifzman(zmanref(zshoptions))\ +ifnzman(noderef(Options))\ +. Flags may be specified by name using the tt(-o) option. + +If the tt(-A) flag is specified, var(name) is +set to an array containing the given var(arg)s. if tt(PLUS()A) is used and +var(name) is an array, the given arguments will replace the initial +elements of that array; if no var(name) is specified, all arrays are +printed. Otherwise the positional parameters are set. If no arguments are +given, then the names and values of all parameters are printed on the +standard output. If the only argument is `tt(PLUS())', +the names of all parameters are printed. +) +findex(setopt) +cindex(options, setting) +item(tt(setopt) [ {tt(PLUS())|tt(-)}var(options) | \ +{tt(PLUS())|tt(-)}tt(o) var(option_name) ] [ var(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. +If the tt(-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 set. +) +findex(shift) +cindex(parameters, positional) +item(tt(shift) [ var(n) ] [ var(name) ... ])( +The positional parameters tt(${)var(n)PLUS()1tt(}) ... are renamed +to tt($1) ..., where var(n) is an arithmetic expression that +defaults to 1. +If any var(name)s are given then the arrays with these names are +shifted instead of the positional parameters. +) +findex(source) +item(tt(source) var(file) [ var(arg) ... ])( +Same as tt(.), except that the current directory is always searched and +is always searched first, before directories in tt($path). +) +findex(suspend) +cindex(shell, suspending) +cindex(suspending the shell) +item(tt(suspend) [ tt(-f) ])( +Suspend the execution of the shell (send it a tt(SIGTSTP)) +until it receives a tt(SIGCONT). +Unless the tt(-f) option is given, this will refuse to suspend a login shell. +) +findex(test) +xitem(tt(test) [ var(arg) ... ]) +item(tt([) [ var(arg) ... ] tt(]))( +Like the system version of tt(test). Added for compatibility; +use conditional expressions instead (see noderef(Conditional Expressions)). +) +findex(times) +cindex(shell, timing) +cindex(timing the shell) +item(tt(times))( +Print the accumulated user and system times for the shell +and for processes run from the shell. +) +findex(trap) +cindex(signals, trapping) +cindex(trapping signals) +item(tt(trap) [ var(arg) [ var(sig) ... ] ])( +var(arg) is a command to be read and executed when the shell +receives var(sig). Each var(sig) can be given as a number +or as the name of a signal. +If var(arg) is `tt(-)', then all traps var(sig) are reset to their +default values. If var(arg) is the null string, then this signal +is ignored by the shell and by the commands it invokes. + +If var(sig) is tt(ZERR) then var(arg) will be executed +after each command with a nonzero exit status. +If var(sig) is tt(DEBUG) then var(arg) will be executed +after each command. +If var(sig) is tt(0) or tt(EXIT) +and the tt(trap) statement is executed inside the body of a function, +then the command var(arg) is executed after the function completes. +If var(sig) is tt(0) or tt(EXIT) +and the tt(trap) statement is not executed inside the body of a function, +then the command var(arg) is executed when the shell terminates. + +The tt(trap) command with no arguments prints a list of commands +associated with each signal. +) +findex(true) +cindex(doing nothing, successfully) +item(tt(true) [ var(arg) ... ])( +Do nothing and return an exit code of 0. +) +findex(ttyctl) +cindex(tty, freezing) +item(tt(ttyctl) tt(-fu))( +The tt(-f) option freezes the tty, and tt(-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, tt(stty) and similar programs have +no effect when the tty is frozen. Without options it reports whether the +terminal is frozen or not. +) +findex(type) +item(tt(type) [ tt(-wfpams) ] var(name) ...)( +Equivalent to tt(whence -v). +) +findex(typeset) +cindex(parameters, setting) +cindex(parameters, declaring) +item(tt(typeset) [ {tt(PLUS())|tt(-)}tt(LRUZfilrtuxm) [var(n)]] [ var(name)[tt(=)var(value)] ... ])( +Set attributes and values for shell parameters. +When invoked inside a function a new parameter is created which will be +unset when the function completes. The new parameter will not be +exported unless tt(ALL_EXPORT) is set, in which case the parameter will be +exported provided no parameter of that name already exists. +The following attributes are valid: + +startitem() +item(tt(-L))( +Left justify and remove leading blanks from var(value). +If var(n) is nonzero, it defines the width of the field; +otherwise it is determined by the width of the value of the first +assignment. +When the parameter is printed, it is filled on the right with +blanks or truncated if necessary to fit the field. +Leading zeros are removed if the tt(-Z) flag is also set. +) +item(tt(-R))( +Right justify and fill with leading blanks. If var(n) is nonzero +if defines the width of the field; +otherwise it is determined by the width of the value of the first +assignment. +When the parameter is printed, the field is left filled with +blanks or truncated from the end. +) +item(tt(-U))( +For arrays keep only the first element of each duplications. It can also be +set for colon separated special parameters like tt(PATH) or tt(FIGNORE), +etc. +) +item(tt(-Z))( +Right justify and fill with leading zeros if the first non-blank +character is a digit and the tt(-L) flag has not been set. +If var(n) is nonzero it defines the width of the field; +otherwise it is determined by the width of the value of the +first assignment. +) +item(tt(-f))( +The names refer to functions rather than parameters. No assignments +can be made, and the only other valid flags are tt(-t) +and tt(-u). The flag tt(-t) turns on execution tracing for this +function. The flag tt(-u) causes this function to be marked +for autoloading. The tt(fpath) parameter will be searched to find the +function definition when the function is first referenced; see +noderef(Functions). +) +item(tt(-i))( +Use an internal integer representation. If var(n) is nonzero +it defines the output arithmetic base, otherwise it is determined by the first +assignment. +) +item(tt(-l))( +Convert to lower case. +) +item(tt(-r))( +The given var(name)s are marked readonly. +) +item(tt(-t))( +Tags the named parameters. Tags have no special meaning to the shell. +) +item(tt(-u))( +Convert to upper case. +) +item(tt(-x))( +Mark for automatic export to the environment of subsequently +executed commands. +) +enditem() + +Using `tt(PLUS())' rather than `tt(-)' causes these flags to be turned off. +If no arguments are given but flags are specified, +a list of named parameters which have these flags set is printed. +Using `tt(PLUS())' instead of `tt(-)' keeps their values from being printed. +If no arguments or options are given, the names and attributes +of all parameters are printed. If only the tt(-m) flag is given the +arguments are taken as patterns (should be quoted) and all parameters +or functions (with the tt(-f) flag) with matching names are printed. +) +findex(ulimit) +cindex(resource limits) +cindex(limits, resource) +item(tt(ulimit) [ tt(-SHacdflmnpstv) [ tt(limit) ] ... ])( +Set or display resource limits of the shell and the processes started by +the shell. The value of var(limit) can be a number in the unit specified +below or the value `tt(unlimited)'. If the tt(-H) flag is given use +hard limits instead of soft limits. If the tt(-S) flag is given +together with the tt(-H) flag set both hard and soft limits. If no +options are used, the file size limit (tt(-f)) is assumed. If +var(limit) is omitted the current value of the specified resources are +printed. When more than one resource values are printed the limit name and +unit is printed before each value. + +startsitem() +sitem(tt(-a))(Lists all of the current resource limits.) +sitem(tt(-c))(512-byte blocks on the size of core dumps.) +sitem(tt(-d))(K-bytes on the size of the data segment.) +sitem(tt(-f))(512-byte blocks on the size of files written.) +sitem(tt(-l))(K-bytes on the size of locked-in memory.) +sitem(tt(-m))(K-bytes on the size of physical memory.) +sitem(tt(-n))(open file descriptors.) +sitem(tt(-s))(K-bytes on the size of the stack.) +sitem(tt(-t))(CPU seconds to be used.) +sitem(tt(-u))(processes available to the user.) +sitem(tt(-v))(K-bytes on the size of virtual memory.) +endsitem() +) +findex(umask) +cindex(umask) +item(tt(umask) [ tt(-S) ] [ var(mask) ])( +The umask is set to var(mask). var(mask) can be either +an octal number or a symbolic value as described in manref(chmod)(1). +If var(mask) is omitted, the current value is printed. The tt(-S) +option causes the mask to be printed as a symbolic value. Otherwise, +the mask is printed as an octal number. Note that in +the symbolic form the permissions you specify are those which are to be +allowed (not denied) to the users specified. +) +cindex(aliases, removing) +alias(unalias)(unhash -a) +cindex(functions, removing) +alias(unfunction)(unhash -f) +findex(unhash) +item(tt(unhash) [ tt(-adfm) ] var(name) ...)( +Remove the element named var(name) from an internal hash table. The +default is remove elements from the command hash table. The tt(-a) +option causes tt(unhash) to remove aliases. The tt(-f) option causes +tt(unhash) to remove shell functions. The tt(-d) options causes +tt(unhash) to remove named directories. If the tt(-m) flag is given +the arguments are taken as patterns (should be quoted) and all elements +of the corresponding hash table with matching names will be removed. +) +findex(unlimit) +cindex(resource limits) +cindex(limits, resource) +item(tt(unlimit) [ tt(-hs) ] var(resource) ...)( +The resource limit for each var(resource) is set to the hard limit. +If the tt(-h) flag is given and the shell has appropriate privileges, +the hard resource limit for each var(resource) is removed. +The resources of the shell process are only changed if the tt(-s) +flag is given. +) +findex(unset) +cindex(parameters, unsetting) +item(tt(unset) [ tt(-fm) ] var(name) ...)( +Each named parameter is unset. +Local parameters remain local even if unset; they appear unset within scope, +but the previous value will still reappear when the scope ends. + +If the tt(-m) flag is specified the +arguments are taken as patterns (should be quoted) and all parameters +with matching names are unset. tt(unset -f) is equivalent to +tt(unfunction). +) +findex(unsetopt) +cindex(options, unsetting) +item(tt(unsetopt) [ {tt(PLUS())|tt(-)}var(options) | \ +{tt(PLUS())|tt(-)}tt(o) var(option_name) ] [ var(name) ... ])( +Unset the options for the shell. All options specified either +with flags or by name are unset. If no arguments are supplied, +the names of all options currently unset are printed. +If the tt(-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. +) +findex(wait) +cindex(waiting for jobs) +cindex(jobs, waiting for) +item(tt(wait) [ var(job) ... ])( +Wait for the specified jobs or processes. If var(job) is not given +then all currently active child processes are waited for. +Each var(job) can be either a job specification or the process ID +of a job in the job table. +The exit status from this command is that of the job waited for. +) +findex(whence) +item(tt(whence) [ tt(-vcwfpams) ] var(name) ...)( +For each name, indicate how it would be interpreted if used as a +command name. + +startitem() +item(tt(-v))( +Produce a more verbose report. +) +item(tt(-c))( +Print the results in a bf(csh)-like format. +This takes precedence over tt(-v). +) +item(tt(-w))( +For each var(name), print `var(name)tt(:) var(word)' where var(word) +is one of tt(alias), tt(builtin), tt(command), tt(function), +tt(hashed), tt(reserved) or tt(none), according as var(name) +corresponds to an alias, a built-in command, an external command, a +shell function, a command defined with the tt(hash) builtin, a +reserved word, or is not recognised. This takes precedence over +tt(-v) and tt(-c). +) +item(tt(-f))( +Causes the contents of a shell function to be +displayed, which would otherwise not happen unless the tt(-c) +flag were used. +) +item(tt(-p))( +Do a path search for var(name) +even if it is an alias, reserved word, shell function or builtin. +) +item(tt(-a))( +Do a search for all occurrences of var(name) +throughout the command path. +Normally only the first occurrence is printed. +) +item(tt(-m))( +The arguments are taken as patterns (should be +quoted), and the information is displayed for each command matching one +of these patterns. +) +item(tt(-s))( +If a pathname contains symlinks, print the symlink-free pathname as well. +) +enditem() +) +findex(where) +item(tt(where) [ tt(-wpms) ] var(name) ...)( +Equivalent to tt(whence -ca). +) +findex(which) +item(tt(which) [ tt(-wpams) ] var(name) ...)( +Equivalent to tt(whence -c). +) +findex(zmodload) +cindex(modules, loading) +cindex(loading modules) +xitem(tt(zmodload) [ tt(-iL) ] [ var(name) ... ]) +xitem(tt(zmodload) tt(-u) [ tt(-i) ] var(name) ...) +xitem(tt(zmodload) tt(-d) [ tt(-L) ] [ var(name) [ var(dep) ... ] ]) +xitem(tt(zmodload) tt(-du) var(name) [ var(dep) ... ]) +xitem(tt(zmodload) tt(-a) [ tt(-iL) ] [ var(name) [ var(builtin) ... ] ]) +item(tt(zmodload) tt(-au) [ tt(-i) ] var(builtin) ...)( +tt(zmodload) performs operations relating to zsh's loadable modules. +This feature is not available on all operating systems, +or on all installations on a particular operating system. + +In the simplest case, +tt(zmodload) loads a binary module. The module must be in a file with a +name consisting of the specified var(name) followed by a standard suffix, +usually `tt(.so)'. If this can't be found, the var(name) is tried without +the suffix. +If the module to be loaded is already loaded and the tt(-i) +option is given, the duplicate module is ignored. Otherwise +tt(zmodload) prints an error message. + +The var(name)d module is searched for in the same way a command is, using +tt($module_path) instead of tt($path). If var(name) contains a `tt(/)', +it will be used as-is, and a path search will be performed otherwise. +This behaviour can be modified by the tt(PATH_DIRS) option. +cindex(PATH_DIRS, use of) + +With tt(-u), tt(zmodload) unloads modules. The same var(name) +must be given that was given when the module was loaded, but it is not +necessary for the module to exist in the filesystem. +The tt(-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. + +Without arguments all currently loaded binary modules are printed. +The tt(-L) option causes this list to be in the form of a series of +tt(zmodload) commands. + +The tt(-d) option can be used to specify module dependencies. +This operation is idempotent regardless of the tt(-i) option. +The modules named in the second and subsequent arguments will be +loaded before the module named in the first argument. + +With tt(-d) and one +argument, all dependencies for that module are listed. With tt(-d) and no +arguments, all module dependencies are listed. +This listing is by default in a Makefile-like format. +The tt(-L) option changes this format to a list of +tt(zmodload -d) commands. + +If tt(-d) and tt(-u) are both used, dependencies are removed. +This operation is idempotent regardless of the tt(-i) option. +If only one argument is given, all dependencies for that module are removed. + +The tt(-a) option defines autoloaded builtins. It defines the +specified var(builtin)s. When any of those builtins is called, the module +specified in the first argument is loaded. If only one argument is given, +one builtin is defined, with the same name as the module. +tt(-i) suppresses the error if the builtin is already defined or +autoloaded, regardless of which module it came from. + +With tt(-a) and no arguments, all +autoloaded builtins are listed, with the module name (if different) +shown in parentheses after the builtin name. The tt(-L) option changes +this format to a list of tt(zmodload -a) commands. + +If tt(-a) is used +together with the tt(-u) option it removes builtins defined with +tt(zmodload -a). This is only possible if the builtin is not yet +loaded. tt(-i) suppresses the error if the builtin is already +removed (or never existed). +) +enditem() diff --git a/Doc/Zsh/compat.yo b/Doc/Zsh/compat.yo new file mode 100644 index 000000000..529bd4557 --- /dev/null +++ b/Doc/Zsh/compat.yo @@ -0,0 +1,69 @@ +texinode(Compatibility)(Prompt Expansion)(Conditional Expressions)(Top) +chapter(Compatibility) +ifzman(\ +sect(Compatibility) +)\ +cindex(compatibility) +cindex(sh, compatibility) +cindex(ksh, compatibility) +Zsh tries to emulate bf(sh) or bf(ksh) when it is invoked as +tt(sh) or tt(ksh) respectively. In this mode the following +parameters are not special and not initialized by the shell: +tt(ARGC), +tt(argv), +tt(cdpath), +tt(fignore), +tt(fpath), +tt(HISTCHARS), +tt(mailpath), +tt(MANPATH), +tt(manpath), +tt(path), +tt(prompt), +tt(PROMPT), +tt(PROMPT2), +tt(PROMPT3), +tt(PROMPT4), +tt(psvar), +tt(status), +tt(watch). + +The usual zsh startup/shutdown scripts are not executed. Login shells +source tt(/etc/profile) followed by tt($HOME/.profile). If the +tt(ENV) environment variable is set on invocation, tt($ENV) is sourced +after the profile scripts. The value of tt(ENV) is subjected to +parameter expansion, command substitution, and arithmetic expansion before +being interpreted as a pathname. Note that the tt(PRIVILEGED) option +also affects the execution of startup files. + +The following options are set if the shell is invoked as tt(sh) or +tt(ksh): +tt(NO_BAD_PATTERN), +tt(NO_BANG_HIST), +tt(NO_BG_NICE), +tt(NO_EQUALS), +tt(NO_FUNCTION_ARGZERO), +tt(GLOB_SUBST), +tt(NO_HUP), +tt(INTERACTIVE_COMMENTS), +tt(KSH_ARRAYS), +tt(NO_MULTIOS), +tt(NO_NOMATCH), +tt(NO_NOTIFY), +tt(POSIX_BUILTINS), +tt(NO_PROMPT_PERCENT), +tt(RM_STAR_SILENT), +tt(SH_FILE_EXPANSION), +tt(SH_GLOB), +tt(SH_OPTION_LETTERS), +tt(SH_WORD_SPLIT). +Additionally the tt(BSD_ECHO) and tt(IGNORE_BRACES) +options are set if zsh is invoked as tt(sh). +Also, the +tt(KSH_OPTION_PRINT), +tt(LOCAL_OPTIONS), +tt(PROMPT_BANG), +tt(PROMPT_SUBST) +and +tt(SINGLE_LINE_ZLE) +options are set if zsh is invoked as tt(ksh). diff --git a/Doc/Zsh/compctl.yo b/Doc/Zsh/compctl.yo new file mode 100644 index 000000000..a78a18fa9 --- /dev/null +++ b/Doc/Zsh/compctl.yo @@ -0,0 +1,526 @@ +texinode(Programmable Completion)(Zsh Modules)(Zsh Line Editor)(Top) +chapter(Programmable Completion) +cindex(completion, programmable) +cindex(completion, controlling) +findex(compctl) +sect(Description) +startlist() +list(tt(compctl) [ tt(-CDT) ] var(options) [ var(command) ... ]) +list(tt(compctl) [ tt(-CDT) ] var(options) \ + [ tt(-x) var(pattern) var(options) tt(-) ... tt(--) ] \ + [ tt(PLUS()) var(options) [ tt(-x) ... tt(--) ] ... [tt(PLUS())] ] \ + [ var(command) ... ]) +list(tt(compctl) tt(-L) [ tt(-CDT) ] [ var(command) ... ]) +list(tt(compctl) tt(PLUS()) var(command) ...) +endlist() + +Control the editor's completion behavior according to the supplied set +of var(options). Various editing commands, notably +tt(expand-or-complete-word), usually bound to tab, will +attempt to complete a word typed by the user, while others, notably +tt(delete-char-or-list), usually bound to ^D in EMACS editing +mode, list the possibilities; tt(compctl) controls what those +possibilities are. They may for example be filenames (the most common +case, and hence the default), shell variables, or words from a +user-specified list. +startmenu() +menu(Command Flags) +menu(Option Flags) +menu(Alternative Completion) +menu(Extended Completion) +menu(Example) +endmenu() +texinode(Command Flags)(Option Flags)()(Programmable Completion) +sect(Command Flags) +Completion of the arguments of a command may be different for each +command or may use the default. The behavior when completing the +command word itself may also be separately specified. These +correspond to the following flags and arguments, all of which (except +for tt(-L)) may be combined with any combination of the +var(options) described subsequently in noderef(Option Flags): + +startitem() +item(var(command) ...)( +controls completion for the named commands, which must be listed last +on the command line. If completion is attempted for a command with a +pathname containing slashes and no completion definition is found, the +search is retried with the last pathname component. Note that aliases +are expanded before the command name is determined unless the +tt(COMPLETE_ALIASES) option is set. Commands should not be combined +with the tt(-C), tt(-D) or tt(-T) flags. +) +item(tt(-C))( +controls completion when the command word itself is being completed. +If no tt(compctl -C) command has been issued, the names of any +executable command (whether in the path or specific to the shell, such +as aliases or functions) are completed. +) +item(tt(-D))( +controls default completion behavior for the arguments of commands not +assigned any special behavior. If no tt(compctl -D) command has +been issued, filenames are completed. +) +item(tt(-T))( +supplies completion flags to be used before any other processing is +done, even those given to specific commands with other compctl +definitions. This is only useful when combined with extended +completion (the tt(-x) flag, see noderef(Extended Completion) below). +Using this flag you can define default behavior +which will apply to all commands without exception, or you can alter +the standard behavior for all commands. For example, if your access +to the user database is too slow and/or it contains too many users (so +that completion after `tt(~)' is too slow to be usable), you can use + +nofill(tt(compctl -Tx 'C[0,*/*]' -f - 's[~]' -k friends -S/)) + +to complete the strings in the array tt(friends) after a `tt(~)'. +The first argument is necessary so that this form of ~-completion is +not tried after the directory name is finished. +) +item(tt(-L))( +lists the existing completion behavior in a manner suitable for +putting into a start-up script; the existing behavior is not changed. +Any combination of the above forms may be specified, otherwise all +defined completions are listed. Any other flags supplied +are ignored. +) +item(em(no argument))( +If no argument is given, tt(compctl) lists all defined completions +in an abbreviated form; with a list of var(options), all completions +with those flags set (not counting extended completion) are listed. +) +endlist() + +If the tt(PLUS()) flag is alone and followed immediately by the var(command) +list, the completion behavior for all the commands in the list is reset to +the default. In other words, completion will subsequently use the +options specified by the tt(-D) flag. +texinode(Option Flags)(Alternative Completion)(Command Flags)(Programmable Completion) +sect(Option Flags) +startlist() +list([ tt(-fcFBdeaRGovNAIOPZEnbjrzu/) ]) +list([ tt(-k) var(array) ] [ tt(-g) var(globstring) ] \ + [ tt(-s) var(subststring) ]) +list([ tt(-K) var(function) ] [ tt(-H) var(num pattern) ]) +list([ tt(-Q) ] [ tt(-P) var(prefix) ] [ tt(-S) var(suffix) ]) +list([ tt(-W) var(file-prefix) ]) +list([ tt(-q) ] [ tt(-X) var(explanation) ] [ tt(-Y) var(explanation) ]) +list([ tt(-y) var(func-or-var) ] [ tt(-l) var(cmd) ] [ tt(-U) ]) +endlist() + +The remaining var(options) specify the type of command arguments +to look for during completion. Any combination of these flags may be +specified; the result is a sorted list of all the possibilities. The +options are as follows. +startmenu() +menu(Simple Flags) +menu(Flags with Arguments) +menu(Control Flags) +endmenu() +texinode(Simple Flags)(Flags with Arguments)()(Option Flags) +subsect(Simple Flags) +These produce completion lists made up by the shell itself: + +startitem() +item(tt(-f))( +Filenames and filesystem paths. +) +item(tt(-/))( +Just filesystem paths. +) +item(tt(-c))( +Command names, including aliases, shell functions, builtins +and reserved words. +) +item(tt(-F))( +Function names. +) +item(tt(-B))( +Names of builtin commands. +) +item(tt(-m))( +Names of external commands. +) +item(tt(-w))( +Reserved words. +) +item(tt(-a))( +Alias names. +) +item(tt(-R))( +Names of regular (non-global) aliases. +) +item(tt(-G))( +Names of global aliases. +) +item(tt(-d))( +This can be combined with tt(-F), tt(-B), tt(-w), +tt(-a), tt(-R) and tt(-G) to get names of disabled +functions, builtins, reserved words or aliases. +) +item(tt(-e))( +This option (to show enabled commands) is in effect by default, but +may be combined with tt(-d); tt(-de) in combination with +tt(-F), tt(-B), tt(-w), tt(-a), tt(-R) and tt(-G) +will complete names of functions, builtins, reserved words or aliases +whether or not they are disabled. +) +item(tt(-o))( +Names of shell options (see +ifzman(zmanref(zshoptions))\ +ifnzman(noderef(Options))\ +). +) +item(tt(-v))( +Names of any variable defined in the shell. +) +item(tt(-N))( +Names of scalar (non-array) parameters. +) +item(tt(-A))( +Array names. +) +item(tt(-I))( +Names of integer variables. +) +item(tt(-O))( +Names of read-only variables. +) +item(tt(-p))( +Names of parameters used by the shell (including special parameters). +) +item(tt(-Z))( +Names of shell special parameters. +) +item(tt(-E))( +Names of environment variables. +) +item(tt(-n))( +Named directories. +) +item(tt(-b))( +Key binding names. +) +item(tt(-j))( +Job names: the first word of the job leader's command line. This is useful +with the tt(kill) builtin. +) +item(tt(-r))( +Names of running jobs. +) +item(tt(-z))( +Names of suspended jobs. +) +item(tt(-u))( +User names. +) +enditem() +texinode(Flags with Arguments)(Control Flags)(Simple Flags)(Option Flags) +subsect(Flags with Arguments) +These have user supplied arguments to determine how the list of +completions is to be made up: + +startitem() +item(tt(-k) var(array))( +Names taken from the elements of tt($)var(array) (note that the `tt($)' +does not appear on the command line). +Alternatively, the argument var(array) itself may be a set +of space- or comma-separated values in parentheses, in which any +delimiter may be escaped with a backslash; in this case the argument +should be quoted. For example, + +nofill(tt(compctl -k "(cputime filesize datasize stacksize + coredumpsize resident descriptors)" limit)) +) +item(tt(-g) var(globstring))( +The var(globstring) is expanded using filename globbing; it should be +quoted to protect it from immediate expansion. The resulting +filenames are taken as the possible completions. Use `tt(*(/))' instead of +`tt(*/)' for directories. The tt(fignore) special parameter is not +applied to the resulting files. More than one pattern may be given +separated by blanks. (Note that brace expansion is em(not) part of +globbing. Use the syntax `tt((either|or))' to match alternatives.) +) +item(tt(-s) var(subststring))( +The var(subststring) is split into words and these words are than +expanded using all shell expansion mechanisms (see +ifzman(zmanref(zshexpn))\ +ifnzman(noderef(Expansion))\ +). The resulting words are taken as possible +completions. The tt(fignore) special parameter is not applied to the +resulting files. Note that tt(-g) is faster for filenames. +) +item(tt(-K) var(function))( +Call the given function to get the completions. The function is +passed two arguments: the prefix and the suffix of the word on which +completion is to be attempted, in other words those characters before +the cursor position, and those from the cursor position onwards. The +whole command line can be accessed with the tt(-c) and tt(-l) flags +of the tt(read) builtin. The +function should set the variable tt(reply) to an array containing +the completions (one completion per element); note that tt(reply) +should not be made local to the function. From such a function the +command line can be accessed with the tt(-c) and tt(-l) flags to +the tt(read) builtin. For example, + +nofill(tt(function whoson { reply=(`users`); } +compctl -K whoson talk)) + +completes only logged-on users after `tt(talk)'. Note that `tt(whoson)' must +return an array, so `tt(reply=`users`)' would be incorrect. +) +item(tt(-H) var(num pattern))( +The possible completions are taken from the last var(num) history +lines. Only words matching var(pattern) are taken. If var(num) is +zero or negative the whole history is searched and if var(pattern) is +the empty string all words are taken (as with `tt(*)'). A typical +use is + +nofill(tt(compctl -D -f PLUS() -H 0 '')) + +which forces completion to look back in the history list for a word if +no filename matches. +) +enditem() +texinode(Control Flags)()(Flags with Arguments)(Option Flags) +subsect(Control Flags) +These do not directly specify types of name to be completed, but +manipulate the options that do: + +startitem() +item(tt(-Q))( +This instructs the shell not to quote any metacharacters in the possible +completions. Normally the results of a completion are inserted into +the command line with any metacharacters quoted so that they are +interpreted as normal characters. This is appropriate for filenames +and ordinary strings. However, for special effects, such as inserting +a backquoted expression from a completion array (tt(-k)) so that +the expression will not be evaluated until the complete line is +executed, this option must be used. +) +item(tt(-P) var(prefix))( +The var(prefix) is inserted just before the completed string; any +initial part already typed will be completed and the whole var(prefix) +ignored for completion purposes. For example, + +nofill(tt(compctl -j -P "%" kill)) + +inserts a `%' after the kill command and then completes job names. +) +item(tt(-S) var(suffix))( +When a completion is found the var(suffix) is inserted after +the completed string. In the case of menu completion the suffix is +inserted immediately, but it is still possible to cycle through the +list of completions by repeatedly hitting the same key. +) +item(tt(-W) var(file-prefix))( +With directory var(file-prefix): for command, file, directory and +globbing completion (options tt(-c), tt(-f), tt(-/), tt(-g)), the file +prefix is implicitly added in front of the completion. For example, + +nofill(tt(compctl -/ -W ~/Mail maildirs)) + +completes any subdirectories to any depth beneath the directory +tt(~/Mail), although that prefix does not appear on the command line. +) +item(tt(-q))( +If used with a suffix as specified by the tt(-S) option, this +causes the suffix to be removed if the next character typed is a blank +or does not insert anything (the same rule as used for the +tt(AUTO_REMOVE_SLASH) option). The option is most useful for list +separators (comma, colon, etc.). +) +item(tt(-l) var(cmd))( +This option cannot be combined with any other. It restricts the range +of command line words that are considered to be arguments. If +combined with one of the extended completion patterns `tt(p[)...tt(])', +`tt(r[)...tt(])', or `tt(R[)...tt(])' (see noderef(Extended Completion) +below) the range is restricted to the range of arguments +specified in the brackets. Completion is then performed as if these +had been given as arguments to the var(cmd) supplied with the +option. If the var(cmd) string is empty the first word in the range +is instead taken as the command name, and command name completion +performed on the first word in the range. For example, + +nofill(tt(compctl -x 'r[-exec,;]' -l '' -- find)) + +completes arguments between `tt(-exec)' and the following `tt(;)' (or the end +of the command line if there is no such string) as if they were +a separate command line. +) +item(tt(-U))( +Use the whole list of possible completions, whether or not they +actually match the word on the command line. The word typed so far +will be deleted. This is most useful with a function (given by the +tt(-K) option) which can examine the word components passed to it +(or via the tt(read) builtin's tt(-c) and tt(-l) flags) and +use its own criteria to decide what matches. If there is no +completion, the original word is retained. +) +item(tt(-y) var(func-or-var))( +The list provided by var(func-or-var) is displayed instead of the list +of completions whenever a listing is required; the actual completions +to be inserted are not affected. It can be provided in two +ways. Firstly, if var(func-or-var) begins with a tt($) it defines a +variable, or if it begins with a left parenthesis a literal +array, which contains the list. A variable may have been set by a +call to a function using the tt(-K) option. Otherwise it contains the +name of a function which will be executed to create the list. The +function will be passed as an argument list all matching completions, +including prefixes and suffixes expanded in full, and should set the +array var(reply) to the result. In both cases, the display list will +only be retrieved after a complete list of matches has been created. + +Note that the returned list does not have to correspond, even in +length, to the original set of matches, and may be passed as a scalar +instead of an array. No special formatting of characters is +performed on the output in this case; in particular, newlines are +printed literally and if they appear output in columns is suppressed. +) +item(tt(-X) var(explanation))( +Print var(explanation) when trying completion on the current set of +options. A `tt(%n)' in this string is replaced by the number of matches. +The explanation only appears if completion was tried and there was +no unique match, or when listing completions. +) +item(tt(-Y) var(explanation))( +Identical to tt(-X), except that the var(explanation) first undergoes +expansion following the usual rules for strings in double quotes. +The expansion will be carried out after any functions are called for +the tt(-K) or tt(-y) options, allowing them to set variables. +) +enditem() +texinode(Alternative Completion)(Extended Completion)(Option Flags)(Programmable Completion) +sect(Alternative Completion) +startlist() +list(tt(compctl) [ tt(-CDT) ] var(options) tt(PLUS()) var(options) [ tt(PLUS()) ... ] \ +[ tt(PLUS()) ] var(command) ...) +endlist() + +The form with `tt(PLUS())' specifies alternative options. Completion is +tried with the options before the first `tt(PLUS())'. If this produces no +matches completion is tried with the flags after the `tt(PLUS())' and so on. If +there are no flags after the last `tt(PLUS())' and a match has not been found +up to that point, default completion is tried. +texinode(Extended Completion)(Example)(Alternative Completion)(Programmable Completion) +sect(Extended Completion) +startlist() +list(tt(compctl) [ tt(-CDT) ] var(options) \ +tt(-x) var(pattern) var(options) tt(-) ... tt(--) \ +[ var(command) ... ]) +list(tt(compctl) [ tt(-CDT) ] var(options) \ +[ tt(-x) var(pattern) var(options) tt(-) ... tt(--) ] \ +[ tt(PLUS()) var(options) [ tt(-x) ... tt(--) ] ... [tt(PLUS())] ] \ +[ var(command) ... ]) +endlist() + +The form with `tt(-x)' specifies extended completion for the +commands given; as shown, it may be combined with alternative +completion using `tt(PLUS())'. Each var(pattern) is examined in turn; when a +match is found, the corresponding var(options), as described in +noderef(Option Flags) above, are used to generate possible +completions. If no var(pattern) matches, the var(options) given +before the tt(-x) are used. + +Note that each pattern should be supplied as a single argument and +should be quoted to prevent expansion of metacharacters by the +shell. + +A var(pattern) is built of sub-patterns separated by commas; it +matches if at least one of these sub-patterns matches (they are +`or'ed). These sub-patterns are in turn composed of other +sub-patterns separated by white spaces which match if all of the +sub-patterns match (they are `and'ed). An element of the +sub-patterns is of the form `var(c)tt([)...tt(][)...tt(])', where the pairs of +brackets may be repeated as often as necessary, and matches if any of +the sets of brackets match (an `or'). The example below makes this +clearer. + +The elements may be any of the following: + +startitem() +item(tt(s[)var(string)tt(])...)( +Matches if the current word on the command line starts with +one of the strings given in brackets. The var(string) is not removed +and is not part of the completion. +) +item(tt(S[)var(string)tt(])...)( +Like tt(s[)var(string)tt(]) except that the var(string) is part of the +completion. +) +item(tt(p[)var(from)tt(,)var(to)tt(])...)( +Matches if the number of the current word is between one of +the var(from) and var(to) pairs inclusive. The comma and var(to) +are optional; var(to) defaults to the same value as var(from). The +numbers may be negative: tt(-)var(n) refers to the var(n)'th last word +on the line. +) +item(tt(c[)var(offset)tt(,)var(string)tt(])...)( +Matches if the var(string) matches the word offset by +var(offset) from the current word position. Usually var(offset) +will be negative. +) +item(tt(C[)var(offset)tt(,)var(pattern)tt(])...)( +Like tt(c) but using pattern matching instead. +) +item(tt(w[)var(index)tt(,)var(string)tt(])...)( +Matches if the word in position var(index) is equal +to the corresponding var(string). Note that the word count is made +after any alias expansion. +) +item(tt(W[)var(index)tt(,)var(pattern)tt(])...)( +Like tt(w) but using pattern matching instead. +) +item(tt(n[)var(index)tt(,)var(string)tt(])...)( +Matches if the current word contains var(string). Anything up to and +including the var(index)th occurrence of this string will not be +considered part of the completion, but the rest will. var(index) may +be negative to count from the end: in most cases, var(index) will be +1 or -1. For example, + +nofill(tt(compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk)) + +will usually complete usernames, but if you insert an tt(@) after the +name, names from the array var(hosts) (assumed to contain hostnames, +though you must make the array yourself) will be completed. Other +commands such as tt(rcp) can be handled similarly. +) +item(tt(N[)var(index)tt(,)var(string)tt(])...)( +Like tt(n) except that the string will be +taken as a character class. Anything up to and including the +var(index)th occurrence of any of the characters in var(string) +will not be considered part of the completion. +) +item(tt(m[)var(min)tt(,)var(max)tt(])...)( +Matches if the total number of words lies between var(min) and +var(max) inclusive. +) +item(tt(r[)var(str1)tt(,)var(str2)tt(])...)( +Matches if the cursor is after a word with prefix var(str1). If there +is also a word with prefix var(str2) on the command line it matches +only if the cursor is before this word. +) +item(tt(R[)var(str1)tt(,)var(str2)tt(])...)( +Like tt(r) but using pattern matching instead. +) +enditem() +texinode(Example)()(Extended Completion)(Programmable Completion) +sect(Example) +nofill(tt(compctl -u -x 's[tt(PLUS())] c[-1,-f],s[-f+PLUS()]' -g '~/Mail/*(:t)' \ + - 's[-f],c[-1,-f]' -f -- mail)) + +This is to be interpreted as follows: + +If the current command is tt(mail), then + +indent( +if ((the current word begins with tt(PLUS()) and the previous word is tt(-f)) +or (the current word begins with tt(-f+PLUS()))), then complete the +non-directory part (the `tt(:t)' glob modifier) of files in the directory +tt(~/Mail); else + +if the current word begins with tt(-f) or the previous word was tt(-f), then +complete any file; else + +complete user names. +) diff --git a/Doc/Zsh/cond.yo b/Doc/Zsh/cond.yo new file mode 100644 index 000000000..0ff49b187 --- /dev/null +++ b/Doc/Zsh/cond.yo @@ -0,0 +1,158 @@ +texinode(Conditional Expressions)(Compatibility)(Arithmetic Evaluation)(Top) +chapter(Conditional Expressions) +ifzman(\ +sect(Conditional Expressions) +)\ +cindex(conditional expressions) +cindex(expressions, conditional) +A em(conditional expression) is used with the tt([[) +compound command to test attributes of files and to compare strings. +Each expression can be constructed from one or more +of the following unary or binary expressions: + +startitem() +item(tt(-a) var(file))( +true if var(file) exists. +) +item(tt(-b) var(file))( +true if var(file) exists and is a block special file. +) +item(tt(-c) var(file))( +true if var(file) exists and is a character special file. +) +item(tt(-d) var(file))( +true if var(file) exists and is a directory. +) +item(tt(-e) var(file))( +true if var(file) exists. +) +item(tt(-f) var(file))( +true if var(file) exists and is a regular file. +) +item(tt(-g) var(file))( +true if var(file) exists and has its setgid bit set. +) +item(tt(-h) var(file))( +true if var(file) exists and is a symbolic link. +) +item(tt(-k) var(file))( +true if var(file) exists and has its sticky bit set. +) +item(tt(-n) var(string))( +true if length of var(string) is non-zero. +) +item(tt(-o) var(option))( +true if option named var(option) is on. var(option) +may be a single character, in which case it is a single letter option name. +(See noderef(Specifying Options).) +) +item(tt(-p) var(file))( +true if var(file) exists and is a FIFO special file (named pipe). +) +item(tt(-r) var(file))( +true if var(file) exists and is readable by current process. +) +item(tt(-s) var(file))( +true if var(file) exists and has size greater than zero. +) +item(tt(-t) var(fd))( +true if file descriptor number var(fd) +is open and associated with a terminal device. +(note: var(fd) is not optional) +) +item(tt(-u) var(file))( +true if var(file) exists and has its setuid bit set. +) +item(tt(-w) var(file))( +true if var(file) exists and is writable by current process. +) +item(tt(-x) var(file))( +true if var(file) exists and is executable by current process. +If var(file) exists and is a directory, then the current process +has permission to search in the directory. +) +item(tt(-z) var(string))( +true if length of var(string) is zero. +) +item(tt(-L) var(file))( +true if var(file) exists and is a symbolic link. +) +item(tt(-O) var(file))( +true if var(file) exists and is owned by the effective user ID of this process. +) +item(tt(-G) var(file))( +true if var(file) exists and its group matches +the effective group ID of this process. +) +item(tt(-S) var(file))( +true if var(file) exists and is a socket. +) +item(tt(-N) var(file))( +true if var(file) exists and its access time is +not newer than its modification time. +) +item(var(file1) tt(-nt) var(file2))( +true if var(file1) exists and is newer than var(file2). +) +item(var(file1) tt(-ot) var(file2))( +true if var(file1) exists and is older than var(file2). +) +item(var(file1) tt(-ef) var(file2))( +true if var(file1) and var(file2) exist and refer to the same file. +) +xitem(var(string) tt(=) var(pattern)) +item(var(string) tt(==) var(pattern))( +true if var(string) matches var(pattern). +The `tt(==)' form is the preferred one. The `tt(=)' form is for +backward compatibility and should be considered obsolete. +) +item(var(string) tt(!=) var(pattern))( +true if var(string) does not match var(pattern). +) +item(var(string1) tt(<) var(string2))( +true if var(string1) comes before var(string2) +based on ASCII value of their characters. +) +item(var(string1) tt(>) var(string2))( +true if var(string1) comes after var(string2) +based on ASCII value of their characters. +) +item(var(exp1) tt(-eq) var(exp2))( +true if var(exp1) is numerically equal to var(exp2). +) +item(var(exp1) tt(-ne) var(exp2))( +true if var(exp1) is numerically not equal to var(exp2). +) +item(var(exp1) tt(-lt) var(exp2))( +true if var(exp1) is numerically less than var(exp2). +) +item(var(exp1) tt(-gt) var(exp2))( +true if var(exp1) is numerically greater than var(exp2). +) +item(var(exp1) tt(-le) var(exp2))( +true if var(exp1) is numerically less than or equal to var(exp2). +) +item(var(exp1) tt(-ge) var(exp2))( +true if var(exp1) is numerically greater than or equal to var(exp2). +) +item(tt(LPAR()) var(exp) tt(RPAR()))( +true if var(exp) is true. +) +item(tt(!) var(exp))( +true if var(exp) is false. +) +item(var(exp1) tt(&&) var(exp2))( +true if var(exp1) and var(exp2) are both true. +) +item(var(exp1) tt(||) var(exp2))( +true if either var(exp1) or var(exp2) is true. +) +enditem() + +In each of the above expressions, if +var(file) is of the form `tt(/dev/fd/)var(n)', +where var(n) is an integer, +then the test applied to the open file whose +descriptor number is var(n), +even if the underlying system does not support +the tt(/dev/fd) directory. diff --git a/Doc/Zsh/exec.yo b/Doc/Zsh/exec.yo new file mode 100644 index 000000000..0d53b14b8 --- /dev/null +++ b/Doc/Zsh/exec.yo @@ -0,0 +1,25 @@ +texinode(Command Execution)(Functions)(Redirection)(Top) +chapter(Command Execution) +ifzman(\ +sect(Command Execution) +)\ +cindex(command execution) +cindex(execution, of commands) +If a command name contains no slashes, the shell attempts to locate +it. If there exists a shell function by that name, the function +is invoked as described in noderef(Functions). If there exists +a shell builtin by that name, the builtin is invoked. + +vindex(path, use of) +Otherwise, the shell searches each element of tt($path) for a +directory containing an executable file by that name. If the +search is unsuccessful, the shell prints an error message and returns +a nonzero exit status. + +If execution fails because the file is not in executable format, +and the file is not a directory, it is assumed to be a shell +script. tt(/bin/sh) is spawned to execute it. If the program +is a file beginning with `tt(#!)', the remainder of the first line +specifies an interpreter for the program. The shell will +execute the specified interpreter on operating systems that do +not handle this executable format in the kernel. diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo new file mode 100644 index 000000000..99844b42a --- /dev/null +++ b/Doc/Zsh/expn.yo @@ -0,0 +1,1052 @@ +texinode(Expansion)(Parameters)(Restricted Shell)(Top) +chapter(Expansion) +cindex(expansion) +sect(Description) +The types of expansions performed are + +startlist() +list(em(history expansion)) +list(em(alias expansion)) +list(em(process substitution)) +list(em(parameter expansion)) +list(em(command substitution)) +list(em(arithmetic expansion)) +list(em(brace expansion)) +list(em(filename expansion)) +list(em(filename generation)) +endlist() + +Expansion is done in the above specified order in five steps. The +first is em(history expansion), which is only performed in +interactive shells. The next step is em(alias expansion), which is +done right before the command line is parsed. They are followed by +em(process substitution), em(parameter expansion), em(command +substitution), em(arithmetic expansion) and em(brace expansion) +which are performed in one step in left-to-right fashion. After +these expansions, all unquoted occurrences of the characters `tt(\)', +`tt(')' and `tt(")' are removed, and the result is subjected to +em(filename expansion) followed by em(filename generation). + +If the tt(SH_FILE_EXPANSION) option is set, the order of expansion is modified +for compatibility with bf(sh) and bf(ksh). em(Filename expansion) +is performed immediately after em(alias substitution), +preceding the set of five substitutions mentioned above. +startmenu() +menu(History Expansion) +menu(Process Substitution) +menu(Parameter Expansion) +menu(Command Substitution) +menu(Arithmetic Expansion) +menu(Brace Expansion) +menu(Filename Expansion) +menu(Filename Generation) +endmenu() +texinode(History Expansion)(Process Substitution)()(Expansion) +sect(History Expansion) +cindex(history) +cindex(history expansion) +cindex(expansion, history) +History expansion allows you to use words from previous command +lines in the command line you are typing. This simplifies spelling +corrections and the repetition of complicated commands or arguments. +Command lines are saved in the history list, the size of which +is controlled by the tt(HISTSIZE) +vindex(HISTSIZE, use of) +variable. The most recent command is retained in any case. +A history expansion begins with the first character of the +tt(histchars) parameter which is `tt(!)' +by default and may occur anywhere on the command line; history +expansions do not nest. The `tt(!)' can be escaped with `tt(\)' +or can be enclosed between a pair of single quotes (tt('')) to suppress +its special meaning. Double quotes will em(not) work for this. + +Input lines containing history expansions are echoed on the +terminal after being expanded, but before any other +expansions take place or the command gets executed. +startmenu() +menu(Event Designators) +menu(Word Designators) +menu(Modifiers) +endmenu() +texinode(Event Designators)(Word Designators)()(History Expansion) +subsect(Event Designators) +cindex(history event designators) +cindex(event designators, history) +An event designator is a reference to a command-line entry in +the history list. + +startitem() +item(tt(!))( +Start a history expansion, except when followed by a blank, newline, +`tt(=)' or `tt(LPAR())'. +) +item(tt(!!))( +Refer to the previous command. +By itself, this expansion +repeats the previous command. +) +item(tt(!)var(n))( +Refer to command-line var(n). +) +item(tt(!-)var(n))( +Refer to the current command-line minus var(n). +) +item(tt(!)var(str))( +Refer to the most recent command starting with var(str). +) +item(tt(!?)var(str)[tt(?)])( +Refer to the most recent command containing var(str). +) +item(tt(!#))( +Refer to the current command line typed in so far. The line is +treated as if it were complete up to and including the word before the +one with the `tt(!#)' reference. +) +item(tt(!{)...tt(}))( +Insulate a history reference from adjacent characters (if necessary). +) +enditem() +texinode(Word Designators)(Modifiers)(Event Designators)(History Expansion) +subsect(Word Designators) +cindex(history word designators) +cindex(word designators, history) +A word designator indicates which word or words of a given command line will +be included in a history reference. A `tt(:)' +separates the event specification from the word designator. +It can be omitted if the word designator begins with a +`tt(^)', `tt($)', `tt(*)', `tt(-)' or `tt(%)'. +Word designators include: + +startsitem() +sitem(tt(0))(The first input word (command).) +sitem(var(n))(The var(n)th argument.) +sitem(tt(^))(The first argument. That is, tt(1).) +sitem(tt($))(The last argument.) +sitem(tt(%))(The word matched by (the most recent) tt(?)var(str) search.) +sitem(var(x)tt(-)var(y))(A range of words; var(x) defaults to tt(0).) +sitem(tt(*))(All the arguments, or a null value if there are none.) +sitem(var(x)tt(*))(Abbreviates `var(x)tt(-$)'.) +sitem(var(x)tt(-))(Like `var(x)tt(*)' but omitting word tt($).) +endsitem() + +Note that a `tt(%)' word designator will only work when used as +`tt(!%)', `tt(!:%)' or `tt(!?)var(str)tt(?:%)', +and only when used after a tt(!?) expansion. Anything else will result +in an error, although the error may not be the most obvious one. +texinode(Modifiers)()(Word Designators)(History Expansion) +subsect(Modifiers) +cindex(modifiers, history) +cindex(history modifiers) +After the optional word designator, you can add +a sequence of one or more of the following modifiers, +each preceded by a `tt(:)'. These modifiers also work on the result +of em(filename generation) and em(parameter expansion), except where +noted. + +startitem() +item(tt(h))( +Remove a trailing pathname component, leaving the head. +) +item(tt(r))( +Remove a trailing suffix of the form `tt(.)var(xxx)', leaving the basename. +) +item(tt(e))( +Remove all but the suffix. +) +item(tt(t))( +Remove all leading pathname components, leaving the tail. +) +item(tt(p))( +Print the new command but do not execute it. Only works with history +expansion. +) +item(tt(q))( +Quote the substituted words, escaping further substitutions. Only +works with history expansion. +) +item(tt(x))( +Like tt(q), but break into words at each blank. +) +item(tt(l))( +Convert the words to all lowercase. +) +item(tt(u))( +Convert the words to all uppercase. +) +item(tt(f))( +(This and the following +tt(F), tt(w) and tt(W) modifier only work with parameter and +filename expansion.) +Repeats the immediately (without a colon) following modifier until the +resulting word doesn't change any more. +) +item(tt(F:)var(expr)tt(:))( +Like tt(f), but repeats only var(n) times if the expression +var(expr) evaluates to var(n). Any character can be used instead of +the `tt(:)', if any of `tt(LPAR())', `tt([)', or `tt({)' +is used as the opening delimiter +the second one has to be 'tt(RPAR())', `tt(])', or `tt(})' respectively. +) +item(tt(w))( +Makes the immediately following modifier work on each word in the +string. +) +item(tt(W:)var(sep)tt(:))( +Like tt(w) but words are considered to be the parts of the string +that are separated by var(sep). Any character can be used instead of +the `tt(:)'; opening parentheses are handled specially, see above. +) +item(tt(s/)var(l)tt(/)var(r)[tt(/)])( +Substitute var(r) for var(l) as described below. +Unless preceded immediately by a tt(g), with no colon between, +the substitution is done only for the +first string that matches var(l). For arrays and filename +expansion, this applies to each word of the expanded text. +) +item(tt(&))( +Repeat the previous tt(s) substitution. Like tt(s), may be preceded +immediately by a tt(g). In variable expansion the tt(&) must appear +inside braces, and in filename expansion it must be quoted with a +backslash. +) +enditem() + +The tt(s/l/r/) substitution works as follows. The left-hand side of +substitutions are not regular expressions, but character strings. Any +character can be used as the delimiter in place of `tt(/)'. A +backslash quotes the delimiter character. The character `tt(&)', in +the right-hand-side var(r), is replaced by the text from the +left-hand-side var(l). The `tt(&)' can be quoted with a backslash. A +null var(l) uses the previous string either from the previous var(l) +or from the contextual scan string var(s) from `tt(!?)var(s)'. You can +omit the rightmost delimiter if a newline immediately follows var(r); +the rightmost `tt(?)' in a context scan can similarly be omitted. +Note the same record of the last var(l) and var(r) is maintained +across all forms of expansion. + +By default, a history reference with no event specification refers to the same +line as the last history reference on that command line, unless it is the +first history reference in a command. In that case, a history reference +with no event specification always refers to the previous command. However, +if the option tt(CSH_JUNKIE_HISTORY) is set, +pindex(CSH_JUNKIE_HISTORY, use of) +then history reference with no +event specification will em(always) refer to the previous command. + +For example, `tt(!!:1)' +will always refer to the first word of the previous command, and `tt(!!$)' +will always refer to the last word of the previous command. And with +tt(CSH_JUNKIE_HISTORY) set, then `tt(!:1)' and `tt(!$)' +will function in the same manner as `tt(!!:1)' and `tt(!!$)', +respectively. However, if tt(CSH_JUNKIE_HISTORY) is unset, then +`tt(!:1)' and `tt(!$)' +will refer to the first and last words respectively, of the last command +referenced on the current command line. However, if they are the first history +reference on the command line, then they refer to the previous command. + +The character sequence `tt(^)var(foo)tt(^)var(bar)' +repeats the last command, replacing the string var(foo) with var(bar). + +If the shell encounters the character sequence `tt(!")' +in the input, the history mechanism is temporarily disabled until +the current list is fully parsed. The `tt(!")' +is removed from the input, and any subsequent `tt(!)' +characters have no special significance. + +A less convenient but more comprehensible +form of command history support +is provided by the tt(fc) builtin. +findex(fc, use of) +texinode(Process Substitution)(Parameter Expansion)(History Expansion)(Expansion) +sect(Process Substitution) +cindex(process substitution) +cindex(substitution, process) +Each command argument of the form +`tt(LPAR())var(list)tt(RPAR())' or +`tt(=LPAR())var(list)tt(RPAR())' +is subject to process substitution. +In the case of the tt(<) or tt(>) forms, the shell will run process +var(list) asynchronously, connected to a named pipe (FIFO). +The name of this pipe will become the argument to the command. +If the form with tt(>) +is selected then writing on this file will provide input for var(list). +If tt(<) is used, then the file passed as an argument will +be a named pipe connected to the output of the var(list) process. +For example, + +nofill(tt(paste LPAR())var(process1)tt(RPAR() >LPAR())var(process2)tt(RPAR() >/dev/null)) + +cuts fields 1 and 3 from the files var(file1) and var(file2) respectively, +pastes the results together, and sends it to the processes +var(process1) and var(process2). +Note that the file, which is passed as an argument to the command, +is a system pipe, so programs that expect to lseek (see manref(lseek)(2)) +on the file will not work. +Also note that the previous example can be more compactly and +efficiently written as: + +nofill(tt(paste >LPAR())var(process1)tt(RPAR() > >LPAR())var(process2)tt(RPAR())) + +The shell uses pipes instead of FIFOs to implement the latter +two process substitutions in the above example. + +If tt(=) is used, +then the file passed as an argument will be the name +of a temporary file containing the output of the var(list) +process. This may be used instead of the tt(<) +form for a program that expects to lseek (see manref(lseek)(2)) +on the input file. +texinode(Parameter Expansion)(Command Substitution)(Process Substitution)(Expansion) +sect(Parameter Expansion) +cindex(parameter expansion) +cindex(expansion, parameter) +The character `tt($)' is used to introduce parameter expansions. +See +ifzman(\ +zmanref(zshparam) +)\ +ifnzman(\ +noderef(Parameters) +)\ +for a description of parameters. +In the expansions discussed below that require a pattern, the form of +the pattern is the same as that used for filename generation; +see noderef(Filename Generation). In addition to the following +operations, the file modifiers described in +noderef(Modifiers) in noderef(History Expansion) can be +applied: for example, tt(${i:s/foo/bar/}) performs string +substitution on the value of parameter tt($i). + +startitem() +item(tt(${)var(name)tt(}))( +The value, if any, of the parameter var(name) is substituted. +The braces are required if var(name) is followed by +a letter, digit, or underscore that is not to be interpreted +as part of its name. + +If var(name) is an array parameter, then the values of each +element of var(name) is substituted, one element per word. +Otherwise, the expansion results in one word only; no field +splitting is done on the result unless the tt(SH_WORD_SPLIT) +option is set. +) +item(tt(${PLUS())var(name)tt(}))( +If var(name) is the name of a set parameter `tt(1)' is substituted, +otherwise `tt(0)' is substituted. +) +item(tt(${)var(name)tt(:-)var(word)tt(}))( +If var(name) is set and is non-null then substitute its +value; otherwise substitute var(word). If var(name) is +missing, substitute var(word). +) +item(tt(${)var(name)tt(:=)var(word)tt(}))( +If var(name) is unset or is null then +set it to var(word); the value of the parameter is then +substituted. +) +item(tt(${)var(name)tt(:?)var(word)tt(}))( +If var(name) is set and is non-null, then substitute +its value; otherwise, print var(word) and exit from the shell. +If var(word) is omitted, then a standard message is printed. +) +item(tt(${)var(name)tt(:PLUS())var(word)tt(}))( +If var(name) is set and is non-null then substitute +var(word); otherwise substitute nothing. +) +enditem() + +If the colon is omitted from one of the above expressions +containing a colon, then the shell only checks whether +var(name) is set or not, not whether it is null. + +startitem() +item(tt(${)var(name)tt(::=)var(word)tt(}))( +Set var(name) to var(word); the value of the parameter is then +substituted. +) +xitem(tt(${)var(name)tt(#)var(pattern)tt(})) +item(tt(${)var(name)tt(##)var(pattern)tt(}))( +If the var(pattern) matches the beginning of the value of +var(name), then substitute the value of var(name) with +the matched portion deleted; otherwise, just +substitute the value of var(name). In the first +form, the smallest matching pattern is preferred; +in the second form, the largest matching pattern is +preferred. If var(name) is an array and the substitution +is not quoted or the tt((@)) flag or the `var(name)tt([@])' syntax +is used, matching is performed on each array elements separately. +) +xitem(tt(${)var(name)tt(%)var(pattern)tt(})) +item(tt(${)var(name)tt(%%)var(pattern)tt(}))( +If the var(pattern) matches the end of the value of +var(name), then substitute the value of var(name) with +the matched portion deleted; otherwise, just +substitute the value of var(name). In the first +form, the smallest matching pattern is preferred; +in the second form, the largest matching pattern is +preferred. If var(name) is an array and the substitution +is not quoted or the tt((@)) flag or the `var(name)tt([@])' syntax +is used, matching is performed on each array elements separately. +) +item(tt(${)var(name)tt(:#)var(pattern)tt(}))( +If the var(pattern) matches the value of var(name), then substitute +the empty string; otherwise, just substitute the value of var(name). +If var(name) is an array and the substitution +is not quoted or the tt((@)) flag or the `var(name)tt([@])' syntax +is used, matching is performed on each array elements separately, and +the matched array elements are removed (use the tt((M)) flag to +remove the non-matched elements). +) +item(tt(${#)var(spec)tt(}))( +If var(spec) is one of the above substitutions, substitute +the length in characters of the result instead of +the result itself. If var(spec) is an array expression, +substitute the number of elements of the result. +) +item(tt(${^)var(spec)tt(}))( +pindex(RC_EXPAND_PARAM, use of) +cindex(array expansion style, rc) +cindex(rc, array expansion style) +Turn on the tt(RC_EXPAND_PARAM) option for the +evaluation of var(spec); if the `tt(^)' is doubled, turn it off. +When this option is set, array expansions of the form +`var(foo)tt(${)var(xx)tt(})var(bar)', +where the parameter var(xx) +is set to tt(LPAR())var(a b c)tt(RPAR()), are substituted with +`var(fooabar foobbar foocbar)' instead of the default +`var(fooa b cbar)'. + +Internally, each such expansion is converted into the +equivalent list for brace expansion. E.g., tt(${^var}) becomes +tt({$var[1],$var[2],)...tt(}), and is processed as described in +noderef(Brace Expansion) above. +If word splitting is also in effect the +tt($var[)var(N)tt(]) may themselves be split into different list +elements. +) +item(tt(${=)var(spec)tt(}))( +pindex(SH_WORD_SPLIT, use of) +cindex(field splitting, sh style) +cindex(sh, field splitting style) +Turn on the tt(SH_WORD_SPLIT) option for the +evaluation of var(spec); if the `tt(=)' is doubled, turn it off. +vindex(IFS, use of) +When this option is set, parameter values are split into +separate words using tt(IFS) as a delimiter +before substitution. +This is done by default in most other shells. +) +item(tt(${~)var(spec)tt(}))( +pindex(GLOB_SUBST) +Turn on the tt(GLOB_SUBST) option for the evaluation of +var(spec); if the `tt(~)' is doubled, turn it off. When this option is +set, any pattern characters resulting +from the substitution become eligible for file expansion and filename +generation. +) +enditem() + +If a tt(${)...tt(}) type parameter expression or a +tt($LPAR())...tt(RPAR()) type command substitution is used in place of +var(name) above, it is substituted first and the result is used as if +it were the value of var(name). Thus it is +possible to perform nested operations: tt(${${foo#head}%tail}) +substitues the value of tt($foo) with both tt(head) and tt(tail) +deleted. The form with tt($LPAR())...tt(RPAR()) is often useful in +combination with the flags described next; see the example below. +subsect(Parameter Expansion Flags) +cindex(parameter expansion flags) +cindex(flags, parameter expansion) +cindex(expansion, parameter, flags) +If the opening brace is directly followed by an opening parenthesis, +the string up to the matching closing parenthesis will be taken as a +list of flags. Where arguments are valid, any character, or the +matching pairs `tt(LPAR())...tt(RPAR())', `tt({)...tt(})', +`tt([)...tt(])', or `tt(<)...tt(>)', may be used +in place of the colon as delimiters. The following flags are supported: + +startitem() +item(tt(A))( +Create an array parameter with +tt(${)...tt(:=)...tt(}) or tt(${)...tt(::=)...tt(}). +Assignment is made before sorting or padding. +) +item(tt(@))( +In double quotes, array elements are put into separate words. +E.g., `tt("${(@)foo}")' is equivalent to `tt("${foo[@]}")' and +`tt("${(@)foo[1,2]}")' is the same as `tt("$foo[1]" "$foo[2]")'. +) +item(tt(e))( +Perform em(parameter expansion), em(command substitution) and +em(arithmetic expansion) on the result. Such expansions can be +nested but too deep recursion may have unpredictable effects. +) +item(tt(o))( +Sort the resulting words in ascending order. +) +item(tt(O))( +Sort the resulting words in descending order. +) +item(tt(i))( +With tt(o) or tt(O), sort case-independently. +) +item(tt(L))( +Convert all letters in the result to lower case. +) +item(tt(U))( +Convert all letters in the result to upper case. +) +item(tt(C))( +Capitalize the resulting words. +) +item(tt(c))( +With tt(${#)var(name)tt(}), count the total number of characters in an array, +as if the elements were concatenated with spaces between them. +) +item(tt(w))( +With tt(${#)var(name)tt(}), count words in arrays or strings; the tt(s) +flag may be used to set a word delimiter. +) +item(tt(W))( +Similar to tt(w) with the difference that empty words between +repeated delimiters are also counted. +) +item(tt(p))( +Recognize the same escape sequences as the tt(print) builtin +in string arguments to subsequent flags. +) +item(tt(l:)var(expr)tt(::)var(string1)tt(::)var(string2)tt(:))( +Pad the resulting words on the left. Each word will be truncated if +required and placed in a field var(expr) characters wide. The space +to the left will be filled with var(string1) (concatenated as often +as needed) or spaces if var(string1) is not given. If both +var(string1) and var(string2) are given, this string will be placed +exactly once directly to the left of the resulting word. +) +item(tt(r:)var(expr)tt(::)var(string1)tt(::)var(string2)tt(:))( +As tt(l), but pad the words on the right. +) +item(tt(j:)var(string)tt(:))( +Join the words of arrays together using var(string) as a separator. +pindex(SH_WORD_SPLIT, use of) +Note that this occurs before field splitting by the tt(SH_WORD_SPLIT) +option. +) +item(tt(F))( +Join the words of arrays together using newline as a separator. +This is a shorthand for `tt(pj:\n:)'. +) +item(tt(s:)var(string)tt(:))( +Force field splitting (see the option tt(SH_WORD_SPLIT)) at the +separator var(string). Splitting only occurs in places where an +array value is valid. +) +item(tt(f))( +Split the result of the expansion to lines. This is a shorthand +for `tt(ps:\n:)'. +) +item(tt(S))( +(This and all remaining flags are used with the tt(${)...tt(#)...tt(}) or +tt(${)...tt(%)...tt(}) forms.) +Search substrings as well as beginnings or ends. +) +item(tt(I:)var(expr)tt(:))( +Search the var(expr)th match (where var(expr) evaluates to a number). +) +item(tt(M))( +Include the matched portion in the result. +) +item(tt(R))( +Include the unmatched portion in the result (the em(R)est). +) +item(tt(B))( +Include the index of the beginning of the match in the result. +) +item(tt(E))( +Include the index of the end of the match in the result. +) +item(tt(N))( +Include the length of the match in the result. +) +enditem() +subsect(Example) +The flag tt(f) is useful to split a double-quoted substitution line by +line. For example, `tt("${(f)$LPAR()<)var(file)tt(RPAR()}")' +will substitue the contents of var(file) divided so that one line is +supplied per argument to var(cmd). Compare this with the effect of +`tt($)tt(LPAR()<)var(file)tt(RPAR())' alone, which divides the file +up by words, or the same inside double quotes, where the entire +contents of the file are passed as a single argument. +texinode(Command Substitution)(Arithmetic Expansion)(Parameter Expansion)(Expansion) +sect(Command Substitution) +cindex(command substitution) +cindex(substitution, command) +A command enclosed in parentheses +preceded by a dollar sign, like `tt($LPAR())...tt(RPAR())', or quoted with grave +accents, like `tt(`)...tt(`)', is replaced with its standard output, with any +trailing newlines deleted. +If the substitution is not enclosed in double quotes, the +output is broken into words using the tt(IFS) parameter. +vindex(IFS, use of) +The substitution `tt($LPAR()cat) var(foo)tt(RPAR())' may be replaced +by the equivalent but faster `tt($LPAR()<)var(foo)tt(RPAR())'. +In either case, if the option tt(GLOB_SUBST) is set, +the output is eligible for filename generation. +texinode(Arithmetic Expansion)(Brace Expansion)(Command Substitution)(Expansion) +sect(Arithmetic Expansion) +cindex(arithmetic expansion) +cindex(expansion, arithmetic) +A string of the form `tt($[)var(exp)tt(])' or +`tt($LPAR()LPAR())var(exp)tt(RPAR()RPAR())' is substituted +with the value of the arithmetic expression var(exp). var(exp) is +subjected to em(parameter expansion), em(command substitution) +and em(arithmetic expansion) before it is evaluated. +See noderef(Arithmetic Evaluation). +texinode(Brace Expansion)(Filename Expansion)(Arithmetic Expansion)(Expansion) +sect(Brace Expansion) +cindex(brace expansion) +cindex(expansion, brace) +A string of the form +`var(foo)tt({)var(xx)tt(,)var(yy)tt(,)var(zz)tt(})var(bar)' +is expanded to the individual words +`var(fooxxbar)', `var(fooyybar)' and `var(foozzbar)'. +Left-to-right order is preserved. This construct +may be nested. Commas may be quoted in order to +include them literally in a word. + +An expression of the form `tt({)var(n1)tt(..)var(n2)tt(})', +where var(n1) and var(n2) are integers, +is expanded to every number between +var(n1) and var(n2) inclusive. If either number begins with a +zero, all the resulting numbers will be padded with leading zeroes to +that minimum width. If the numbers are in decreasing order the +resulting sequence will also be in decreasing order. + +If a brace expression matches none of the above forms, it is left +unchanged, unless the tt(BRACE_CCL) option is set. +pindex(BRACE_CCL, use of) +In that case, it is expanded to a sorted list of the individual +characters between the braces, in the manner of a search set. +`tt(-)' is treated specially as in a search set, but `tt(^)' or `tt(!)' as +the first character is treated normally. +texinode(Filename Expansion)(Filename Generation)(Brace Expansion)(Expansion) +sect(Filename Expansion) +cindex(filename expansion) +cindex(expansion, filename) +Each word is checked to see if it begins with an unquoted `tt(~)'. +If it does, then the word up to a `tt(/)', +or the end of the word if there is no `tt(/)', +is checked to see if it can be substituted in one of the ways +described here. If so, then the `tt(~)' and the checked portion are +replaced with the appropriate substitute value. + +A `tt(~)' by itself is replaced by the value of tt($HOME). +A `tt(~)' followed by a `tt(PLUS())' or a `tt(-)' is replaced by the value of +tt($PWD) or tt($OLDPWD), respectively. + +A `tt(~)' followed by a number is replaced by the directory at that +position in the directory stack. +`tt(~0)' is equivalent to `tt(~PLUS())', +and `tt(~1)' is the top of the stack. +`tt(~PLUS())' followed by a number is replaced by the directory at that +position in the directory stack. +`tt(~PLUS()0)' is equivalent to `tt(~PLUS())', +and `tt(~PLUS()1)' is the top of the stack. +`tt(~-)' followed by a number is replaced by the directory that +many positions from the bottom of the stack. +`tt(~-0)' is the bottom of the stack. +pindex(PUSHD_MINUS, use of) +The tt(PUSHD_MINUS) +option exchanges the effects of `tt(~PLUS())' and `tt(~-)' where they are +followed by a number. + +cindex(directories, named) +cindex(named directories) +A `tt(~)' followed by anything not already covered is looked up as a +named directory, and replaced by the value of that named directory if found. +Named directories are typically home directories for users on the system. +They may also be defined if the text after the `tt(~)' is the name +of a string shell parameter whose value begins with a `tt(/)'. +It is also possible to define directory names using the tt(-d) option to the +tt(hash) builtin. + +In certain circumstances (in prompts, for instance), when the shell +prints a path, the path is checked to see if it has a named +directory as its prefix. If so, then the prefix portion +is replaced with a `tt(~)' followed by the name of the directory. +The shortest way of referring to the directory is used, +with ties broken in favour of using a named directory, +except when the directory is tt(/) itself. + +If a word begins with an unquoted `tt(=)' +and the tt(EQUALS) option is set, +the remainder of the word is taken as the +name of a command or alias. If a command +exists by that name, the word is replaced +by the full pathname of the command. +If an alias exists by that name, the word +is replaced with the text of the alias. + +Filename expansion is performed on the right hand side of a parameter +assignment, including those appearing after commands of the +tt(typeset) family. In this case, the right hand side will be treated +as a colon-separated list in the manner of the tt(PATH) parameter, +so that a `tt(~)' or an `tt(=)' following a `tt(:)' is eligible for expansion. +All such behaviour can be +disabled by quoting the `tt(~)', the `tt(=)', or the whole expression (but not +simply the colon); the tt(EQUALS) option is also respected. + +If the option tt(MAGIC_EQUAL_SUBST) is set, any unquoted shell +argument in the form `var(identifier)tt(=)var(expression)' becomes eligible +for file expansion as described in the previous paragraph. Quoting the +first `tt(=)' also inhibits this. +texinode(Filename Generation)()(Filename Expansion)(Expansion) +sect(Filename Generation) +cindex(filename generation) +cindex(globbing) +If a word contains an unquoted instance of one of the characters +`tt(*)', `tt(LPAR())', `tt(|)', `tt(<)', `tt([)', or `tt(?)', it is regarded +as a pattern for filename generation, unless the tt(GLOB) option is unset. +pindex(GLOB, use of) +If the tt(EXTENDED_GLOB) option is set, +pindex(EXTENDED_GLOB, use of) +the `tt(^)' and `tt(#)' characters also denote a pattern; otherwise +they are not treated specially by the shell. + +The word is replaced with a list of sorted filenames that match +the pattern. If no matching pattern is found, the shell gives +an error message, unless the tt(NULL_GLOB) option is set, +pindex(NULL_GLOB, use of) +in which case the word is deleted; or unless the tt(NOMATCH) +option is unset, in which case the word is left unchanged. +pindex(NOMATCH, use of) + +In filename generation, +the character `tt(/)' must be matched explicitly; +also, a `tt(.)' must be matched +explicitly at the beginning of a pattern or after a `tt(/)', unless the +tt(GLOB_DOTS) option is set. +pindex(GLOB_DOTS, use of) +No filename generation pattern +matches the files `tt(.)' or `tt(..)'. In other instances of pattern +matching, the `tt(/)' and `tt(.)' are not treated specially. +subsect(Glob Operators) +startitem() +item(tt(*))( +Matches any string, including the null string. +) +item(tt(?))( +Matches any character. +) +item(tt([)...tt(]))( +Matches any of the enclosed characters. Ranges of characters +can be specified by separating two characters by a `tt(-)'. +A `tt(-)' or `tt(])' may be matched by including it as the +first character in the list. +There are also several named classes of characters, in the form +`tt([:)var(name)(tt:])' with the following meanings: `tt([:alnum:])' +alphanumeric, `tt([:alpha:])' alphabetic, +`tt([:blank:])' space or tab, +`tt([:cntrl:])' control character, `tt([:digit:])' decimal +digit, `tt([:graph:])' printable character except whitespace, +`tt([:lower:])' lowercase letter, `tt([:print:])' printable character, +`tt([:punct:])' printable character neither alphanumeric nor whitespace, +`tt([:space:])' whitespace character, `tt([:upper:])' uppercase letter, +`tt([:xdigit:])' hexadecimal digit. These use the macros provided by +the operating system to test for the given character combinations, +including any modifications due to local language settings: see +manref(ctype)(3). Note that the square brackets are additional +to those enclosing the whole set of characters, so to test for a +single alphanumeric character you need `tt([[:alnum:]])'. Named +character sets can be used alongside other types, +e.g. `tt([[:alpha:]0-9])'. +) +xitem(tt([^)...tt(])) +item(tt([!)...tt(]))( +Like tt([)...tt(]), except that it matches any character which is +not in the given set. +) +item(tt(<)[var(x)]tt(-)[var(y)]tt(>))( +Matches any number in the range var(x) to var(y), inclusive. +Either of the numbers may be omitted to make the range open-ended; +hence `tt(<->)' matches any number. +) +item(tt(LPAR())...tt(RPAR()))( +Matches the enclosed pattern. This is used for grouping. +If the tt(KSH_GLOB) option is set, then a +`tt(@)', `tt(*)', `tt(+)', `tt(?)' or `tt(!)' immediately preceding +the `tt(LPAR())' is treated specially, as detailed below. +) +item(var(x)tt(|)var(y))( +Matches either var(x) or var(y). +This operator has lower precedence than any other. +The `tt(|)' character +must be within parentheses, to avoid interpretation as a pipeline. +) +item(tt(^)var(x))( +(Requires tt(EXTENDED_GLOB) to be set.) +Matches anything except the pattern var(x). +This has a higher precedence than `tt(/)', so `tt(^foo/bar)' +will search directories in `tt(.)' except `tt(./foo)' +for a file named `tt(bar)'. +) +item(var(x)tt(~)var(y))( +(Requires tt(EXTENDED_GLOB) to be set.) +Match anything that matches the pattern var(x) but does not match var(y). +This has lower precedence than any operator except `tt(|)', so +`tt(*/*~foo/bar)' will search for all files in all directories in `tt(.)' +and then exclude `tt(foo/bar)' if there was such a match. +It groups left-to-right, so multiple patterns can be excluded by +`var(foo)tt(~)var(bar)tt(~)var(baz)'. +In the exclusion pattern (var(y)), `tt(/)' and `tt(.)' are not treated +specially the way they usually are in globbing. +) +item(var(x)tt(#))( +(Requires tt(EXTENDED_GLOB) to be set.) +Matches zero or more occurrences of the pattern var(x). +This operator has high precedence; `tt(12#)' is equivalent to `tt(1(2#))', +rather than `tt((12)#)'. +) +item(var(x)tt(##))( +(Requires tt(EXTENDED_GLOB) to be set.) +Matches one or more occurrences of the pattern var(x). +This operator has high precedence; `tt(12##)' is equivalent to `tt(1(2##))', +rather than `tt((12)##)'. +) +enditem() +subsect(ksh-like Glob Operators) +pindex(KSH_GLOB, use of) +If the tt(KSH_GLOB) option is set, the effects of parentheses can be +modified by a preceding `tt(@)', `tt(*)', `tt(+)', `tt(?)' or `tt(!)'. +This character need not be unquoted to have special effects, +but the `tt(LPAR())' must be. + +startitem() +item(tt(@LPAR())...tt(RPAR()))( +Match the pattern in the parentheses. (Like `tt(LPAR())...tt(RPAR())'.) +) +item(tt(*LPAR())...tt(RPAR()))( +Match any number of occurrences. (Like `tt(LPAR())...tt(RPAR()#)'.) +) +item(tt(PLUS()LPAR())...tt(RPAR()))( +Match at least one occurrence. (Like `tt(LPAR())...tt(RPAR()##)'.) +) +item(tt(?LPAR())...tt(RPAR()))( +Match zero or one occurrence. (Like `tt(LPAR()|)...tt(RPAR())'.) +) +item(tt(!LPAR())...tt(RPAR()))( +Match anything but the expression in parentheses. +(Like `tt(LPAR()^LPAR())...tt(RPAR()RPAR())'.) +) +enditem() +subsect(Recursive Globbing) +A pathname component of the form `tt(LPAR())var(foo)tt(/RPAR()#)' +matches a path consisting of zero or more directories +matching the pattern var(foo). +As a shorthand, `tt(**/)' is equivalent to `tt((*/)#)'. +Thus: + +nofill(tt(ls (*/)#bar)) + +or + +nofill(tt(ls **/bar)) + +does a recursive directory search for files named `tt(bar)', not following +symbolic links. To follow links, use `tt(***/)'. +subsect(Glob Qualifiers) +cindex(globbing, qualifiers) +cindex(qualifiers, globbing) +Patterns used for filename generation may end in a +list of qualifiers enclosed in parentheses. +The qualifiers specify which filenames that otherwise match the given pattern +will be inserted in the argument list. + +pindex(BARE_GLOB_QUAL, use of) +If the option tt(BARE_GLOB_QUAL) is set, then a trailing set of parentheses +containing no `tt(|)' or `tt(LPAR())' characters (or `tt(~)' if it is special) +is taken as a set of +glob qualifiers. A glob subexpression that would normally be taken as glob +qualifiers, for example `tt((^x))', can be forced to be treated as part of +the glob pattern by doubling the parentheses, for example `tt(((^x)))'. + +A qualifier may be any one of the following: + +startitem() +item(tt(/))( +directories +) +item(tt(.))( +plain files +) +item(tt(@))( +symbolic links +) +item(tt(=))( +sockets +) +item(tt(p))( +named pipes (FIFOs) +) +item(tt(*))( +executable plain files (0100) +) +item(tt(%))( +device files (character or block special) +) +item(tt(%b))( +block special files +) +item(tt(%c))( +character special files +) +item(tt(r))( +owner-readable files (0400) +) +item(tt(w))( +owner-writable files (0200) +) +item(tt(x))( +owner-executable files (0100) +) +item(tt(A))( +group-readable files (0040) +) +item(tt(I))( +group-writable files (0020) +) +item(tt(E))( +group-executable files (0010) +) +item(tt(R))( +world-readable files (0004) +) +item(tt(W))( +world-writable files (0002) +) +item(tt(X))( +world-executable files (0001) +) +item(tt(s))( +setuid files (04000) +) +item(tt(S))( +setgid files (02000) +) +item(tt(t))( +files with the sticky bit (01000) +) +item(tt(d)var(dev))( +files on the device var(dev) +) +item(tt(l)[tt(-)|tt(PLUS())]var(ct))( +files having a link count less than var(ct) (tt(-)), greater than +var(ct) (tt(PLUS())), or is equal to var(ct) +) +item(tt(U))( +files owned by the effective user ID +) +item(tt(G))( +files owned by the effective group ID +) +item(tt(u)var(id))( +files owned by user ID var(id) if it is a number, if not, than the +character after the `tt(u)' will be used as a separator and the string +between it and the next matching separator +(`tt(LPAR())', `tt([)', `tt({)', and `tt(<)' +match `tt(RPAR())', `tt(])', `tt(})', and `tt(>)' respectively, +any other character matches +itself) will be taken as a user name, and the user ID of this user will +be taken (e.g. `tt(u:foo:)' or `tt(u[foo])' for user `tt(foo)') +) +item(tt(g)var(id))( +like tt(u)var(id) but with group IDs or names +) +item(tt(a)[tt(Mwhm)][tt(-)|tt(PLUS())]var(n))( +files accessed exactly var(n) days ago. Files accessed within the +last var(n) days are selected using a negative value for var(n) +(tt(-)var(n)). Files accessed more than var(n) days ago are selected by a +positive var(n) value (tt(PLUS())var(n)). Optional unit specifiers `tt(M)', +`tt(w)', `tt(h)' or `tt(m)' (e.g. `tt(ah5)') cause the check to be +performed with months (of 30 days), weeks, hours, or minutes instead of +days, respectively. For instance, `tt(echo *(ah-5))' would echo files +accessed within the last five hours. +) +item(tt(m)[tt(Mwhm)][tt(-)|tt(PLUS())]var(n))( +like the file access qualifier, except that it uses the file modification +time. +) +item(tt(c)[tt(Mwhm)][tt(-)|tt(PLUS())]var(n))( +like the file access qualifier, except that it uses the file inode change +time. +) +item(tt(L)[tt(PLUS())|tt(-)]var(n))( +files less than var(n) bytes (tt(-)), more than var(n) bytes (tt(PLUS())), or +exactly var(n) bytes in length. If this flag is directly followed by a `tt(k)' +(`tt(K)'), `tt(m)' (`tt(M)'), or `tt(p)' (`tt(P)') (e.g. `tt(Lk-50)') +the check is performed with kilobytes, megabytes, or blocks (of 512 bytes) +instead. +) +item(tt(^))( +negates all qualifiers following it +) +item(tt(-))( +toggles between making the qualifiers work on symbolic links (the +default) and the files they point to +) +item(tt(M))( +sets the tt(MARK_DIRS) option for the current pattern +pindex(MARK_DIRS, setting in pattern) +) +item(tt(T))( +appends a trailing qualifier mark to the file names, analogous to the +tt(LIST_TYPES) option, for the current pattern (overrides tt(M)) +) +item(tt(N))( +sets the tt(NULL_GLOB) option for the current pattern +pindex(NULL_GLOB, setting in pattern) +) +item(tt(D))( +sets the tt(GLOB_DOTS) option for the current pattern +pindex(GLOB_DOTS, setting in pattern) +) +enditem() + +More than one of these lists can be combined, separated by commas. The +whole list matches if at least one of the sublists matches (they are +`or'ed, the qualifiers in the sublists are `and'ed). + +If a `tt(:)' appears in a qualifier list, the remainder of the expression in +parenthesis is interpreted as a modifier (see noderef(Modifiers) +in noderef(History Expansion)). Note that +each modifier must be introduced by a separate `tt(:)'. Note also that the +result after modification does not have to be an existing file. The +name of any existing file can be followed by a modifier of the form +`tt((:..))' even if no actual filename generation is performed. +Thus: + +nofill(tt(ls *(-/))) + +lists all directories and symbolic links that point to directories, +and + +nofill(tt(ls *(%W))) + +lists all world-writable device files in the current directory, and + +nofill(tt(ls *(W,X))) + +lists all files in the current directory that are +world-writable or world-executable, and + +nofill(tt(echo /tmp/foo*(u0^@:t))) + +outputs the basename of all root-owned files beginning with the string +`tt(foo)' in tt(/tmp), ignoring symlinks, and + +nofill(tt(ls *.*~(lex|parse).[ch](^D^l1))) + +lists all files having a link count of one whose names contain a dot +(but not those starting with a dot, since tt(GLOB_DOTS) is explicitly +switched off) except for tt(lex.c), tt(lex.h), tt(parse.c) and tt(parse.h). diff --git a/Doc/Zsh/filelist.yo b/Doc/Zsh/filelist.yo new file mode 100644 index 000000000..298eff074 --- /dev/null +++ b/Doc/Zsh/filelist.yo @@ -0,0 +1,15 @@ +sect(Files) +cindex(files used) +startlist() +list(tt($ZDOTDIR/.zshenv)) +list(tt($ZDOTDIR/.zprofile)) +list(tt($ZDOTDIR/.zshrc)) +list(tt($ZDOTDIR/.zlogin)) +list(tt($ZDOTDIR/.zlogout)) +list(tt(${TMPPREFIX}*) (default is /tmp/zsh*)) +list(tt(/etc/zshenv)) +list(tt(/etc/zprofile)) +list(tt(/etc/zshrc)) +list(tt(/etc/zlogin)) +list(tt(/etc/zlogout) (installation-specific - tt(/etc) is the default)) +endlist() diff --git a/Doc/Zsh/files.yo b/Doc/Zsh/files.yo new file mode 100644 index 000000000..0d775a14f --- /dev/null +++ b/Doc/Zsh/files.yo @@ -0,0 +1,26 @@ +texinode(Files)(Shell Grammar)(Invocation)(Top) +chapter(Files) +sect(Startup/Shutdown Files) +cindex(files, startup) +cindex(startup files) +cindex(files, shutdown) +cindex(shutdown files) +pindex(NO_RCS, use of) +Commands are first read from tt(/etc/zshenv). +If the tt(RCS) option is unset +within tt(/etc/zshenv), all other +initialization files are skipped. +Otherwise, commands are read +from tt($ZDOTDIR/.zshenv). +pindex(LOGIN, use of) +If the shell is a login shell, commands +are read from tt(/etc/zprofile) and then tt($ZDOTDIR/.zprofile). +Then, if the shell is interactive, +commands are read from tt(/etc/zshrc) and then tt($ZDOTDIR/.zshrc). +Finally, if the shell is a login shell, tt(/etc/zlogin) and +tt($ZDOTDIR/.zlogin) are read. + +If tt(ZDOTDIR) is unset, tt(HOME) is used instead. +Those files listed above as being in tt(/etc) may be in another +directory, depending on the installation. +ifnzman(includefile(Zsh/filelist.yo)) diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo new file mode 100644 index 000000000..c2fc71d55 --- /dev/null +++ b/Doc/Zsh/func.yo @@ -0,0 +1,107 @@ +texinode(Functions)(Jobs & Signals)(Command Execution)(Top) +chapter(Functions) +ifzman(\ +sect(Functions) +)\ +cindex(functions) +findex(function) +The tt(function) reserved word is used to define shell functions. +Shell functions are read in and stored internally. +Alias names are resolved when the function is read. +Functions are executed like commands with the arguments +passed as positional parameters. +(See noderef(Command Execution).) + +Functions execute in the same process as the caller and +share all files +and present working directory with the +caller. A trap on tt(EXIT) set inside a function +is executed after the function completes in the environment +of the caller. + +findex(return, use of) +The tt(return) builtin is used to return from function calls. + +findex(functions, use of) +Function identifiers can be listed with the tt(functions) builtin. +findex(unfunction, use of) +Functions can be undefined with the tt(unfunction) builtin. +sect(Autoloading Functions) +findex(autoload, use of) +cindex(autoloading functions) +cindex(functions, autoloading) +A function can be marked as em(undefined) using the tt(autoload) builtin +(or `tt(functions -u)' or `tt(typeset -fu)'). Such a function has no +body. When the function is first executed, the tt(fpath) +variable will be searched for a file with the same name as the +function. + +pindex(KSH_AUTOLOAD, use of) +If the tt(KSH_AUTOLOAD) option is set, or the file contains only a simple +definition of the function, the file's contents will be +executed. It would normally define the function in question, but may +also perform initialisation. +It is executed in the context of the function +execution, and may therefore define local parameters. + +Otherwise, the function is defined such that its body is the +complete contents of the file. This form allows the file to be +used directly as an executable shell script. +Initialisation code can be executed, but only as part of the first +function execution, so the function would have to redefine itself to +avoid reinitialising on the next execution. + +If this processing of the file results in the function being +fully defined, the function itself is then executed. +sect(Special Functions) +The following functions, if defined, have special meaning to +the shell: + +startitem() +findex(chpwd) +item(tt(chpwd))( +Executed whenever the current working directory is changed. +) +findex(periodic) +item(tt(periodic))( +vindex(PERIOD) +If the parameter tt(PERIOD) +is set, this function is executed every tt($PERIOD) +seconds, just before a prompt. +) +findex(precmd) +item(tt(precmd))( +Executed before each prompt. +) +findex(preexec) +item(tt(preexec))( +Executed just after a command has been read and is about to be +executed. If the history mechanism is active, the string to be +executed is passed as an argument. +) +item(tt(TRAP)var(NAL))( +cindex(signals, trapping) +cindex(trapping signals) +If defined and non-null, +this function will be executed whenever the shell +catches a signal tt(SIG)var(NAL), where var(NAL) is a signal +name as specified for the tt(kill) builtin. +The signal number will be passed as the first parameter to the function. + +If a function of this form is defined and null, +the shell and processes spawned by it will ignore tt(SIG)var(NAL). +) +findex(TRAPDEBUG) +item(tt(TRAPDEBUG))( +Executed after each command. +) +findex(TRAPEXIT) +item(tt(TRAPEXIT))( +Executed when the shell exits, +or when the current function exits if defined inside a function. +) +findex(TRAPZERR) +item(tt(TRAPZERR))( +Executed whenever a command has a non-zero exit status. +) +enditem() diff --git a/Doc/Zsh/grammar.yo b/Doc/Zsh/grammar.yo new file mode 100644 index 000000000..c78aed4b4 --- /dev/null +++ b/Doc/Zsh/grammar.yo @@ -0,0 +1,335 @@ +texinode(Shell Grammar)(Redirection)(Files)(Top) +chapter(Shell Grammar) +cindex(shell grammar) +cindex(grammar, shell) +startmenu() +menu(Simple Commands & Pipelines) +menu(Precommand Modifiers) +menu(Complex Commands) +menu(Alternate Forms For Complex Commands) +menu(Reserved Words) +menu(Comments) +menu(Aliasing) +menu(Quoting) +endmenu() +texinode(Simple Commands & Pipelines)(Precommand Modifiers)()(Shell Grammar) +sect(Simple Commands & Pipelines) +cindex(simple commands) +cindex(commands, simple) +A em(simple command) is a sequence of optional parameter +assignments followed by blank-separated words, +with optional redirections interspersed. +The first word is the command to be executed, and the remaining +words, if any, are arguments to the command. +If a command name is given, the parameter assignments modify +the environment of the command when it is executed. +The value of a simple command is its exit status, +or 128 plus the signal number if terminated by a signal. + +cindex(pipeline) +A em(pipeline) is either a simple command, or a sequence of two or more +simple commands where each command is separated from the next by `tt(|)' +or `tt(|&)'. Where commands are separated by `tt(|)', the standard +output of the first command is connected to the +standard input of the next. `tt(|&)' is shorthand for `tt(2>&1 |)', which +connects both the standard output and the standard error of the +command to the standard input of the next. The value of a pipeline +is the value of the last command, unless the pipeline is preceded by +`tt(!)' in which case the value is the logical inverse of the value of the +last command. + +findex(coproc) +cindex(coprocess) +If a pipeline is preceded by `tt(coproc)', it is executed as a coprocess; +a two-way pipe is established between it and the parent shell. The +shell can read from or write to the coprocess by means of the `tt(>&p)' +and `tt(<&p)' redirection operators or with `tt(print -p)' and `tt(read -p)'. +A pipeline cannot be preceded by both `tt(coproc)' and `tt(!)'. + +cindex(sublist) +A em(sublist) is either a single pipeline, or a sequence of two or more +pipelines separated by `tt(&&)' or `tt(||)'. If two pipelines are separated +by `tt(&&)', the second pipeline is executed only if the first succeeds +(returns a zero value). If two pipelines are separated by `tt(||)', the +second is executed only if the first fails (returns a nonzero value). +Both operators have equal precedence and are left associative. +The value of the sublist is the value of the last pipeline executed. + +cindex(list) +A em(list) is a sequence of zero or more sublists, in which each sublist +is terminated by `tt(;)', `tt(&)', `tt(&|)', `tt(&!)', or a newline. +This terminator +may optionally be omitted from the last sublist in the list when the +list appears as a complex command inside `tt(LPAR())...tt(RPAR())' +or `tt({)...tt(})'. When a +sublist is terminated by `tt(;)' or newline, the shell waits for it to +finish before executing the next sublist. If a sublist is terminated +by a `tt(&)', `tt(&|)', or `tt(&!)', +the shell executes it in the background, and +does not wait for it to finish. +A backgrounded sublist returns a status of zero. +texinode(Precommand Modifiers)(Complex Commands)(Simple Commands & Pipelines)(Shell Grammar) +sect(Precommand Modifiers) +cindex(precommand modifiers) +cindex(modifiers, precommand) +A simple command may be preceded by a em(precommand modifier), +which will alter how the command is interpreted. These modifiers are +shell builtin commands with the exception of tt(nocorrect) which is +a reserved word. + +startitem() +item(tt(-))( +The command is executed with a `tt(-)' prepended to its +tt(argv[0]) string. +) +item(tt(noglob))( +Filename generation (globbing) is not performed on any of +the words. +) +item(tt(nocorrect))( +Spelling correction is not done on any of the words. +) +item(tt(exec))( +The command is executed in the parent shell without forking. +) +item(tt(command))( +The command word is taken to be the name of an external command, +rather than a shell function or builtin. +) +item(tt(builtin))( +The command word is taken to be the name of a builtin command, +rather than a shell function or external command. +) +enditem() +texinode(Complex Commands)(Alternate Forms For Complex Commands)(Precommand Modifiers)(Shell Grammar) +sect(Complex Commands) +cindex(complex commands) +cindex(commands, complex) +A em(complex command) in zsh is one of the following: + +startitem() +findex(if) +cindex(if construct) +item(tt(if) var(list) tt(then) var(list) [ tt(elif) var(list) tt(then) var(list) ] ... [ tt(else) var(list) ] tt(fi))( +The tt(if) var(list) is executed, and if it returns a zero exit status, +the tt(then) var(list) is executed. +Otherwise, the tt(elif) var(list) is executed and if its value is zero, +the tt(then) var(list) is executed. +If each tt(elif) var(list) returns nonzero, the tt(else) var(list) is executed. +) +findex(for) +cindex(for loops) +cindex(loops, for) +item(tt(for) var(name) [ tt(in) var(word) ... var(term) ] tt(do) var(list) tt(done))( +where var(term) is at least one newline or tt(;). +Expand the list of var(word)s, and set the parameter +var(name) to each of them in turn, executing +var(list) each time. If the tt(in) var(word) is omitted, +use the positional parameters instead of the var(word)s. +) +item(tt(for LPAR()LPAR()) [var(expr1)] tt(;) [var(expr2)] tt(;) [var(expr3)] tt(RPAR()RPAR() do) var(list) tt(done))( +The arithmetic expression var(expr1) is evaluated first (see +noderef(Arithmetic Evaluation)). The arithmetic expression +var(expr2) is repeatedly evaluated until it evaluates to zero and +when non-zero, var(list) is executed and the arithmetic expression +var(expr3) evaluated. If any expression is omitted, then it behaves +as if it evaluated to 1. +) +findex(while) +cindex(while loops) +cindex(loops, while) +item(tt(while) var(list) tt(do) var(list) tt(done))( +Execute the tt(do) var(list) as long as the tt(while) var(list) +returns a zero exit status. +) +findex(until) +cindex(until loops) +cindex(loops, until) +item(tt(until) var(list) tt(do) var(list) tt(done))( +Execute the tt(do) var(list) as long as tt(until) var(list) +returns a nonzero exit status. +) +findex(repeat) +cindex(repeat loops) +cindex(loops, repeat) +item(tt(repeat) var(word) tt(do) var(list) tt(done))( +var(word) is expanded and treated as an arithmetic expression, +which must evaluate to a number var(n). +var(list) is then executed var(n) times. +) +findex(case) +cindex(case selection) +cindex(selection, case) +item(tt(case) var(word) tt(in) [ [tt(LPAR())] var(pattern) [ tt(|) var(pattern) ] ... tt(RPAR()) var(list) (tt(;;)|tt(;&)) ] ... tt(esac))( +Execute the var(list) associated with the first var(pattern) +that matches var(word), if any. The form of the patterns +is the same as that used for filename generation. See +noderef(Filename Generation). +If the var(list) that is executed is terminated with tt(;&) rather than +tt(;;), the following list is also executed. This continues until either +a list is terminated with tt(;;) or the tt(esac) is reached. +) +findex(select) +cindex(user selection) +cindex(selection, user) +item(tt(select) var(name) [ tt(in) var(word) ... var(term) ] tt(do) var(list) tt(done))( +where var(term) is one ore more newline or tt(;). +Print the set of var(word)s, each preceded by a number. +If the tt(in) var(word) is omitted, use the positional parameters. +The tt(PROMPT3) prompt is printed and a line is read from standard +input. If this line consists of the number of one of the listed +var(word)s, then the parameter var(name) +is set to the var(word) corresponding to this number. +If this line is empty, the selection list is printed again. +Otherwise, the value of the parameter var(name) is set to null. +The contents of the line read from standard input is saved +in the parameter tt(REPLY). var(list) is executed +for each selection until a break or end-of-file is encountered. +) +cindex(subshells) +item(tt(LPAR()) var(list) tt(RPAR()))( +Execute var(list) in a subshell. Traps set by the tt(trap) builtin +are reset to their default values while executing var(list). +) +item(tt({) var(list) tt(}))( +Execute var(list). +) +xitem(tt(function) var(word) ... [ tt(()) ] [ var(term) ] tt({) var(list) tt(})) +xitem(var(word) ... tt(()) [ var(term) ] tt({) var(list) tt(})) +item(var(word) ... tt(()) [ var(term) ] var(command))( +where var(term) is one or more newline or tt(;). +Define a function which is referenced by any one of var(word). +Normally, only one var(word) is provided; multiple var(word)s +are usually only useful for setting traps. +The body of the function is the var(list) between +the tt({) and tt(}). See noderef(Functions). +) +cindex(timing) +item(tt(time) [ var(pipeline) ])( +The var(pipeline) is executed, and timing statistics are +reported on the standard error in the form specified +by the tt(TIMEFMT) parameter. +If var(pipeline) is omitted, print statistics about the +shell process and its children. +) +cindex(testing conditional expression) +item(tt([[) var(exp) tt(]]))( +Evaluates the conditional expression var(exp) +and return a zero exit status if it is true. +See noderef(Conditional Expressions) +for a description of var(exp). +) +enditem() +texinode(Alternate Forms For Complex Commands)(Reserved Words)(Complex Commands)(Shell Grammar) +sect(Alternate Forms For Complex Commands) +cindex(alternate forms for complex commands) +cindex(commands, alternate forms for complex) +Many of zsh's complex commands have alternate forms. These particular +versions of complex commands should be considered deprecated and may be +removed in the future. The versions in the previous section should be +preferred instead. The short versions below only work if var(sublist) +is of the form `tt({) var(list) tt(})' or if the tt(SHORT_LOOPS) +option is set. + +startitem() +item(tt(if) var(list) tt({) var(list) tt(}) [ tt(elif) var(list) tt({) var(list) tt(}) ] ... [ tt(else {) var(list) tt(}) ])( +An alternate form of tt(if). +) +item(tt(if) var(list) var(sublist))( +A short form of the alternate `if'. +) +item(tt(for) var(name) tt(LPAR()) var(word) ... tt(RPAR()) var(sublist))( +A short form of tt(for). +) +item(tt(for) var(name) [ tt(in) var(word) ... var(term) ] var(sublist))( +where var(term) is at least one newline or tt(;). +Another short form of tt(for). +) +item(tt(for LPAR()LPAR()) [var(expr1)] tt(;) [var(expr2)] tt(;) [var(expr3)] tt(RPAR()RPAR()) var(sublist))( +A short form of the arithmetic tt(for) command. +) +item(tt(foreach) var(name) tt(LPAR()) var(word) ... tt(RPAR()) var(list) tt(end))( +Another form of tt(for). +) +item(tt(while) var(list) tt({) var(list) tt(}))( +An alternative form of tt(while). +) +item(tt(until) var(list) tt({) var(list) tt(}))( +An alternative form of tt(until). +) +item(tt(repeat) var(word) var(sublist))( +This is a short form of tt(repeat). +) +item(tt(case) var(word) tt({) [ [tt(LPAR())] var(pattern) [ tt(|) var(pattern) ] ... tt(RPAR()) var(list) (tt(;;)|tt(;&)) ] ... tt(}))( +An alternative form of tt(case). +) +item(tt(select) var(name) [ tt(in) var(word) var(term) ] var(sublist))( +where var(term) is at least one newline or tt(;). +A short form of tt(select). +) +enditem() +texinode(Reserved Words)(Comments)(Alternate Forms For Complex Commands)(Shell Grammar) +sect(Reserved Words) +cindex(reserved words) +findex(disable, use of) +The following words are recognized as reserved words when used as the first +word of a command unless quoted or disabled using tt(disable -r): + +tt(do done esac then elif else fi for case +if while function repeat time until +select coproc nocorrect foreach end ! [[ { }) + +Additionally, `tt(})' is recognized in any position if the tt(IGNORE_BRACES) option +is not set. +texinode(Comments)(Aliasing)(Reserved Words)(Shell Grammar) +sect(Comments) +cindex(comments) +pindex(INTERACTIVE_COMMENTS, use of) +vindex(histchars, use of) +In noninteractive shells, or in interactive shells with the +tt(INTERACTIVE_COMMENTS) option set, a word beginning +with the third character of the tt(histchars) parameter +(`tt(#)' by default) causes that word and all the following +characters up to a newline to be ignored. +texinode(Aliasing)(Quoting)(Comments)(Shell Grammar) +sect(Aliasing) +cindex(aliasing) +Every token in the shell input is checked to see if there +is an alias defined for it. +If so, it is replaced by the text of the alias if it is in command +position (if it could be the first word of a simple command), +or if the alias is global. +If the text ends with a space, the next word in the shell input +is treated as though it were in command position for purposes of alias +expansion. +findex(alias, use of) +cindex(aliases, global) +An alias is defined using the tt(alias) builtin; global aliases +may be defined using the tt(-g) option to that builtin. + +Alias substitution is done on the shell input before any +other substitution except history substitution. Therefore, +if an alias is defined for the word tt(foo), alias substitution +may be avoided by quoting part of the word, e.g. tt(\foo). +But there is nothing to prevent an alias being defined +for tt(\foo) as well. +texinode(Quoting)()(Aliasing)(Shell Grammar) +sect(Quoting) +cindex(quoting) +A character may be var(quoted) (that is, made +to stand for itself) by preceding it with a `tt(\)'. +`tt(\)' followed by a newline is ignored. + +A string enclosed between `tt($')' and `tt(')' is +processed the same way as the string arguments of the +tt(print) builtin, and the resulting string is considered to be +entirely quoted. A literal `tt(')' character can be included in the +string by using the `tt(\')' escape. + +All characters enclosed between a pair of single quotes (tt('')) that +is not preceded by a `tt($)' are quoted. A single quote cannot appear +within single quotes. + +Inside double quotes (tt("")), parameter and +command substitution occurs, and `tt(\)' quotes the characters +`tt(\)', `tt(`)', `tt(")', and `tt($)'. diff --git a/Doc/Zsh/guide.yo b/Doc/Zsh/guide.yo new file mode 100644 index 000000000..d38a0d308 --- /dev/null +++ b/Doc/Zsh/guide.yo @@ -0,0 +1,149 @@ +texiifinfo(\ +texinode(Top)(The Z Shell Guide)((dir))((dir)) +texitop(The Z Shell Guide) +This Info file documents Zsh, a freely available UNIX command interpreter +(shell), which of the standard shells most closely resembles the Korn shell +(ksh), although it is not completely compatible. + +Version version(), last updated date(). +)\ + +startmenu() +menu(The Z Shell Guide) +menu(Introduction) +menu(Invocation) +menu(Files) +menu(Shell Grammar) +menu(Redirection) +menu(Command Execution) +menu(Functions) +menu(Jobs & Signals) +menu(Arithmetic Evaluation) +menu(Conditional Expressions) +menu(Compatibility) +menu(Prompt Expansion) +menu(Restricted Shell) +menu(Expansion) +menu(Parameters) +menu(Options) +menu(Shell Builtin Commands) +menu(Zsh Line Editor) +menu(Programmable Completion) +menu(Zsh Modules) + + --- Indices --- + +menu(Concept Index) +menu(Variables Index) +menu(Options Index) +menu(Functions Index) +menu(Editor Functions Index) +menu(Keystroke Index) + + --- The Detailed Node Listing --- + +Introduction + +menu(Author) +menu(Availability) +menu(Mailing Lists) +menu(The Zsh FAQ) +menu(The Zsh Web Page) +menu(See Also) + +Shell Grammar + +menu(Simple Commands & Pipelines) +menu(Precommand Modifiers) +menu(Complex Commands) +menu(Alternate Forms For Complex Commands) +menu(Reserved Words) +menu(Comments) +menu(Aliasing) +menu(Quoting) + +Expansion + +menu(History Expansion) +menu(Process Substitution) +menu(Parameter Expansion) +menu(Command Substitution) +menu(Arithmetic Expansion) +menu(Brace Expansion) +menu(Filename Expansion) +menu(Filename Generation) + +Parameters + +menu(Local Parameters) +menu(Array Parameters) +menu(Positional Parameters) +menu(Parameters Set By The Shell) +menu(Parameters Used By The Shell) + +Options + +menu(Description of Options) +menu(Single Letter Options) + +Zsh Line Editor + +menu(Movement) +menu(History Control) +menu(Modifying Text) +menu(Arguments) +menu(Completion) +menu(Miscellaneous) + +Programmable Completion + +menu(Command Flags) +menu(Option Flags) +menu(Alternative Completion) +menu(Extended Completion) +menu(Example) + +Zsh Modules + +menu(The cap Module) +menu(The clone Module) +menu(The comp1 Module) +menu(The compctl Module) +menu(The deltochar Module) +menu(The example Module) +menu(The files Module) +menu(The sched Module) +menu(The stat Module) +menu(The zle Module) +endmenu() +texinode(The Z Shell Guide)(Introduction)(Top)(Top) +chapter(The Z Shell Guide) +This document has been produced from the texinfo file tt(zsh.texi), +included in the tt(Doc) sub-directory of the Zsh distribution. +sect(Producing documentation from zsh.texi) +The texinfo source may be converted into several formats: + +startitem() +item(The Info guide)( +The Info format allows searching for topics, commands, functions, etc. +from the many Indices. The command `tt(makeinfo zsh.texi)' is used to +produce the Info documentation. +) +item(The printed guide)( +The command `tt(texi2dvi zsh.texi)' will output tt(zsh.dvi) which can +then be processed with bf(dvips) and optionally bf(gs) (Ghostscript) to +produce a nicely formatted printed guide. +) +item(The HTML guide)( +Mark Borges, tt(). +Zsh is now maintained by the members of the zsh-workers mailing +list tt(). The development is currently +coordinated by Andrew Main (Zefram) tt(). The coordinator +can be contacted at tt(), but matters relating to +the code should generally go to the mailing list. +texinode(Availability)(Mailing Lists)(Author)(Introduction) +sect(Availability) +Zsh is available from the following anonymous FTP sites. These mirror +sites are kept frequently up to date. The sites marked with em((G)) +may be mirroring tt(ftp.math.gatech.edu) instead of the primary site. +The sites marked with em((H)) may be mirroring tt(ftp.cs.elte.hu) +instead of the primary site. + +startitem() +item(Primary site)( +nofill(tt(ftp://ftp.zsh.org/pub/zsh/) +tt(http://www.zsh.org/pub/zsh/)) +) +item(Australia)( +nofill(tt(ftp://ftp.zsh.org/pub/zsh/) +tt(http://www.zsh.org/pub/zsh/) +tt(ftp://ftp.ips.oz.au/pub/packages/zsh/) em((G)) em((H))) +) +item(Denmark)( +nofill(tt(ftp://sunsite.auc.dk/pub/unix/shells/zsh/)) +) +item(Finland)( +nofill(tt(ftp://ftp.funet.fi/pub/unix/shells/zsh/) em((H))) +) +item(France)( +nofill(tt(ftp://ftp.cenatls.cena.dgac.fr/pub/shells/zsh/)) +) +item(Germany)( +nofill(tt(ftp://ftp.fu-berlin.de/pub/unix/shells/zsh/) em((H)) +tt(ftp://ftp.gmd.de/packages/zsh/) em((H)) +tt(ftp://ftp.uni-trier.de/pub/unix/shell/zsh/) em((H))) +) +item(Hungary)( +nofill(tt(ftp://ftp.cs.elte.hu/pub/zsh/) +tt(http://www.cs.elte.hu/pub/zsh/) +tt(ftp://ftp.kfki.hu/pub/packages/zsh/) em((H))) +) +item(Israel)( +nofill(tt(ftp://ftp.math.technion.ac.il/mirror/ftp.zsh.org/pub/zsh/) +tt(http://www.math.technion.ac.il/mirror/ftp.zsh.org/pub/zsh/)) +) +item(Japan)( +nofill(tt(ftp://ftp.tohoku.ac.jp/mirror/zsh/) em((H)) +tt(ftp://ftp.nis.co.jp/pub/shells/zsh/) em((H))) +) +item(Norway)( +nofill(tt(ftp://ftp.uit.no/pub/unix/shells/zsh/) em((H))) +) +item(Romania)( +nofill(tt(ftp://ftp.roedu.net/pub/mirrors/ftp.zsh.org/pub/zsh/)) +) +item(Slovenia)( +nofill(tt(ftp://ftp.siol.net/pub/unix/shells/zsh/) em((H))) +) +item(Sweden)( +nofill(tt(ftp://ftp.lysator.liu.se/pub/unix/zsh/) em((H))) +) +item(UK)( +nofill(tt(ftp://ftp.net.lut.ac.uk/zsh/) em((H)) +tt(ftp://sunsite.doc.ic.ac.uk/packages/unix/shells/zsh/) em((G))) +) +item(USA)( +nofill(tt(ftp://ftp.math.gatech.edu/pub/zsh/) +tt(ftp://uiarchive.uiuc.edu/pub/packages/shells/zsh/) +tt(ftp://ftp.sterling.com/zsh/) em((G)) em((H)) +tt(ftp://ftp.rge.com/pub/shells/zsh/) em((G)) em((H)) +tt(ftp://foad.org/pub/zsh/) +tt(http://foad.org/zsh/)) +) +enditem() +texinode(Mailing Lists)(The Zsh FAQ)(Availability)(Introduction) +sect(Mailing Lists) +cindex(mailing lists) +Zsh has 3 mailing lists: + +startitem() +item(tt())( +Announcements about releases, major changes in the shell and the +monthly posting of the Zsh FAQ. (moderated) +) +item(tt())( +User discussions. +) +item(tt())( +Hacking, development, bug reports and patches. +) +enditem() + +To subscribe, send mail with the SUBJECT `tt(subscribe) var()' +to the associated administrative address for the mailing list. + +startlist() +list(tt()) +list(tt()) +list(tt()) +endlist() + +Unsubscribing is done similarly. + +YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED. +All submissions to bf(zsh-announce) are automatically forwarded to +bf(zsh-users). All submissions to bf(zsh-users) are automatically +forwarded to bf(zsh-workers). + +If you have problems subscribing/unsubscribing to any of the mailing +lists, send mail to tt(). The mailing lists are +maintained by Richard Coleman tt(). + +The mailing lists are archived; the archives can be accessed via the +administrative addresses listed above. There is also a hypertext +archive, maintained by Geoff Wing tt(), available at +tt(http://www.zsh.org/mla/). +texinode(The Zsh FAQ)(The Zsh Web Page)(Mailing Lists)(Introduction) +sect(The Zsh FAQ) +Zsh has a list of Frequently Asked Questions (FAQ), maintained by +Peter Stephenson tt(). It is regularly posted to the +newsgroup bf(comp.unix.shell) and the bf(zsh-announce) mailing list. +The latest version can be found at any of the Zsh FTP sites, or at +tt(http://www.zsh.org/FAQ/). The contact address for FAQ-related matters +is tt(). +texinode(The Zsh Web Page)(See Also)(The Zsh FAQ)(Introduction) +sect(The Zsh Web Page) +Zsh has a web page which is located at tt(http://www.zsh.org/). This is +maintained by Karsten Thygesen tt(), of SunSITE Denmark. +The contact address for web-related matters is tt(). diff --git a/Doc/Zsh/mod_cap.yo b/Doc/Zsh/mod_cap.yo new file mode 100644 index 000000000..f6513b314 --- /dev/null +++ b/Doc/Zsh/mod_cap.yo @@ -0,0 +1,28 @@ +texinode(The cap Module)(The clone Module)()(Zsh Modules) +sect(The cap Module) +The tt(cap) module is used for manipulating POSIX.1e (POSIX.6) capability +sets. If the operating system does not support this interface, the +builtins defined by this module will do nothing. +The builtins in this module are: + +startitem() +findex(cap) +cindex(capabilities, setting) +item(tt(cap) [ var(capabilities) ])( +Change the shell's process capability sets to the specified var(capabilities), +otherwise display the shell's current capabilities. +) +findex(getcap) +cindex(capabilities, getting from files) +item(tt(getcap) var(filename) ...)( +This is a built-in implementation of the POSIX standard utility. It displays +the capability sets on each specified var(filename). +) +findex(setcap) +cindex(capabilities, setting on files) +item(tt(setcap) var(capabilities) var(filename) ...)( +This is a built-in implementation of the POSIX standard utility. It sets +the capability sets on each specified var(filename) to the specified +var(capabilities). +) +enditem() diff --git a/Doc/Zsh/mod_clone.yo b/Doc/Zsh/mod_clone.yo new file mode 100644 index 000000000..9bb7dc255 --- /dev/null +++ b/Doc/Zsh/mod_clone.yo @@ -0,0 +1,19 @@ +texinode(The clone Module)(The comp1 Module)(The cap Module)(Zsh Modules) +sect(The clone Module) +The tt(clone) module makes available one builtin command: + +startitem() +findex(clone) +cindex(shell, cloning) +cindex(cloning the shell) +cindex(terminal) +item(tt(clone) var(tty))( +Creates a forked instance of the current shell, attached to the specified +var(tty). In the new shell, the tt(PID), tt(PPID) and tt(TTY) special +parameters are changed appropriately. tt($!) is set to zero in the new +shell, and to the new shell's PID in the original shell. + +The return value of the builtin is zero in both shells if successful, +and non-zero on error. +) +enditem() diff --git a/Doc/Zsh/mod_comp1.yo b/Doc/Zsh/mod_comp1.yo new file mode 100644 index 000000000..879b6d927 --- /dev/null +++ b/Doc/Zsh/mod_comp1.yo @@ -0,0 +1,11 @@ +texinode(The comp1 Module)(The compctl Module)(The clone Module)(Zsh Modules) +sect(The comp1 Module) +The tt(comp1) module does nothing that is visible to the user. +Its purpose is to provide the internal basis of the programmable +completion mechanism. + +This module must be loaded before any module that +provides a means of controlling completion (such as the tt(compctl) +module), or that uses completions (such as the tt(zle) module). +This is done automatically for modules distributed with zsh, and +for other modules can be effected by the use of tt(zmodload -d). diff --git a/Doc/Zsh/mod_compctl.yo b/Doc/Zsh/mod_compctl.yo new file mode 100644 index 000000000..b7adf8fa6 --- /dev/null +++ b/Doc/Zsh/mod_compctl.yo @@ -0,0 +1,7 @@ +texinode(The compctl Module)(The deltochar Module)(The comp1 Module)(Zsh Modules) +sect(The compctl Module) +The tt(compctl) module makes available one builtin command, tt(compctl), +which is the standard way to control completions for ZLE. See +ifzman(zmanref(zshcompctl))\ +ifnzman(noderef(Programmable Completion))\ +. diff --git a/Doc/Zsh/mod_deltochar.yo b/Doc/Zsh/mod_deltochar.yo new file mode 100644 index 000000000..f92a3da0d --- /dev/null +++ b/Doc/Zsh/mod_deltochar.yo @@ -0,0 +1,12 @@ +texinode(The deltochar Module)(The example Module)(The compctl Module)(Zsh Modules) +sect(The deltochar Module) +The tt(deltochar) module makes available one ZLE function: + +startitem() +tindex(delete-to-char) +item(tt(delete-to-char))( +Read a character from the keyboard, and +delete from the cursor position up to and including the next +(or, with repeat count var(n), the var(n)th) instance of that character. +) +enditem() diff --git a/Doc/Zsh/mod_example.yo b/Doc/Zsh/mod_example.yo new file mode 100644 index 000000000..5339253d9 --- /dev/null +++ b/Doc/Zsh/mod_example.yo @@ -0,0 +1,16 @@ +texinode(The example Module)(The files Module)(The deltochar Module)(Zsh Modules) +sect(The example Module) +The tt(example) module makes available one builtin command: + +startitem() +findex(example) +cindex(modules, example) +cindex(modules, writing) +cindex(writing modules) +item(tt(example) [ tt(-flags) ] [ var(args) ... ])( +Displays the flags and arguments it is invoked with. +) +enditem() + +The purpose of the module is to serve as an example of how to write a +module. diff --git a/Doc/Zsh/mod_files.yo b/Doc/Zsh/mod_files.yo new file mode 100644 index 000000000..541ebb4a9 --- /dev/null +++ b/Doc/Zsh/mod_files.yo @@ -0,0 +1,100 @@ +texinode(The files Module)(The sched Module)(The example Module)(Zsh Modules) +sect(The files Module) +cindex(files, manipulating) +The tt(files) module makes some standard commands available as builtins: + +startitem() +findex(ln) +xitem(tt(ln) [ tt(-dfis) ] var(filename) var(dest)) +item(tt(ln) [ tt(-dfis) ] var(filename) ... var(dir))( +Creates hard (or, with tt(-s), symbolic) links. In the first form, the +specified var(dest)ination is created, as a link to the specified +var(filename). In the second form, each of the var(filename)s is +taken in turn, and linked to a pathname in the specified var(dir)ectory +that has the same last pathname component. + +Normally, tt(ln) will not attempt to create hard links to +directories. This check can be overridden using the tt(-d) option. +Typically only the super-user can actually succeed in creating +hard links to directories. +This does not apply to symbolic links in any case. + +By default, existing files cannot be replaced by links. +The tt(-i) option causes the user to be queried about replacing +existing files. The tt(-f) option causes existing files to be +silently deleted, without querying. tt(-f) takes precedence. +) +findex(mkdir) +item(tt(mkdir) [ tt(-p) ] [ tt(-m) var(mode) ] var(dir) ...)( +Creates directories. With the tt(-p) option, non-existing parent +directories are first created if necessary, and there will be +no complaint if the directory already exists. +The tt(-m) option can be used to specify (in octal) a set of file permissions +for the created directories, otherwise mode 777 modified by the current +tt(umask) (see manref(umask)(2)) is used. +) +findex(mv) +xitem(tt(mv) [ tt(-fi) ] var(filename) var(dest)) +item(tt(mv) [ tt(-fi) ] var(filename) ... var(dir))( +Moves files. In the first form, the specified var(filename) is moved +to the specified var(dest)ination. In the second form, each of the +var(filename)s is +taken in turn, and moved to a pathname in the specified var(dir)ectory +that has the same last pathname component. + +By default, the user will be queried before replacing any file +that the user cannot write to, but writable files will be silently +removed. +The tt(-i) option causes the user to be queried about replacing +any existing files. The tt(-f) option causes any existing files to be +silently deleted, without querying. tt(-f) takes precedence. + +Note that this tt(mv) will not move files across devices. +Historical versions of tt(mv), when actual renaming is impossible, +fall back on copying and removing files; if this behaviour is desired, +use tt(cp) and tt(rm) manually. This may change in a future version. +) +findex(rm) +item(tt(rm) [ tt(-dfirs) ] var(filename) ...)( +Removes files and directories specified. + +Normally, tt(rm) will not remove directories (except with the tt(-r) +option). The tt(-d) option causes tt(rm) to try removing directories +with tt(unlink) (see manref(unlink)(2)), the same method used for files. +Typically only the super-user can actually succeed in unlinking +directories in this way. +tt(-d) takes precedence over tt(-r). + +By default, the user will be queried before removing any file +that the user cannot write to, but writable files will be silently +removed. +The tt(-i) option causes the user to be queried about removing +any files. The tt(-f) option causes files to be +silently deleted, without querying, and suppresses all error indications. +tt(-f) takes precedence. + +The tt(-r) option causes tt(rm) to recursively descend into directories, +deleting all files in the directory before removing the directory with +the tt(rmdir) system call (see manref(rmdir)(2)). + +The tt(-s) option is a zsh extension to tt(rm) functionality. It enables +paranoid behaviour, intended to avoid common security problems involving +a root-run tt(rm) being tricked into removing files other than the ones +intended. It will refuse to follow symbolic links, so that (for example) +``tt(rm /tmp/foo/passwd)'' can't accidentally remove tt(/etc/passwd) +if tt(/tmp/foo) happens to be a link to tt(/etc). It will also check +where it is after leaving directories, so that a recursive removal of +a deep directory tree can't end up recursively removing tt(/usr) as +a result of directories being moved up the tree. +) +findex(rmdir) +item(tt(rmdir) var(dir) ...)( +Removes empty directories specified. +) +findex(sync) +item(tt(sync))( +Calls the system call of the same name (see manref(sync)(2)), which +flushes dirty buffers to disk. It might return before the I/O has +actually been completed. +) +enditem() diff --git a/Doc/Zsh/mod_sched.yo b/Doc/Zsh/mod_sched.yo new file mode 100644 index 000000000..1be550a79 --- /dev/null +++ b/Doc/Zsh/mod_sched.yo @@ -0,0 +1,17 @@ +texinode(The sched Module)(The stat Module)(The files Module)(Zsh Modules) +sect(The sched Module) +The tt(sched) module makes available one builtin command: + +startitem() +findex(sched) +cindex(timed execution) +cindex(execution, timed) +xitem(tt(sched) [tt(PLUS())]var(hh)tt(:)var(mm) var(command) ...) +item(tt(sched) [ tt(-)var(item) ])( +Make an entry in the scheduled list of commands to execute. +The time may be specified in either absolute or relative time. +With no arguments, prints the list of scheduled commands. +With the argument `tt(-)var(item)', removes the given item +from the list. +) +enditem() diff --git a/Doc/Zsh/mod_stat.yo b/Doc/Zsh/mod_stat.yo new file mode 100644 index 000000000..22fbe2a73 --- /dev/null +++ b/Doc/Zsh/mod_stat.yo @@ -0,0 +1,145 @@ +texinode(The stat Module)(The zle Module)(The sched Module)(Zsh Modules) +sect(The stat Module) +The tt(stat) module makes available one builtin command: + +startitem() +findex(stat) +cindex(files, listing) +cindex(files, examining) +item(tt(stat) [ tt(-gnNlLtTrs) ] [ tt(-f) var(fd) ] [ tt(-A) var(array) ] \ + [ tt(-F) var(fmt) ] [ tt(PLUS())var(element) ] [ var(file) ... ])( +The command acts as a front end to the tt(stat) system call (see +manref(stat)(2)). +If the tt(stat) call fails, the appropriate system error message +printed and status 1 is returned. +The fields of tt(struct stat) give information about +the files provided as arguments to the command. In addition to those +available from the tt(stat) call, an extra element `tt(link)' is provided. +These elements are: + +startitem() +item(tt(device))( +The number of the device on which the file resides. +) +item(tt(inode))( +The unique number of the file on this device (`em(inode)' number). +) +item(tt(mode))( +The mode of the file; that is, the file's type and access permissions. +With the tt(-s) option, this will +be returned as a string corresponding to the first column in the +display of the tt(ls -l) command. +) +item(tt(nlink))( +The number of hard links to the file. +) +item(tt(uid))( +The user ID of the owner of the file. With the tt(-s) +option, this is displayed as a user name. +) +item(tt(gid))( +The group ID of the file. With the tt(-s) option, this +is displayed as a group name. +) +item(tt(rdev))( +The raw device number. This is only useful for special devices. +) +item(tt(size))( +The size of the file in bytes. +) +xitem(tt(atime)) +xitem(tt(mtime)) +item(tt(ctime))( +The last access, modification and inode change times +of the file, respectively, as the number of seconds since +midnight GMT on 1st January, 1970. With the tt(-s) option, +these are printed as strings for the local time zone; the format +can be altered with the tt(-F) option, and with the tt(-g) +option the times are in GMT. +) +item(tt(blksize))( +The number of bytes in one allocation block on the +device on which the file resides. +) +item(tt(block))( +The number of disk blocks used by the file. +) +item(tt(link))( +If the file is a link and the tt(-L) option is in +effect, this contains the name of the file linked to, otherwise +it is empty. Note that if this element is selected (``tt(stat PLUS()link)'') +then the tt(-L) option is automatically used. +) +enditem() + +A particular element may be selected by including its name +preceded by a `tt(PLUS())' in the option list; only one element is allowed. +The element may be shortened to any unique set of leading +characters. Otherwise, all elements will be shown for all files. + +Options: + +startitem() +item(tt(-A) var(array))( +Instead of displaying the results on standard +output, assign them to an var(array), one tt(struct stat) element per array +element for each file in order. In this case neither the name +of the element nor the name of the files is provided unless the +tt(-t) or tt(-n) options are provided, respectively. In the +former case the element name appears as a prefix to the +appropriate array element and in the latter case the file name +appears as a separate array element preceding all the others. +Other formatting options are respected. +) +item(tt(-f) var(fd))( +Use the file on file descriptor var(fd) instead of +named files; no list of file names is allowed in this case. +) +item(tt(-F) var(fmt))( +Supplies a tt(strftime) (see manref(strftime)(3)) string for the +formatting of the time elements. The tt(-s) option is implied. +) +item(tt(-g))( +Show the time elements in the GMT time zone. The +tt(-s) option is implied. +) +item(tt(-l))( +List the names of the type elements (to standard +output or an array as appropriate) and return immediately; +options other than tt(-A) and arguments are ignored. +) +item(tt(-L))( +Perform an tt(lstat) (see manref(lstat)(2)) rather than a tt(stat) +system call. In this case, if the file is a link, information +about the link itself rather than the target file is returned. +This option is required to make the tt(link) element useful. +) +item(tt(-n))( +Always show the names of files. Usually these are +only shown when output is to standard output and there is more +than one file in the list. +) +item(tt(-N))( +Never show the names of files. +) +item(tt(-r))( +Print raw data (the default format) alongside string +data (the tt(-s) format); the string data appears in parentheses +after the raw data. +) +item(tt(-s))( +Print tt(mode), tt(uid), tt(gid) and the three time +elements as strings instead of numbers. In each case the format +is like that of tt(ls -l). +) +item(tt(-t))( +Always show the type names for the elements of +tt(struct stat). Usually these are only shown when output is to +standard output and no individual element has been selected. +) +item(tt(-T))( +Never show the type names of the tt(struct stat) elements. +) +enditem() +) +enditem() diff --git a/Doc/Zsh/mod_zftp.yo b/Doc/Zsh/mod_zftp.yo new file mode 100644 index 000000000..a15be60d6 --- /dev/null +++ b/Doc/Zsh/mod_zftp.yo @@ -0,0 +1,421 @@ +texinode(The zftp Module)(The zle Module)(The stat Module)(Zsh Modules) +sect(The zftp Module) +The tt(zftp) module makes available one builtin command: + +startitem() +findex(zftp) +cindex(FTP) +cindex(files, transferring) +item(tt(zftp) var(subcommand) [ var(args) ])( +The tt(zftp) module is a client for FTP (file transfer protocol). It +is implemented as a builtin to allow full use of shell command line +editing, file I/O, and job control mechanisms. Often, users will +access it via shell functions providing higher level abilities such as +username and password lookup. However, it is entirely usable in its +own right. + +All commands consist of the command name tt(zftp) followed by the name +of a subcommand. These are listed below. The return status of each +subcommand is supposed to reflect the success or failure of the remote +operation. See a description of the variable tt(ZFTP_VERBOSE) for +more information on how responses from the server may be printed. +) +enditem() + +subsect(Subcommands) +cindex(zftp, subcommands) + +startitem() +cindex(FTP, starting a session) +item(tt(open) var(host) [ var(user) [ var(password) [ var(account) ] ] ])( +Open a new FTP session to var(host), which may be the name of a TCP/IP +connected host or an IP number in the standard dot notation. +Remaining arguments are passed to the tt(login) subcommand. Note that +if no arguments beyond var(host) are supplied, tt(open) will em(not) +automatically call tt(login). If no arguments at all are supplied, +tt(open) will use the parameters set by the tt(params) subcommand. + +After a successful open, the shell variables tt(ZFTP_HOST), +tt(ZFTP_IP) and tt(ZFTP_SYSTEM) are available; see `Variables' +below. +) +xitem(tt(login) [ var(name) [ var(password) [ var(account) ] ] ]) +item(tt(user) [ var(name) [ var(password) [ var(account) ] ] ])( +Login the user var(name) with parameters var(password) and var(account). +Any of the parameters can be omitted, and will be read from standard +input if needed (var(name) is always needed). If +standard input is a terminal, a prompt for each one will be printed on +standard error and var(password) will not be echoed. If any of the +parameters are not used, a warning message is printed. + +After a successful login, the shell variables tt(ZFTP_USER), +tt(ZFTP_ACCOUNT) and tt(ZFTP_PWD) are available; see `Variables' +below. + +This command may be re-issued when a user is already logged in, and +the server will first be reinitialized for a new user. +) +xitem(tt(params) [ var(host) [ var(user) [ var(password) \ +[ var(account) ] ] ] ]) +item(tt(params) tt(-))( +Store the given parameters for a later tt(open) command with no +arguments. Only those given on the command line will be remembered. +Any of the parameters may, however, be specified as a `tt(?)', which +may need to be quoted to protect it from shell expansion: in this case, +the appropriate parameter will be read from stdin as with the +tt(login) subcommand, including special handling of var(password). + +If no arguments are given, the parameters currently set are printed, +although the password will appear as a line of stars. + +If instead a single `tt(-)' is given, the existing parameters, if any, +are deleted. In that case, calling tt(open) with no arguments will +cause an error. + +The list of parameters is not deleted after a tt(close), however it +will be deleted if the tt(zftp) module is unloaded. + +For example, + +nofill(tt(zftp params ftp.elsewhere.xx juser '?')) + +will store the host tt(ftp.elsewhere.xx) and the user tt(juser) and +then prompt the user for the corresponding password. + +This command may also be used to set up a transfer which then takes +place completely in the background, freeing tt(zftp) for concurrent +foreground use. For example, + +nofill(tt(zftp params ftp.soreeyes.ca bubble squeak)) +nofill(tt(LPAR()zftp open; zftp get foo >bar; zftp close)tt(RPAR() &)) + +--- here, the connection is restricted to a background subshell and +you are free to open a simultaneous connection in the foreground. +) +item(tt(cd) var(directory))( +Change the remote directory to var(directory). Also alters the shell +variable tt(ZFTP_PWD). +) +item(tt(cdup))( +Change the remote directory to the one higher in the directory tree. +Note that tt(cd ..) will also work correctly on non-UNIX systems. +) +item(tt(dir) [ var(args...) ])( +Give a (verbose) listing of the remote directory. The var(args) are +passed directly to the server. The command's behaviour is implementation +dependent, but a UNIX server will typically interpret var(args) as +arguments to the tt(ls) command and with no arguments return the +result of `tt(ls -l)'. The directory is listed to standard output. +) +item(tt(ls) [ var(args) ])( +Give a (short) listing of the remote directory. With no var(args), +produces a raw list of the files in the directory, one per line. +Otherwise, up to vagaries of the server implementation, behaves +similar to tt(dir). +) +item(tt(type) [ var(type) ])( +Change the type for transfer to var(type), or print the current type +if var(type) is absent. The allowed values are `tt(A)' (ASCII), +`tt(I)' (Image, i.e. binary), or `tt(B)' (a synonym for `tt(I)'). + +The FTP default for a transfer is ASCII. However, if tt(zftp) finds +that the remote host is a UNIX machine with 8-bit byes, it will +automatically switch to using binary for file transfers upon +tt(open). This can subsequently be overridden. + +The transfer type is only passed to the remote host when a data +connection is established; this command involves no network overhead. +) +item(tt(ascii))( +The same as tt(type A). +) +item(tt(binary))( +The same as tt(type I). +) +item(tt(mode) [ tt(S) | tt(B) ])( +Set the mode type to stream (tt(S)) or block (tt(B)). Stream mode is +the default; block mode is not widely supported. +) +xitem(tt(remote) var(files...)) +item(tt(local) [ var(files...) ])( +Print the size and last modification time of the remote or local +files. If there is more than one item on the list, the name of the +file is printed first. The first number is the file size, the second +is the last modification time of the file in the format +tt(CCYYMMDDhhmmSS) consisting of year, month, date, hour, minutes and +seconds in GMT. Note that this format, including the length, is +guaranteed, so that time strings can be directly compared via the +tt([[) builtin's tt(<) and tt(>) operators, even if they are too long +to be represented as integers. + +Not all servers support the commands for retrieving this information. +In that case, the tt(remote) command will print nothing and return +status 2, compared with status 1 for a file not found. + +The tt(local) command (but not tt(remote)) may be used with no +arguments, in which case the information comes from examining file +descriptor zero. This is the same file as seen by a tt(put) command +with no further redirection. +) +item(tt(get) var(file) [...])( +Retrieve all var(file)s from the server, concatenating them +and sending them to standard output. +) +item(tt(put) var(file) [...])( +For each var(file), read a file from standard input and send that to +the remote host with the given name. +) +item(tt(append) var(file) [...])( +As tt(put), but if the remote var(file) already exists, data is +appended to it instead of overwriting it. +) +xitem(tt(getat) var(file) var(point)) +xitem(tt(putat) var(file) var(point)) +item(tt(appendat) var(file) var(point))( +Versions of tt(get), tt(put) and tt(append) which will start the +transfer at the given var(point) in the remote var(file). This is +useful for appending to an incomplete local file. However, note that +this ability is not universally supported by servers (and is not quite +the behaviour specified by the standard). +) +item(tt(delete) var(file) [...])( +Delete the list of files on the server. +) +item(tt(mkdir) var(directory))( +Create a new directory var(directory) on the server. +) +item(tt(rmdir) var(directory))( +Delete the diretory var(directory) on the server. +) +item(tt(rename) var(old-name) var(new-name))( +Rename file var(old-name) to var(new-name) on the server. +) +item(tt(site) var(args...))( +Send a host-specific command to the server. You will probably +only need this if instructed by the server to use it. +) +item(tt(quote) var(args...))( +Send the raw FTP command sequence to the server. You should be +familiar with the FTP command set as defined in RFC959 before doing +this. Useful comands may include tt(STAT) and tt(HELP). Note also +the mechanism for returning messages as described for the variable +tt(ZFTP_VERBOSE) below, in particular that all messages from the +control connection are sent to standard error. +) +xitem(tt(close)) +item(tt(quit))( +Close the current data connection. This unsets the shell parameters +tt(ZFTP_HOST), tt(ZFTP_IP), tt(ZFTP_SYSTEM), tt(ZFTP_USER), +tt(ZFTP_ACCOUNT) and tt(ZFTP_PWD). +) +enditem() + +subsect(Parameters) +cindex(zftp, parameters) +The following shell parameters are used by tt(zftp). Currently none +of them are special. + +startitem() +item(tt(ZFTP_TMOUT))( +Integer. The time in seconds to wait for a network operation to +complete before returning an error. If this is not set when the +module is loaded, it will be given the default value 60. A value of +zero turns off timeouts. If a timeout occurs on the control +connection it will be closed. Use a larger value if this occurs too +frequently. +) +vindex(ZFTP_IP) +item(tt(ZFTP_IP))( +Readonly. The IP address of the current connection in dot notation. +) +vindex(ZFTP_HOST) +item(tt(ZFTP_HOST))( +Readonly. The hostname of the current remote server. If the host was +opened as an IP number, tt(ZFTP_HOST) contains that instead; this +saves the overhead for a name lookup, as IP numbers are most commonly +used when a nameserver is unavailable. +) +vindex(ZFTP_SYSTEM) +item(tt(ZFTP_SYSTEM))( +Readonly. The system type string returned by the server in response +to an FTP tt(SYST) request. The most interesting case is a string +beginning tt("UNIX Type: L8"), which ensures maximum compatibility +with a local UNIX host. +) +vindex(ZFTP_TYPE) +item(tt(ZFTP_TYPE))( +Readonly. The type to be used for data transfers , either `tt(A)' or +`tt(I)'. Use the tt(type) subcommand to change this. +) +vindex(ZFTP_USER) +item(tt(ZFTP_USER))( +Readonly. The username currently logged in, if any. +) +vindex(ZFTP_ACCT) +item(tt(ZFTP_ACCT))( +Readonly. The account name of the current user, if any. Most servers +do not require an account name. +) +vindex(ZFTP_PWD) +item(tt(ZFTP_PWD))( +Readonly. The current directory on the server. +) +vindex(ZFTP_CODE) +item(tt(ZFTP_CODE))( +Readonly. The three digit code of the last FTP reply from the server +as a string. This can still be read after the connection is closed. +) +vindex(ZFTP_REPLY) +item(tt(ZFTP_REPLY))( +Readonly. The last line of the last reply sent by the server. This +can still be read after the connection is closed. +) +vindex(ZFTP_PREFS) +item(tt(ZFTP_PREFS))( +A string of preferences for altering aspects of tt(zftp)'s behaviour. +Each preference is a single character. The following are defined: + +startitem() +item(tt(P))( +Passive: attempt to make the remote server initiate data transfers. +This is slightly more efficient than sendport mode. If the letter +tt(S) occurs later in the string, tt(zftp) will use sendport mode if +passive mode is not available. +) +item(tt(S))( +Sendport: initiate transfers by the FTP tt(PORT) command. If this +occurs before any tt(P) in the string, passive mode will never be +attempted. +) +item(tt(D))( +Dumb: use only the bare minimum of FTP commands. This prevents +the variables tt(ZFTP_SYSTEM) and tt(ZFTP_PWD) from being set, and +will mean all connections default to ASCII type. It may prevent +tt(ZFTP_SIZE) from being set during a transfer if the server +does not send it anyway (many servers do). +) +enditem() + +If tt(ZFTP_PREFS) is not set when tt(zftp) is loaded, it will be set to a +default of `tt(PS)', i.e. use passive mode if available, otherwise +fall back to sendport mode. +) +vindex(ZFTP_VERBOSE) +item(tt(ZFTP_VERBOSE))( +A string of digits between 0 and 5 inclusive, specifying which +responses from the server should be printed. All responses go to +standard error. If any of the numbers 1 to 5 appear in the string, +raw responses from the server with reply codes beginning with that +digit will be printed to standard error. The first digit of the three +digit reply code is defined by RFC959 to correspond to: + +startitem() +item(1.)( +A positive prelimnary reply. +) +item(2.)( +A positive completion reply. +) +item(3.)( +A positive intermediate reply. +) +item(4.)( +A transient negative completion reply. +) +item(5.)( +A permanent negative completion reply. +) +enditem() + +It should be noted that, for unknown reasons, the reply `Service not +available', which forces termination of a connection, is classified as +421, i.e. `transient negative', an interesting interpretation of the word +`transient'. + +The code 0 is special: it indicates that all but the last line of +multiline replies read from the server will be printed to standard +error in a processed format. By convention, servers use this +mechanism for sending information for the user to read. The +appropriate reply code, if it matches the same response, takes +priority. + +If tt(ZFTP_VERBOSE) is not set when tt(zftp) is loaded, it will be +set to the default value tt(450), i.e., messages destined for the user +and all errors will be printed. A null string is valid and +specifies that no messages should be printed. +) +enditem() + +subsect(Functions) +cindex(zftp, functions) + +startitem() +findex(zftp_chpwd) +item(tt(zftp_chpwd))( +If this function is set by the user, it is called every time the +directory changes on the server, including when a user is logged +in, or when a connection is closed. In the last case, tt($ZFTP_PWD) +will be unset; otherwise it will reflect the new directory. +) +findex(zftp_progress) +item(tt(zftp_progress))( +If this function is set by the user, it will be called during +a tt(get), tt(put) or tt(append) operation each time sufficient data +has been received from the host. During a tt(get), the data is sent +to standard output, so it is vital that this function should write +to standard error or directly to the terminal, em(not) to standard +output. + +When it is called with a transfer in progress, the following +additional shell parameters are set: + +startitem() +vindex(ZFTP_FILE) +item(tt(ZFTP_FILE))( +The name of the remote file being transferred from or to. +) +vindex(ZFTP_TRANSFER) +item(tt(ZFTP_TRANSFER))( +A tt(G) for a tt(get) operation and a tt(P) for a tt(put) operation. +) +vindex(ZFTP_SIZE) +item(tt(ZFTP_SIZE))( +The total size of the complete file being transferred: +the same as the first value provided by the +tt(remote) and tt(local) subcommands for a particular file. +If the server cannot supply this value for a remote file being +retrieved, it will not be set. If input is from a pipe the value may +be incorrect and correspond simply to a full pipe buffer. +) +vindex(ZFTP_COUNT) +item(tt(ZFTP_COUNT))( +The amount of data so far transferred; a number between zero and +tt($ZFTP_SIZE), if that is set. This number is always available. +) +enditem() + +The function is initially called with tt(ZFTP_TRANSFER) set +appropriately and tt(ZFTP_COUNT) set to zero. After the transfer is +finished, the function will be called one more time with +tt(ZFTP_TRANSFER) set to tt(GF) or tt(PF), in case it wishes to tidy +up. It is otherwise never called twice with the same value of +tt(ZFTP_COUNT). + +Sometimes the progress meter may cause disruption. It is up to the +user to decide whether the function should be defined and to use +tt(unfunction) when necessary. +) + +subsect(Problems) +cindex(zftp, problems) + +With the exception noted for the tt(params) subcommand, a connection +may not be opened in the left hand side of a pipe as this occurs in a +subshell and the file information is not updated in the main shell. +In the case of type or mode changes or closing the connection in a +subshell, the information is returned but variables are not updated +until the next call to tt(zftp). Other status changes in subshells +will not be reflected by changes to the variables (but should +be otherwise harmless). + +enditem() diff --git a/Doc/Zsh/mod_zle.yo b/Doc/Zsh/mod_zle.yo new file mode 100644 index 000000000..9aa03f7f8 --- /dev/null +++ b/Doc/Zsh/mod_zle.yo @@ -0,0 +1,193 @@ +texinode(The zle Module)()(The stat Module)(Zsh Modules) +sect(The zle Module) +The tt(zle) module contains the Zsh Line Editor. See +ifzman(zmanref(zshzle))\ +ifnzman(noderef(Zsh Line Editor))\ +. It also contains three related builtin commands: + +startitem() +findex(bindkey) +cindex(keys, rebinding) +cindex(rebinding keys) +cindex(keys, binding) +cindex(binding keys) +cindex(keymaps) +xitem(tt(bindkey) [ var(options) ] tt(-l)) +xitem(tt(bindkey) [ var(options) ] tt(-d)) +xitem(tt(bindkey) [ var(options) ] tt(-D) var(keymap) ...) +xitem(tt(bindkey) [ var(options) ] tt(-A) var(old-keymap new-keymap)) +xitem(tt(bindkey) [ var(options) ] tt(-N) var(new-keymap) [ var(old-keymap) ]) +xitem(tt(bindkey) [ var(options) ] tt(-m)) +xitem(tt(bindkey) [ var(options) ] tt(-r) var(in-string) ...) +xitem(tt(bindkey) [ var(options) ] tt(-s) var(in-string out-string) ...) +xitem(tt(bindkey) [ var(options) ] var(in-string command) ...) +item(tt(bindkey) [ var(options) ] [ var(in-string) ])( +tt(bindkey)'s options can be divided into three categories: keymap selection, +operation selection, and others. The keymap selection options are: + +startitem() +item(tt(-e))( +Selects keymap `tt(emacs)', and also links it to `tt(main)'. +) +item(tt(-v))( +Selects keymap `tt(viins)', and also links it to `tt(main)'. +) +item(tt(-a))( +Selects keymap `tt(vicmd)'. +) +item(tt(-M))( +The first non-option argument is used as a keymap name, +and does not otherwise count as an argument. +) +enditem() + +Some operations do not permit a keymap to be selected. +If a keymap selection is required and none of the options above are used, the +`tt(main)' keymap is used. These operations do not permit a keymap to be +selected: + +startitem() +item(tt(-l))( +List all existing keymap names. If the tt(-L) +option is used, list in the form of tt(bindkey) +commands to create the keymaps. +) +item(tt(-d))( +Delete all existing keymaps and reset to the default state. +) +item(tt(-D) var(keymap) ...)( +Delete the named var(keymap)s. +) +item(tt(-A) var(old-keymap new-keymap))( +Make the var(new-keymap) name an alias for var(old-keymap), so that +both names refer to the same keymap. The names have equal standing; +if either is deleted, the other remains. If there is already a keymap +with the var(new-keymap) name, it is deleted. +) +item(tt(-N) var(new-keymap) [ var(old-keymap) ])( +Create a new keymap, named var(new-keymap). If a keymap already has that +name, it is deleted. If an var(old-keymap) name is given, the new keymap +is initialised to be a duplicate of it, otherwise the new keymap will +be empty. +) +enditem() + +The following operations require a keymap to be selected: + +startitem() +item(tt(-m))( +Add the built-in set of meta-key bindings to the selected keymap. +Only keys that are unbound or bound to tt(self-insert) are affected. +) +item(tt(-r) var(in-string) ...)( +Unbind the specified var(in-string)s in the selected keymap. +This is exactly equivalent to binding the strings to tt(undefined-key). +) +item(tt(-s) var(in-string out-string) ...)( +Bind each var(in-string) to each var(out-string). +When var(in-string) is typed, var(out-string) will be +pushed back and treated as input to the line editor. +) +item(var(in-string command) ...)( +Bind each var(in-string) to each var(command). +) +item([ var(in-string) ])( +List key bindings. If an var(in-string) is specified, the binding of +that string in the selected keymap is displayed. Otherwise, all key +bindings in the selected keymap are displayed. As an exception, +if the tt(-e) or tt(-v) options are used alone, the keymap is em(not) +displayed - the implicit linking of keymaps is the only thing that happens. +) +enditem() + +In the binding operations, if the tt(-R) option is used, the var(in-string)s +are interpreted as ranges, instead of plain strings. A valid range +consists of two characters, with an optional `tt(-)' +between them. All characters between the two specified, inclusive, +are bound as specified. + +For either var(in-string) or var(out-string), the following +escape sequences are recognised: + +startsitem() +sitem(tt(\a))(bell character) +sitem(tt(\b))(backspace) +sitem(tt(\e), tt(\E))(escape) +sitem(tt(\f))(form feed) +sitem(tt(\n))(linefeed (newline)) +sitem(tt(\r))(carriage return) +sitem(tt(\t))(horizontal tab) +sitem(tt(\v))(vertical tab) +sitem(tt(\)var(NNN))(character code in octal) +sitem(tt(\x)var(NN))(character code in hexadecimal) +sitem(tt(\M)[tt(-)]var(X))(character with meta bit set) +sitem(tt(\C)[tt(-)]var(X))(control character) +sitem(tt(^)var(X))(control character) +endsitem() + +In all other cases, `tt(\)' escapes the following character. Delete is +written as `tt(^?)'. Note that `tt(\M^?)' and `tt(^\M?)' are not the same. +) +findex(vared) +cindex(parameters, editing) +cindex(editing parameters) +item(tt(vared) [ tt(-ch) ] [ tt(-p) var(prompt) ] [ tt(-r) var(rprompt) ] var(name))( +The value of the parameter var(name) is loaded into the edit +buffer, and the line editor is invoked. When the editor exits, +var(name) is set to the string value returned by the editor. +If the tt(-c) flag is given, the parameter is created if it doesn't +already exist. +If the tt(-p) flag is given, the following string will be taken as +the prompt to display at the left. If the tt(-r) flag is given, +the following string gives the prompt to display at the right. If the +tt(-h) flag is specified, the history can be accessed from ZLE. +) +findex(zle) +cindex(widgets, rebinding) +cindex(rebinding widgets) +cindex(widgets, binding) +cindex(binding widgets) +cindex(widgets, invoking) +cindex(invoking widgets) +cindex(widgets, calling) +cindex(calling widgets) +cindex(widgets, defining) +cindex(defining widgets) +xitem(tt(zle) tt(-l) [ tt(-L) ]) +xitem(tt(zle) tt(-D) var(widget) ...) +xitem(tt(zle) tt(-A) var(old-widget) var(new-widget)) +xitem(tt(zle) tt(-N) var(widget) [ var(function) ]) +item(tt(zle) var(widget))( +The tt(zle) builtin performs a number of different actions concerning +ZLE. Which operation it performs depends on its options: + +startitem() +item(tt(-l) [ tt(-L) ])( +List all existing user-defined widgets. If the tt(-L) +option is used, list in the form of tt(zle) +commands to create the widgets. +Built-in widgets are not listed. +) +item(tt(-D) var(widget) ...)( +Delete the named var(widget)s. +) +item(tt(-A) var(old-widget) var(new-widget))( +Make the var(new-widget) name an alias for var(old-widget), so that +both names refer to the same widget. The names have equal standing; +if either is deleted, the other remains. If there is already a widget +with the var(new-widget) name, it is deleted. +) +item(tt(-N) var(widget) [ var(function) ])( +Create a user-defined widget. If there is already a widget with the +specified name, it is overwritten. When the new +widget is invoked from within the editor, the specified shell var(function) +is called. If no function name is specified, it defaults to +the same name as the widget. +) +item(var(widget))( +Invoke the specified widget. This can only be done when ZLE is +active; normally this will be within a user-defined widget. +) +enditem() +) +enditem() diff --git a/Doc/Zsh/modules.yo b/Doc/Zsh/modules.yo new file mode 100644 index 000000000..b44b00e6b --- /dev/null +++ b/Doc/Zsh/modules.yo @@ -0,0 +1,64 @@ +texinode(Zsh Modules)()(Programmable Completion)(Top) +chapter(Zsh Modules) +cindex(modules) +sect(Description) +Some optional parts of zsh are in modules, separate from the core +of the shell. Each of these modules may be linked in to the +shell at build time, +or can be dynamically linked while the shell is running +if the installation supports this feature. The modules available are: + +startitem() +item(tt(cap))( +Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege) sets. +) +item(tt(clone))( +A builtin that can clone a running shell onto another terminal. +) +item(tt(comp1))( +Base of the completion system. Used by the tt(compctl) and tt(zle) modules. +) +item(tt(compctl))( +The tt(compctl) builtin for controlling completion. +) +item(tt(deltochar))( +A ZLE function duplicating EMACS' tt(zap-to-char). +) +item(tt(example))( +An example of how to write a module. +) +item(tt(files))( +Some basic file manipulation commands as builtins. +) +item(tt(sched))( +A builtin that provides a timed execution facility within the shell. +) +item(tt(stat))( +A builtin command interface to the tt(stat) system call. +) +item(tt(zle))( +The Zsh Line Editor, including the tt(bindkey) and tt(vared) builtins. +) +enditem() +startmenu() +menu(The cap Module) +menu(The clone Module) +menu(The comp1 Module) +menu(The compctl Module) +menu(The deltochar Module) +menu(The example Module) +menu(The files Module) +menu(The sched Module) +menu(The stat Module) +menu(The zle Module) +endmenu() +includefile(Zsh/mod_cap.yo) +includefile(Zsh/mod_clone.yo) +includefile(Zsh/mod_comp1.yo) +includefile(Zsh/mod_compctl.yo) +includefile(Zsh/mod_deltochar.yo) +includefile(Zsh/mod_example.yo) +includefile(Zsh/mod_files.yo) +includefile(Zsh/mod_sched.yo) +includefile(Zsh/mod_stat.yo) +includefile(Zsh/mod_zle.yo) diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo new file mode 100644 index 000000000..0fdf78e8a --- /dev/null +++ b/Doc/Zsh/options.yo @@ -0,0 +1,1039 @@ +texinode(Options)(Shell Builtin Commands)(Parameters)(Top) +chapter(Options) +cindex(options) +startmenu() +menu(Specifying Options) +menu(Description of Options) +menu(Option Aliases) +menu(Single Letter Options) +endmenu() +texinode(Specifying Options)(Description of Options)()(Options) +sect(Specifying Options) +cindex(options, specifying) +Options are primarily referred to by name. +These names are case insensitive and underscores are ignored. +For example, `tt(allexport)' is equivalent to `tt(A__lleXP_ort)'. + +The sense of an option name may be inverted by preceding it with +`tt(no)', so `tt(setopt No_Beep)' is equivalent to `tt(unsetopt beep)'. +This inversion can only be done once, so `tt(nonobeep)' is em(not) +a synonym for `tt(beep)'. Similarly, `tt(tify)' is not a synonym for +`tt(nonotify)' (the inversion of `tt(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 bf(sh)/bf(ksh) (used when the +tt(SH_OPTION_LETTERS) option is set). +The single letter options can be used on the shell command line, +or with the tt(set), tt(setopt) and tt(unsetopt) +builtins, as normal Unix options preceded by `tt(-)'. + +The sense of the single letter options may be inverted by using +`tt(PLUS())' instead of `tt(-)'. +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, `tt(PLUS()n)' is the short name of `tt(exec)', and +`tt(-n)' is the short name of its inversion, `tt(noexec)'. +texinode(Description of Options)(Option Aliases)(Specifying Options)(Options) +sect(Description of Options) +cindex(options, description) +startitem() +pindex(ALL_EXPORT) +cindex(export, automatic) +item(tt(ALL_EXPORT) (tt(-a), ksh: tt(-a)))( +All parameters subsequently defined are automatically exported. +) +pindex(ALWAYS_LAST_PROMPT) +item(tt(ALWAYS_LAST_PROMPT))( +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 em(no) numeric argument. +) +pindex(ALWAYS_TO_END) +item(tt(ALWAYS_TO_END))( +If a completion is performed with the cursor within a word, and a +full completion is inserted, the cursor is moved to the end of the +word. That is, the cursor is moved to the end of the word if either +a single match is inserted or menu completion is performed. +) +pindex(APPEND_HISTORY) +cindex(history, appending to a file) +item(tt(APPEND_HISTORY))( +If this is set, zsh sessions will append their history list to +the history file, rather than overwrite it. Thus, multiple parallel +zsh sessions will all have their history lists added to the +history file, in the order they are killed. +) +pindex(AUTO_CD) +cindex(cd, automatic) +item(tt(AUTO_CD) (tt(-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 tt(cd) +command to that directory. +) +pindex(AUTO_LIST) +cindex(completion, listing choices) +item(tt(AUTO_LIST) (tt(-9)))( +Automatically list choices on an ambiguous completion. +) +pindex(AUTO_MENU) +cindex(completion, menu) +item(tt(AUTO_MENU))( +Automatically use menu completion after the second consecutive request for +completion, for example by pressing the tab key repeatedly. This option +is overridden by tt(MENU_COMPLETE). +) +pindex(AUTO_NAME_DIRS) +cindex(directories, named) +item(tt(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 `tt(%~)' +and related prompt sequences, and will be available when completion +is performed on a word starting with `tt(~)'. +(Otherwise, the parameter must be used in the form `tt(~)var(param)' first.) +) +pindex(AUTO_PARAM_KEYS) +item(tt(AUTO_PARAM_KEYS))( +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 `tt(})', `tt(:)', +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 `tt(,)', which will be removed if `tt(})' is typed next. +) +pindex(AUTO_PARAM_SLASH) +item(tt(AUTO_PARAM_SLASH))( +If a parameter is completed whose content is the name of a directory, +then add a trailing slash instead of a space. +) +pindex(AUTO_PUSHD) +cindex(cd, behaving like pushd) +cindex(pushd, making cd behave like) +item(tt(AUTO_PUSHD) (tt(-N)))( +Make tt(cd) push the old directory onto the directory stack. +) +pindex(AUTO_REMOVE_SLASH) +cindex(slash, removing trailing) +item(tt(AUTO_REMOVE_SLASH))( +When the last character resulting from a completion is a slash and the next +character typed is a word delimiter or a slash, remove the slash. +) +pindex(AUTO_RESUME) +cindex(jobs, resuming automatically) +cindex(resuming jobs automatically) +item(tt(AUTO_RESUME) (tt(-W)))( +Treat single word simple commands without redirection +as candidates for resumption of an existing job. +) +pindex(BAD_PATTERN) +cindex(globbing, bad pattern) +cindex(filename generation, bad pattern) +item(tt(BAD_PATTERN) (tt(PLUS()2)))( +If a pattern for filename generation is badly formed, print an error message. +(If this option is unset, the pattern will be left unchanged.) +) +pindex(BANG_HIST) +cindex(history, enable substitution) +cindex(enable history substitution) +item(tt(BANG_HIST) (tt(PLUS()K)))( +Perform textual history substitution, bf(csh)-style, +treating the character `tt(!)' specially. +) +pindex(BARE_GLOB_QUAL) +cindex(globbing qualifiers, enable) +cindex(enable globbing qualifiers) +item(tt(BARE_GLOB_QUAL))( +In a glob pattern, treat a trailing set of parentheses as a qualifier +list, if it contains no `tt(|)', `tt(LPAR())' or (if special) `tt(~)' +characters. See noderef(Filename Generation). +) +pindex(BEEP) +cindex(beep, enabling) +cindex(enabling the beep) +item(tt(BEEP) (tt(PLUS()B)))( +Beep on error in ZLE. +) +pindex(BG_NICE) +cindex(jobs, background priority) +cindex(background jobs, priority of) +cindex(priority of background jobs) +item(tt(BG_NICE) (tt(-6)))( +Run all background jobs at a lower priority. This option +is set by default. +) +pindex(BRACE_CCL) +cindex(brace expansion, extending) +cindex(expansion, brace, extending) +item(tt(BRACE_CCL))( +Expand expressions in braces which would not otherwise undergo brace +expansion to a lexically ordered list of all the characters. See +noderef(Brace Expansion). +) +pindex(BSD_ECHO) +cindex(echo, BSD compatible) +item(tt(BSD_ECHO))( +Make the tt(echo) builtin compatible with the BSD manref(echo)(1) command. +This disables backslashed escape sequences in echo strings unless the +tt(-e) option is specified. +) +pindex(CDABLE_VARS) +cindex(cd, to parameter) +item(tt(CDABLE_VARS) (tt(-T)))( +If the argument to a tt(cd) command (or an implied tt(cd) with the +tt(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 `tt(~)' (see +noderef(Filename Expansion)). +) +pindex(CHASE_LINKS) +cindex(links, symbolic) +cindex(symbolic links) +item(tt(CHASE_LINKS) (tt(-w)))( +Resolve symbolic links to their true values when changing directory. +) +pindex(CLOBBER) +cindex(clobbering, of files) +cindex(file clobbering, allowing) +item(tt(CLOBBER) (tt(PLUS()C), ksh: tt(PLUS()C)))( +Allows `tt(>)' redirection to truncate existing files, +and `tt(>>)' to create files. +Otherwise `tt(>!)' or `tt(>|)' must be used to truncate a file, +and `tt(>>!)' or `tt(>>|)' to create a file. +) +pindex(COMPLETE_ALIASES) +cindex(aliases, completion of) +item(tt(COMPLETE_ALIASES))( +Prevents aliases on the command line from being internally substituted +before completion is attempted. The effect is to make the alias a +distinct command for completion purposes. +) +pindex(COMPLETE_IN_WORD) +item(tt(COMPLETE_IN_WORD))( +If unset, the cursor is set to the end of the word if completion is +started. Otherwise it stays there and completion is done from both ends. +) +pindex(CORRECT) +cindex(correction, spelling) +cindex(spelling correction) +item(tt(CORRECT) (tt(-0)))( +Try to correct the spelling of commands. +) +pindex(CORRECT_ALL) +item(tt(CORRECT_ALL) (tt(-O)))( +Try to correct the spelling of all arguments in a line. +) +pindex(CSH_JUNKIE_HISTORY) +cindex(csh, history style) +cindex(history style, csh) +item(tt(CSH_JUNKIE_HISTORY))( +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, defaulting to the +previous command. +) +pindex(CSH_JUNKIE_LOOPS) +cindex(csh, loop style) +cindex(loop style, csh) +item(tt(CSH_JUNKIE_LOOPS))( +Allow loop bodies to take the form `var(list); tt(end)' instead of +`tt(do) var(list); tt(done)'. +) +pindex(CSH_JUNKIE_QUOTES) +cindex(csh, quoting style) +cindex(quoting style, csh) +item(tt(CSH_JUNKIE_QUOTES))( +Changes the rules for single- and double-quoted text to match that of +bf(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 `tt($)', `tt(`)' +or `tt(")' (and `tt(\)' itself no longer needs escaping). +Command substitutions are only expanded once, and cannot be nested. +) +pindex(CSH_NULL_GLOB) +cindex(csh, null globbing style) +cindex(null globbing style, csh) +cindex(globbing, null, style, csh) +item(tt(CSH_NULL_GLOB))( +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 tt(NULL_GLOB). +) +pindex(EQUALS) +cindex(filename substitution, =) +item(tt(EQUALS))( +Perform tt(=) filename substitution. +(See noderef(Filename Expansion).) +) +pindex(ERR_EXIT) +cindex(exit status, trapping) +item(tt(ERR_EXIT) (tt(-e), ksh: tt(-e)))( +If a command has a non-zero exit status, execute the tt(ZERR) +trap, if set, and exit. This is disabled while running initialization +scripts. +) +pindex(EXEC) +cindex(command execution, enabling) +item(tt(EXEC) (tt(PLUS()n), ksh: tt(PLUS()n)))( +Do execute commands. Without this option, commands are +read and checked for syntax errors, but not executed. +) +pindex(EXTENDED_GLOB) +cindex(globbing, extended) +item(tt(EXTENDED_GLOB))( +Treat the `tt(#)', `tt(~)' and `tt(^)' characters as part of patterns +for filename generation, etc. (An initial unquoted `tt(~)' +always produces named directory expansion.) +) +pindex(EXTENDED_HISTORY) +cindex(history, timestamping) +item(tt(EXTENDED_HISTORY))( +Save beginning and ending timestamps to the history file. +The format of these timestamps is +`tt(:)var()tt(:)var()tt(:)var()'. +) +pindex(FLOW_CONTROL) +cindex(flow control) +item(tt(FLOW_CONTROL))( +If this option is unset, +output flow control via start/stop characters (usually assigned to +^S/^Q) is disabled in the shell's editor. +) +pindex(FUNCTION_ARGZERO) +cindex($0, setting) +item(tt(FUNCTION_ARGZERO))( +When executing a shell function or sourcing a script, set tt($0) +temporarily to the name of the function/script. +) +pindex(GLOB) +cindex(globbing, enabling) +cindex(enabling globbing) +item(tt(GLOB) (tt(PLUS()F), ksh: tt(PLUS()f)))( +Perform filename generation (globbing). +(See noderef(Filename Generation).) +) +pindex(GLOB_ASSIGN) +item(tt(GLOB_ASSIGN))( +If this option is set, filename generation (globbing) is +performed on the right hand side of scalar parameter assignments of +the form `var(name)tt(=)var(pattern) (e.g. `tt(foo=*)'). +If the result has more than one word the parameter will become an array +with those words as arguments. This option is provided for backwards +compatibility only: globbing is always performed on the right hand side +of array assignments of the form `var(name)tt(=LPAR())var(value)tt(RPAR())' +(e.g. `tt(foo=(*))') and this form is recommended for clarity; +with this option set, it is not possible to predict whether the result +will be an array or a scalar. +) +pindex(GLOB_COMPLETE) +item(tt(GLOB_COMPLETE))( +When the current word has a glob pattern, do not insert all the words +resulting from the expansion but cycle through them like +tt(MENU_COMPLETE). If no matches are found, a `tt(*)' is added to the end of the +word or inserted at the cursor if tt(COMPLETE_IN_WORD) is set, and expansion +is attempted again. Using patterns works not only for files but for all +completions, such as options, user names, etc. +) +pindex(GLOB_DOTS) +cindex(globbing, of . files) +item(tt(GLOB_DOTS) (tt(-4)))( +Do not require a leading `tt(.)' in a filename to be matched explicitly. +) +pindex(GLOB_SUBST) +item(tt(GLOB_SUBST))( +Treat any characters resulting from parameter substitution as being +eligible for file expansion and filename generation, and any +characters resulting from command substitution as being eligible for +filename generation. +) +pindex(HASH_CMDS) +cindex(hashing, of commands) +cindex(command hashing) +item(tt(HASH_CMDS))( +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 will be done at all. +) +pindex(HASH_DIRS) +cindex(hashing, of directories) +cindex(directories, hashing) +item(tt(HASH_DIRS))( +Whenever a command is executed, hash the directory containing it, +as well as all directories that occur earlier in the path. +Has no effect if tt(HASH_CMDS) is unset. +) +pindex(HASH_LIST_ALL) +item(tt(HASH_LIST_ALL))( +Whenever a command completion is attempted, make sure the entire +command path is hashed first. This makes the first completion slower. +) +pindex(HIST_ALLOW_CLOBBER) +item(tt(HIST_ALLOW_CLOBBER))( +Add `tt(|)' to output redirections in the history. This allows history +references to clobber files even when tt(CLOBBER) is unset. +) +pindex(HIST_BEEP) +cindex(history beeping) +cindex(beep, history) +item(tt(HIST_BEEP))( +Beep when an attempt is made to access a history entry which +isn't there. +) +pindex(HIST_IGNORE_DUPS) +cindex(history, ignoring duplicates) +item(tt(HIST_IGNORE_DUPS) (tt(-h)))( +Do not enter command lines into the history list +if they are duplicates of the previous event. +) +pindex(HIST_IGNORE_SPACE) +cindex(history, ignoring spaces) +item(tt(HIST_IGNORE_SPACE) (tt(-g)))( +Do not enter command lines into the history list +if any command on the line begins with a blank. +) +pindex(HIST_NO_FUNCTIONS) +item(tt(HIST_NO_FUNCTIONS))( +Do not store function definitions in the history list. +) +pindex(HIST_NO_STORE) +item(tt(HIST_NO_STORE))( +Remove the tt(history) (tt(fc -l)) command from +the history when invoked. +) +pindex(HIST_REDUCE_BLANKS) +item(tt(HIST_REDUCE_BLANKS))( +Remove superfluous blanks from each command line +being added to the history list. +) +pindex(HIST_VERIFY) +cindex(history, verifying substitution) +item(tt(HIST_VERIFY))( +Whenever the user enters a line with history substitution, +don't execute the line directly; instead, perform +history substitution and reload the line into the editing buffer. +) +pindex(HUP) +cindex(jobs, HUP) +item(tt(HUP))( +Send the tt(HUP) signal to running jobs when the +shell exits. +) +pindex(IGNORE_BRACES) +cindex(disabling brace expansion) +cindex(brace expansion, disabling) +cindex(expansion, brace, disabling) +item(tt(IGNORE_BRACES) (tt(-I)))( +Do not perform brace expansion. +) +pindex(IGNORE_EOF) +cindex(EOF, ignoring) +item(tt(IGNORE_EOF) (tt(-7)))( +Do not exit on end-of-file. Require the use +of tt(exit) or tt(logout) instead. +However, ten consecutive EOFs will cause the shell to exit anyway, +to avoid the shell hanging if its tty goes away. +) +pindex(INTERACTIVE) +item(tt(INTERACTIVE) (tt(-i), ksh: tt(-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 tt(SHIN_STDIN).) +This heuristic may be overridden by specifying a state for this option +on the command line. +The value of this option cannot be changed anywhere other than the command line. +) +pindex(INTERACTIVE_COMMENTS) +cindex(comments, in interactive shells) +item(tt(INTERACTIVE_COMMENTS) (tt(-k)))( +Allow comments even in interactive shells. +) +pindex(KSH_ARRAYS) +cindex(arrays, ksh style) +cindex(array style, ksh) +cindex(ksh, array style) +item(tt(KSH_ARRAYS))( +Emulate bf(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 (`tt(${path[2]})' rather +than just `tt($path[2])'). +) +pindex(KSH_AUTOLOAD) +item(tt(KSH_AUTOLOAD))( +Emulate bf(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 bf(ksh)-style case - of the file +containing only a simple definition of the function - is always handled +in the bf(ksh)-compatible manner.) +) +pindex(KSH_GLOB) +item(tt(KSH_GLOB))( +In pattern matching, the interpretation of parentheses is affected by +a preceding `tt(@)', `tt(*)', `tt(+)', `tt(?)' or `tt(!)'. +See noderef(Filename Generation). +) +pindex(KSH_OPTION_PRINT) +cindex(option printing, ksh style) +cindex(option printing style, ksh) +cindex(ksh, option printing style) +item(tt(KSH_OPTION_PRINT))( +Alters the way options settings are printed. +) +pindex(LIST_AMBIGUOUS) +cindex(ambiguous completion) +cindex(completion, ambiguous) +item(tt(LIST_AMBIGUOUS))( +If this option is set, completions are shown only if the completions +don't have a unambiguous prefix or suffix that could be inserted in +the command line. +) +pindex(LIST_BEEP) +cindex(beep, ambiguous completion) +cindex(completion, beep on ambiguous) +item(tt(LIST_BEEP))( +Beep on an ambiguous completion. +) +pindex(LIST_TYPES) +cindex(marking file types) +cindex(files, marking type of) +item(tt(LIST_TYPES) (tt(-X)))( +When listing files that are possible completions, show the +type of each file with a trailing identifying mark. +) +pindex(LOCAL_OPTIONS) +item(tt(LOCAL_OPTIONS))( +If this option is set at the point of return from a shell function, +all the options (including this one) which were in force upon entry to +the function are restored. Otherwise, only this option and the +tt(XTRACE) and tt(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 `tt(emulate zsh; setopt localoptions)'. +) +pindex(LOGIN) +item(tt(LOGIN) (tt(-l), ksh: tt(-l)))( +This is a login shell. +If this option is not explicitly set, the shell is a login shell if +the first character of the tt(argv[0]) passed to the shell is a `tt(-)'. +) +pindex(LONG_LIST_JOBS) +cindex(jobs, list format) +item(tt(LONG_LIST_JOBS) (tt(-R)))( +List jobs in the long format by default. +) +pindex(MAGIC_EQUAL_SUBST) +item(tt(MAGIC_EQUAL_SUBST))( +All unquoted arguments of the form `var(identifier)tt(=)var(expression)' +appearing after the command name have filename expansion (that is, +where var(expression) has a leading `tt(~)' or `tt(=)') performed on +var(expression) as if it were a parameter assignment. The argument is +not otherwise treated specially; it is passed to the command as a single +argument, and not used as an actual parameter assignment. +) +pindex(MAIL_WARNING) +cindex(mail, warning of reading) +item(tt(MAIL_WARNING) (tt(-U)))( +Print a warning message if a mail file has been +accessed since the shell last checked. +) +pindex(MARK_DIRS) +cindex(directories, marking) +cindex(marking directories) +item(tt(MARK_DIRS) (tt(-8), ksh: tt(-X)))( +Append a trailing `tt(/)' to all directory +names resulting from filename generation (globbing). +) +pindex(MENU_COMPLETE) +cindex(completion, menu) +item(tt(MENU_COMPLETE) (tt(-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. +tt(reverse-menu-complete) may be used to loop through the list +in the other direction. This option overrides tt(AUTO_MENU). +) +pindex(MONITOR) +cindex(job control, allowing) +item(tt(MONITOR) (tt(-m), ksh: tt(-m)))( +Allow job control. Set by default in interactive shells. +) +pindex(MULTIOS) +item(tt(MULTIOS))( +Perform implicit bf(tee)s or bf(cat)s when multiple +redirections are attempted (see noderef(Redirection)). +) +pindex(NOMATCH) +cindex(globbing, no matches) +item(tt(NOMATCH) (tt(PLUS()3)))( +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 `tt(~)' or `tt(=)'. +) +pindex(NOTIFY) +cindex(background jobs, notification) +cindex(notification of background jobs) +item(tt(NOTIFY) (tt(-5), ksh: tt(-b)))( +Report the status of background jobs immediately, rather than +waiting until just before printing a prompt. +) +pindex(NULL_GLOB) +cindex(globbing, no matches) +item(tt(NULL_GLOB) (tt(-G)))( +If a pattern for filename generation has no matches, +delete the pattern from the argument list instead +of reporting an error. Overrides tt(NOMATCH). +) +pindex(NUMERIC_GLOB_SORT) +cindex(globbing, sorting numerically) +item(tt(NUMERIC_GLOB_SORT))( +If numeric filenames are matched by a filename generation pattern, +sort the filenames numerically rather than lexicographically. +) +pindex(OVERSTRIKE) +cindex(editor, overstrike mode) +cindex(overstrike mode, of editor) +item(tt(OVERSTRIKE))( +Start up the line editor in overstrike mode. +) +pindex(PATH_DIRS) +cindex(path search, extended) +item(tt(PATH_DIRS) (tt(-Q)))( +Perform a path search even on command names with slashes in them. +Thus if `tt(/usr/local/bin)' is in the user's path, and he types +`tt(X11/xinit)', the command `tt(/usr/local/bin/X11/xinit)' will be executed +(assuming it exists). +Commands explicitly beginning with `tt(/)', `tt(./)' or `tt(../)' +are not subject to the path search. +This also applies to the tt(.) builtin, +and searches for modules performed by the tt(zmodload) builtin. +) +pindex(POSIX_BUILTINS) +item(tt(POSIX_BUILTINS))( +When this option is set the tt(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 tt(command) builtin. Special +builtins are +tt(.), +tt(:), +tt(break), +tt(continue), +tt(declare), +tt(eval), +tt(exit), +tt(export), +tt(integer), +tt(local), +tt(readonly), +tt(return), +tt(set), +tt(shift), +tt(source), +tt(times), +tt(trap) and +tt(unset). +) +pindex(PRINT_EIGHT_BIT) +cindex(exit status, printing) +item(tt(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 manref(ctype)(3)). +) +pindex(PRINT_EXIT_VALUE) +cindex(exit status, printing) +item(tt(PRINT_EXIT_VALUE) (tt(-1)))( +Print the exit value of programs with non-zero exit status. +) +pindex(PRIVILEGED) +cindex(privileged mode) +cindex(mode, privileged) +item(tt(PRIVILEGED) (tt(-p), ksh: tt(-p)))( +Turn on privileged mode. This is enabled automatically on startup if the +effective user (group) ID is not equal to the real user (group) ID. Turning +this option off causes the effective user and group IDs to be set to the +real user and group IDs. This option disables sourcing user startup files. +If zsh is invoked as `tt(sh)' or `tt(ksh)' with this option set, +tt(/etc/suid_profile) is sourced (after tt(/etc/profile) on interactive +shells). Sourcing tt(~/.profile) is disabled and the contents of the +tt(ENV) variable is ignored. This option cannot be changed using the +tt(-m) option of tt(setopt) and tt(unsetopt), and changing it inside a +function always changes it globally regardless of the tt(LOCAL_OPTIONS) +option. +) +pindex(PROMPT_BANG) +cindex(prompt, ! expansion) +item(tt(PROMPT_BANG))( +If set, `tt(!)' is treated specially in prompt expansion. +See noderef(Prompt Expansion). +) +pindex(PROMPT_CR) +cindex(prompt, with CR) +item(tt(PROMPT_CR) (tt(PLUS()V)))( +Print a carriage return just before printing +a prompt in the line editor. +) +pindex(PROMPT_PERCENT) +cindex(prompt, % expansion) +item(tt(PROMPT_PERCENT))( +If set, `tt(%)' is treated specially in prompt expansion. +See noderef(Prompt Expansion). +) +pindex(PROMPT_SUBST) +cindex(prompt, parameter expansion) +item(tt(PROMPT_SUBST))( +If set, em(parameter expansion), em(command substitution) and +em(arithmetic expansion) are performed in prompts. +) +pindex(PUSHD_IGNORE_DUPS) +cindex(directory stack, ignoring duplicates) +item(tt(PUSHD_IGNORE_DUPS))( +Don't push multiple copies of the same directory onto the directory stack. +) +pindex(PUSHD_MINUS) +cindex(directory stack, controlling syntax) +item(tt(PUSHD_MINUS))( +Exchanges the meanings of `tt(PLUS())' and `tt(-)' +when used with a number to specify a directory in the stack. +) +pindex(PUSHD_SILENT) +cindex(directory stack, silencing) +item(tt(PUSHD_SILENT) (tt(-E)))( +Do not print the directory stack after tt(pushd) or tt(popd). +) +pindex(PUSHD_TO_HOME) +cindex(pushd, to home) +item(tt(PUSHD_TO_HOME) (tt(-D)))( +Have tt(pushd) with no arguments act like `tt(pushd $HOME)'. +) +pindex(RC_EXPAND_PARAM) +cindex(rc, parameter expansion style) +cindex(parameter expansion style, rc) +item(tt(RC_EXPAND_PARAM) (tt(-P)))( +Array expansions of the form +`var(foo)tt(${)var(xx)tt(})var(bar)', where the parameter +var(xx) is set to tt(LPAR())var(a b c)tt(RPAR()), are substituted with +`var(fooabar foobbar foocbar)' instead of the default +`var(fooa b cbar)'. +) +pindex(RC_QUOTES) +cindex(rc, quoting style) +cindex(quoting style, rc) +item(tt(RC_QUOTES))( +Allow the character sequence `tt('')' to signify a single quote +within singly quoted strings. +) +pindex(RCS) +cindex(startup files, sourcing) +item(tt(RCS) (tt(PLUS()f)))( +After tt(/etc/zshenv) is sourced on startup, source the +tt(.zshenv), tt(/etc/zprofile), tt(.zprofile), +tt(/etc/zshrc), tt(.zshrc), tt(/etc/zlogin), tt(.zlogin), and tt(.zlogout) +files, as described in noderef(Files). +If this option is unset, only the tt(/etc/zshenv) file is sourced. +) +pindex(REC_EXACT) +cindex(completion, exact matches) +item(tt(REC_EXACT) (tt(-S)))( +In completion, recognize exact matches even +if they are ambiguous. +) +pindex(RESTRICTED) +cindex(restricted shell) +item(tt(RESTRICTED) (tt(-r)))( +Enables restricted mode. This option cannot be changed using +tt(unsetopt), and setting it inside a function always changes it +globally regardless of the tt(LOCAL_OPTIONS) option. See +noderef(Restricted Shell). +) +pindex(RM_STAR_SILENT) +cindex(rm *, querying before) +cindex(querying before rm *) +item(tt(RM_STAR_SILENT) (tt(-H)))( +Do not query the user before executing `tt(rm *)' or `tt(rm path/*)'. +) +pindex(RM_STAR_WAIT) +cindex(rm *, waiting before) +cindex(waiting before rm *) +item(tt(RM_STAR_WAIT))( +If querying the user before executing `tt(rm *)' or `tt(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 `tt(*)' in ZLE (with tab). +) +pindex(SH_FILE_EXPANSION) +cindex(sh, expansion style) +cindex(expansion style, sh) +item(tt(SH_FILE_EXPANSION))( +Perform filename expansion (e.g., ~ expansion) em(before) +parameter expansion, command substitution, arithmetic expansion +and brace expansion. +If this option is unset, it is performed em(after) +brace expansion, so things like `tt(~$USERNAME)' and +`tt(~{pfalstad,rc})' will work. +) +pindex(SH_GLOB) +cindex(sh, globbing style) +cindex(globbing style, sh) +item(tt(SH_GLOB))( +Disables the special meaning of `tt(LPAR())', `tt(|)', `tt(RPAR())' +and 'tt(<)' for globbing the result of parameter and command substitutions, +and in some other places where +the shell accepts patterns. This option is set by default if zsh is +invoked as tt(sh) or tt(ksh). +) +pindex(SHIN_STDIN) +item(tt(SHIN_STDIN) (tt(-s), ksh: tt(-s)))( +Commands are being read from the standard input. +Commands are read from standard input if no command is specified with +tt(-c) and no file of commands is specified. If tt(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 on not commands are +em(actually) being read from standard input. +The value of this option cannot be changed anywhere other than the command line. +) +pindex(SH_OPTION_LETTERS) +cindex(sh, single letter options style) +cindex(ksh, single letter options style) +cindex(single letter options, ksh style) +cindex(options, single letter, ksh style) +item(tt(SH_OPTION_LETTERS))( +If this option is set the shell tries to interpret single letter options +(which are used with tt(set) and tt(setopt)) like bf(ksh) does. +This also affects the value of the tt(-) special parameter. +) +pindex(SHORT_LOOPS) +item(tt(SHORT_LOOPS))( +Allow the short forms of tt(for), tt(select), +tt(if), and tt(function) constructs. +) +pindex(SH_WORD_SPLIT) +cindex(field splitting, sh style) +cindex(sh, field splitting style) +item(tt(SH_WORD_SPLIT) (tt(-y)))( +Causes field splitting to be performed on unquoted parameter expansions. +Note that this option has nothing to do with word splitting. +(See noderef(Parameter Expansion).) +) +pindex(SINGLE_COMMAND) +cindex(single command) +pindex(INTERACTIVE, use of) +item(tt(SINGLE_COMMAND) (tt(-t), ksh: tt(-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 +tt(INTERACTIVE) option is explicitly set on the command line. +The value of this option cannot be changed anywhere other than the command line. +) +pindex(SINGLE_LINE_ZLE) +cindex(editor, single line mode) +item(tt(SINGLE_LINE_ZLE) (tt(-M)))( +Use single-line command line editing instead of multi-line. +) +pindex(SUN_KEYBOARD_HACK) +cindex(sun keyboard, annoying) +cindex(annoying keyboard, sun) +item(tt(SUN_KEYBOARD_HACK) (tt(-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. +) +pindex(UNSET) +cindex(parameters, substituting unset) +cindex(unset parameters, substituting) +item(tt(UNSET) (tt(PLUS()u), ksh: tt(PLUS()u)))( +Treat unset parameters as if they were empty when substituting. +Otherwise they are treated as an error. +) +pindex(VERBOSE) +cindex(tracing, of input lines) +cindex(input, tracing) +item(tt(VERBOSE) (tt(-v), ksh: tt(-v)))( +Print shell input lines as they are read. +) +pindex(XTRACE) +cindex(tracing, of commands) +cindex(commands, tracing) +item(tt(XTRACE) (tt(-x), ksh: tt(-x)))( +Print commands and their arguments as they are executed. +) +pindex(ZLE) +cindex(editor, enabling) +cindex(enabling the editor) +item(tt(ZLE) (tt(-Z)))( +Use the zsh line editor. +) +enditem() +texinode(Option Aliases)(Single Letter Options)(Description of Options)(Options) +sect(Option Aliases) +cindex(options, aliases) +Some options have alternative names. These aliases are never used for +output, but can be used just like normal option names when specifying +options to the shell. + +startitem() +pindex(BRACE_EXPAND) +item(tt(BRACE_EXPAND))( +em(NO_)tt(IGNORE_BRACES) +(ksh and bash compatibility) +) +pindex(DOT_GLOB) +item(tt(DOT_GLOB))( +tt(GLOB_DOTS) +(bash compatibility) +) +pindex(HASH_ALL) +item(tt(HASH_ALL))( +tt(HASH_CMDS) +(bash compatibility) +) +pindex(HIST_APPEND) +item(tt(HIST_APPEND))( +tt(APPEND_HISTORY) +(bash compatibility) +) +pindex(HIST_EXPAND) +item(tt(HIST_EXPAND))( +tt(BANG_HIST) +(bash compatibility) +) +pindex(LOG) +item(tt(LOG))( +em(NO_)tt(HIST_NO_FUNCTIONS) +(ksh compatibility) +) +pindex(MAIL_WARN) +item(tt(MAIL_WARN))( +tt(MAIL_WARNING) +(bash compatibility) +) +pindex(ONE_CMD) +item(tt(ONE_CMD))( +tt(SINGLE_COMMAND) +(bash compatibility) +) +pindex(PHYSICAL) +item(tt(PHYSICAL))( +tt(CHASE_LINKS) +(ksh and bash compatibility) +) +pindex(PROMPT_VARS) +item(tt(PROMPT_VARS))( +tt(PROMPT_SUBST) +(bash compatibility) +) +pindex(STDIN) +item(tt(STDIN))( +tt(SHIN_STDIN) +(ksh compatibility) +) +pindex(TRACK_ALL) +item(tt(TRACK_ALL))( +tt(HASH_CMDS) +(ksh compatibility) +) +enditem() +texinode(Single Letter Options)()(Option Aliases)(Options) +sect(Single Letter Options) +cindex(options, single letter) +cindex(single letter options) +subsect(Default set) +startsitem() +sitem(tt(-0))(CORRECT) +sitem(tt(-1))(PRINT_EXIT_VALUE) +sitem(tt(-2))(em(NO_)BAD_PATTERN) +sitem(tt(-3))(em(NO_)NOMATCH) +sitem(tt(-4))(GLOB_DOTS) +sitem(tt(-5))(NOTIFY) +sitem(tt(-6))(BG_NICE) +sitem(tt(-7))(IGNORE_EOF) +sitem(tt(-8))(MARK_DIRS) +sitem(tt(-9))(AUTO_LIST) +sitem(tt(-B))(em(NO_)BEEP) +sitem(tt(-C))(em(NO_)CLOBBER) +sitem(tt(-D))(PUSHD_TO_HOME) +sitem(tt(-E))(PUSHD_SILENT) +sitem(tt(-F))(em(NO_)GLOB) +sitem(tt(-G))(NULL_GLOB) +sitem(tt(-H))(RM_STAR_SILENT) +sitem(tt(-I))(IGNORE_BRACES) +sitem(tt(-J))(AUTO_CD) +sitem(tt(-K))(em(NO_)BANG_HIST) +sitem(tt(-L))(SUN_KEYBOARD_HACK) +sitem(tt(-M))(SINGLE_LINE_ZLE) +sitem(tt(-N))(AUTO_PUSHD) +sitem(tt(-O))(CORRECT_ALL) +sitem(tt(-P))(RC_EXPAND_PARAM) +sitem(tt(-Q))(PATH_DIRS) +sitem(tt(-R))(LONG_LIST_JOBS) +sitem(tt(-S))(REC_EXACT) +sitem(tt(-T))(CDABLE_VARS) +sitem(tt(-U))(MAIL_WARNING) +sitem(tt(-V))(em(NO_)PROMPT_CR) +sitem(tt(-W))(AUTO_RESUME) +sitem(tt(-X))(LIST_TYPES) +sitem(tt(-Y))(MENU_COMPLETE) +sitem(tt(-Z))(ZLE) +sitem(tt(-a))(ALL_EXPORT) +sitem(tt(-e))(ERR_EXIT) +sitem(tt(-f))(em(NO_)RCS) +sitem(tt(-g))(HIST_IGNORE_SPACE) +sitem(tt(-h))(HIST_IGNORE_DUPS) +sitem(tt(-i))(INTERACTIVE) +sitem(tt(-k))(INTERACTIVE_COMMENTS) +sitem(tt(-l))(LOGIN) +sitem(tt(-m))(MONITOR) +sitem(tt(-n))(em(NO_)EXEC) +sitem(tt(-p))(PRIVILEGED) +sitem(tt(-r))(RESTRICTED) +sitem(tt(-s))(SHIN_STDIN) +sitem(tt(-t))(SINGLE_COMMAND) +sitem(tt(-u))(em(NO_)UNSET) +sitem(tt(-v))(VERBOSE) +sitem(tt(-w))(CHASE_LINKS) +sitem(tt(-x))(XTRACE) +sitem(tt(-y))(SH_WORD_SPLIT) +endsitem() +subsect(sh/ksh emulation set) +startsitem() +sitem(tt(-C))(em(NO_)CLOBBER) +sitem(tt(-X))(MARK_DIRS) +sitem(tt(-a))(ALL_EXPORT) +sitem(tt(-b))(NOTIFY) +sitem(tt(-e))(ERR_EXIT) +sitem(tt(-f))(em(NO_)GLOB) +sitem(tt(-i))(INTERACTIVE) +sitem(tt(-l))(LOGIN) +sitem(tt(-m))(MONITOR) +sitem(tt(-n))(em(NO_)EXEC) +sitem(tt(-p))(PRIVILEGED) +sitem(tt(-r))(RESTRICTED) +sitem(tt(-s))(SHIN_STDIN) +sitem(tt(-t))(SINGLE_COMMAND) +sitem(tt(-u))(em(NO_)UNSET) +sitem(tt(-v))(VERBOSE) +sitem(tt(-x))(XTRACE) +endsitem() +subsect(Also note) +startsitem() +sitem(tt(-A))(Used by tt(set) for setting arrays) +sitem(tt(-c))(Used on the command line to specify a single command) +sitem(tt(-m))(Used by tt(setopt) for pattern-matching option setting) +sitem(tt(-o))(Used in all places to allow use of long option names) +sitem(tt(-s))(Used by tt(set) to sort positional parameters) +endsitem() diff --git a/Doc/Zsh/params.yo b/Doc/Zsh/params.yo new file mode 100644 index 000000000..4c25a18ef --- /dev/null +++ b/Doc/Zsh/params.yo @@ -0,0 +1,812 @@ +texinode(Parameters)(Options)(Expansion)(Top) +chapter(Parameters) +cindex(parameters) +sect(Description) +A parameter has a name, a value, and a number of attributes. +A name may be any sequence of alphanumeric +characters and underscores, or the single characters +`tt(*)', `tt(@)', `tt(#)', `tt(?)', `tt(-)', `tt($)', or `tt(!)'. +The value may be a em(scalar) (a string), +an integer, or an array. +To assign a scalar or integer value to a parameter, +use the tt(typeset) builtin. +findex(typeset, use of) +To assign an array value, use `tt(set -A) var(name) var(value) ...'. +findex(set, use of) +The value of a parameter may also be assigned by writing: + +nofill(var(name)tt(=)var(value)) + +If the integer attribute, tt(-i), is set for var(name), +the var(value) is subject to arithmetic evaluation. + +In the parameter lists, the mark `' indicates that the parameter is special. +Special parameters cannot have their type changed, and they stay special even +if unset. `' indicates that the parameter does not exist when the shell +initialises in tt(sh) or tt(ksh) emulation mode. +startmenu() +menu(Local Parameters) +menu(Array Parameters) +menu(Positional Parameters) +menu(Parameters Set By The Shell) +menu(Parameters Used By The Shell) +endmenu() +texinode(Local Parameters)(Array Parameters)()(Parameters) +sect(Local Parameters) +Shell function executions delimit scopes for shell parameters. +(Parameters are dynamically scoped.) The tt(typeset) builtin, and its +alternative forms tt(declare), tt(integer), tt(local) and tt(readonly) +(but not tt(export)), can be used to declare a parameter as being local +to the innermost scope. + +When a parameter is read or assigned to, the +innermost existing parameter of that name is used. (That is, the +local parameter hides any less-local parameter.) However, assigning +to a non-existent parameter, or declaring a new parameter with tt(export), +causes it to be created in the em(outer)most scope. + +Local parameters disappear when their scope ends. +tt(unset) can be used to delete a parameter while it is still in scope; this +will reveal the next outer parameter of the same name. However, em(special) +parameters are still special when unset. +texinode(Array Parameters)(Positional Parameters)(Local Parameters)(Parameters) +sect(Array Parameters) +The value of an array parameter may be assigned by writing: + +nofill(var(name)tt(=LPAR())var(value) ...tt(RPAR())) + +Individual elements of an array may be selected using a +subscript. A subscript of the form `tt([)var(exp)tt(])' +selects the single element var(exp), where var(exp) is +an arithmetic expression which will be subject to arithmetic +expansion as if it were surrounded by `tt($LPAR()LPAR())...tt(RPAR()RPAR())'. +The elements are numbered beginning with 1 unless the +tt(KSH_ARRAYS) option is set when they are numbered from zero. +pindex(KSH_ARRAYS, use of) + +A subscript of the form `tt([*])' or `tt([@])' evaluates to all +elements of an array; there is no difference between the two +except when they appear within double quotes. +`tt("$foo[*]")' evaluates to `tt("$foo[1] $foo[2] )...tt(")', while +`tt("$foo[@]")' evaluates to `tt("$foo[1]" "$foo[2]")', etc. + +A subscript of the form `tt([)var(exp1)tt(,)var(exp2)tt(])' +selects all elements in the range var(exp1) to var(exp2), +inclusive. +If one of the subscripts evaluates to a negative number, +say tt(-)var(n), then the var(n)th element from the end +of the array is used. Thus `tt($foo[-3])' is the third element +from the end of the array tt(foo), and +`tt($foo[1,-1])' is the same as `tt($foo[*])'. + +Subscripting may also be performed on non-array values, in which +case the subscripts specify a substring to be extracted. +For example, if tt(FOO) is set to `tt(foobar)', then +`tt(echo $FOO[2,5])' prints `tt(ooba)'. + +Subscripts may be used inside braces used to delimit a parameter name, thus +`tt(${foo[2]})' is equivalent to `tt($foo[2])'. If the tt(KSH_ARRAYS) +option is set, the braced form is the only one that will +work, the subscript otherwise not being treated specially. + +If a subscript is used on the left side of an assignment the selected +range is replaced by the expression on the right side. + +If the opening bracket or the comma is directly followed by an opening +parentheses the string up to the matching closing one is considered to +be a list of flags. The flags currently understood are: + +startitem() +item(tt(e))( +this option has no effect and retained for backward compatibility only. +) +item(tt(w))( +if the parameter subscripted is a scalar than this flag makes +subscription work on a per-word basis instead of characters. +) +item(tt(s:)var(string)tt(:))( +this gives the var(string) that separates words (for use with the +tt(w) flag). +) +item(tt(p))( +Recognize the same escape sequences as the tt(print) builtin in +the string argument of a subsequent `tt(s)' flag. +) +item(tt(f))( +if the parameter subscripted is a scalar than this flag makes +subscription work on a per-line basis instead of characters. +This is a shorthand for `tt(pws:\n:)'. +) +item(tt(r))( +if this flag is given the var(exp) is taken as a pattern and the +result is the first matching array element, substring or word (if the +parameter is an array, if it is a scalar, or if it is a scalar and the +`tt(w)' flag is given, respectively); note that this is like giving a +number: `tt($foo[(r))var(??)tt(,3])' and `tt($foo[(r))var(??)tt(,(r)f*])' work. +) +item(tt(R))( +like `tt(r)', but gives the last match. +) +item(tt(i))( +like `tt(r)', but gives the index of the match instead; this may not +be combined with a second argument. +) +item(tt(I))( +like `tt(i), but gives the index of the last match. +) +item(tt(n:)var(expr)tt(:))( +if combined with `tt(r)', `tt(R)', `tt(i)' or `tt(I)', makes them give +the var(n)th or var(n)th last match (if var(expr) evaluates to +var(n)). +) +enditem() +texinode(Positional Parameters)(Parameters Set By The Shell)(Array Parameters)(Parameters) +sect(Positional Parameters) +Positional parameters are set by the shell on invocation, +by the tt(set) builtin, or by direct assignment. +The parameter var(n), where var(n) is a number, +is the var(n)th positional parameter. +The parameters tt(*), tt(@) and tt(argv) are +arrays containing all the positional parameters; +thus `tt($argv[)var(n)tt(])', etc., is equivalent to simply `tt($)var(n)'. + +texinode(Parameters Set By The Shell)(Parameters Used By The Shell)(Positional Parameters)(Parameters) +sect(Parameters Set By The Shell) +The following parameters are automatically set by the shell: + +startitem() +vindex(!) +item(tt(!) )( +The process ID of the last background command invoked. +) +vindex(#) +item(tt(#) )( +The number of positional parameters in decimal. +) +vindex(ARGC) +item(tt(ARGC) )( +Same as tt(#). +) +vindex($) +item(tt($) )( +The process ID of this shell. +) +vindex(-) +item(tt(-) )( +Flags supplied to the shell on invocation or by the tt(set) +or tt(setopt) commands. +) +vindex(*) +item(tt(*) )( +An array containing the positional parameters. +) +vindex(argv) +item(tt(argv) )( +Same as tt(*). +) +vindex(@) +item(tt(@) )( +Same as tt(argv[@]). +) +vindex(?) +item(tt(?) )( +The exit value returned by the last command. +) +vindex(0) +item(tt(0) )( +The name used to invoke the current shell. If the tt(FUNCTION_ARGZERO) option +is set, this is set temporarily within a shell function to the name of the +function, and within a sourced script to the name of the script. +) +vindex(status) +item(tt(status) )( +Same as tt(?). +) +vindex(_) +item(tt(_) )( +The last argument of the previous command. +Also, this parameter is set in the environment of every command +executed to the full pathname of the command. +) +vindex(EGID) +item(tt(EGID) )( +The effective group ID of the shell process. If you have sufficient +privileges, you may change the effective group ID of the shell +process by assigning to this parameter. Also (assuming sufficient +privileges), you may start a single command with a different +effective group ID by `tt(LPAR()EGID=)var(gid)tt(; command+RPAR())' +) +vindex(EUID) +item(tt(EUID) )( +The effective user ID of the shell process. If you have sufficient +privileges, you may change the effective user ID of the shell process +by assigning to this parameter. Also (assuming sufficient privileges), +you may start a single command with a different +effective user ID by `tt(LPAR()EUID=)var(uid)tt(; command+RPAR())' +) +vindex(ERRNO) +item(tt(ERRNO) )( +The value of errno (see manref(errno)(3)) +as set by the most recently failed system call. +This value is system dependent and is intended for debugging +purposes. +) +vindex(GID) +item(tt(GID) )( +The real group ID of the shell process. If you have sufficient privileges, +you may change the group ID of the shell process by assigning to this +parameter. Also (assuming sufficient privileges), you may start a single +command under a different +group ID by `tt(LPAR()GID=)var(gid)tt(; command+RPAR())' +) +vindex(HOST) +item(tt(HOST))( +The current hostname. +) +vindex(LINENO) +item(tt(LINENO) )( +The line number of the current line within the current script +being executed. +) +vindex(LOGNAME) +item(tt(LOGNAME))( +If the corresponding variable is not set in the environment of the +shell, it is initialized to the login name corresponding to the +current login session. This parameter is exported by default but +this can be disabled using the tt(typeset) builtin. +) +vindex(MACHTYPE) +item(tt(MACHTYPE))( +The machine type (microprocessor class or machine model), +as determined at compile time. +) +vindex(OLDPWD) +item(tt(OLDPWD))( +The previous working directory. This is set when the shell initialises +and whenever the directory changes. +) +vindex(OPTARG) +item(tt(OPTARG) )( +The value of the last option argument processed by the tt(getopts) +command. +) +vindex(OPTIND) +item(tt(OPTIND) )( +The index of the last option argument processed by the tt(getopts) +command. +) +vindex(OSTYPE) +item(tt(OSTYPE))( +The operating system, as determined at compile time. +) +vindex(PPID) +item(tt(PPID) )( +The process ID of the parent of the shell. +) +vindex(PWD) +item(tt(PWD))( +The present working directory. This is set when the shell initialises +and whenever the directory changes. +) +vindex(RANDOM) +item(tt(RANDOM) )( +A random integer from 0 to 32767, newly generated each time +this parameter is referenced. The random number generator +can be seeded by assigning a numeric value to tt(RANDOM). +) +vindex(SECONDS) +item(tt(SECONDS) )( +The number of seconds since shell invocation. If this parameter +is assigned a value, then the value returned upon reference +will be the value that was assigned plus the number of seconds +since the assignment. +) +vindex(SHLVL) +item(tt(SHLVL) )( +Incremented by one each time a new shell is started. +) +vindex(signals) +item(tt(signals))( +An array containing the names of the signals. +) +vindex(TTY) +item(tt(TTY))( +The name of the tty associated with the shell, if any. +) +vindex(TTYIDLE) +item(tt(TTYIDLE) )( +The idle time of the tty associated with the shell in seconds or -1 if there +is no such tty. +) +vindex(UID) +item(tt(UID) )( +The real user ID of the shell process. If you have sufficient privileges, +you may change the user ID of the shell by assigning to this parameter. +Also (assuming sufficient privileges), you may start a single command +under a different +user ID by `tt(LPAR()UID=)var(uid)tt(; command+RPAR())' +) +vindex(USERNAME) +item(tt(USERNAME) )( +The username corresponding to the real user ID of the shell process. If you +have sufficient privileges, you may change the username (and also the +user ID and group ID) of the shell by assigning to this parameter. +Also (assuming sufficient privileges), you may start a single command +under a different username (and user ID and group ID) +by `tt(LPAR()USERNAME=)var(username)tt(; command+RPAR())' +) +vindex(VENDOR) +item(tt(VENDOR))( +The vendor, as determined at compile time. +) +vindex(ZSH_NAME) +item(tt(ZSH_NAME))( +Expands to the basename of the command used to invoke this instance +of zsh. +) +vindex(ZSH_VERSION) +item(tt(ZSH_VERSION))( +The version number of this zsh. +) +enditem() +texinode(Parameters Used By The Shell)()(Parameters Set By The Shell)(Parameters) +sect(Parameters Used By The Shell) +The following parameters are used by the shell: + +startitem() +vindex(ARGV0) +item(tt(ARGV0))( +If exported, its value is used as tt(argv[0]) of external commands. +Usually used in constructs like `tt(ARGV0=emacs nethack)'. +) +vindex(BAUD) +item(tt(BAUD))( +The baud rate of the current connection. Used by the line editor +update mechanism to compensate for a slow terminal by delaying +updates until necessary. This may be profitably set to a lower value +in some circumstances, e.g. +for slow modems dialing into a communications server which is connected +to a host via a fast link; in this case, this variable +would be set by default to the speed of the fast link, and not +the modem. +This parameter should be set to the baud +rate of the slowest part of the link for best performance. The compensation +mechanism can be turned off by setting the variable to zero. +) +vindex(cdpath) +vindex(CDPATH) +item(tt(cdpath) (tt(CDPATH) ))( +An array (colon-separated list) +of directories specifying the search path for the tt(cd) command. +) +vindex(COLUMNS) +item(tt(COLUMNS) )( +The number of columns for this terminal session. +Used for printing select lists and for the line editor. +) +vindex(DIRSTACKSIZE) +item(tt(DIRSTACKSIZE))( +The maximum size of the directory stack. If the +stack gets larger than this, it will be truncated automatically. +This is useful with the tt(AUTO_PUSHD) option. +pindex(AUTO_PUSHD, use of) +) +vindex(FCEDIT) +item(tt(FCEDIT))( +The default editor for the tt(fc) builtin. +) +vindex(fignore) +vindex(FIGNORE) +item(tt(fignore) (tt(FIGNORE) ))( +An array (colon separated list) +containing the suffixes of files to be ignored +during filename completion. However, if the completion generates only files +which would match if this variable would be ignored, than these files are +completed anyway. +) +vindex(fpath) +vindex(FPATH) +item(tt(fpath) (tt(FPATH) ))( +An array (colon separated list) +of directories specifying the search path for +function definitions. This path is searched when a function +with the tt(-u) attribute is referenced. If an executable +file is found, then it is read and executed in the current environment. +) +vindex(histchars) +item(tt(histchars) )( +Three characters used by the shell's history and lexical analysis +mechanism. The first character signals the start of a history +substitution (default `tt(!)'). The second character signals the +start of a quick history substitution (default `tt(^)'). The third +character is the comment character (default `tt(#)'). +) +vindex(HISTCHARS) +item(tt(HISTCHARS) )( +Same as tt(histchars). (Deprecated.) +) +vindex(HISTFILE) +item(tt(HISTFILE))( +The file to save the history in when an interactive shell exits. +If unset, the history is not saved. +) +vindex(HISTSIZE) +item(tt(HISTSIZE) )( +The maximum size of the history list. +) +vindex(HOME) +item(tt(HOME) )( +The default argument for the tt(cd) command. +) +vindex(IFS) +item(tt(IFS) )( +Internal field separators (by default space, tab, newline and NUL), that +are used to separate words which result from +command or parameter substitution and words read by +the tt(read) builtin. Any characters from the set space, tab and +newline that appear in the IFS are called em(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. +) +vindex(KEYTIMEOUT) +item(tt(KEYTIMEOUT))( +The time the shell waits, in hundredths of seconds, for another key to +be pressed when reading bound multi-character sequences. +) +vindex(LANG) +item(tt(LANG) )( +This variable determines the locale category for any category not +specifically selected via a variable starting with `tt(LC_)'. +) +vindex(LC_ALL) +item(tt(LC_ALL) )( +This variable overrides the value of the `tt(LANG)' variable and the value +of any of the other variables starting with `tt(LC_)'. +) +vindex(LC_COLLATE) +item(tt(LC_COLLATE) )( +This variable determines the locale category for character collation +information within ranges in glob brackets and for sorting. +) +vindex(LC_CTYPE) +item(tt(LC_CTYPE) )( +This variable determines the locale category for character handling +functions. +) +vindex(LC_MESSAGES) +item(tt(LC_MESSAGES) )( +This variable determines the language in which messages should be +written. Note that zsh does not use message catalogs. +) +vindex(LC_TIME) +item(tt(LC_TIME) )( +This variable determines the locale category for date and time +formatting in prompt escape sequences. +) +vindex(LINES) +item(tt(LINES) )( +The number of lines for this terminal session. +Used for printing select lists and for the line editor. +) +vindex(LISTMAX) +item(tt(LISTMAX))( +In the line editor, the number of filenames to list without asking first. +If set to zero, the shell asks only if the top of the listing would scroll +off the screen. +) +vindex(LOGCHECK) +item(tt(LOGCHECK))( +The interval in seconds between checks for login/logout activity +using the tt(watch) parameter. +) +vindex(MAIL) +item(tt(MAIL))( +If this parameter is set and tt(mailpath) is not set, +the shell looks for mail in the specified file. +) +vindex(MAILCHECK) +item(tt(MAILCHECK))( +The interval in seconds between checks for new mail. +) +vindex(mailpath) +vindex(MAILPATH) +item(tt(mailpath) (tt(MAILPATH) ))( +An array (colon-separated list) of filenames to check for +new mail. Each filename can be followed by a `tt(?)' and a +message that will be printed. The message will undergo +parameter expansion, command substitution and arithmetic +substitution with the variable tt($_) defined as the name +of the file that has changed. The default message is +`tt(You have new mail)'. If an element is a directory +instead of a file the shell will recursively check every +file in every subdirectory of the element. +) +vindex(manpath) +vindex(MANPATH) +item(tt(manpath) (tt(MANPATH) ))( +An array (colon-separated list) +whose value is not used by the shell. The tt(manpath) +array can be useful, however, since setting it also sets +tt(MANPATH), and vice versa. +) +vindex(module_path) +vindex(MODULE_PATH) +item(tt(module_path) (tt(MODULE_PATH) ))( +An array (colon-separated list) +of directories that tt(zmodload) +searches for dynamically loadable modules. +This is initialised to a standard pathname, +usually `tt(/usr/local/lib/zsh/$ZSH_VERSION)'. +(The `tt(/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. +) +vindex(NULLCMD) +cindex(null command style) +cindex(csh, null command style) +cindex(ksh, null command style) +item(tt(NULLCMD) )( +The command name to assume if a redirection is specified +with no command. Defaults to tt(cat). For bf(sh)/bf(ksh) +behavior, change this to tt(:). For bf(csh)-like +behavior, unset this parameter; the shell will print an +error message if null commands are entered. +) +vindex(path) +vindex(PATH) +item(tt(path) (tt(PATH) ))( +An array (colon-separated list) +of directories to search for commands. +When this parameter is set, each directory is scanned +and all files found are put in a hash table. +) +vindex(POSTEDIT) +item(tt(POSTEDIT) )( +This string is output whenever the line editor exits. +It usually contains termcap strings to reset the terminal. +) +vindex(PS1) +item(tt(PS1) )( +The primary prompt string, printed before a command is read. +the default is `tt(%m%# )'. It undergoes a special form of expansion +before being displayed; see noderef(Prompt Expansion). +) +vindex(PS2) +item(tt(PS2) )( +The secondary prompt, printed when the shell needs more information +to complete a command. +It is expanded in the same way as tt(PS1). +The default is `tt(%_> )', which displays any shell constructs or quotation +marks which are currently being processed. +) +vindex(PS3) +item(tt(PS3) )( +Selection prompt used within a tt(select) loop. +It is expanded in the same way as tt(PS1). +The default is `tt(?# )'. +) +vindex(PS4) +item(tt(PS4) )( +The execution trace prompt. Default is `tt(PLUS() )'. +) +vindex(PROMPT) +xitem(tt(PROMPT) ) +vindex(PROMPT2) +xitem(tt(PROMPT2) ) +vindex(PROMPT3) +xitem(tt(PROMPT3) ) +vindex(PROMPT4) +item(tt(PROMPT4) )( +Same as tt(PS1), tt(PS2), tt(PS3) and tt(PS4), +respectively. +) +vindex(psvar) +vindex(PSVAR) +item(tt(psvar) (tt(PSVAR) ))( +An array (colon-separated list) whose first nine values can be used in +tt(PROMPT) strings. Setting tt(psvar) also sets tt(PSVAR), and +vice versa. +) +vindex(prompt) +item(tt(prompt) )( +Same as tt(PS1). +) +vindex(READNULLCMD) +item(tt(READNULLCMD) )( +The command name to assume if a single input redirection +is specified with no command. Defaults to tt(more). +) +vindex(REPORTTIME) +item(tt(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. +) +vindex(RPROMPT) +xitem(tt(RPROMPT) ) +vindex(RPS1) +item(tt(RPS1) )( +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 tt(SINGLELINEZLE) option is set. +It is expanded in the same way as tt(PS1). +) +vindex(SAVEHIST) +item(tt(SAVEHIST))( +The maximum number of history events to save in the history file. +) +vindex(SPROMPT) +item(tt(SPROMPT) )( +The prompt used for spelling correction. The sequence +`tt(%R)' expands to the string which presumably needs spelling +correction, and `tt(%r)' expands to the proposed correction. +All other prompt escapes are also allowed. +) +vindex(STTY) +item(tt(STTY))( +If this parameter is set in a command's environment, the shell runs the +tt(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 tt(fg) or tt(wait) builtins it will +see the modes specified by tt(STTY), as if it were not suspended. This +(intentionally) does not apply if the command is continued via `tt(kill -CONT)'. +tt(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 tt(STTY) should not be used for window size specifications; these +will not be local to the command. +) +vindex(TERM) +item(tt(TERM) )( +The type of terminal in use. This is used when looking up termcap sequences. +) +vindex(TIMEFMT) +item(tt(TIMEFMT))( +The format of process time reports with the tt(time) keyword. +The default is `tt(%E real %U user %S system %P %J)'. +Recognizes the following escape sequences: + +startsitem() +sitem(tt(%%))(A `tt(%)'.) +sitem(tt(%U))(CPU seconds spent in user mode.) +sitem(tt(%S))(CPU seconds spent in kernel mode.) +sitem(tt(%E))(Elapsed time in seconds.) +sitem(tt(%P))(The CPU percentage, computed as (tt(%U)PLUS()tt(%S))/tt(%E).) +sitem(tt(%J))(The name of this job.) +endsitem() + +A star may be inserted between the percent sign and flags printing time. +This cause the time to be printed in +`var(hh)tt(:)var(mm)tt(:)var(ss)tt(.)var(ttt)' +format (hours and minutes are only printed if they are not zero). +) +vindex(TMOUT) +item(tt(TMOUT))( +If this parameter is nonzero, the shell will receive an tt(ALRM) +signal if a command is not entered within the specified number of +seconds after issuing a prompt. If there is a trap on tt(SIGALRM), it +will be executed and a new alarm is scheduled using the value of the +tt(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 +tt(TMOUT) parameter, zsh terminates. Otherwise a new alarm is +scheduled to tt(TMOUT) seconds after the last keypress. +) +vindex(TMPPREFIX) +item(tt(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 `tt(/tmp/zsh)'. +) +vindex(watch) +vindex(WATCH) +item(tt(watch) (tt(WATCH) ))( +An array (colon-separated list) of login/logout events to report. +If it contains the single word `tt(all)', then all login/logout events +are reported. If it contains the single word `tt(notme)', then all +events are reported as with `tt(all)' except tt($USERNAME). +An entry in this list may consist of a username, +an `tt(@)' followed by a remote hostname, +and a `tt(%)' followed by a line (tty). +Any or all of these components may be present in an entry; +if a login/logout event matches all of them, +it is reported. +) +vindex(WATCHFMT) +item(tt(WATCHFMT))( +The format of login/logout reports if the tt(watch) parameter is set. +Default is `tt(%n has %a %l from %m)'. +Recognizes the following escape sequences: + +startitem() +item(tt(%n))( +The name of the user that logged in/out. +) +item(tt(%a))( +The observed action, i.e. "logged on" or "logged off". +) +item(tt(%l))( +The line (tty) the user is logged in on. +) +item(tt(%M))( +The full hostname of the remote host. +) +item(tt(%m))( +The hostname up to the first `tt(.)'. If only the +IP address is available or the utmp field contains +the name of an X-windows display, the whole name is printed. + +em(NOTE:) +The `tt(%m)' and `tt(%M)' escapes will work only if there is a host name +field in the utmp on your machine. Otherwise they are +treated as ordinary strings. +) +item(tt(%S) LPAR()tt(%s)RPAR())( +Start (stop) standout mode. +) +item(tt(%U) LPAR()tt(%u)RPAR())( +Start (stop) underline mode. +) +item(tt(%B) LPAR()tt(%b)RPAR())( +Start (stop) boldface mode. +) +xitem(tt(%t)) +item(tt(%@))( +The time, in 12-hour, am/pm format. +) +item(tt(%T))( +The time, in 24-hour format. +) +item(tt(%w))( +The date in `var(day)tt(-)var(dd)' format. +) +item(tt(%W))( +The date in `var(mm)tt(/)var(dd)tt(/)var(yy)' format. +) +item(tt(%D))( +The date in `var(yy)tt(-)var(mm)tt(-)var(dd)' format. +) +item(tt(%LPAR())var(x)tt(:)var(true-text)tt(:)var(false-text)tt(RPAR()))( +Specifies a ternary expression. +The character following the var(x) is +arbitrary; the same character is used to separate the text +for the "true" result from that for the "false" result. +Both the separator and the right parenthesis may be escaped +with a backslash. +Ternary expressions may be nested. + +The test character var(x) may be any one of `tt(l)', `tt(n)', `tt(m)' +or `tt(M)', which indicate a `true' result if the corresponding +escape sequence would return a non-empty value; or it may be `tt(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 var(true-text) +is formatted according to the rules above and printed, +and the var(false-text) is skipped. +If `false', the var(true-text) is skipped and the var(false-text) +is formatted and printed. +Either or both of the branches may be empty, but +both separators must be present in any case. +) +enditem() +) +vindex(WORDCHARS) +item(tt(WORDCHARS) )( +A list of non-alphanumeric characters considered part of a word +by the line editor. +) +vindex(ZDOTDIR) +item(tt(ZDOTDIR))( +The directory to search for shell startup files (.zshrc, etc), +if not tt($HOME). +) +enditem() diff --git a/Doc/Zsh/prompt.yo b/Doc/Zsh/prompt.yo new file mode 100644 index 000000000..e1628da86 --- /dev/null +++ b/Doc/Zsh/prompt.yo @@ -0,0 +1,209 @@ +texinode(Prompt Expansion)(Restricted Shell)(Compatibility)(Top) +chapter(Prompt Expansion) +ifzman(\ +sect(Prompt Expansion) +)\ +Prompt sequences undergo a special form of expansion. This type of expansion +is also available using the tt(-P) option to the tt(print) builtin. + +pindex(PROMPT_SUBST, use of) +If the tt(PROMPT_SUBST) option is set, the prompt string is first subjected to +em(parameter expansion), +em(command substitution) and +em(arithmetic expansion). +See +ifzman(\ +zmanref(zshexpn). +)\ +ifnzman(\ +noderef(Expansion). +)\ + +Certain escape sequences may be recognised in the prompt string. + +pindex(PROMPT_BANG, use of) +If the tt(PROMPT_BANG) option is set, a `tt(!)' in the prompt is replaced +by the current history event number. A literal `tt(!)' may then be +represented as `tt(!!)'. + +pindex(PROMPT_PERCENT, use of) +If the tt(PROMPT_PERCENT) option is set, certain escape sequences that +start with `tt(%)' are expanded. +Some escapes take an optional integer argument, which +should appear between the `tt(%)' and the next character of the +sequence. The following escape sequences are recognized: + +startitem() +item(tt(%%))( +A `tt(%)'. +) +item(tt(%RPAR()))( +A `tt(RPAR())'. +) +xitem(tt(%d)) +item(tt(%/))( +Present working directory (tt($PWD)). +) +item(tt(%~))( +tt($PWD). +If it has a named directory as its prefix, that part is replaced +by a `tt(~)' followed by the name of the directory. +If it starts with tt($HOME), that part is +replaced by a `tt(~)'. +) +xitem(tt(%c)) +xitem(tt(%.)) +item(tt(%C))( +Trailing component of tt($PWD). +An integer may follow the `tt(%)' to get more than one component. +Unless `tt(%C)' is used, tilde contraction is performed first. +) +xitem(tt(%h)) +item(tt(%!))( +Current history event number. +) +item(tt(%L))( +The current value of tt($SHLVL). +) +item(tt(%M))( +The full machine hostname. +) +item(tt(%m))( +The hostname up to the first `tt(.)'. +An integer may follow the `tt(%)' to specify +how many components of the hostname are desired. +) +item(tt(%S) LPAR()tt(%s)RPAR())( +Start (stop) standout mode. +) +item(tt(%U) LPAR()tt(%u)RPAR())( +Start (stop) underline mode. +) +item(tt(%B) LPAR()tt(%b)RPAR())( +Start (stop) boldface mode. +) +xitem(tt(%t)) +item(tt(%@))( +Current time of day, in 12-hour, am/pm format. +) +item(tt(%T))( +Current time of day, in 24-hour format. +) +item(tt(%*))( +Current time of day in 24-hour format, with seconds. +) +item(tt(%n))( +tt($USERNAME). +) +item(tt(%w))( +The date in var(day)tt(-)var(dd) format. +) +item(tt(%W))( +The date in var(mm)tt(/)var(dd)tt(/)var(yy) format. +) +item(tt(%D))( +The date in var(yy)tt(-)var(mm)tt(-)var(dd) format. +) +item(tt(%D{)var(string)tt(}))( +var(string) is formatted using the tt(strftime) function. +See manref(strftime)(3) for more details. Three additional codes are +available: tt(%f) prints the day of the month, like tt(%e) but +without any preceding space if the day is a single digit, and +tt(%K)/tt(%L) correspond to tt(%k)/tt(%l) for the hour of the day +(24/12 hour clock) in the same way. +) +item(tt(%l))( +The line (tty) the user is logged in on. +) +item(tt(%?))( +The return code of the last command executed just before the prompt. +) +item(tt(%_))( +The status of the parser, i.e. the shell constructs (like `tt(if)' and +`tt(for)') that have been started on the command line. If given an integer +number that many strings will be printed; zero or no integer means +print as many as there are. +) +item(tt(%E))( +Clears to end of line. +) +item(tt(%#))( +A `tt(#)' if the shell is running with privileges, a `tt(%)' if not. +Equivalent to `tt(%(!.#.%%))'. +The definition of `privileged', for these purposes, is that either the +effective user ID is zero, or, if POSIX.1e capabilities are supported, that +at least one capability is raised in either the Effective or Inheritable +capability vectors. +) +item(tt(%v))( +vindex(psvar, use of) +The value of the first element of the tt(psvar) array parameter. Following +the `tt(%)' with an integer gives that element of the array. +) +item(tt(%{)...tt(%}))( +Include a string as a literal escape sequence. +The string within the braces should not change the cursor +position. Brace pairs can nest. +) +item(tt(%LPAR())var(x.true-text.false-text)tt(RPAR()))( +Specifies a ternary expression. The character following the var(x) is +arbitrary; the same character is used to separate the text for the +`true' result from that for the `false' result. +This separator may not appear in the var(true-text), except as part of a +%-escape +sequence. A `tt(RPAR())' may appear in the var(false-text) as `tt(%RPAR())'. +var(true-text) +and var(false-text) may both contain arbitrarily-nested escape +sequences, including further ternary expressions. + +The left +parenthesis may be preceded or followed by a positive integer var(n), +which defaults to zero. The test character var(x) may be any of the +following: + +startsitem() +sxitem(tt(c)) +sxitem(tt(.)) +sitem(tt(~))(True if the current path, with prefix replacement, has at least var(n) elements.) +sxitem(tt(/)) +sitem(tt(C))(True if the current absolute path has at least var(n) elements.) +sitem(tt(t))(True if the time in minutes is equal to var(n).) +sitem(tt(T))(True if the time in hours is equal to var(n).) +sitem(tt(d))(True if the day of the month is equal to var(n).) +sitem(tt(D))(True if the month is equal to var(n) (January = 0).) +sitem(tt(w))(True if the day of the week is equal to var(n) (Sunday = 0).) +sitem(tt(?))(True if the exit status of the last command was var(n).) +sitem(tt(#))(True if the effective uid of the current process is var(n).) +sitem(tt(g))(True if the effective gid of the current process is var(n).) +sitem(tt(L))(True if the tt(SHLVL) parameter is at least var(n).) +sitem(tt(S))(True if the tt(SECONDS) parameter is at least var(n).) +sitem(tt(v))(True if the array tt(psvar) has at least var(n) elements.) +sitem(tt(_))(True if at least var(n) shell constructs were started.) +sitem(tt(!))(True if the shell is running with privileges.) +endsitem() +) +xitem(tt(%<)var(string)tt(<)) +xitem(tt(%>)var(string)tt(>)) +item(tt(%[)var(xstring)tt(]))( +Specifies truncation behaviour. +The third, deprecated, form is equivalent to `tt(%)var(xstringx)', +i.e. var(x) may be `tt(<)' or `tt(>)'. +The numeric argument, which in the third form may appear immediately +after the `tt([)', specifies the maximum permitted length of +the various strings that can be displayed in the prompt. If this +integer is zero, or missing, truncation is disabled. Truncation is +initially disabled. +The var(string) will be displayed in +place of the truncated portion of any string. + +The forms with `tt(<)' truncate at the left of the string, +and the forms with `tt(>)' truncate at the right of the string. +For example, if the current directory is `tt(/home/pike)', +the prompt `tt(%8<..<%/)' will expand to `tt(..e/pike)'. +In this string, the terminating character (`tt(<)', `tt(>)' or `tt(])'), +or in fact any character, may be quoted by a preceding `tt(\)'. +% escapes are em(not) recognised. +If the var(string) is longer than the specified truncation length, +it will appear in full, completely replacing the truncated string. +) +enditem() diff --git a/Doc/Zsh/redirect.yo b/Doc/Zsh/redirect.yo new file mode 100644 index 000000000..8955e67ac --- /dev/null +++ b/Doc/Zsh/redirect.yo @@ -0,0 +1,183 @@ +texinode(Redirection)(Command Execution)(Shell Grammar)(Top) +chapter(Redirection) +cindex(redirection) +ifzman(\ +sect(Redirection) +)\ +cindex(file descriptors) +cindex(descriptors, file) +If a command is followed by tt(&) +and job control is not active, +then the default standard input +for the command is the empty file tt(/dev/null). +Otherwise, the environment for the execution of a command contains the +file descriptors of the invoking shell as modified by +input/output specifications. + +The following may appear anywhere in a simple command +or may precede or follow a complex command. +Substitution occurs before var(word) or var(digit) +is used except as noted below. +If the result of substitution on var(word) +produces more than one filename, +redirection occurs for each +separate filename in turn. + +startitem() +item(tt(<) var(word))( +Open file var(word) for reading as standard input. +) +item(tt(<>) var(word))( +Open file var(word) for reading and writing as standard input. +If the file does not exist then it is created. +) +item(tt(>) var(word))( +Open file var(word) for writing as standard output. +If the file does not exist then it is created. +If the file exists, and the tt(CLOBBER) option is unset, +this causes an error; +otherwise, it is truncated to zero length. +) +xitem(tt(>|) var(word)) +item(tt(>!) var(word))( +Same as tt(>), except that the file is truncated to zero length +if it exists, even if tt(CLOBBER) is unset. +) +item(tt(>>) var(word))( +Open file var(word) for writing in append mode as standard output. +If the file does not exist, and the tt(CLOBBER) +option is unset, this causes an error; +otherwise, the file is created. +) +xitem(tt(>>|) var(word)) +item(tt(>>!) var(word))( +Same as tt(>>), except that the file is created if it does not +exist, even if tt(CLOBBER) is unset. +) +item(tt(<<)[tt(-)] var(word))( +The shell input is read up to a line that is the same as +var(word), or to an end-of-file. +No parameter substitution, command substitution or +filename generation is performed on var(word). +The resulting document, called a +em(here-document), becomes the standard input. + +If any character of var(word) is quoted with +single or double quotes or a `tt(\)', +no interpretation is placed upon the characters of the document. +Otherwise, parameter and command substitution +occurs, `tt(\)' followed by a newline is removed, +and `tt(\)' must be used to quote the characters +`tt(\)', `tt($)', `tt(`)' and the first character of var(word). + +If tt(<<-) is used, then all leading +tabs are stripped from var(word) and from the document. +) +item(tt(<<<) var(word))( +Perform shell expansion on var(word) and pass the result +to standard input. This is known as a em(here-string). +) +xitem(tt(<&) var(digit)) +item(tt(>&) var(digit))( +The standard input/output is duplicated from file descriptor +var(digit) (see manref(dup)(2)). +) +xitem(tt(<& -)) +item(tt(>& -))( +Close the standard input/output. +) +xitem(tt(<& p)) +item(tt(>& p))( +The input/output from/to the coprocess is moved to the standard input/output. +) +item(tt(>&) var(word))( +Same as `tt(>) var(word) tt(2>&1)'. +) +item(tt(>>&) var(word))( +Same as `tt(>>) var(word) tt(2>&1)'. +) +enditem() + +If one of the above is preceded by a digit, then the file +descriptor referred to is that specified by the digit +instead of the default 0 or 1. +The order in which redirections are specified is significant. +The shell evaluates each redirection in terms of the +(em(file descriptor), em(file)) +association at the time of evaluation. +For example: + +nofill(... tt(1>)var(fname) tt(2>&1)) + +first associates file descriptor 1 with file var(fname). +It then associates file descriptor 2 with the file associated with file +descriptor 1 (that is, var(fname)). +If the order of redirections were reversed, +file descriptor 2 would be associated +with the terminal (assuming file descriptor 1 had been) +and then file descriptor 1 would be associated with file var(fname). +sect(Multios) +pindex(MULTIOS, use of) +If the user tries to open a file descriptor for writing more than once, +the shell opens the file descriptor as a pipe to a process that copies +its input to all the specified outputs, similar to bf(tee), +provided the tt(MULTIOS) option is set. Thus: + +nofill(tt(date >foo >bar)) + +writes the date to two files, named `tt(foo)' and `tt(bar)'. +Note that a pipe is an implicit redirection; thus + +nofill(tt(date >foo | cat)) + +writes the date to the file `tt(foo)', and also pipes it to cat. + +If the tt(MULTIOS) +option is set, the word after a redirection operator is also subjected +to filename generation (globbing). Thus + +nofill(tt(: > *)) + +will truncate all files in the current directory, +assuming there's at least one. (Without the tt(MULTIOS) +option, it would create an empty file called `tt(*)'.) +Similarly, you can do + +nofill(tt(echo exit 0 >> *.sh)) + +If the user tries to open a file descriptor for reading more than once, +the shell opens the file descriptor as a pipe to a process that copies +all the specified inputs to its output in the order +specified, similar to bf(cat), +provided the tt(MULTIOS) option is set. Thus + +nofill(tt(sort bar > baz)) + +when tt(MULTIOS) is unset will truncate bar, and write `tt(foo)' into baz. + +If a simple command consists of one or more redirection operators +and zero or more parameter assignments, but no command name, +the command named in the shell variable tt(READNULLCMD) is assumed. +(If tt(READNULLCMD) is empty or not set, `tt(cat)' is used.) Thus + +nofill(tt(< file)) + +prints the contents of tt(file). diff --git a/Doc/Zsh/restricted.yo b/Doc/Zsh/restricted.yo new file mode 100644 index 000000000..a61fd4955 --- /dev/null +++ b/Doc/Zsh/restricted.yo @@ -0,0 +1,44 @@ +texinode(Restricted Shell)(Expansion)(Prompt Expansion)(Top) +chapter(Restricted Shell) +ifzman(\ +sect(Restricted Shell) +)\ +cindex(restricted shell) +pindex(RESTRICTED) +When the basename of the command used to invoke zsh starts with the letter +`tt(r)' or the `tt(-r)' command line option is supplied at invocation, the +shell becomes restricted. Emulation mode is determined after stripping the +letter `tt(r)' from the invocation name. The following are disabled in +restricted mode: + +startitemize() +itemiz(changing directories with the tt(cd) builtin) +itemiz(changing or unsetting the tt(PATH), tt(path), tt(MODULE_PATH), +tt(module_path), tt(SHELL), tt(HISTFILE), tt(HISTSIZE), tt(GID), tt(EGID), +tt(UID), tt(EUID), tt(USERNAME), tt(LD_LIBRARY_PATH), +tt(LD_AOUT_LIBRARY_PATH), tt(LD_PRELOAD) and tt(LD_AOUT_PRELOAD) +parameters) +itemiz(specifying command names containing tt(/)) +itemiz(specifying command pathnames using tt(hash)) +itemiz(redirecting output to files) +itemiz(using the tt(exec) builtin command to replace the shell with another +command) +itemiz(using tt(jobs -Z) to overwrite the shell process' argument and +environment space) +itemiz(using the tt(ARGV0) parameter to override tt(argv[0]) for external +commands) +itemiz(turning off restricted mode with tt(set +r) or tt(unsetopt +RESTRICTED)) +itemiz(specifying modules to be loaded with an explicitly given +pathname containing slashes) +enditemize() + +These restrictions are enforced after processing the startup files. The +startup files should set up tt(PATH) to point to a directory of commands +which can be safely invoked in the restricted environment. They may also +add further restrictions by disabling selected builtins. + +Restricted mode can also be activated any time by setting the +tt(RESTRICTED) option. This immediately enables all the restrictions +described above even if the shell still have not processed all startup +files. diff --git a/Doc/Zsh/seealso.yo b/Doc/Zsh/seealso.yo new file mode 100644 index 000000000..8289e6628 --- /dev/null +++ b/Doc/Zsh/seealso.yo @@ -0,0 +1,25 @@ +texinode(See Also)()(The Zsh Web Page)(Introduction) +sect(See Also) +manref(sh)(1), +manref(csh)(1), +manref(tcsh)(1), +manref(rc)(1), +manref(bash)(1), +manref(ksh)(1)\ +ifzshone(\ +, +zmanref(zshbuiltins), +zmanref(zshcompctl), +zmanref(zshexpn), +zmanref(zshmisc), +zmanref(zshmodules), +zmanref(zshoptions), +zmanref(zshparam), +zmanref(zshzle)\ +)\ + + +bf(IEEE Standard for information Technology - +Portable Operating System Interface (POSIX) - +Part 2: Shell and Utilities), +IEEE Inc, 1993, ISBN 1-55937-255-9. diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo new file mode 100644 index 000000000..fccf538bd --- /dev/null +++ b/Doc/Zsh/zle.yo @@ -0,0 +1,1076 @@ +texinode(Zsh Line Editor)(Programmable Completion)(Shell Builtin Commands)(Top) +chapter(Zsh Line Editor) +cindex(line editor) +cindex(editor, line) +sect(Description) +pindex(ZLE, use of) +If the tt(ZLE) option is set (it is by default) +and the shell input is attached to the terminal, the user +is allowed to edit command lines. + +There are two display modes. The first, multiline mode, is the +default. It only works if the tt(TERM) parameter is set to a valid +terminal type that can move the cursor up. The second, single line +mode, is used if tt(TERM) is invalid or incapable of moving the +cursor up, or if the tt(SINGLE_LINE_ZLE) option is set. +pindex(SINGLE_LINE_ZLE, use of) +cindex(ksh, editor mode) +cindex(editor ksh style) +This mode +is similar to bf(ksh), and uses no termcap sequences. If tt(TERM) is +"emacs", the tt(ZLE) option will be unset by default. +sect(Keymaps) +cindex(keymaps) +cindex(key bindings) +cindex(bindings, key) +A keymap in ZLE contains a set of bindings between key sequences +and ZLE commands. The empty key sequence cannot be bound. + +There can be any number of keymaps at any time, and each keymap has one +or more names. If all of a keymap's names are deleted, it disappears. +findex(bindkey, use of) +tt(bindkey) can be used to manipulate keymap names. + +Initially, there are four keymaps: + +startsitem() +sitem(tt(emacs))(EMACS emulation) +sitem(tt(viins))(vi emulation - insert mode) +sitem(tt(vicmd))(vi emulation - command mode) +sitem(tt(.safe))(fallback keymap) +endsitem() + +The `tt(.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 `tt(.)' for their own keymaps. + +vindex(VISUAL) +vindex(EDITOR) +In addition to these four names, either `tt(emacs)' or `tt(viins)' is +also linked to the name `tt(main)'. If one of the tt(VISUAL) or +tt(EDITOR) environment variables contain the string `tt(vi)' when the shell +starts up then it will be `tt(viins)', otherwise it will be `tt(emacs)'. +tt(bindkey)'s tt(-e) and tt(-v) +options provide a convenient way to override this default choice. + +When the editor starts up, it will select the `tt(main)' keymap. +If that keymap doesn't exist, it will use `tt(.safe)' instead. + +In the `tt(.safe)' keymap, each single key is bound to tt(self-insert), +except for ^J (line feed) and ^M (return) which are bound to tt(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. +subsect(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 tt(KEYTIMEOUT) parameter; +its default is 0.4 sec. No timeout is done if the prefix string is not bound. + +As well as ZLE commands, key sequences can be bound to other strings, by using +`tt(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. +sect(Widgets) +cindex(widgets) +All actions in the editor are performed by `widgets'. A widget's job is +simply to perform some small action. The ZLE commands that key sequences +in keymaps are bound to are in fact widgets. Widgets can be user-defined +or built in. + +There are 162 standard widgets built in to ZLE (see sectref(Standard Widgets)). +Other built-in widgets can be defined by other modules (see +ifzman(zmanref(zshmodules))\ +ifnzman(noderef(Zsh Modules))\ +). Each built-in widget has two names: its normal canonical name, and the +same name preceded by a `tt(.)'. The `tt(.)' 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 `tt(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 `tt(.)'. +sect(User-Defined Widgets) +cindex(widgets, user-defined) +User-defined widgets, being implemented as shell functions, +can execute any normal shell command. They can also run other widgets +(whether built-in or user-defined) using the tt(zle) builtin command. +Finally, they can examine and edit the ZLE buffer being edited by +reading and setting the special parameters described below. + +cindex(parameters, editor) +cindex(parameters, zle) +These special parameters are always available in widget functions, but +are not in any way special outside ZLE. If they have some normal value +outside ZLE, that value is temporarily inaccessible, but will return +when the widget function exits. These special parameters in fact have +local scope, like parameters created in a function using tt(local). + +startitem() +vindex(BUFFER) +item(tt(BUFFER) (scalar))( +The entire contents of the edit buffer. If it is written to, the +cursor remains at the same offset, unless that would put it outside the +buffer. +) +vindex(CURSOR) +item(tt(CURSOR) (integer))( +The offset of the cursor, within the edit buffer. This is in the range +0 to tt($#BUFFER), and is by definition equal to tt($#LBUFFER). +Attempts to move the cursor outside the buffer will result in the +cursor being moved to the appropriate end of the buffer. +) +vindex(LBUFFER) +item(tt(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 tt($LBUFFER) and the old tt($RBUFFER). +) +vindex(RBUFFER) +item(tt(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 tt($LBUFFER) and the new tt($RBUFFER). +) +enditem() +sect(Standard Widgets) +cindex(widgets, standard) +The following is a list of all the standard widgets, +and their default bindings in emacs mode, +vi command mode and vi insert mode +(the `tt(emacs)', `tt(vicmd)' and `tt(viins)' keymaps, respectively). +startmenu() +menu(Movement) +menu(History Control) +menu(Modifying Text) +menu(Arguments) +menu(Completion) +menu(Miscellaneous) +endmenu() +texinode(Movement)(History Control)()(Zsh Line Editor) +subsect(Movement) +startitem() +tindex(vi-backward-blank-word) +item(tt(vi-backward-blank-word) (unbound) (B) (unbound))( +Move backward one word, where a word is defined as a series of +non-blank characters. +) +tindex(backward-char) +item(tt(backward-char) (^B ESC-[D) (unbound) (unbound))( +Move backward one character. +) +tindex(vi-backward-char) +item(tt(vi-backward-char) (unbound) (^H h ^?) (unbound))( +Move backward one character, without changing lines. +) +tindex(backward-word) +item(tt(backward-word) (ESC-B ESC-b) (unbound) (unbound))( +Move to the beginning of the previous word. +) +tindex(emacs-backward-word) +item(tt(emacs-backward-word))( +Move to the beginning of the previous word. +) +tindex(vi-backward-word) +item(tt(vi-backward-word) (unbound) (b) (unbound))( +Move to the beginning of the previous word, vi-style. +) +tindex(beginning-of-line) +item(tt(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. +) +tindex(vi-beginning-of-line) +item(tt(vi-beginning-of-line))( +Move to the beginning of the line, without changing lines. +) +tindex(end-of-line) +item(tt(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. +) +tindex(vi-end-of-line) +item(tt(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. +) +tindex(vi-forward-blank-word) +item(tt(vi-forward-blank-word) (unbound) (W) (unbound))( +Move forward one word, where a word is defined as a series of +non-blank characters. +) +tindex(vi-forward-blank-word-end) +item(tt(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. +) +tindex(forward-char) +item(tt(forward-char) (^F ESC-[C) (unbound) (unbound))( +Move forward one character. +) +tindex(vi-forward-char) +item(tt(vi-forward-char) (unbound) (space l) (unbound))( +Move forward one character. +) +tindex(vi-find-next-char) +item(tt(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. +) +tindex(vi-find-next-char-skip) +item(tt(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. +) +tindex(vi-find-prev-char) +item(tt(vi-find-prev-char) (unbound) (F) (unbound))( +Read a character from the keyboard, and move to +the previous occurrence of it in the line. +) +tindex(vi-find-prev-char-skip) +item(tt(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. +) +tindex(vi-first-non-blank) +item(tt(vi-first-non-blank) (unbound) (^) (unbound))( +Move to the first non-blank character in the line. +) +tindex(vi-forward-word) +item(tt(vi-forward-word) (unbound) (w) (unbound))( +Move forward one word, vi-style. +) +tindex(forward-word) +item(tt(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 tt(WORDCHARS) +parameter. +) +tindex(emacs-forward-word) +item(tt(emacs-forward-word))( +Move to the end of the next word. +) +tindex(vi-forward-word-end) +item(tt(vi-forward-word-end) (unbound) (e) (unbound))( +Move to the end of the next word. +) +tindex(vi-goto-column) +item(tt(vi-goto-column) (ESC-|) (|) (unbound))( +Move to the column specified by the numeric argument. +) +tindex(vi-goto-mark) +item(tt(vi-goto-mark) (unbound) (`) (unbound))( +Move to the specified mark. +) +tindex(vi-goto-mark-line) +item(tt(vi-goto-mark-line) (unbound) (') (unbound))( +Move to beginning of the line containing the specified mark. +) +tindex(vi-repeat-find) +item(tt(vi-repeat-find) (unbound) (;) (unbound))( +Repeat the last tt(vi-find) command. +) +tindex(vi-rev-repeat-find) +item(tt(vi-rev-repeat-find) (unbound) (,) (unbound))( +Repeat the last tt(vi-find) command in the opposite direction. +) +enditem() +texinode(History Control)(Modifying Text)(Movement)(Zsh Line Editor) +subsect(History Control) +startitem() +tindex(beginning-of-buffer-or-history) +item(tt(beginning-of-buffer-or-history) (ESC-<) (unbound) (unbound))( +Move to the beginning of the buffer, or if already there, +move to the first event in the history list. +) +tindex(beginning-of-line-hist) +item(tt(beginning-of-line-hist))( +Move to the beginning of the line. If already at the +beginning of the buffer, move to the previous history line. +) +tindex(beginning-of-history) +item(tt(beginning-of-history))( +Move to the first event in the history list. +) +tindex(down-line-or-history) +item(tt(down-line-or-history) (^N ESC-[B) (j) (unbound))( +Move down a line in the buffer, or if already at the bottom line, +move to the next event in the history list. +) +tindex(vi-down-line-or-history) +item(tt(vi-down-line-or-history) (unbound) (PLUS()) (unbound))( +Move down a line in the buffer, or if already at the bottom line, +move to the next event in the history list. +Then move to the first non-blank character on the line. +) +tindex(down-line-or-search) +item(tt(down-line-or-search))( +Move down a line in the buffer, or if already at the bottom line, +search forward in the history for a line beginning with the first +word in the buffer. +) +tindex(down-history) +item(tt(down-history) (unbound) (^N) (unbound))( +Move to the next event in the history list. +) +tindex(history-beginning-search-backward) +item(tt(history-beginning-search-backward))( +Search backward in the history for a line beginning with the current +line up to the cursor. +This leaves the cursor in its original position. +) +tindex(end-of-buffer-or-history) +item(tt(end-of-buffer-or-history) (ESC->) (unbound) (unbound))( +Move to the end of the buffer, or if already there, +move to the last event in the history list. +) +tindex(end-of-line-hist) +item(tt(end-of-line-hist))( +Move to the end of the line. If already at the end of +the buffer, move to the next history line. +) +tindex(end-of-history) +item(tt(end-of-history))( +Move to the last event in the history list. +) +tindex(vi-fetch-history) +item(tt(vi-fetch-history) (unbound) (G) (unbound))( +Fetch the history line specified by the numeric argument. +This defaults to the current history line +(i.e. the one that isn't history yet). +) +tindex(history-incremental-search-backward) +item(tt(history-incremental-search-backward) (^R ^Xr) (unbound) (unbound))( +Search backward incrementally for a specified string. The search is +case-insensitive if the search string does not have uppercase letters and no +numeric argument was given. The string may begin with `tt(^)' to anchor the +search to the beginning of the line. + +A restricted set of editing functions +is available in the mini-buffer. An interrupt signal, as defined by the stty +setting, will stop the search and go back to the original line. An undefined +key will have the same effect. The supported functions are: +tt(backward-delete-char), +tt(vi-backward-delete-char), +tt(clear-screen), +tt(redisplay), +tt(quoted-insert), +tt(vi-quoted-insert), +tt(accept-and-hold), +tt(accept-and-infer-next-history), +tt(accept-line) and +tt(accept-line-and-down-history). + +tt(magic-space) just inserts a space. +tt(vi-cmd-mode) toggles between the `tt(main)' and `tt(vicmd)' keymaps; +the `tt(main)' keymap (insert mode) will be selected initially. +tt(history-incremental-search-backward) will get the +next occurrence of the contents of the mini-buffer. +tt(history-incremental-search-forward) inverts the sense of the search. +tt(vi-repeat-search) and tt(vi-rev-repeat-search) are similarly supported. +The direction of the search is indicated in the mini-buffer. + +Any multi-character string +that is not bound to one of the above functions will beep and interrupt the +search, leaving the last found line in the buffer. Any single character that +is not bound to one of the above functions, or tt(self-insert) or +tt(self-insert-unmeta), will have the same effect but the function will be +executed. +) +tindex(history-incremental-search-forward) +item(tt(history-incremental-search-forward) (^S ^Xs) (unbound) (unbound))( +Search forward incrementally for a specified string. The search is +case-insensitive if the search string does not have uppercase letters and no +numeric argument was given. The string may begin with `tt(^)' to anchor the +search to the beginning of the line. The functions available in the +mini-buffer are the same as for tt(history-incremental-search-backward). +) +tindex(history-search-backward) +item(tt(history-search-backward) (ESC-P ESC-p) (unbound) (unbound))( +Search backward in the history for a line beginning with the first +word in the buffer. +) +tindex(vi-history-search-backward) +item(tt(vi-history-search-backward) (unbound) (/) (unbound))( +Search backward in the history for a specified string. +The string may begin with `tt(^)' to anchor the search to the +beginning of the line. + +A restricted set of editing functions is available in +the mini-buffer. An interrupt signal, as defined by the stty setting, will +stop the search. +The functions available in the mini-buffer are: +tt(accept-line), +tt(backward-delete-char), +tt(vi-backward-delete-char), +tt(backward-kill-word), +tt(vi-backward-kill-word), +tt(clear-screen), +tt(redisplay), +tt(quoted-insert) +and +tt(vi-quoted-insert). + +tt(vi-cmd-mode) is treated the same as accept-line, and +tt(magic-space) is treated as a space. +Any other character that is not bound to self-insert or +self-insert-unmeta will beep and be ignored. If the function is called from vi +command mode, the bindings of the current insert mode will be used. +) +tindex(history-search-forward) +item(tt(history-search-forward) (ESC-N ESC-n) (unbound) (unbound))( +Search forward in the history for a line beginning with the first +word in the buffer. +) +tindex(vi-history-search-forward) +item(tt(vi-history-search-forward) (unbound) (?) (unbound))( +Search forward in the history for a specified string. +The string may begin with `tt(^)' to anchor the search to the +beginning of the line. The functions available in the mini-buffer are the same +as for tt(vi-history-search-backward). +) +tindex(infer-next-history) +item(tt(infer-next-history) (^X^N) (unbound) (unbound))( +Search in the history list for a line matching the current one and +fetch the event following it. +) +tindex(insert-last-word) +item(tt(insert-last-word) (ESC-_ ESC-.) (unbound) (unbound))( +Insert the last word from the previous history event at the +cursor position. If a positive numeric argument is given, +insert that word from the end of the previous history event. +If the argument is zero or negative insert that word from the +left (zero inserts the previous command word). +) +tindex(vi-repeat-search) +item(tt(vi-repeat-search) (unbound) (n) (unbound))( +Repeat the last vi history search. +) +tindex(vi-rev-repeat-search) +item(tt(vi-rev-repeat-search) (unbound) (N) (unbound))( +Repeat the last vi history search, but in reverse. +) +tindex(up-line-or-history) +item(tt(up-line-or-history) (^P ESC-[A) (k) (unbound))( +Move up a line in the buffer, or if already at the top line, +move to the previous event in the history list. +) +tindex(vi-up-line-or-history) +item(tt(vi-up-line-or-history) (unbound) (-) (unbound))( +Move up a line in the buffer, or if already at the top line, +move to the previous event in the history list. +Then move to the first non-blank character on the line. +) +tindex(up-line-or-search) +item(tt(up-line-or-search))( +Move up a line in the buffer, or if already at the top line, +search backward in the history for a line beginning with the +first word in the buffer. +) +tindex(up-history) +item(tt(up-history) (unbound) (^P) (unbound))( +Move to the previous event in the history list. +) +tindex(history-beginning-search-forward) +item(tt(history-beginning-search-forward))( +Search forward in the history for a line beginning with the current +line up to the cursor. +This leaves the cursor in its original position. +) +enditem() +texinode(Modifying Text)(Arguments)(History Control)(Zsh Line Editor) +subsect(Modifying Text) +startitem() +tindex(vi-add-eol) +item(tt(vi-add-eol) (unbound) (A) (unbound))( +Move to the end of the line and enter insert mode. +) +tindex(vi-add-next) +item(tt(vi-add-next) (unbound) (a) (unbound))( +Enter insert mode after the current cursor position, without changing lines. +) +tindex(backward-delete-char) +item(tt(backward-delete-char) (^H ^?) (unbound) (unbound))( +Delete the character behind the cursor. +) +tindex(vi-backward-delete-char) +item(tt(vi-backward-delete-char) (unbound) (X) (^H))( +Delete the character behind the cursor, without changing lines. +If in insert mode, this won't delete past the point where insert mode was +last entered. +) +tindex(backward-delete-word) +item(tt(backward-delete-word))( +Delete the word behind the cursor. +) +tindex(backward-kill-line) +item(tt(backward-kill-line))( +Kill from the beginning of the line to the cursor position. +) +tindex(backward-kill-word) +item(tt(backward-kill-word) (^W ESC-^H ESC-^?) (unbound) (unbound))( +Kill the word behind the cursor. +) +tindex(vi-backward-kill-word) +item(tt(vi-backward-kill-word) (unbound) (unbound) (^W))( +Kill the word behind the cursor, without going past the point where insert +mode was last entered. +) +tindex(capitalize-word) +item(tt(capitalize-word) (ESC-C ESC-c) (unbound) (unbound))( +Capitalize the current word and move past it. +) +tindex(vi-change) +item(tt(vi-change) (unbound) (c) (unbound))( +Read a movement command from the keyboard, and kill +from the cursor position to the endpoint of the movement. +Then enter insert mode. +If the command is tt(vi-change), change the current line. +) +tindex(vi-change-eol) +item(tt(vi-change-eol) (unbound) (C) (unbound))( +Kill to the end of the line and enter insert mode. +) +tindex(vi-change-whole-line) +item(tt(vi-change-whole-line) (unbound) (S) (unbound))( +Kill the current line and enter insert mode. +) +tindex(copy-region-as-kill) +item(tt(copy-region-as-kill) (ESC-W ESC-w) (unbound) (unbound))( +Copy the area from the cursor to the mark to the kill buffer. +) +tindex(copy-prev-word) +item(tt(copy-prev-word) (ESC-^_) (unbound) (unbound))( +Duplicate the word behind the cursor. +) +tindex(vi-delete) +item(tt(vi-delete) (unbound) (d) (unbound))( +Read a movement command from the keyboard, and kill +from the cursor position to the endpoint of the movement. +If the command is tt(vi-delete), kill the current line. +) +tindex(delete-char) +item(tt(delete-char))( +Delete the character under the cursor. +) +tindex(vi-delete-char) +item(tt(vi-delete-char) (unbound) (x) (unbound))( +Delete the character under the cursor, +without going past the end of the line. +) +tindex(delete-word) +item(tt(delete-word))( +Delete the current word. +) +tindex(down-case-word) +item(tt(down-case-word) (ESC-L ESC-l) (unbound) (unbound))( +Convert the current word to all lowercase and move past it. +) +tindex(kill-word) +item(tt(kill-word) (ESC-D ESC-d) (unbound) (unbound))( +Kill the current word. +) +tindex(gosmacs-transpose-chars) +item(tt(gosmacs-transpose-chars))( +Exchange the two characters behind the cursor. +) +tindex(vi-indent) +item(tt(vi-indent) (unbound) (>) (unbound))( +Indent a number of lines. +) +tindex(vi-insert) +item(tt(vi-insert) (unbound) (i) (unbound))( +Enter insert mode. +) +tindex(vi-insert-bol) +item(tt(vi-insert-bol) (unbound) (I) (unbound))( +Move to the first non-blank character on the line and enter insert mode. +) +tindex(vi-join) +item(tt(vi-join) (^X^J) (J) (unbound))( +Join the current line with the next one. +) +tindex(kill-line) +item(tt(kill-line) (^K) (unbound) (unbound))( +Kill from the cursor to the end of the line. +If already on the end of the line, kill the newline character. +) +tindex(vi-kill-line) +item(tt(vi-kill-line) (unbound) (unbound) (^U))( +Kill from the cursor back to wherever insert mode was last entered. +) +tindex(vi-kill-eol) +item(tt(vi-kill-eol) (unbound) (D) (unbound))( +Kill from the cursor to the end of the line. +) +tindex(kill-region) +item(tt(kill-region))( +Kill from the cursor to the mark. +) +tindex(kill-buffer) +item(tt(kill-buffer) (^X^K) (unbound) (unbound))( +Kill the entire buffer. +) +tindex(kill-whole-line) +item(tt(kill-whole-line) (^U) (unbound) (unbound))( +Kill the current line. +) +tindex(vi-match-bracket) +item(tt(vi-match-bracket) (^X^B) (%) (unbound))( +Move to the bracket character (one of tt({}), tt(()) or tt([])) that +matches the one under the cursor. +If the cursor is not on a bracket character, move forward without going +past the end of the line to find one, and then go to the matching bracket. +) +tindex(vi-open-line-above) +item(tt(vi-open-line-above) (unbound) (O) (unbound))( +Open a line above the cursor and enter insert mode. +) +tindex(vi-open-line-below) +item(tt(vi-open-line-below) (unbound) (o) (unbound))( +Open a line below the cursor and enter insert mode. +) +tindex(vi-oper-swap-case) +item(tt(vi-oper-swap-case))( +Read a movement command from the keyboard, and swap +the case of all characters +from the cursor position to the endpoint of the movement. +If the movement command is tt(vi-oper-swap-case), +swap the case of all characters on the current line. +) +tindex(overwrite-mode) +item(tt(overwrite-mode) (^X^O) (unbound) (unbound))( +Toggle between overwrite mode and insert mode. +) +tindex(vi-put-before) +item(tt(vi-put-before) (unbound) (P) (unbound))( +Insert the contents of the kill buffer before the cursor. +If the kill buffer contains a sequence of lines (as opposed to characters), +paste it above the current line. +) +tindex(vi-put-after) +item(tt(vi-put-after) (unbound) (p) (unbound))( +Insert the contents of the kill buffer after the cursor. +If the kill buffer contains a sequence of lines (as opposed to characters), +paste it below the current line. +) +tindex(quoted-insert) +item(tt(quoted-insert) (^V) (unbound) (unbound))( +Insert the next character typed into the buffer literally. +An interrupt character will not be inserted. +) +tindex(vi-quoted-insert) +item(tt(vi-quoted-insert) (unbound) (unbound) (^Q ^V))( +Display a `tt(^)' at the cursor position, and +insert the next character typed into the buffer literally. +An interrupt character will not be inserted. +) +tindex(quote-line) +item(tt(quote-line) (ESC-') (unbound) (unbound))( +Quote the current line; that is, put a `tt(')' character at the +beginning and the end, and convert all `tt(')' characters +to `tt('\'')'. +) +tindex(quote-region) +item(tt(quote-region) (ESC-") (unbound) (unbound))( +Quote the region from the cursor to the mark. +) +tindex(vi-replace) +item(tt(vi-replace) (unbound) (R) (unbound))( +Enter overwrite mode. +) +tindex(vi-repeat-change) +item(tt(vi-repeat-change) (unbound) (.) (unbound))( +Repeat the last vi mode text modification. +If a count was used with the modification, it is remembered. +If a count is given to this command, it overrides the remembered count, +and is remembered for future uses of this command. +The cut buffer specification is similarly remembered. +) +tindex(vi-replace-chars) +item(tt(vi-replace-chars) (unbound) (r) (unbound))( +Replace the character under the cursor with a character +read from the keyboard. +) +tindex(self-insert) +item(tt(self-insert) (printable characters) (unbound) (printable characters and some control characters))( +Insert a character into the buffer at the cursor position. +) +tindex(self-insert-unmeta) +item(tt(self-insert-unmeta) (ESC-^I ESC-^J ESC-^M) (unbound) (unbound))( +Insert a character into the buffer after stripping the meta bit +and converting ^M to ^J. +) +tindex(vi-substitute) +item(tt(vi-substitute) (unbound) (s) (unbound))( +Substitute the next characte+CHAR(r)(s). +) +tindex(vi-swap-case) +item(tt(vi-swap-case) (unbound) (~) (unbound))( +Swap the case of the character under the cursor and move past it. +) +tindex(transpose-chars) +item(tt(transpose-chars) (^T) (unbound) (unbound))( +Exchange the two characters to the left of the +cursor if at end of line, else exchange the +character under the cursor with the character +to the left. +) +tindex(transpose-words) +item(tt(transpose-words) (ESC-T ESC-t) (unbound) (unbound))( +Exchange the current word with the one before it. +) +tindex(vi-unindent) +item(tt(vi-unindent) (unbound) (<) (unbound))( +Unindent a number of lines. +) +tindex(up-case-word) +item(tt(up-case-word) (ESC-U ESC-u) (unbound) (unbound))( +Convert the current word to all caps and move past it. +) +tindex(yank) +item(tt(yank) (^Y) (unbound) (unbound))( +Insert the contents of the kill buffer at the cursor position. +) +tindex(yank-pop) +item(tt(yank-pop) (ESC-y) (unbound) (unbound))( +Remove the text just yanked, rotate the kill-ring, +and yank the new top. Only works following +tt(yank) or tt(yank-pop). +) +tindex(vi-yank) +item(tt(vi-yank) (unbound) (y) (unbound))( +Read a movement command from the keyboard, and copy the region +from the cursor position to the endpoint of the movement +into the kill buffer. +If the command is tt(vi-yank), copy the current line. +) +tindex(vi-yank-whole-line) +item(tt(vi-yank-whole-line) (unbound) (Y) (unbound))( +Copy the current line into the kill buffer. +) +tindex(vi-yank-eol) +item(tt(vi-yank-eol))( +Copy the region from the cursor position to the end of the line +into the kill buffer. +Arguably, this is what Y should do in vi, but it isn't what it actually does. +) +enditem() +texinode(Arguments)(Completion)(Modifying Text)(Zsh Line Editor) +subsect(Arguments) +startitem() +tindex(digit-argument) +item(tt(digit-argument) (ESC-0..ESC-9) (1-9) (unbound))( +Start a new numeric argument, or add to the current one. +See also tt(vi-digit-or-beginning-of-line). +) +tindex(neg-argument) +item(tt(neg-argument) (ESC--) (unbound) (unbound))( +Changes the sign of the following argument. +) +tindex(universal-argument) +item(tt(universal-argument))( +Multiply the argument of the next command by 4. Alternatively, if +this command is followed by an integer (positive or negative), use +that as the argument for the next command. Thus digits cannot be +repeated using this command. For example, if this command occurs +twice, followed immediately by tt(forward-char), move forward sixteen +spaces; if instead it is followed by tt(-2), then tt(forward-char), +move backward two spaces. +) +enditem() +texinode(Completion)(Miscellaneous)(Arguments)(Zsh Line Editor) +subsect(Completion) +startitem() +tindex(accept-and-menu-complete) +item(tt(accept-and-menu-complete))( +In a menu completion, insert the current completion into the buffer, +and advance to the next possible completion. +) +tindex(complete-word) +item(tt(complete-word))( +Attempt completion on the current word. +) +tindex(delete-char-or-list) +item(tt(delete-char-or-list) (^D) (unbound) (unbound))( +Delete the character under the cursor. If the cursor +is at the end of the line, list possible completions for the +current word. +) +tindex(expand-cmd-path) +item(tt(expand-cmd-path))( +Expand the current command to its full pathname. +) +tindex(expand-or-complete) +item(tt(expand-or-complete) (TAB) (unbound) (TAB))( +Attempt shell expansion on the current word. +If that fails, +attempt completion. +) +tindex(expand-or-complete-prefix) +item(tt(expand-or-complete-prefix))( +Attempt shell expansion on the current word up to cursor. +) +tindex(expand-history) +item(tt(expand-history) (ESC-space ESC-!) (unbound) (unbound))( +Perform history expansion on the edit buffer. +) +tindex(expand-word) +item(tt(expand-word) (^X*) (unbound) (unbound))( +Attempt shell expansion on the current word. +) +tindex(list-choices) +item(tt(list-choices) (ESC-^D) (^D =) (^D))( +List possible completions for the current word. +) +tindex(list-expand) +item(tt(list-expand) (^Xg ^XG) (^G) (^G))( +List the expansion of the current word. +) +tindex(magic-space) +item(tt(magic-space))( +Perform history expansion and insert a space into the +buffer. This is intended to be bound to space. +) +tindex(menu-complete) +pindex(MENU_COMPLETE, use of) +item(tt(menu-complete))( +Like tt(complete-word), except that menu completion is used. +See the tt(MENU_COMPLETE) option. +) +tindex(menu-expand-or-complete) +item(tt(menu-expand-or-complete))( +Like tt(expand-or-complete), except that menu completion is used. +) +tindex(reverse-menu-complete) +item(tt(reverse-menu-complete))( +Perform menu completion, like tt(menu-complete), except that if +a menu completion is already in progress, move to the em(previous) +completion rather than the next. +) +enditem() +texinode(Miscellaneous)()(Completion)(Zsh Line Editor) +subsect(Miscellaneous) +startitem() +tindex(accept-and-hold) +item(tt(accept-and-hold) (ESC-A ESC-a) (unbound) (unbound))( +Push the contents of the buffer on the buffer stack +and execute it. +) +tindex(accept-and-infer-next-history) +item(tt(accept-and-infer-next-history))( +Execute the contents of the buffer. +Then search the history list for a line matching the current one +and push the event following onto the buffer stack. +) +tindex(accept-line) +item(tt(accept-line) (^J ^M) (^J ^M) (^J ^M))( +Finish editing the buffer. Normally this causes the buffer to be +executed as a shell command. +) +tindex(accept-line-and-down-history) +item(tt(accept-line-and-down-history) (^O) (unbound) (unbound))( +Execute the current line, and push the next history +event on the the buffer stack. +) +tindex(vi-cmd-mode) +item(tt(vi-cmd-mode) (^X^V) (unbound) (^[))( +Enter command mode; that is, select the `tt(vicmd)' keymap. +Yes, this is bound by default in emacs mode. +) +tindex(vi-caps-lock-panic) +item(tt(vi-caps-lock-panic))( +Hang until any lowercase key is pressed. +This is for vi users without the mental capacity to keep +track of their caps lock key (like the author). +) +tindex(clear-screen) +item(tt(clear-screen) (^L ESC-^L) (^L) (^L))( +Clear the screen and redraw the prompt. +) +tindex(describe-key-briefly) +item(tt(describe-key-briefly))( +Reads a key sequence, then prints the function bound to that sequence. +) +tindex(exchange-point-and-mark) +item(tt(exchange-point-and-mark) (^X^X) (unbound) (unbound))( +Exchange the cursor position with the position of the mark. +) +tindex(execute-named-cmd) +item(tt(execute-named-cmd) (ESC-x) (unbound) (unbound))( +Read the name of an editor command and +execute it. A restricted set of editing functions is available in the +mini-buffer. An interrupt signal, as defined by the stty setting, will +abort the function. The allowed functions are: +tt(backward-delete-char), +tt(vi-backward-delete-char), +tt(clear-screen), +tt(redisplay), +tt(quoted-insert), +tt(vi-quoted-insert), +tt(backward-kill-word), +tt(vi-backward-kill-word), +tt(kill-whole-line), +tt(vi-kill-line), +tt(backward-kill-line), +tt(list-choices), +tt(delete-char-or-list), +tt(complete-word), +tt(accept-line), +tt(expand-or-complete) and +tt(expand-or-complete-prefix). + +tt(kill-region) kills the last word, +and vi-cmd-mode is treated the same as accept-line. +The space and tab characters, if not bound to one of +these functions, will complete the name and then list the +possibilities if the tt(AUTO_LIST) option is set. +Any other character that is not bound to tt(self-insert) or +tt(self-insert-unmeta) will beep and be ignored. +The bindings of the current insert mode will be used. +) +tindex(execute-last-named-cmd) +item(tt(execute-last-named-cmd) (ESC-z) (unbound) (unbound))( +Redo the last function executed with tt(execute-named-cmd). +) +tindex(get-line) +item(tt(get-line) (ESC-G ESC-g) (unbound) (unbound))( +Pop the top line off the buffer stack and insert it at the +cursor position. +) +tindex(pound-insert) +item(tt(pound-insert) (unbound) (#) (unbound))( +If there is no # character at the beginning of the buffer, +add one to the beginning of each line. +If there is one, remove a # from each line that has one. +In either case, accept the current line. +The tt(INTERACTIVE_COMMENTS) option must be set +for this to have any usefulness. +) +tindex(vi-pound-insert) +item(tt(vi-pound-insert))( +If there is no # character at the beginning of the current line, +add one. If there is one, remove it. +The tt(INTERACTIVE_COMMENTS) option must be set +for this to have any usefulness. +) +tindex(push-input) +item(tt(push-input))( +Push the entire current multiline construct onto the buffer stack and +return to the top-level (tt(PS1)) prompt. +If the current parser construct is only a single line, this is exactly +like tt(push-line). +Next time the editor starts up or is popped with tt(get-line), the +construct will be popped off the top of the buffer stack and loaded +into the editing buffer. +) +tindex(push-line) +item(tt(push-line) (^Q ESC-Q ESC-q) (unbound) (unbound))( +Push the current buffer onto the buffer stack and clear +the buffer. +Next time the editor starts up, the buffer will be popped +off the top of the buffer stack and loaded into the editing +buffer. +) +tindex(push-line-or-edit) +item(tt(push-line-or-edit))( +At the top-level (tt(PS1)) prompt, equivalent to tt(push-line). +At a secondary (tt(PS2)) prompt, move the entire current multiline +construct into the editor buffer. +The latter is equivalent to tt(push-input) followed by tt(get-line). +) +tindex(redisplay) +item(tt(redisplay) (unbound) (^R) (^R))( +Redisplays the edit buffer. +) +tindex(send-break) +item(tt(send-break) (^G ESC-^G) (unbound) (unbound))( +Abort the current editor function, e.g. tt(execute-named-command), or the +editor itself, e.g. if you are in tt(vared). Otherwise abort the parsing of +the current line. +) +tindex(run-help) +item(tt(run-help) (ESC-H ESC-h) (unbound) (unbound))( +Push the buffer onto the buffer stack, and execute the +command `tt(run-help) var(cmd)', where var(cmd) is the current +command. tt(run-help) is normally aliased to var(man). +) +tindex(vi-set-buffer) +item(tt(vi-set-buffer) (unbound) (") (unbound))( +Specify a buffer to be used in the following command. +There are 35 buffers that can be specified: +the 26 `named' buffers tt("a) to tt("z) +and the nine `queued' buffers tt("1) to tt("9). The named buffers can also +be specified as tt("A) to tt("Z). + +When a buffer is specified for a cut command, the text being cut replaces +the previous contents of the specified buffer. If a named buffer +is specified using a capital, the newly cut text is appended to the buffer +instead of overwriting it. + +If no buffer is specified for a cut command, tt("1) is used, and the +contents of tt("1) to tt("8) are each shifted along one buffer; the contents of +tt("9) is lost. +) +tindex(vi-set-mark) +item(tt(vi-set-mark) (unbound) (m) (unbound))( +Set the specified mark at the cursor position. +) +tindex(set-mark-command) +item(tt(set-mark-command) (^@) (unbound) (unbound))( +Set the mark at the cursor position. +) +tindex(spell-word) +item(tt(spell-word) (ESC-$ ESC-S ESC-s) (unbound) (unbound))( +Attempt spelling correction on the current word. +) +tindex(undefined-key) +item(tt(undefined-key))( +This command is executed when a key sequence that is not bound to any +command is typed. By default it beeps. +) +tindex(undo) +item(tt(undo) (^_ ^Xu ^X^U) (unbound) (unbound))( +Incrementally undo the last text modification. +) +tindex(redo) +item(tt(redo))( +Incrementally redo undone text modifications. +) +tindex(vi-undo-change) +item(tt(vi-undo-change) (unbound) (u) (unbound))( +Undo the last text modification. +If repeated, redo the modification. +) +tindex(what-cursor-position) +item(tt(what-cursor-position) (^X=) (unbound) (unbound))( +Print the character under the cursor, its code as an octal, decimal and +hexadecimal number, the current cursor position within the buffer and the +column of the cursor in the current line. +) +tindex(where-is) +item(tt(where-is))( +Read the name of an editor command and and print the listing of key +sequences that invoke the specified command. +) +tindex(which-command) +item(tt(which-command) (ESC-?) (unbound) (unbound))( +Push the buffer onto the buffer stack, and execute the +command `tt(which-command) var(cmd)'. where var(cmd) is the current +command. tt(which-command) is normally aliased to var(whence). +) +tindex(vi-digit-or-beginning-of-line) +item(tt(vi-digit-or-beginning-of-line) (unbound) (0) (unbound))( +If the last command executed was a digit as part of an argument, +continue the argument. Otherwise, execute vi-beginning-of-line. +) +enditem() -- cgit 1.4.1