diff options
Diffstat (limited to 'Doc/Zsh/builtins.yo')
| -rw-r--r-- | Doc/Zsh/builtins.yo | 230 |
1 files changed, 155 insertions, 75 deletions
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 46f40cc3a..c4acf7672 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -54,13 +54,13 @@ in a group before any non-option arguments; once the first non-option argument has been found, option processing is terminated. All builtin commands other than precommand modifiers, even those that -have no options, can be given the argument `tt(--)' to terminate option +have no options, can be given the argument `tt(-)tt(-)' to terminate option processing. This indicates that the following words are non-option arguments, but is otherwise ignored. This is useful in cases where arguments to the command may begin with `tt(-)'. For historical reasons, most builtin commands also recognize a single `tt(-)' in a separate word for this purpose; note that this is less standard and -use of `tt(--) is recommended. +use of `tt(-)tt(-)' is recommended. startitem() prefix(-) @@ -142,7 +142,7 @@ ifnzman(noderef(Aliasing)). findex(autoload) cindex(functions, autoloading) cindex(autoloading functions) -item(tt(autoload) [ {tt(PLUS())|tt(-)}tt(UXkmtz) ] [ tt(-w) ] [ var(name) ... ])( +item(tt(autoload) [ {tt(PLUS())|tt(-)}tt(TUXkmtz) ] [ tt(-w) ] [ var(name) ... ])( Equivalent to tt(functions -u), with the exception of tt(-X)/tt(+X) and tt(-w). @@ -198,7 +198,7 @@ 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) +tt(until), tt(select) or tt(repeat) loop. If an arithmetic expression var(n) is specified, then break var(n) levels instead of just one. ) findex(builtin) @@ -291,7 +291,7 @@ 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 +tt(repeat) loop. If an arithmetic expression var(n) is specified, break out of var(n)-1 loops and resume at the var(n)th enclosing loop. ) alias(declare)(typeset) @@ -615,16 +615,21 @@ the same as if the commands had been executed directly by the shell; if there are no var(args) or they contain no commands (i.e. are an empty string or whitespace) the return status is zero. ) -item(tt(exec) [ tt(-cl) ] [ tt(-a) var(argv0) ] var(simple command))( -Replace the current shell with an external command rather than forking. +item(tt(exec) [ tt(-cl) ] [ tt(-a) var(argv0) ] [ var(command) [ var(arg) ... ]])( +Replace the current shell with an external var(command) rather than forking. With tt(-c) clear the environment; with tt(-l) prepend tt(-) to the tt(argv[0]) string of the command executed (to simulate a login shell); with tt(-a) var(argv0) set the tt(argv[0]) string of the command executed. See noderef(Precommand Modifiers). + +cindex(redirection, current shell's I/O) +If var(command) is omitted but any redirections are specified, +then the redirections will take effect in the current shell. ) findex(exit) item(tt(exit) [ var(n) ])( -Exit the shell with the exit status specified by var(n); if none +Exit the shell with the exit status specified by an arithmetic +expression var(n); if none is specified, use the exit status from the last command executed. pindex(IGNORE_EOF, use of) An EOF condition will also cause the shell to exit, unless @@ -657,6 +662,12 @@ xitem(tt( )[ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ]) xitem(tt(fc) tt(-p) [ tt(-a) ] [ var(filename) [ var(histsize) [ var(savehistsize) ] ] ]) xitem(tt(fc) tt(-P)) item(tt(fc) tt(-ARWI) [ var(filename) ])( +The tt(fc) command controls the interactive history mechanism. Note +that reading and writing of history options is only performed if the +shell is interactive. Usually this is detected automatically, but +it can be forced by setting the tt(interactive) option when starting the +shell. + 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 @@ -1088,10 +1099,13 @@ item( [ tt(-R) [ tt(-en) ]] [ var(arg) ... ])( With the `tt(-f)' option the arguments are printed as described by tt(printf). With no flags or with the 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 +the escape sequence `tt(\M-)var(x)' (or `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)'. +`tt(\C-)var(x)' (or `tt(\C)var(x)') produces a control character +(`tt(\C-@)' and `tt(\C-?)' give the characters NULL and delete), +a character code in octal is represented by `tt(\)var(NNN)' +(instead of `tt(\0)var(NNN)'), +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. @@ -1294,10 +1308,10 @@ 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 status is zero only if the character was -`tt(y)' or `tt(Y)'. This option may be used with a timeout; if -the read times out, or encounters end of file, status 2 is returned. -Input is read from the terminal unless one of tt(-u) -or tt(-p) is present. This option may also be used within zle widgets. +`tt(y)' or `tt(Y)'. This option may be used with a timeout (see tt(-t)); if +the read times out, or encounters end of file, status 2 is returned. Input is +read from the terminal unless one of tt(-u) or tt(-p) is present. This option +may also be used within zle widgets. ) item(tt(-k) [ var(num) ])( Read only one (or var(num)) characters. All are assigned to the first @@ -1400,7 +1414,8 @@ 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) +the invoking script with the return status specified by +an arithmetic expression var(n). If var(n) is omitted, the return status is that of the last command executed. @@ -1661,7 +1676,7 @@ See also the shell variable tt(STTY) for a means of initialising the tty before running external commands. ) findex(type) -item(tt(type) [ tt(-wfpams) ] var(name) ...)( +item(tt(type) [ tt(-wfpamsS) ] var(name) ...)( Equivalent to tt(whence -v). ) findex(typeset) @@ -1702,66 +1717,98 @@ newly-created parameters, or when any attribute flags listed below are given along with the var(name). Using `tt(PLUS())' instead of minus to introduce an attribute turns it off. -If the tt(-p) option is given, parameters and values are printed in the -form of a typeset command and an assignment (which will be printed -separately for arrays and associative arrays), regardless of other flags -and options. Note that the tt(-h) flag on parameters is respected; no -value will be shown for these parameters. - -If the tt(-T) option is given, two or three arguments must be present (an -exception is that zero arguments are allowed to show the list of parameters -created in this fashion). The first two are the name of a scalar and an -array parameter (in that order) that will be tied together in the manner of -tt($PATH) and tt($path). The optional third argument is a single-character -separator which will be used to join the elements of the array to form the -scalar; if absent, a colon is used, as with tt($PATH). Only the first -character of the separator is significant; any remaining characters are -ignored. Only the scalar parameter may be assigned an initial value. Both -the scalar and the array may otherwise be manipulated as normal. If one is -unset, the other will automatically be unset too. There is no way of -untying the variables without unsetting them, or converting the type of one -of them with another tt(typeset) command; tt(+T) does not work, assigning -an array to var(SCALAR) is an error, and assigning a scalar to var(array) -sets it to be a single-element array. Note that both `tt(typeset -xT ...)' -and `tt(export -T ...)' work, but only the scalar will be marked for -export. Setting the value using the scalar version causes a split on all -separators (which cannot be quoted). It is possible to use the -same two tied variables with a different separator character in which -case the variables remain joined as before but the separator is changed. -This flag has a different meaning when used with tt(-f); see below. - -The tt(-g) (global) flag is treated specially: it means that any -resulting parameter will not be restricted to local scope. Note that this -does not necessarily mean that the parameter will be global, as the flag -will apply to any existing parameter (even if unset) from an enclosing -function. This flag does not affect the parameter after creation, hence it -has no effect when listing existing parameters, nor does the flag tt(+g) -have any effect except in combination with tt(-m) (see below). - If no var(name) is present, the names and values of all parameters are printed. In this case the attribute flags restrict the display to only those parameters that have the specified attributes, and using `tt(PLUS())' rather than `tt(-)' to introduce the flag suppresses printing of the values -of parameters when there is no parameter name. Also, if the last option -is the word `tt(PLUS())', then names are printed but values are not. +of parameters when there is no parameter 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), +tt(association), tt(exported), tt(float), tt(integer), tt(readonly), +or tt(undefined) for autoloaded parameters not yet loaded). If tt(+m) is +used with attribute flags, and all those flags are introduced with +tt(PLUS()), the matching parameter names are printed but their values +are not. + +The following control flags change the behavior of tt(typeset): +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 +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 +the uniqueness attribute, whereas `tt(typeset -f -U PLUS())' displays the +names of all autoloadable functions. If tt(PLUS()) is the only option, +then type information (array, readonly, etc.) is also printed for each +parameter, in the same manner as `tt(typeset +m "*")'. +) +item(tt(-g))( +The tt(-g) (global) means that any resulting parameter will not be +restricted to local scope. Note that this does not necessarily mean that +the parameter will be global, as the flag will apply to any existing +parameter (even if unset) from an enclosing function. This flag does not +affect the parameter after creation, hence it has no effect when listing +existing parameters, nor does the flag tt(+g) have any effect except in +combination with tt(-m) (see below). +) +item(tt(-m))( If the tt(-m) flag is given the var(name) arguments are taken as patterns -(which should be quoted). With no attribute flags, all parameters (or -functions with the tt(-f) flag) with matching names are printed (the shell -option tt(TYPESET_SILENT) is not used in this case). Note that tt(-m) is -ignored if no patterns are given. 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. Except when assignments are made -with var(name)tt(=)var(value), using tt(+m) forces the matching parameters -to be printed, even inside a function. - -If no attribute flags are given and either no tt(-m) flag is present or -the tt(+m) form was used, each parameter name printed is preceded by a -list of the attributes of that parameter (tt(array), tt(association), -tt(exported), tt(integer), tt(readonly)). If tt(+m) is used with attribute -flags, and all those flags are introduced with tt(PLUS()), the matching -parameter names are printed but their values are not. +(use quoting to prevent these from being interpreted as file patterns). +With no attribute flags, all parameters (or functions with the tt(-f) +flag) with matching names are printed (the shell option tt(TYPESET_SILENT) +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. + +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. +) +item(tt(-p))( +If the tt(-p) option is given, parameters and values are printed in the +form of a typeset command and an assignment (which will be printed +separately for arrays and associative arrays), regardless of other flags +and options. Note that the tt(-H) flag on parameters is respected; no +value will be shown for these parameters. +) +item(tt(-T) [ var(scalar)[tt(=)var(value)] var(array) [ var(sep) ] ])( +This flag has a different meaning when used with tt(-f); see below. +Otherwise the tt(-T) option requires zero, two, or three arguments to be +present. With no arguments, the list of parameters created in this +fashion is shown. With two or three arguments, the first two are the name +of a scalar and of an array parameter (in that order) that will be tied +together in the manner of tt($PATH) and tt($path). The optional third +argument is a single-character separator which will be used to join the +elements of the array to form the scalar; if absent, a colon is used, as +with tt($PATH). Only the first character of the separator is significant; +any remaining characters are ignored. + +Only the scalar parameter may be assigned an initial value. Both the +scalar and the array may otherwise be manipulated as normal. If one is +unset, the other will automatically be unset too. There is no way of +untying the variables without unsetting them, nor of converting the type +of one of them with another tt(typeset) command; tt(+T) does not work, +assigning an array to var(scalar) is an error, and assigning a scalar to +var(array) sets it to be a single-element array. + +Note that both `tt(typeset -xT ...)' and `tt(export -T ...)' work, but +only the scalar will be marked for export. Setting the value using the +scalar version causes a split on all separators (which cannot be quoted). +It is possible to apply tt(-T) to two previously tied variables but with a +different separator character, in which case the variables remain joined +as before but the separator is changed. +) +enditem() Attribute flags that transform the final value (tt(-L), tt(-R), tt(-Z), tt(-l), tt(u)) are only applied to the expanded value at the point @@ -1892,6 +1939,13 @@ item(tt(-r))( The given var(name)s are marked readonly. Note that if var(name) is a special parameter, the readonly attribute can be turned on, but cannot then be turned off. + +If the tt(POSIX_BUILTINS) option is set, the readonly attribute is +more restrictive: unset variables can be marked readonly and cannot then +be set; furthermore, the readonly attribute cannot be removed from any +variable. Note that in zsh (unlike other shells) it is still possible +to create a local variable of the same name as this is considered a +different variable (though this variable, too, can be marked readonly). ) item(tt(-t))( Tags the named parameters. Tags have no special meaning to the shell. @@ -2059,12 +2113,33 @@ 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. + +It is possible to wait for recent processes (specified by process ID, +not by job) that were running in the background even if the process has +exited. Typically the process ID will be recorded by capturing the +value of the variable tt($!) immediately after the process has been +started. There is a limit on the number of process IDs remembered by +the shell; this is given by the value of the system configuration +parameter tt(CHILD_MAX). When this limit is reached, older process IDs +are discarded, least recently started processes first. + +Note there is no protection against the process ID wrapping, i.e. if the +wait is not executed soon enough there is a chance the process waited +for is the wrong one. A conflict implies both process IDs have been +generated by the shell, as other processes are not recorded, and that +the user is potentially interested in both, so this problem is intrinsic +to process IDs. ) findex(whence) -item(tt(whence) [ tt(-vcwfpams) ] var(name) ...)( +item(tt(whence) [ tt(-vcwfpamsS) ] var(name) ...)( For each name, indicate how it would be interpreted if used as a command name. +tt(whence) is most useful when var(name) is only the last path component +of a command, i.e. does not include a `tt(/)'; in particular, pattern +matching only succeeds if just the non-directory component of the command is +passed. + startitem() item(tt(-v))( Produce a more verbose report. @@ -2097,21 +2172,26 @@ throughout the command path. Normally only the first occurrence is printed. ) item(tt(-m))( -The arguments are taken as patterns (should be +The arguments are taken as patterns (pattern characters should be quoted), and the information is displayed for each command matching one of these patterns. ) item(tt(-s))( If a pathname contains symlinks, print the symlink-free pathname as well. ) +item(tt(-S))( +As tt(-s), but if the pathname had to be resolved by following +multiple symlinks, the intermediate steps are printed, too. The +symlink resolved at each step might be anywhere in the path. +) enditem() ) findex(where) -item(tt(where) [ tt(-wpms) ] var(name) ...)( +item(tt(where) [ tt(-wpmsS) ] var(name) ...)( Equivalent to tt(whence -ca). ) findex(which) -item(tt(which) [ tt(-wpams) ] var(name) ...)( +item(tt(which) [ tt(-wpamsS) ] var(name) ...)( Equivalent to tt(whence -c). ) findex(zcompile) |