1ZSHPARAM(1) General Commands Manual ZSHPARAM(1)
2
6 zshparam - zsh parameters
7
9 A parameter has a name, a value, and a number of attributes. A name
10 may be any sequence of alphanumeric characters and underscores, or the
11 single characters `*', `@', `#', `?', `-', `$', or `!'. The value may
12 be a scalar (a string), an integer, an array (indexed numerically), or
13 an associative array (an unordered set of name-value pairs, indexed by
14 name). To declare the type of a parameter, or to assign a scalar or
15 integer value to a parameter, use the typeset builtin.
16 The value of a scalar or integer parameter may also be assigned by
18 writing:
19 name=value
21 If the integer attribute, -i, is set for name, the value is subject to
23 arithmetic evaluation. Furthermore, by replacing `=' with `+=', a
24 parameter can be added or appended to. See the section `Array Parame‐
25 ters' for additional forms of assignment.
26 To refer to the value of a parameter, write `$name' or `${name}'. See
28 Parameter Expansion in zshexpn(1) for complete details.
29 In the parameter lists that follow, the mark `<S>' indicates that the
31 parameter is special. Special parameters cannot have their type
32 changed or their readonly attribute turned off, and if a special param‐
33 eter is unset, then later recreated, the special properties will be
34 retained. `<Z>' indicates that the parameter does not exist when the
35 shell initializes in sh or ksh emulation mode.
36
38 To assign an array value, write one of:
39 set -A name value ...
41 name=(value ...)
42 If no parameter name exists, an ordinary array parameter is created.
44 If the parameter name exists and is a scalar, it is replaced by a new
45 array. Ordinary array parameters may also be explicitly declared with:
46 typeset -a name
48 Associative arrays must be declared before assignment, by using:
50 typeset -A name
52 When name refers to an associative array, the list in an assignment is
54 interpreted as alternating keys and values:
55 set -A name key value ...
57 name=(key value ...)
58 Every key must have a value in this case. Note that this assigns to
60 the entire array, deleting any elements that do not appear in the list.
61 To create an empty array (including associative arrays), use one of:
63 set -A name
65 name=()
66 Array Subscripts
68 Individual elements of an array may be selected using a subscript. A
69 subscript of the form `[exp]' selects the single element exp, where exp
70 is an arithmetic expression which will be subject to arithmetic expan‐
71 sion as if it were surrounded by `$((...))'. The elements are numbered
72 beginning with 1, unless the KSH_ARRAYS option is set in which case
73 they are numbered from zero.
74 Subscripts may be used inside braces used to delimit a parameter name,
76 thus `${foo[2]}' is equivalent to `$foo[2]'. If the KSH_ARRAYS option
77 is set, the braced form is the only one that works, as bracketed
78 expressions otherwise are not treated as subscripts.
79 If the KSH_ARRAYS option is not set, then by default accesses to an
81 array element with a subscript that evaluates to zero return an empty
82 string, while an attempt to write such an element is treated as an
83 error. For backward compatibility the KSH_ZERO_SUBSCRIPT option can be
84 set to cause subscript values 0 and 1 to be equivalent; see the
85 description of the option in zshoptions(1).
86 The same subscripting syntax is used for associative arrays, except
88 that no arithmetic expansion is applied to exp. However, the parsing
89 rules for arithmetic expressions still apply, which affects the way
90 that certain special characters must be protected from interpretation.
91 See Subscript Parsing below for details.
92 A subscript of the form `[*]' or `[@]' evaluates to all elements of an
94 array; there is no difference between the two except when they appear
95 within double quotes. `"$foo[*]"' evaluates to `"$foo[1] $foo[2]
96 ..."', whereas `"$foo[@]"' evaluates to `"$foo[1]" "$foo[2]" ...'. For
97 associative arrays, `[*]' or `[@]' evaluate to all the values, in no
98 particular order. Note that this does not substitute the keys; see the
99 documentation for the `k' flag under Parameter Expansion Flags in zsh‐
100 expn(1) for complete details. When an array parameter is referenced as
101 `$name' (with no subscript) it evaluates to `$name[*]', unless the
102 KSH_ARRAYS option is set in which case it evaluates to `${name[0]}'
103 (for an associative array, this means the value of the key `0', which
104 may not exist even if there are values for other keys).
105 A subscript of the form `[exp1,exp2]' selects all elements in the range
107 exp1 to exp2, inclusive. (Associative arrays are unordered, and so do
108 not support ranges.) If one of the subscripts evaluates to a negative
109 number, say -n, then the nth element from the end of the array is used.
110 Thus `$foo[-3]' is the third element from the end of the array foo, and
111 `$foo[1,-1]' is the same as `$foo[*]'.
112 Subscripting may also be performed on non-array values, in which case
114 the subscripts specify a substring to be extracted. For example, if
115 FOO is set to `foobar', then `echo $FOO[2,5]' prints `ooba'.
116 Array Element Assignment
118 A subscript may be used on the left side of an assignment like so:
119 name[exp]=value
121 In this form of assignment the element or range specified by exp is
123 replaced by the expression on the right side. An array (but not an
124 associative array) may be created by assignment to a range or element.
125 Arrays do not nest, so assigning a parenthesized list of values to an
126 element or range changes the number of elements in the array, shifting
127 the other elements to accommodate the new values. (This is not sup‐
128 ported for associative arrays.)
129 This syntax also works as an argument to the typeset command:
131 typeset "name[exp]"=value
133 The value may not be a parenthesized list in this case; only sin‐
135 gle-element assignments may be made with typeset. Note that quotes are
136 necessary in this case to prevent the brackets from being interpreted
137 as filename generation operators. The noglob precommand modifier could
138 be used instead.
139 To delete an element of an ordinary array, assign `()' to that element.
141 To delete an element of an associative array, use the unset command:
142 unset "name[exp]"
144 Subscript Flags
146 If the opening bracket, or the comma in a range, in any subscript
147 expression is directly followed by an opening parenthesis, the string
148 up to the matching closing one is considered to be a list of flags, as
149 in `name[(flags)exp]'.
150 The flags s, n and b take an argument; the delimiter is shown below as
152 `:', but any character, or the matching pairs `(...)', `{...}',
153 `[...]', or `<...>', may be used, but note that `<...>' can only be
154 used if the subscript is inside a double quoted expression or a parame‐
155 ter substitution enclosed in braces as otherwise the expression is
156 interpreted as a redirection.
157 The flags currently understood are:
159 w If the parameter subscripted is a scalar then this flag makes
161 subscripting work on words instead of characters. The default
162 word separator is whitespace. This flag may not be used with
163 the i or I flag.
164 s:string:
166 This gives the string that separates words (for use with the w
167 flag). The delimiter character : is arbitrary; see above.
168 p Recognize the same escape sequences as the print builtin in the
170 string argument of a subsequent `s' flag.
171 f If the parameter subscripted is a scalar then this flag makes
173 subscripting work on lines instead of characters, i.e. with ele‐
174 ments separated by newlines. This is a shorthand for `pws:\n:'.
175 r Reverse subscripting: if this flag is given, the exp is taken as
177 a pattern and the result is the first matching array element,
178 substring or word (if the parameter is an array, if it is a
179 scalar, or if it is a scalar and the `w' flag is given, respec‐
180 tively). The subscript used is the number of the matching ele‐
181 ment, so that pairs of subscripts such as `$foo[(r)??,3]' and
182 `$foo[(r)??,(r)f*]' are possible if the parameter is not an
183 associative array. If the parameter is an associative array,
184 only the value part of each pair is compared to the pattern, and
185 the result is that value.
186 If a search through an ordinary array failed, the search sets
188 the subscript to one past the end of the array, and hence
189 ${array[(r)pattern]} will substitute the empty string. Thus the
190 success of a search can be tested by using the (i) flag, for
191 example (assuming the option KSH_ARRAYS is not in effect):
192 [[ ${array[(i)pattern]} -le ${#array} ]]
194 If KSH_ARRAYS is in effect, the -le should be replaced by -lt.
196 R Like `r', but gives the last match. For associative arrays,
198 gives all possible matches. May be used for assigning to ordi‐
199 nary array elements, but not for assigning to associative
200 arrays. On failure, for normal arrays this has the effect of
201 returning the element corresponding to subscript 0; this is
202 empty unless one of the options KSH_ARRAYS or KSH_ZERO_SUBSCRIPT
203 is in effect.
204 Note that in subscripts with both `r' and `R' pattern characters
206 are active even if they were substituted for a parameter
207 (regardless of the setting of GLOB_SUBST which controls this
208 feature in normal pattern matching). The flag `e' can be added
209 to inhibit pattern matching. As this flag does not inhibit
210 other forms of substitution, care is still required; using a
211 parameter to hold the key has the desired effect:
212 key2='original key'
214 print ${array[(Re)$key2]}
215 i Like `r', but gives the index of the match instead; this may not
217 be combined with a second argument. On the left side of an
218 assignment, behaves like `r'. For associative arrays, the key
219 part of each pair is compared to the pattern, and the first
220 matching key found is the result. On failure substitutes the
221 length of the array plus one, as discussed under the description
222 of `r', or the empty string for an associative array.
223 I Like `i', but gives the index of the last match, or all possible
225 matching keys in an associative array. On failure substitutes
226 0, or the empty string for an associative array. This flag is
227 best when testing for values or keys that do not exist.
228 k If used in a subscript on an associative array, this flag causes
230 the keys to be interpreted as patterns, and returns the value
231 for the first key found where exp is matched by the key. Note
232 this could be any such key as no ordering of associative arrays
233 is defined. This flag does not work on the left side of an
234 assignment to an associative array element. If used on another
235 type of parameter, this behaves like `r'.
236 K On an associative array this is like `k' but returns all values
238 where exp is matched by the keys. On other types of parameters
239 this has the same effect as `R'.
240 n:expr:
242 If combined with `r', `R', `i' or `I', makes them give the nth
243 or nth last match (if expr evaluates to n). This flag is
244 ignored when the array is associative. The delimiter character
245 : is arbitrary; see above.
246 b:expr:
248 If combined with `r', `R', `i' or `I', makes them begin at the
249 nth or nth last element, word, or character (if expr evaluates
250 to n). This flag is ignored when the array is associative. The
251 delimiter character : is arbitrary; see above.
252 e This flag causes any pattern matching that would be performed on
254 the subscript to use plain string matching instead. Hence
255 `${array[(re)*]}' matches only the array element whose value is
256 *. Note that other forms of substitution such as parameter sub‐
257 stitution are not inhibited.
258 This flag can also be used to force * or @ to be interpreted as
260 a single key rather than as a reference to all values. It may
261 be used for either purpose on the left side of an assignment.
262 See Parameter Expansion Flags (zshexpn(1)) for additional ways to
264 manipulate the results of array subscripting.
265 Subscript Parsing
267 This discussion applies mainly to associative array key strings and to
268 patterns used for reverse subscripting (the `r', `R', `i', etc. flags),
269 but it may also affect parameter substitutions that appear as part of
270 an arithmetic expression in an ordinary subscript.
271 It is possible to avoid the use of subscripts in assignments to asso‐
273 ciative array elements by using the syntax:
274 aa+=('key with "*strange*" characters' 'value string')
276 This adds a new key/value pair if the key is not already present, and
278 replaces the value for the existing key if it is.
279 The basic rule to remember when writing a subscript expression is that
281 all text between the opening `[' and the closing `]' is interpreted as
282 if it were in double quotes (see zshmisc(1)). However, unlike double
283 quotes which normally cannot nest, subscript expressions may appear
284 inside double-quoted strings or inside other subscript expressions (or
285 both!), so the rules have two important differences.
286 The first difference is that brackets (`[' and `]') must appear as bal‐
288 anced pairs in a subscript expression unless they are preceded by a
289 backslash (`\'). Therefore, within a subscript expression (and unlike
290 true double-quoting) the sequence `\[' becomes `[', and similarly `\]'
291 becomes `]'. This applies even in cases where a backslash is not nor‐
292 mally required; for example, the pattern `[^[]' (to match any character
293 other than an open bracket) should be written `[^\[]' in a reverse-sub‐
294 script pattern. However, note that `\[^\[\]' and even `\[^[]' mean the
295 same thing, because backslashes are always stripped when they appear
296 before brackets!
297 The same rule applies to parentheses (`(' and `)') and braces (`{' and
299 `}'): they must appear either in balanced pairs or preceded by a back‐
300 slash, and backslashes that protect parentheses or braces are removed
301 during parsing. This is because parameter expansions may be surrounded
302 by balanced braces, and subscript flags are introduced by balanced
303 parentheses.
304 The second difference is that a double-quote (`"') may appear as part
306 of a subscript expression without being preceded by a backslash, and
307 therefore that the two characters `\"' remain as two characters in the
308 subscript (in true double-quoting, `\"' becomes `"'). However, because
309 of the standard shell quoting rules, any double-quotes that appear must
310 occur in balanced pairs unless preceded by a backslash. This makes it
311 more difficult to write a subscript expression that contains an odd
312 number of double-quote characters, but the reason for this difference
313 is so that when a subscript expression appears inside true dou‐
314 ble-quotes, one can still write `\"' (rather than `\\\"') for `"'.
315 To use an odd number of double quotes as a key in an assignment, use
317 the typeset builtin and an enclosing pair of double quotes; to refer to
318 the value of that key, again use double quotes:
319 typeset -A aa
321 typeset "aa[one\"two\"three\"quotes]"=QQQ
322 print "$aa[one\"two\"three\"quotes]"
323 It is important to note that the quoting rules do not change when a
325 parameter expansion with a subscript is nested inside another subscript
326 expression. That is, it is not necessary to use additional backslashes
327 within the inner subscript expression; they are removed only once, from
328 the innermost subscript outwards. Parameters are also expanded from
329 the innermost subscript first, as each expansion is encountered left to
330 right in the outer expression.
331 A further complication arises from a way in which subscript parsing is
333 not different from double quote parsing. As in true double-quoting,
334 the sequences `\*', and `\@' remain as two characters when they appear
335 in a subscript expression. To use a literal `*' or `@' as an associa‐
336 tive array key, the `e' flag must be used:
337 typeset -A aa
339 aa[(e)*]=star
340 print $aa[(e)*]
341 A last detail must be considered when reverse subscripting is per‐
343 formed. Parameters appearing in the subscript expression are first
344 expanded and then the complete expression is interpreted as a pattern.
345 This has two effects: first, parameters behave as if GLOB_SUBST were on
346 (and it cannot be turned off); second, backslashes are interpreted
347 twice, once when parsing the array subscript and again when parsing the
348 pattern. In a reverse subscript, it's necessary to use four back‐
349 slashes to cause a single backslash to match literally in the pattern.
350 For complex patterns, it is often easiest to assign the desired pattern
351 to a parameter and then refer to that parameter in the subscript,
352 because then the backslashes, brackets, parentheses, etc., are seen
353 only when the complete expression is converted to a pattern. To match
354 the value of a parameter literally in a reverse subscript, rather than
355 as a pattern, use `${(q)name}' (see zshexpn(1)) to quote the expanded
356 value.
357 Note that the `k' and `K' flags are reverse subscripting for an ordi‐
359 nary array, but are not reverse subscripting for an associative array!
360 (For an associative array, the keys in the array itself are interpreted
361 as patterns by those flags; the subscript is a plain string in that
362 case.)
363 One final note, not directly related to subscripting: the numeric names
365 of positional parameters (described below) are parsed specially, so for
366 example `$2foo' is equivalent to `${2}foo'. Therefore, to use sub‐
367 script syntax to extract a substring from a positional parameter, the
368 expansion must be surrounded by braces; for example, `${2[3,5]}' evalu‐
369 ates to the third through fifth characters of the second positional
370 parameter, but `$2[3,5]' is the entire second parameter concatenated
371 with the filename generation pattern `[3,5]'.
372
374 The positional parameters provide access to the command-line arguments
375 of a shell function, shell script, or the shell itself; see the section
376 `Invocation', and also the section `Functions'. The parameter n, where
377 n is a number, is the nth positional parameter. The parameters *, @
378 and argv are arrays containing all the positional parameters; thus
379 `$argv[n]', etc., is equivalent to simply `$n'.
380 Positional parameters may be changed after the shell or function starts
382 by using the set builtin, by assigning to the argv array, or by direct
383 assignment of the form `n=value' where n is the number of the posi‐
384 tional parameter to be changed. This also creates (with empty values)
385 any of the positions from 1 to n that do not already have values. Note
386 that, because the positional parameters form an array, an array assign‐
387 ment of the form `n=(value ...)' is allowed, and has the effect of
388 shifting all the values at positions greater than n by as many posi‐
389 tions as necessary to accommodate the new values.
390
392 Shell function executions delimit scopes for shell parameters. (Param‐
393 eters are dynamically scoped.) The typeset builtin, and its alterna‐
394 tive forms declare, integer, local and readonly (but not export), can
395 be used to declare a parameter as being local to the innermost scope.
396 When a parameter is read or assigned to, the innermost existing parame‐
398 ter of that name is used. (That is, the local parameter hides any
399 less-local parameter.) However, assigning to a non-existent parameter,
400 or declaring a new parameter with export, causes it to be created in
401 the outermost scope.
402 Local parameters disappear when their scope ends. unset can be used to
404 delete a parameter while it is still in scope; any outer parameter of
405 the same name remains hidden.
406 Special parameters may also be made local; they retain their special
408 attributes unless either the existing or the newly-created parameter
409 has the -h (hide) attribute. This may have unexpected effects: there
410 is no default value, so if there is no assignment at the point the
411 variable is made local, it will be set to an empty value (or zero in
412 the case of integers). The following:
413 typeset PATH=/new/directory:$PATH
415 is valid for temporarily allowing the shell or programmes called from
417 it to find the programs in /new/directory inside a function.
418 Note that the restriction in older versions of zsh that local parame‐
420 ters were never exported has been removed.
421
423 The following parameters are automatically set by the shell:
424 ! <S> The process ID of the last command started in the background
426 with &, or put into the background with the bg builtin.
427 # <S> The number of positional parameters in decimal. Note that some
429 confusion may occur with the syntax $#param which substitutes
430 the length of param. Use ${#} to resolve ambiguities. In par‐
431 ticular, the sequence `$#-...' in an arithmetic expression is
432 interpreted as the length of the parameter -, q.v.
433 ARGC <S> <Z>
435 Same as #.
436 $ <S> The process ID of this shell. Note that this indicates the
438 original shell started by invoking zsh; all processes forked
439 from the shells without executing a new program, such as sub‐
440 shells started by (...), substitute the same value.
441 - <S> Flags supplied to the shell on invocation or by the set or
443 setopt commands.
444 * <S> An array containing the positional parameters.
446 argv <S> <Z>
448 Same as *. Assigning to argv changes the local positional
449 parameters, but argv is not itself a local parameter. Deleting
450 argv with unset in any function deletes it everywhere, although
451 only the innermost positional parameter array is deleted (so *
452 and @ in other scopes are not affected).
453 @ <S> Same as argv[@], even when argv is not set.
455 ? <S> The exit status returned by the last command.
457 0 <S> The name used to invoke the current shell. If the FUNC‐
459 TION_ARGZERO option is set, this is set temporarily within a
460 shell function to the name of the function, and within a sourced
461 script to the name of the script.
462 status <S> <Z>
464 Same as ?.
465 pipestatus <S> <Z>
467 An array containing the exit statuses returned by all commands
468 in the last pipeline.
469 _ <S> The last argument of the previous command. Also, this parameter
471 is set in the environment of every command executed to the full
472 pathname of the command.
473 CPUTYPE
475 The machine type (microprocessor class or machine model), as
476 determined at run time.
477 EGID <S>
479 The effective group ID of the shell process. If you have suffi‐
480 cient privileges, you may change the effective group ID of the
481 shell process by assigning to this parameter. Also (assuming
482 sufficient privileges), you may start a single command with a
483 different effective group ID by `(EGID=gid; command)'
484 EUID <S>
486 The effective user ID of the shell process. If you have suffi‐
487 cient privileges, you may change the effective user ID of the
488 shell process by assigning to this parameter. Also (assuming
489 sufficient privileges), you may start a single command with a
490 different effective user ID by `(EUID=uid; command)'
491 ERRNO <S>
493 The value of errno (see errno(3)) as set by the most recently
494 failed system call. This value is system dependent and is
495 intended for debugging purposes. It is also useful with the
496 zsh/system module which allows the number to be turned into a
497 name or message.
498 GID <S>
500 The real group ID of the shell process. If you have sufficient
501 privileges, you may change the group ID of the shell process by
502 assigning to this parameter. Also (assuming sufficient privi‐
503 leges), you may start a single command under a different group
504 ID by `(GID=gid; command)'
505 HISTCMD
507 The current history line number in an interactive shell, in
508 other words the line number for the command that caused $HISTCMD
509 to be read.
510 HOST The current hostname.
512 LINENO <S>
514 The line number of the current line within the current script,
515 sourced file, or shell function being executed, whichever was
516 started most recently. Note that in the case of shell functions
517 the line number refers to the function as it appeared in the
518 original definition, not necessarily as displayed by the func‐
519 tions builtin.
520 LOGNAME
522 If the corresponding variable is not set in the environment of
523 the shell, it is initialized to the login name corresponding to
524 the current login session. This parameter is exported by default
525 but this can be disabled using the typeset builtin.
526 MACHTYPE
528 The machine type (microprocessor class or machine model), as
529 determined at compile time.
530 OLDPWD The previous working directory. This is set when the shell ini‐
532 tializes and whenever the directory changes.
533 OPTARG <S>
535 The value of the last option argument processed by the getopts
536 command.
537 OPTIND <S>
539 The index of the last option argument processed by the getopts
540 command.
541 OSTYPE The operating system, as determined at compile time.
543 PPID <S>
545 The process ID of the parent of the shell. As for $$, the value
546 indicates the parent of the original shell and does not change
547 in subshells.
548 PWD The present working directory. This is set when the shell ini‐
550 tializes and whenever the directory changes.
551 RANDOM <S>
553 A pseudo-random integer from 0 to 32767, newly generated each
554 time this parameter is referenced. The random number generator
555 can be seeded by assigning a numeric value to RANDOM.
556 The values of RANDOM form an intentionally-repeatable
558 pseudo-random sequence; subshells that reference RANDOM will
559 result in identical pseudo-random values unless the value of
560 RANDOM is referenced or seeded in the parent shell in between
561 subshell invocations.
562 SECONDS <S>
564 The number of seconds since shell invocation. If this parameter
565 is assigned a value, then the value returned upon reference will
566 be the value that was assigned plus the number of seconds since
567 the assignment.
568 Unlike other special parameters, the type of the SECONDS parame‐
570 ter can be changed using the typeset command. Only integer and
571 one of the floating point types are allowed. For example,
572 `typeset -F SECONDS' causes the value to be reported as a float‐
573 ing point number. The value is available to microsecond accu‐
574 racy, although the shell may show more or fewer digits depending
575 on the use of typeset. See the documentation for the builtin
576 typeset in zshbuiltins(1) for more details.
577 SHLVL <S>
579 Incremented by one each time a new shell is started.
580 signals
582 An array containing the names of the signals.
583 TRY_BLOCK_ERROR <S>
585 In an always block, indicates whether the preceding list of code
586 caused an error. The value is 1 to indicate an error, 0 other‐
587 wise. It may be reset, clearing the error condition. See Com‐
588 plex Commands in zshmisc(1)
589 TTY The name of the tty associated with the shell, if any.
591 TTYIDLE <S>
593 The idle time of the tty associated with the shell in seconds or
594 -1 if there is no such tty.
595 UID <S>
597 The real user ID of the shell process. If you have sufficient
598 privileges, you may change the user ID of the shell by assigning
599 to this parameter. Also (assuming sufficient privileges), you
600 may start a single command under a different user ID by
601 `(UID=uid; command)'
602 USERNAME <S>
604 The username corresponding to the real user ID of the shell
605 process. If you have sufficient privileges, you may change the
606 username (and also the user ID and group ID) of the shell by
607 assigning to this parameter. Also (assuming sufficient privi‐
608 leges), you may start a single command under a different user‐
609 name (and user ID and group ID) by `(USERNAME=username; com‐
610 mand)'
611 VENDOR The vendor, as determined at compile time.
613 zsh_eval_context <S> <Z> (ZSH_EVAL_CONTEXT <S>)
615 An array (colon-separated list) indicating the context of shell
616 code that is being run. Each time a piece of shell code that is
617 stored within the shell is executed a string is temporarily
618 appended to the array to indicate the type of operation that is
619 being performed. Read in order the array gives an indication of
620 the stack of operations being performed with the most immediate
621 context last.
622 Note that the variable does not give information on syntactic
624 context such as pipelines or subshells. Use $ZSH_SUBSHELL to
625 detect subshells.
626 The context is one of the following:
628 cmdarg Code specified by the -c option to the command line that
629 invoked the shell.
630 cmdsubst
632 Command substitution using the `...` or $(...) construct.
633 equalsubst
635 File substitution using the =(...) construct.
636 eval Code executed by the eval builtin.
638 evalautofunc
640 Code executed with the KSH_AUTOLOAD mechanism in order to
641 define an autoloaded function.
642 fc Code from the shell history executed by the -e option to
644 the fc builtin.
645 file Lines of code being read directly from a file, for exam‐
647 ple by the source builtin.
648 filecode
650 Lines of code being read from a .zwc file instead of
651 directly from the source file.
652 globqual
654 Code executed by the e or + glob qualifier.
655 globsort
657 Code executed to order files by the o glob qualifier.
658 insubst
660 File substitution using the <(...) construct.
661 loadautofunc
663 Code read directly from a file to define an autoloaded
664 function.
665 outsubst
667 File substitution using the >(...) construct.
668 sched Code executed by the sched builtin.
670 shfunc A shell function.
672 stty Code passed to stty by the STTY environment variable.
674 Normally this is passed directly to the system's stty
675 command, so this value is unlikely to be seen in prac‐
676 tice.
677 style Code executed as part of a style retrieved by the zstyle
679 builtin from the zsh/zutil module.
680 toplevel
682 The highest execution level of a script or interactive
683 shell.
684 trap Code executed as a trap defined by the trap builtin.
686 Traps defined as functions have the context shfunc. As
687 traps are asynchronous they may have a different hierar‐
688 chy from other code.
689 zpty Code executed by the zpty builtin from the zsh/zpty mod‐
691 ule.
692 zregexparse-guard
694 Code executed as a guard by the zregexparse command from
695 the zsh/zutil module.
696 zregexparse-action
698 Code executed as an action by the zregexparse command
699 from the zsh/zutil module.
700 ZSH_NAME
702 Expands to the basename of the command used to invoke this
703 instance of zsh.
704 ZSH_PATCHLEVEL
706 The revision string for the version number of the ChangeLog file
707 in the zsh distribution. This is most useful in order to keep
708 track of versions of the shell during development between
709 releases; hence most users should not use it and should instead
710 rely on $ZSH_VERSION.
711 zsh_scheduled_events
713 See the section `The zsh/sched Module' in zshmodules(1).
714 ZSH_SUBSHELL
716 Readonly integer. Initially zero, incremented each time the
717 shell forks to create a subshell for executing code. Hence
718 `(print $ZSH_SUBSHELL)' and `print $(print $ZSH_SUBSHELL)' out‐
719 put 1, while `( (print $ZSH_SUBSHELL) )' outputs 2.
720 ZSH_VERSION
722 The version number of the release of zsh.
723
725 The following parameters are used by the shell.
726 In cases where there are two parameters with an upper- and lowercase
728 form of the same name, such as path and PATH, the lowercase form is an
729 array and the uppercase form is a scalar with the elements of the array
730 joined together by colons. These are similar to tied parameters cre‐
731 ated via `typeset -T'. The normal use for the colon-separated form is
732 for exporting to the environment, while the array form is easier to
733 manipulate within the shell. Note that unsetting either of the pair
734 will unset the other; they retain their special properties when recre‐
735 ated, and recreating one of the pair will recreate the other.
736 ARGV0 If exported, its value is used as the argv[0] of external com‐
738 mands. Usually used in constructs like `ARGV0=emacs nethack'.
739 BAUD The rate in bits per second at which data reaches the terminal.
741 The line editor will use this value in order to compensate for a
742 slow terminal by delaying updates to the display until neces‐
743 sary. If the parameter is unset or the value is zero the com‐
744 pensation mechanism is turned off. The parameter is not set by
745 default.
746 This parameter may be profitably set in some circumstances, e.g.
748 for slow modems dialing into a communications server, or on a
749 slow wide area network. It should be set to the baud rate of
750 the slowest part of the link for best performance.
751 cdpath <S> <Z> (CDPATH <S>)
753 An array (colon-separated list) of directories specifying the
754 search path for the cd command.
755 COLUMNS <S>
757 The number of columns for this terminal session. Used for
758 printing select lists and for the line editor.
759 CORRECT_IGNORE
761 If set, is treated as a pattern during spelling correction. Any
762 potential correction that matches the pattern is ignored. For
763 example, if the value is `_*' then completion functions (which,
764 by convention, have names beginning with `_') will never be
765 offered as spelling corrections. The pattern does not apply to
766 the correction of file names, as applied by the CORRECT_ALL
767 option (so with the example just given files beginning with `_'
768 in the current directory would still be completed).
769 DIRSTACKSIZE
771 The maximum size of the directory stack, by default there is no
772 limit. If the stack gets larger than this, it will be truncated
773 automatically. This is useful with the AUTO_PUSHD option.
774 ENV If the ENV environment variable is set when zsh is invoked as sh
776 or ksh, $ENV is sourced after the profile scripts. The value of
777 ENV is subjected to parameter expansion, command substitution,
778 and arithmetic expansion before being interpreted as a pathname.
779 Note that ENV is not used unless zsh is emulating sh or ksh.
780 FCEDIT The default editor for the fc builtin. If FCEDIT is not set,
782 the parameter EDITOR is used; if that is not set either, a
783 builtin default, usually vi, is used.
784 fignore <S> <Z> (FIGNORE <S>)
786 An array (colon separated list) containing the suffixes of files
787 to be ignored during filename completion. However, if comple‐
788 tion only generates files with suffixes in this list, then these
789 files are completed anyway.
790 fpath <S> <Z> (FPATH <S>)
792 An array (colon separated list) of directories specifying the
793 search path for function definitions. This path is searched
794 when a function with the -u attribute is referenced. If an exe‐
795 cutable file is found, then it is read and executed in the cur‐
796 rent environment.
797 histchars <S>
799 Three characters used by the shell's history and lexical analy‐
800 sis mechanism. The first character signals the start of a his‐
801 tory expansion (default `!'). The second character signals the
802 start of a quick history substitution (default `^'). The third
803 character is the comment character (default `#').
804 The characters must be in the ASCII character set; any attempt
806 to set histchars to characters with a locale-dependent meaning
807 will be rejected with an error message.
808 HISTCHARS <S> <Z>
810 Same as histchars. (Deprecated.)
811 HISTFILE
813 The file to save the history in when an interactive shell exits.
814 If unset, the history is not saved.
815 HISTSIZE <S>
817 The maximum number of events stored in the internal history
818 list. If you use the HIST_EXPIRE_DUPS_FIRST option, setting
819 this value larger than the SAVEHIST size will give you the dif‐
820 ference as a cushion for saving duplicated history events.
821 HOME <S>
823 The default argument for the cd command. This is not set auto‐
824 matically by the shell in sh, ksh or csh emulation, but it is
825 typically present in the environment anyway, and if it becomes
826 set it has its usual special behaviour.
827 IFS <S>
829 Internal field separators (by default space, tab, newline and
830 NUL), that are used to separate words which result from command
831 or parameter expansion and words read by the read builtin. Any
832 characters from the set space, tab and newline that appear in
833 the IFS are called IFS white space. One or more IFS white space
834 characters or one non-IFS white space character together with
835 any adjacent IFS white space character delimit a field. If an
836 IFS white space character appears twice consecutively in the
837 IFS, this character is treated as if it were not an IFS white
838 space character.
839 If the parameter is unset, the default is used. Note this has a
841 different effect from setting the parameter to an empty string.
842 KEYBOARD_HACK
844 This variable defines a character to be removed from the end of
845 the command line before interpreting it (interactive shells
846 only). It is intended to fix the problem with keys placed annoy‐
847 ingly close to return and replaces the SUNKEYBOARDHACK option
848 which did this for backquotes only. Should the chosen character
849 be one of singlequote, doublequote or backquote, there must also
850 be an odd number of them on the command line for the last one to
851 be removed.
852 For backward compabitility, if the SUNKEYBOARDHACK option is
854 explicitly set, the value of KEYBOARD_HACK reverts to backquote.
855 If the option is explicitly unset, this variable is set to
856 empty.
857 KEYTIMEOUT
859 The time the shell waits, in hundredths of seconds, for another
860 key to be pressed when reading bound multi-character sequences.
861 LANG <S>
863 This variable determines the locale category for any category
864 not specifically selected via a variable starting with `LC_'.
865 LC_ALL <S>
867 This variable overrides the value of the `LANG' variable and the
868 value of any of the other variables starting with `LC_'.
869 LC_COLLATE <S>
871 This variable determines the locale category for character col‐
872 lation information within ranges in glob brackets and for sort‐
873 ing.
874 LC_CTYPE <S>
876 This variable determines the locale category for character han‐
877 dling functions. If the MULTIBYTE option is in effect this
878 variable or LANG should contain a value that reflects the char‐
879 acter set in use, even if it is a single-byte character set,
880 unless only the 7-bit subset (ASCII) is used. For example, if
881 the character set is ISO-8859-1, a suitable value might be
882 en_US.iso88591 (certain Linux distributions) or en_US.ISO8859-1
883 (MacOS).
884 LC_MESSAGES <S>
886 This variable determines the language in which messages should
887 be written. Note that zsh does not use message catalogs.
888 LC_NUMERIC <S>
890 This variable affects the decimal point character and thousands
891 separator character for the formatted input/output functions and
892 string conversion functions. Note that zsh ignores this setting
893 when parsing floating point mathematical expressions.
894 LC_TIME <S>
896 This variable determines the locale category for date and time
897 formatting in prompt escape sequences.
898 LINES <S>
900 The number of lines for this terminal session. Used for print‐
901 ing select lists and for the line editor.
902 LISTMAX
904 In the line editor, the number of matches to list without asking
905 first. If the value is negative, the list will be shown if it
906 spans at most as many lines as given by the absolute value. If
907 set to zero, the shell asks only if the top of the listing would
908 scroll off the screen.
909 LOGCHECK
911 The interval in seconds between checks for login/logout activity
912 using the watch parameter.
913 MAIL If this parameter is set and mailpath is not set, the shell
915 looks for mail in the specified file.
916 MAILCHECK
918 The interval in seconds between checks for new mail.
919 mailpath <S> <Z> (MAILPATH <S>)
921 An array (colon-separated list) of filenames to check for new
922 mail. Each filename can be followed by a `?' and a message that
923 will be printed. The message will undergo parameter expansion,
924 command substitution and arithmetic expansion with the variable
925 $_ defined as the name of the file that has changed. The
926 default message is `You have new mail'. If an element is a
927 directory instead of a file the shell will recursively check
928 every file in every subdirectory of the element.
929 manpath <S> <Z> (MANPATH <S> <Z>)
931 An array (colon-separated list) whose value is not used by the
932 shell. The manpath array can be useful, however, since setting
933 it also sets MANPATH, and vice versa.
934 match
936 mbegin
937 mend Arrays set by the shell when the b globbing flag is used in pat‐
938 tern matches. See the subsection Globbing flags in the documen‐
939 tation for Filename Generation in zshexpn(1).
940 MATCH
942 MBEGIN
943 MEND Set by the shell when the m globbing flag is used in pattern
944 matches. See the subsection Globbing flags in the documentation
945 for Filename Generation in zshexpn(1).
946 module_path <S> <Z> (MODULE_PATH <S>)
948 An array (colon-separated list) of directories that zmodload
949 searches for dynamically loadable modules. This is initialized
950 to a standard pathname, usually `/usr/local/lib/zsh/$ZSH_VER‐
951 SION'. (The `/usr/local/lib' part varies from installation to
952 installation.) For security reasons, any value set in the envi‐
953 ronment when the shell is started will be ignored.
954 These parameters only exist if the installation supports dynamic
956 module loading.
957 NULLCMD <S>
959 The command name to assume if a redirection is specified with no
960 command. Defaults to cat. For sh/ksh behavior, change this to
961 :. For csh-like behavior, unset this parameter; the shell will
962 print an error message if null commands are entered.
963 path <S> <Z> (PATH <S>)
965 An array (colon-separated list) of directories to search for
966 commands. When this parameter is set, each directory is scanned
967 and all files found are put in a hash table.
968 POSTEDIT <S>
970 This string is output whenever the line editor exits. It usu‐
971 ally contains termcap strings to reset the terminal.
972 PROMPT <S> <Z>
974 PROMPT2 <S> <Z>
975 PROMPT3 <S> <Z>
976 PROMPT4 <S> <Z>
977 Same as PS1, PS2, PS3 and PS4, respectively.
978 prompt <S> <Z>
980 Same as PS1.
981 PROMPT_EOL_MARK
983 When the PROMPT_CR and PROMPT_SP options are set, the
984 PROMPT_EOL_MARK parameter can be used to customize how the end
985 of partial lines are shown. This parameter undergoes prompt
986 expansion, with the PROMPT_PERCENT option set. If not set, the
987 default behavior is equivalent to the value `%B%S%#%s%b'.
988 PS1 <S>
990 The primary prompt string, printed before a command is read. It
991 undergoes a special form of expansion before being displayed;
992 see EXPANSION OF PROMPT SEQUENCES in zshmisc(1). The default is
993 `%m%# '.
994 PS2 <S>
996 The secondary prompt, printed when the shell needs more informa‐
997 tion to complete a command. It is expanded in the same way as
998 PS1. The default is `%_> ', which displays any shell constructs
999 or quotation marks which are currently being processed.
1000 PS3 <S>
1002 Selection prompt used within a select loop. It is expanded in
1003 the same way as PS1. The default is `?# '.
1004 PS4 <S>
1006 The execution trace prompt. Default is `+%N:%i> ', which dis‐
1007 plays the name of the current shell structure and the line num‐
1008 ber within it. In sh or ksh emulation, the default is `+ '.
1009 psvar <S> <Z> (PSVAR <S>)
1011 An array (colon-separated list) whose first nine values can be
1012 used in PROMPT strings. Setting psvar also sets PSVAR, and vice
1013 versa.
1014 READNULLCMD <S>
1016 The command name to assume if a single input redirection is
1017 specified with no command. Defaults to more.
1018 REPORTTIME
1020 If nonnegative, commands whose combined user and system execu‐
1021 tion times (measured in seconds) are greater than this value
1022 have timing statistics printed for them. Output is suppressed
1023 for commands executed within the line editor, including comple‐
1024 tion; commands explicitly marked with the time keyword still
1025 cause the summary to be printed in this case.
1026 REPLY This parameter is reserved by convention to pass string values
1028 between shell scripts and shell builtins in situations where a
1029 function call or redirection are impossible or undesirable. The
1030 read builtin and the select complex command may set REPLY, and
1031 filename generation both sets and examines its value when evalu‐
1032 ating certain expressions. Some modules also employ REPLY for
1033 similar purposes.
1034 reply As REPLY, but for array values rather than strings.
1036 RPROMPT <S>
1038 RPS1 <S>
1039 This prompt is displayed on the right-hand side of the screen
1040 when the primary prompt is being displayed on the left. This
1041 does not work if the SINGLE_LINE_ZLE option is set. It is
1042 expanded in the same way as PS1.
1043 RPROMPT2 <S>
1045 RPS2 <S>
1046 This prompt is displayed on the right-hand side of the screen
1047 when the secondary prompt is being displayed on the left. This
1048 does not work if the SINGLE_LINE_ZLE option is set. It is
1049 expanded in the same way as PS2.
1050 SAVEHIST
1052 The maximum number of history events to save in the history
1053 file.
1054 SPROMPT <S>
1056 The prompt used for spelling correction. The sequence `%R'
1057 expands to the string which presumably needs spelling correc‐
1058 tion, and `%r' expands to the proposed correction. All other
1059 prompt escapes are also allowed.
1060 STTY If this parameter is set in a command's environment, the shell
1062 runs the stty command with the value of this parameter as argu‐
1063 ments in order to set up the terminal before executing the com‐
1064 mand. The modes apply only to the command, and are reset when it
1065 finishes or is suspended. If the command is suspended and con‐
1066 tinued later with the fg or wait builtins it will see the modes
1067 specified by STTY, as if it were not suspended. This (inten‐
1068 tionally) does not apply if the command is continued via `kill
1069 -CONT'. STTY is ignored if the command is run in the back‐
1070 ground, or if it is in the environment of the shell but not
1071 explicitly assigned to in the input line. This avoids running
1072 stty at every external command by accidentally exporting it.
1073 Also note that STTY should not be used for window size specifi‐
1074 cations; these will not be local to the command.
1075 TERM <S>
1077 The type of terminal in use. This is used when looking up term‐
1078 cap sequences. An assignment to TERM causes zsh to re-initial‐
1079 ize the terminal, even if the value does not change (e.g.,
1080 `TERM=$TERM'). It is necessary to make such an assignment upon
1081 any change to the terminal definition database or terminal type
1082 in order for the new settings to take effect.
1083 TERMINFO <S>
1085 A reference to a compiled description of the terminal, used by
1086 the `terminfo' library when the system has it; see terminfo(5).
1087 If set, this causes the shell to reinitialise the terminal, mak‐
1088 ing the workaround `TERM=$TERM' unnecessary.
1089 TIMEFMT
1091 The format of process time reports with the time keyword. The
1092 default is `%J %U user %S system %P cpu %*E total'. Recognizes
1093 the following escape sequences, although not all may be avail‐
1094 able on all systems, and some that are available may not be use‐
1095 ful:
1096 %% A `%'.
1098 %U CPU seconds spent in user mode.
1099 %S CPU seconds spent in kernel mode.
1100 %E Elapsed time in seconds.
1101 %P The CPU percentage, computed as (100*%U+%S)/%E.
1102 %W Number of times the process was swapped.
1103 %X The average amount in (shared) text space used in kilo‐
1104 bytes.
1105 %D The average amount in (unshared) data/stack space used in
1106 kilobytes.
1107 %K The total space used (%X+%D) in kilobytes.
1108 %M The maximum memory the process had in use at any time in
1109 megabytes.
1110 %F The number of major page faults (page needed to be
1111 brought from disk).
1112 %R The number of minor page faults.
1113 %I The number of input operations.
1114 %O The number of output operations.
1115 %r The number of socket messages received.
1116 %s The number of socket messages sent.
1117 %k The number of signals received.
1118 %w Number of voluntary context switches (waits).
1119 %c Number of involuntary context switches.
1120 %J The name of this job.
1121 A star may be inserted between the percent sign and flags print‐
1123 ing time. This cause the time to be printed in `hh:mm:ss.ttt'
1124 format (hours and minutes are only printed if they are not
1125 zero).
1126 TMOUT If this parameter is nonzero, the shell will receive an ALRM
1128 signal if a command is not entered within the specified number
1129 of seconds after issuing a prompt. If there is a trap on
1130 SIGALRM, it will be executed and a new alarm is scheduled using
1131 the value of the TMOUT parameter after executing the trap. If
1132 no trap is set, and the idle time of the terminal is not less
1133 than the value of the TMOUT parameter, zsh terminates. Other‐
1134 wise a new alarm is scheduled to TMOUT seconds after the last
1135 keypress.
1136 TMPPREFIX
1138 A pathname prefix which the shell will use for all temporary
1139 files. Note that this should include an initial part for the
1140 file name as well as any directory names. The default is
1141 `/tmp/zsh'.
1142 watch <S> <Z> (WATCH <S>)
1144 An array (colon-separated list) of login/logout events to
1145 report. If it contains the single word `all', then all
1146 login/logout events are reported. If it contains the single
1147 word `notme', then all events are reported as with `all' except
1148 $USERNAME. An entry in this list may consist of a username, an
1149 `@' followed by a remote hostname, and a `%' followed by a line
1150 (tty). Any or all of these components may be present in an
1151 entry; if a login/logout event matches all of them, it is
1152 reported.
1153 WATCHFMT
1155 The format of login/logout reports if the watch parameter is
1156 set. Default is `%n has %a %l from %m'. Recognizes the follow‐
1157 ing escape sequences:
1158 %n The name of the user that logged in/out.
1160 %a The observed action, i.e. "logged on" or "logged off".
1162 %l The line (tty) the user is logged in on.
1164 %M The full hostname of the remote host.
1166 %m The hostname up to the first `.'. If only the IP address
1168 is available or the utmp field contains the name of an
1169 X-windows display, the whole name is printed.
1170 NOTE: The `%m' and `%M' escapes will work only if there
1172 is a host name field in the utmp on your machine. Other‐
1173 wise they are treated as ordinary strings.
1174 %S (%s)
1176 Start (stop) standout mode.
1177 %U (%u)
1179 Start (stop) underline mode.
1180 %B (%b)
1182 Start (stop) boldface mode.
1183 %t
1185 %@ The time, in 12-hour, am/pm format.
1186 %T The time, in 24-hour format.
1188 %w The date in `day-dd' format.
1190 %W The date in `mm/dd/yy' format.
1192 %D The date in `yy-mm-dd' format.
1194 %(x:true-text:false-text)
1196 Specifies a ternary expression. The character following
1197 the x is arbitrary; the same character is used to sepa‐
1198 rate the text for the "true" result from that for the
1199 "false" result. Both the separator and the right paren‐
1200 thesis may be escaped with a backslash. Ternary expres‐
1201 sions may be nested.
1202 The test character x may be any one of `l', `n', `m' or
1204 `M', which indicate a `true' result if the corresponding
1205 escape sequence would return a non-empty value; or it may
1206 be `a', which indicates a `true' result if the watched
1207 user has logged in, or `false' if he has logged out.
1208 Other characters evaluate to neither true nor false; the
1209 entire expression is omitted in this case.
1210 If the result is `true', then the true-text is formatted
1212 according to the rules above and printed, and the
1213 false-text is skipped. If `false', the true-text is
1214 skipped and the false-text is formatted and printed.
1215 Either or both of the branches may be empty, but both
1216 separators must be present in any case.
1217 WORDCHARS <S>
1219 A list of non-alphanumeric characters considered part of a word
1220 by the line editor.
1221 ZBEEP If set, this gives a string of characters, which can use all the
1223 same codes as the bindkey command as described in the zsh/zle
1224 module entry in zshmodules(1), that will be output to the termi‐
1225 nal instead of beeping. This may have a visible instead of an
1226 audible effect; for example, the string `\e[?5h\e[?5l' on a
1227 vt100 or xterm will have the effect of flashing reverse video on
1228 and off (if you usually use reverse video, you should use the
1229 string `\e[?5l\e[?5h' instead). This takes precedence over the
1230 NOBEEP option.
1231 ZDOTDIR
1233 The directory to search for shell startup files (.zshrc, etc),
1234 if not $HOME.
1235 ZLE_LINE_ABORTED
1237 This parameter is set by the line editor when an error occurs.
1238 It contains the line that was being edited at the point of the
1239 error. `print -zr -- $ZLE_LINE_ABORTED' can be used to recover
1240 the line. Only the most recent line of this kind is remembered.
1241 ZLE_REMOVE_SUFFIX_CHARS
1243 ZLE_SPACE_SUFFIX_CHARS
1244 These parameters are used by the line editor. In certain cir‐
1245 cumstances suffixes (typically space or slash) added by the com‐
1246 pletion system will be removed automatically, either because the
1247 next editing command was not an insertable character, or because
1248 the character was marked as requiring the suffix to be removed.
1249 These variables can contain the sets of characters that will
1251 cause the suffix to be removed. If ZLE_REMOVE_SUFFIX_CHARS is
1252 set, those characters will cause the suffix to be removed; if
1253 ZLE_SPACE_SUFFIX_CHARS is set, those characters will cause the
1254 suffix to be removed and replaced by a space.
1255 If ZLE_REMOVE_SUFFIX_CHARS is not set, the default behaviour is
1257 equivalent to:
1258 ZLE_REMOVE_SUFFIX_CHARS=$' \t\n;&|'
1260 If ZLE_REMOVE_SUFFIX_CHARS is set but is empty, no characters
1262 have this behaviour. ZLE_SPACE_SUFFIX_CHARS takes precedence,
1263 so that the following:
1264 ZLE_SPACE_SUFFIX_CHARS=$'&|'
1266 causes the characters `&' and `|' to remove the suffix but to
1268 replace it with a space.
1269 To illustrate the difference, suppose that the option
1271 AUTO_REMOVE_SLASH is in effect and the directory DIR has just
1272 been completed, with an appended /, following which the user
1273 types `&'. The default result is `DIR&'. With ZLE_REMOVE_SUF‐
1274 FIX_CHARS set but without including `&' the result is `DIR/&'.
1275 With ZLE_SPACE_SUFFIX_CHARS set to include `&' the result is
1276 `DIR &'.
1277 Note that certain completions may provide their own suffix
1279 removal or replacement behaviour which overrides the values
1280 described here. See the completion system documentation in zsh‐
1281 compsys(1).
1282zsh 5.0.2 December 21, 2012 ZSHPARAM(1)