diff options
Diffstat (limited to 'Doc/Zsh/builtins.yo')
| -rw-r--r-- | Doc/Zsh/builtins.yo | 84 |
1 files changed, 70 insertions, 14 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 56428a714..7a9684ac8 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -683,6 +683,7 @@ the same as if the commands had been executed directly by the shell; if there are no var(args) or they contain no commands (i.e. are an empty string or whitespace) the return status is zero. ) +findex(exec) item(tt(exec) [ tt(-cl) ] [ tt(-a) var(argv0) ] [ var(command) [ var(arg) ... ] ])( Replace the current shell with var(command) rather than forking. If var(command) is a shell builtin command or a shell function, @@ -1142,8 +1143,9 @@ findex(kill) cindex(killing jobs) cindex(jobs, killing) xitem(tt(kill) [ tt(-s) var(signal_name) | tt(-n) var(signal_number) | \ -tt(-)var(sig) ] var(job) ...) -item(tt(kill) tt(-l) [ var(sig) ... ])( +tt(-)var(sig) ] [ tt(-q) var(value) ] var(job) ...) +xitem(tt(kill) tt(-l) [ var(sig) ... ]) +item(tt(kill) tt(-L))( Sends either tt(SIGTERM) or the specified signal to the given jobs or processes. Signals are given by number or by names, with or without the `tt(SIG)' @@ -1157,7 +1159,8 @@ 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. +stopped by a signal the name of the signal is printed. The final +form with tt(-L) lists each signal name with its corresponding number. On some systems, alternative signal names are allowed for a few signals. Typical examples are tt(SIGCHLD) and tt(SIGCLD) or tt(SIGPOLL) and @@ -1169,6 +1172,9 @@ tt(kill -IO) and tt(kill -POLL) have the same effect. Many systems will allow process IDs to be negative to kill a process group or zero to kill the current process group. + +The tt(-q) option allows an integer value to be sent with the signal +on systems that support tt(sigqueue+LPAR()RPAR()). ) findex(let) item(tt(let) var(arg) ...)( @@ -1633,6 +1639,7 @@ cancels both tt(-p) and tt(-u). The tt(-c) or tt(-l) flags cancel any and all of tt(-kpquz). ) +findex(readonly) cindex(parameters, marking readonly) item(tt(readonly))( Same as tt(typeset -r). With the tt(POSIX_BUILTINS) option set, same @@ -1644,7 +1651,9 @@ 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 -an arithmetic expression var(n). +an arithmetic expression var(n). Also causes a non-interctive +shell to exit, allowing files containing shell code to be used +both as scripts and as autoloadable shell functions. For example, the following prints `tt(42)': example(() { integer foo=40; return "foo + 2" } @@ -1924,6 +1933,8 @@ redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ @ @ ))ifnztexi( ))) xitem(tt(typeset )[ {tt(PLUS())|tt(-)}tt(AHUaghlmrtux) ] \ [ {tt(PLUS())|tt(-)}tt(EFLRZip) [ var(n) ] ]) xitem(SPACES()[ tt(+) ] [ var(name)[tt(=)var(value)] ... ]) +xitem(tt(typeset ){tt(PLUS())|tt(-)}tt(n) [ tt(-g) ] \ +[ {tt(PLUS())|tt(-)}tt(r) ] [ var(name)[tt(=)var(value)] ... ]) xitem(tt(typeset )tt(-T) [ {tt(PLUS())|tt(-)}tt(Uglrux) ] [ {tt(PLUS())|tt(-)}tt(LRZp) [ var(n) ] ]) xitem(SPACES()[ tt(+) | var(SCALAR)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(RPAR())] [ var(sep) ] ]) item(tt(typeset) tt(-f) [ {tt(PLUS())|tt(-)}tt(TUkmtuz) ] [ tt(+) ] [ var(name) ... ])( @@ -2037,6 +2048,36 @@ To initialize a parameter var(param) to a command output and mark it readonly, use tt(typeset -r )var(param) or tt(readonly )var(param) after the parameter assignment statement. +cindex(named reference) +cindex(reference, named) +The flag tt(-n) creates a em(named reference) to another parameter. +The second parameter need not exist at the time the reference is +created. Only tt(-g), tt(-u), and tt(-r) may be used in conjunction with +tt(-n). The var(name) so created may not be an array element nor use +a subscript, but the var(value) assigned may be any valid parameter +name syntax, even a subscripted array element (including an associative +array element) or an array slice, which is evaluated when the named +reference is expanded. It is an error for a named reference to refer +to itself, even indirectly through a chain of references. When tt(-u) +is applied to a named reference, the parameter identified by var(value) +is always found in the calling function scope rather than the current +local scope. In this case, if there is no such parameter in the calling +scope, assignments to the named reference may fail, setting tt($?) to 1. +See ifzman(zmanref(zshexpn))ifnzman(noderef(Parameter Expansion)) and +ifzman(zmanref(zshparam))ifnzman(noderef(Parameters)) for details of the +behavior of named references. + +Local function scoping rules for `tt(typeset)' do apply with `tt(-n)', +so a declaration within a function persists only until the end of the +function unless `tt(-g -n)' is specified, and any local parameter (of +any type) with the same var(name) supplants a named reference from a +surrounding scope. + +A scalar parameter, including an existing named reference, may be +converted to a new named reference by `tt(typeset -n )var(name)', so +the `tt(-p)' option must be included to display the value of a +specific named reference var(name). + If no attribute flags are given, and either no var(name) arguments are present or the flag tt(+m) is used, then each parameter name printed is preceded by a list of the attributes of that parameter (tt(array), @@ -2081,7 +2122,8 @@ is not used in this case). If the tt(+g) flag is combined with tt(-m), a new local parameter is created for every matching parameter that is not already local. Otherwise -tt(-m) applies all other flags or assignments to the existing parameters. +tt(-m) applies all other flags or assignments to the existing parameters, +except that the tt(-n) option cannot create named references in this way. Except when assignments are made with var(name)tt(=)var(value), using tt(+m) forces the matching parameters and their attributes to be printed, @@ -2100,6 +2142,14 @@ tt(-p) may be followed by an optional integer argument. Currently only the value tt(1) is supported. In this case arrays and associative arrays are printed with newlines between indented elements for readability. + +The names and values of readonly special parameters +(most of the parameters marked `<S>' in +ifzman(zmanref(zshparam))ifnzman(noderef(Parameters Set By The Shell)), +except those documented as settable) +are not printed with `tt(-)tt(p)' because to execute those typeset commands +would cause errors. However, these parameters are printed when they +have been made local to the scope where `tt(typeset -p)' is run. ) item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array)[tt(=LPAR())var(value) ...tt(RPAR())] [ var(sep) ] ])( This flag has a different meaning when used with tt(-f); see below. @@ -2242,9 +2292,9 @@ automatically given the tt(-h) attribute to avoid name clashes. item(tt(-H))( Hide value: specifies that tt(typeset) will not display the value of the parameter when listing parameters; the display for such parameters is -always as if the `tt(PLUS())' flag had been given. Use of the parameter is -in other respects normal, and the option does not apply if the parameter is -specified by name, or by pattern with the tt(-m) option. This is on by +always as if the `tt(PLUS())' flag were given, but use of the parameter is +in other respects normal. This effect does not apply when the parameter is +specified by name or by pattern with the tt(-m) option. This is on by default for the parameters in the tt(zsh/parameter) and tt(zsh/mapfile) modules. Note, however, that unlike the tt(-h) flag this is also useful for non-special parameters. @@ -2291,8 +2341,10 @@ readonly). Special variables that have been made readonly retain their value and readonly attribute when made local. ) item(tt(-t))( -Tags the named parameters. Tags have no special meaning to the shell. -This flag has a different meaning when used with tt(-f); see above. +Tags the named parameters. Tags only exist to flag the parameter for +the user's own purposes --- the list of tagged parameters can be queried +using `tt(typeset -t)'. Tags have no other use. Note that the tt(-t) +flag has a different meaning when used with tt(-f); see above. ) item(tt(-u))( Convert the result to upper case whenever the parameter is expanded. @@ -2382,6 +2434,7 @@ 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. ) +findex(unalias) cindex(aliases, removing) item(tt(unalias) [ tt(-ams) ] var(name) ...)( Removes aliases. This command works the same as tt(unhash -a), except that @@ -2423,7 +2476,7 @@ with the command `tt(zmodload -F zsh/rlimits b:unlimit)'. ) findex(unset) cindex(parameters, unsetting) -item(tt(unset) [ tt(-fmv) ] var(name) ...)( +item(tt(unset) [ tt(-fmv) ] [ tt(-n) ] 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. @@ -2437,10 +2490,13 @@ be quoted) and all parameters with matching names are unset. Note that this cannot be used when unsetting associative array elements, as the subscript will be treated as part of the pattern. -The tt(-v) flag specifies that var(name) refers to parameters. This is the -default behaviour. +The tt(-v) flag specifies that var(name) refers to parameters. This is +the default behaviour. If the tt(-n) option is supplied, and +var(name) is a a named reference, var(name) will be unset rather than +the variable it references. -tt(unset -f) is equivalent to tt(unfunction). +tt(unset -f) is equivalent to tt(unfunction). The tt(-n) option has +no effect with tt(-f). ) findex(unsetopt) cindex(options, unsetting) |