diff options
Diffstat (limited to 'Doc/Zsh/builtins.yo')
| -rw-r--r-- | Doc/Zsh/builtins.yo | 149 |
1 files changed, 118 insertions, 31 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 733d8f185..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, @@ -756,15 +757,16 @@ specifies the most recent event beginning with the given string. All substitutions var(old)tt(=)var(new), if any, are then performed on the text of the events. -In addition to the number range, +The range of events selected by numbers can be narrowed further by the +following flags. startsitem() sitem(tt(-I))(restricts to only internal events (not from tt($HISTFILE))) sitem(tt(-L))(restricts to only local events (not from other shells, see tt(SHARE_HISTORY) in ifzman(zmanref(zshoptions))\ ifnzman(noderef(Description of Options)) -- note that tt($HISTFILE) is considered local when read at startup)) -sitem(tt(-m))(takes the first argument as a pattern (should be quoted) and -only the history events matching this pattern are considered) +sitem(tt(-m))(takes the first argument as a pattern (which should be +quoted) and only the history events matching this pattern are considered) endsitem() If var(first) is not specified, it will be set to -1 (the most recent @@ -873,7 +875,8 @@ xitem(tt(functions -M) [ tt(-m) var(pattern) ... ]) item(tt(functions +M) [ tt(-m) ] var(mathfn) ... )( Equivalent to tt(typeset -f), with the exception of the tt(-c), tt(-x), tt(-M) and tt(-W) options. For tt(functions -u) and tt(functions -U), -see tt(autoload), which provides additional options. +see tt(autoload), which provides additional options. For tt(functions -t) +and tt(functions -T), see tt(typeset -f). The tt(-x) option indicates that any functions output will have each leading tab for indentation, added by the shell to show syntactic @@ -1050,9 +1053,11 @@ 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. -A command var(name) starting with a tt(/) is never hashed, whether by -explicit use of the tt(hash) command or otherwise. Such a command -is always found by direct look up in the file system. +A command var(name) starting with a tt(/) or with a relative path +starting with tt(./) or tt(../) is never executed by lookup in +the command hash table, and these can only be added to the table by +explicit use of the tt(hash) command. Such a command is always +found by direct look up in the file system. Given no arguments, and neither the tt(-r) or tt(-f) options, the selected hash table will be listed in full. @@ -1061,9 +1066,11 @@ 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. +all (and em(only)) 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. +Both options remove any explicitly-added elements. The tt(-m) option causes the arguments to be taken as patterns (which should be quoted) and the elements of the hash table @@ -1113,13 +1120,32 @@ 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. + +Full job control is only available in the top-level interactive shell, +not in commands run in the left hand side of pipelines or within +the tt(LPAR())var(...)tt(RPAR()) construct. However, a snapshot +of the job state at that point is taken, so it is still possible +to use the tt(jobs) builtin, or any parameter providing job information. +This gives information about the state of jobs at the point the subshell +was created. If background processes are created within the subshell, +then instead information about those processes is provided. + +For example, + +example(sleep 10 & # Job in background +LPAR() # Shell forks +jobs # Shows information about "sleep 10 &" +sleep 5 & # Process in background (no job control) +jobs # Shows information about "sleep 5 &" +RPAR()) ) 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)' @@ -1133,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 @@ -1145,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) ...)( @@ -1565,7 +1595,8 @@ Input is read from the coprocess. ) item(tt(-d) var(delim))( Input is terminated by the first character of var(delim) instead of -by newline. +by newline. For compatibility with other shells, if var(delim) is an +empty string, input is terminated at the first NUL. ) item(tt(-t) [ var(num) ])( Test if input is available before attempting to read. If var(num) @@ -1608,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 @@ -1619,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" } @@ -1885,7 +1919,8 @@ unfreezing the tty does not guarantee settings made on the command line are preserved. Strings of commands run between editing the command line will see a consistent tty state. See also the shell variable tt(STTY) for a means of initialising -the tty before running external commands. +the tty before running external commands and/or freezing the tty +around a single command. ) findex(type) item(tt(type) [ tt(-wfpamsS) ] var(name) ...)( @@ -1898,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) ... ])( @@ -1915,7 +1952,7 @@ retain their special attributes when made local. For each var(name)tt(=)var(value) assignment, the parameter var(name) is set to var(value). If the assignment is omitted and var(name) -does em(not) refer to an existing parameter, a new parameter is intialized +does em(not) refer to an existing parameter, a new parameter is initialized to empty string, zero, or empty array (as appropriate), em(unless) the shell option tt(TYPESET_TO_UNSET) is set. When that option is set, the parameter attributes are recorded but the parameter remains unset. @@ -2011,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), @@ -2026,8 +2093,9 @@ startitem() item(tt(PLUS()))( If `tt(PLUS())' appears by itself in a separate word as the last option, then the names of all parameters (functions with tt(-f)) are printed, but -the values (function bodies) are not. No var(name) arguments may appear, -and it is an error for any other options to follow `tt(PLUS())'. The +the values (function bodies) are not. If var(name) arguments appear, +both those names and their values are printed in the form of assignments. +It is an error for any other options to follow `tt(PLUS())', but the effect of `tt(PLUS())' is as if all attribute flags which precede it were given with a `tt(PLUS())' prefix. For example, `tt(typeset -U PLUS())' is equivalent to `tt(typeset +U)' and displays the names of all arrays having @@ -2054,13 +2122,15 @@ 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, even inside a function. Note that tt(-m) is ignored if no patterns are given, so `tt(typeset -m)' displays attributes but `tt(typeset -a +m)' -does not. +does not. Ordinary scalar string parameters have no attributes, so for +those tt(+m) prints only the names. ) item(tt(-p) [ var(n) ])( If the tt(-p) option is given, parameters and values are printed in the @@ -2072,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. @@ -2214,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. @@ -2263,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. @@ -2354,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 @@ -2395,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. @@ -2409,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) @@ -2500,11 +2584,14 @@ item(tt(-a))( Do a search for all occurrences of var(name) throughout the command path. Normally only the first occurrence is printed. +When combined with tt(-m), only names appearing in the command hash +table are searched, but all occurrences of those names are printed. ) item(tt(-m))( The arguments are taken as patterns (pattern characters should be -quoted), and the information is displayed for each command matching one -of these patterns. +quoted), and the information is displayed for each entry in the command +hash table matching one of these patterns. The hash table is first +refilled, in case of changes to tt(PATH). ) item(tt(-s))( If a pathname contains symlinks, print the symlink-free pathname as well. |