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.
154 The flags currently understood are:
156 w If the parameter subscripted is a scalar then this flag makes
158 subscripting work on words instead of characters. The default
159 word separator is whitespace. This flag may not be used with
160 the i or I flag.
161 s:string:
163 This gives the string that separates words (for use with the w
164 flag). The delimiter character : is arbitrary; see above.
165 p Recognize the same escape sequences as the print builtin in the
167 string argument of a subsequent `s' flag.
168 f If the parameter subscripted is a scalar then this flag makes
170 subscripting work on lines instead of characters, i.e. with ele‐
171 ments separated by newlines. This is a shorthand for `pws:\n:'.
172 r Reverse subscripting: if this flag is given, the exp is taken as
174 a pattern and the result is the first matching array element,
175 substring or word (if the parameter is an array, if it is a
176 scalar, or if it is a scalar and the `w' flag is given, respec‐
177 tively). The subscript used is the number of the matching ele‐
178 ment, so that pairs of subscripts such as `$foo[(r)??,3]' and
179 `$foo[(r)??,(r)f*]' are possible if the parameter is not an
180 associative array. If the parameter is an associative array,
181 only the value part of each pair is compared to the pattern, and
182 the result is that value.
183 If a search through an ordinary array failed, the search sets
185 the subscript to one past the end of the array, and hence
186 ${array[(r)pattern]} will substitute the empty string. Thus the
187 success of a search can be tested by using the (i) flag, for
188 example (assuming the option KSH_ARRAYS is not in effect):
189 [[ ${array[(i)pattern]} -le ${#array} ]]
191 If KSH_ARRAYS is in effect, the -le should be replaced by -lt.
193 R Like `r', but gives the last match. For associative
195 arrays, gives all possible matches. May be used for
196 assigning to ordinary array elements, but not for assign‐
197 ing to associative arrays. On failure, for normal arrays
198 this has the effect of returning the element correspond‐
199 ing to subscript 0; this is empty unless one of the
200 options KSH_ARRAYS or KSH_ZERO_SUBSCRIPT is in effect.
201 Note that in subscripts with both `r' and `R' pattern
203 characters are active even if they were substituted for a
204 parameter (regardless of the setting of GLOB_SUBST which
205 controls this feature in normal pattern matching). The
206 flag `e' can be added to inhibit pattern matching. As
207 this flag does not inhibit other forms of substitution,
208 care is still required; using a parameter to hold the key
209 has the desired effect:
210 key2='original key'
212 print ${array[(Re)$key2]}
213 i Like `r', but gives the index of the match instead; this may not
215 be combined with a second argument. On the left side of an
216 assignment, behaves like `r'. For associative arrays, the key
217 part of each pair is compared to the pattern, and the first
218 matching key found is the result. On failure substitutes the
219 length of the array plus one, as discussed under the description
220 of `r', or the empty string for an associative array.
221 I Like `i', but gives the index of the last match, or all possible
223 matching keys in an associative array. On failure substitutes
224 0, or the empty string for an associative array. This flag is
225 best when testing for values or keys that do not exist.
226 k If used in a subscript on an associative array, this flag causes
228 the keys to be interpreted as patterns, and returns the value
229 for the first key found where exp is matched by the key. Note
230 this could be any such key as no ordering of associative arrays
231 is defined. This flag does not work on the left side of an
232 assignment to an associative array element. If used on another
233 type of parameter, this behaves like `r'.
234 K On an associative array this is like `k' but returns all values
236 where exp is matched by the keys. On other types of parameters
237 this has the same effect as `R'.
238 n:expr:
240 If combined with `r', `R', `i' or `I', makes them give the nth
241 or nth last match (if expr evaluates to n). This flag is
242 ignored when the array is associative. The delimiter character
243 : is arbitrary; see above.
244 b:expr:
246 If combined with `r', `R', `i' or `I', makes them begin at the
247 nth or nth last element, word, or character (if expr evaluates
248 to n). This flag is ignored when the array is associative. The
249 delimiter character : is arbitrary; see above.
250 e This flag causes any pattern matching that would be performed on
252 the subscript to use plain string matching instead. Hence
253 `${array[(re)*]}' matches only the array element whose value is
254 *. Note that other forms of substitution such as parameter sub‐
255 stitution are not inhibited.
256 This flag can also be used to force * or @ to be interpreted as
258 a single key rather than as a reference to all values. It may
259 be used for either purpose on the left side of an assignment.
260 See Parameter Expansion Flags (zshexpn(1)) for additional ways to
262 manipulate the results of array subscripting.
263 Subscript Parsing
265 This discussion applies mainly to associative array key strings and to
266 patterns used for reverse subscripting (the `r', `R', `i', etc. flags),
267 but it may also affect parameter substitutions that appear as part of
268 an arithmetic expression in an ordinary subscript.
269 It is possible to avoid the use of subscripts in assignments to asso‐
271 ciative array elements by using the syntax:
272 aa+=('key with "*strange*" characters' 'value string')
274 This adds a new key/value pair if the key is not already present, and
276 replaces the value for the existing key if it is.
277 The basic rule to remember when writing a subscript expression is that
279 all text between the opening `[' and the closing `]' is interpreted as
280 if it were in double quotes (see zshmisc(1)). However, unlike double
281 quotes which normally cannot nest, subscript expressions may appear
282 inside double-quoted strings or inside other subscript expressions (or
283 both!), so the rules have two important differences.
284 The first difference is that brackets (`[' and `]') must appear as bal‐
286 anced pairs in a subscript expression unless they are preceded by a
287 backslash (`\'). Therefore, within a subscript expression (and unlike
288 true double-quoting) the sequence `\[' becomes `[', and similarly `\]'
289 becomes `]'. This applies even in cases where a backslash is not nor‐
290 mally required; for example, the pattern `[^[]' (to match any character
291 other than an open bracket) should be written `[^\[]' in a reverse-sub‐
292 script pattern. However, note that `\[^\[\]' and even `\[^[]' mean the
293 same thing, because backslashes are always stripped when they appear
294 before brackets!
295 The same rule applies to parentheses (`(' and `)') and braces (`{' and
297 `}'): they must appear either in balanced pairs or preceded by a back‐
298 slash, and backslashes that protect parentheses or braces are removed
299 during parsing. This is because parameter expansions may be surrounded
300 by balanced braces, and subscript flags are introduced by balanced
301 parentheses.
302 The second difference is that a double-quote (`"') may appear as part
304 of a subscript expression without being preceded by a backslash, and
305 therefore that the two characters `\"' remain as two characters in the
306 subscript (in true double-quoting, `\"' becomes `"'). However, because
307 of the standard shell quoting rules, any double-quotes that appear must
308 occur in balanced pairs unless preceded by a backslash. This makes it
309 more difficult to write a subscript expression that contains an odd
310 number of double-quote characters, but the reason for this difference
311 is so that when a subscript expression appears inside true dou‐
312 ble-quotes, one can still write `\"' (rather than `\\\"') for `"'.
313 To use an odd number of double quotes as a key in an assignment, use
315 the typeset builtin and an enclosing pair of double quotes; to refer to
316 the value of that key, again use double quotes:
317 typeset -A aa
319 typeset "aa[one\"two\"three\"quotes]"=QQQ
320 print "$aa[one\"two\"three\"quotes]"
321 It is important to note that the quoting rules do not change when a
323 parameter expansion with a subscript is nested inside another subscript
324 expression. That is, it is not necessary to use additional backslashes
325 within the inner subscript expression; they are removed only once, from
326 the innermost subscript outwards. Parameters are also expanded from
327 the innermost subscript first, as each expansion is encountered left to
328 right in the outer expression.
329 A further complication arises from a way in which subscript parsing is
331 not different from double quote parsing. As in true double-quoting,
332 the sequences `\*', and `\@' remain as two characters when they appear
333 in a subscript expression. To use a literal `*' or `@' as an associa‐
334 tive array key, the `e' flag must be used:
335 typeset -A aa
337 aa[(e)*]=star
338 print $aa[(e)*]
339 A last detail must be considered when reverse subscripting is per‐
341 formed. Parameters appearing in the subscript expression are first
342 expanded and then the complete expression is interpreted as a pattern.
343 This has two effects: first, parameters behave as if GLOB_SUBST were on
344 (and it cannot be turned off); second, backslashes are interpreted
345 twice, once when parsing the array subscript and again when parsing the
346 pattern. In a reverse subscript, it's necessary to use four back‐
347 slashes to cause a single backslash to match literally in the pattern.
348 For complex patterns, it is often easiest to assign the desired pattern
349 to a parameter and then refer to that parameter in the subscript,
350 because then the backslashes, brackets, parentheses, etc., are seen
351 only when the complete expression is converted to a pattern. To match
352 the value of a parameter literally in a reverse subscript, rather than
353 as a pattern, use `${(q)name}' (see zshexpn(1)) to quote the expanded
354 value.
355 Note that the `k' and `K' flags are reverse subscripting for an ordi‐
357 nary array, but are not reverse subscripting for an associative array!
358 (For an associative array, the keys in the array itself are interpreted
359 as patterns by those flags; the subscript is a plain string in that
360 case.)
361 One final note, not directly related to subscripting: the numeric names
363 of positional parameters (described below) are parsed specially, so for
364 example `$2foo' is equivalent to `${2}foo'. Therefore, to use sub‐
365 script syntax to extract a substring from a positional parameter, the
366 expansion must be surrounded by braces; for example, `${2[3,5]}' evalu‐
367 ates to the third through fifth characters of the second positional
368 parameter, but `$2[3,5]' is the entire second parameter concatenated
369 with the filename generation pattern `[3,5]'.
370
372 The positional parameters provide access to the command-line arguments
373 of a shell function, shell script, or the shell itself; see the section
374 `Invocation', and also the section `Functions'. The parameter n, where
375 n is a number, is the nth positional parameter. The parameters *, @
376 and argv are arrays containing all the positional parameters; thus
377 `$argv[n]', etc., is equivalent to simply `$n'.
378 Positional parameters may be changed after the shell or function starts
380 by using the set builtin, by assigning to the argv array, or by direct
381 assignment of the form `n=value' where n is the number of the posi‐
382 tional parameter to be changed. This also creates (with empty values)
383 any of the positions from 1 to n that do not already have values. Note
384 that, because the positional parameters form an array, an array assign‐
385 ment of the form `n=(value ...)' is allowed, and has the effect of
386 shifting all the values at positions greater than n by as many posi‐
387 tions as necessary to accommodate the new values.
388
390 Shell function executions delimit scopes for shell parameters. (Param‐
391 eters are dynamically scoped.) The typeset builtin, and its alterna‐
392 tive forms declare, integer, local and readonly (but not export), can
393 be used to declare a parameter as being local to the innermost scope.
394 When a parameter is read or assigned to, the innermost existing parame‐
396 ter of that name is used. (That is, the local parameter hides any
397 less-local parameter.) However, assigning to a non-existent parameter,
398 or declaring a new parameter with export, causes it to be created in
399 the outermost scope.
400 Local parameters disappear when their scope ends. unset can be used to
402 delete a parameter while it is still in scope; any outer parameter of
403 the same name remains hidden.
404 Special parameters may also be made local; they retain their special
406 attributes unless either the existing or the newly-created parameter
407 has the -h (hide) attribute. This may have unexpected effects: there
408 is no default value, so if there is no assignment at the point the
409 variable is made local, it will be set to an empty value (or zero in
410 the case of integers). The following:
411 typeset PATH=/new/directory:$PATH
413 is valid for temporarily allowing the shell or programmes called from
415 it to find the programs in /new/directory inside a function.
416 Note that the restriction in older versions of zsh that local parame‐
418 ters were never exported has been removed.
419
421 The following parameters are automatically set by the shell:
422 ! <S> The process ID of the last command started in the background
424 with &, or put into the background with the bg builtin.
425 # <S> The number of positional parameters in decimal. Note that some
427 confusion may occur with the syntax $#param which substitutes
428 the length of param. Use ${#} to resolve ambiguities. In par‐
429 ticular, the sequence `$#-...' in an arithmetic expression is
430 interpreted as the length of the parameter -, q.v.
431 ARGC <S> <Z>
433 Same as #.
434 $ <S> The process ID of this shell. Note that this indicates the
436 original shell started by invoking zsh; all processes forked
437 from the shells without executing a new program, such as sub‐
438 shells started by (...), substitute the same value.
439 - <S> Flags supplied to the shell on invocation or by the set or
441 setopt commands.
442 * <S> An array containing the positional parameters.
444 argv <S> <Z>
446 Same as *. Assigning to argv changes the local positional
447 parameters, but argv is not itself a local parameter. Deleting
448 argv with unset in any function deletes it everywhere, although
449 only the innermost positional parameter array is deleted (so *
450 and @ in other scopes are not affected).
451 @ <S> Same as argv[@], even when argv is not set.
453 ? <S> The exit status returned by the last command.
455 0 <S> The name used to invoke the current shell. If the FUNC‐
457 TION_ARGZERO option is set, this is set temporarily within a
458 shell function to the name of the function, and within a sourced
459 script to the name of the script.
460 status <S> <Z>
462 Same as ?.
463 pipestatus <S> <Z>
465 An array containing the exit statuses returned by all commands
466 in the last pipeline.
467 _ <S> The last argument of the previous command. Also, this parameter
469 is set in the environment of every command executed to the full
470 pathname of the command.
471 CPUTYPE
473 The machine type (microprocessor class or machine model), as
474 determined at run time.
475 EGID <S>
477 The effective group ID of the shell process. If you have suffi‐
478 cient privileges, you may change the effective group ID of the
479 shell process by assigning to this parameter. Also (assuming
480 sufficient privileges), you may start a single command with a
481 different effective group ID by `(EGID=gid; command)'
482 EUID <S>
484 The effective user ID of the shell process. If you have suffi‐
485 cient privileges, you may change the effective user ID of the
486 shell process by assigning to this parameter. Also (assuming
487 sufficient privileges), you may start a single command with a
488 different effective user ID by `(EUID=uid; command)'
489 ERRNO <S>
491 The value of errno (see errno(3)) as set by the most recently
492 failed system call. This value is system dependent and is
493 intended for debugging purposes. It is also useful with the
494 zsh/system module which allows the number to be turned into a
495 name or message.
496 GID <S>
498 The real group ID of the shell process. If you have sufficient
499 privileges, you may change the group ID of the shell process by
500 assigning to this parameter. Also (assuming sufficient privi‐
501 leges), you may start a single command under a different group
502 ID by `(GID=gid; command)'
503 HISTCMD
505 The current history line number in an interactive shell, in
506 other words the line number for the command that caused $HISTCMD
507 to be read.
508 HOST The current hostname.
510 LINENO <S>
512 The line number of the current line within the current script,
513 sourced file, or shell function being executed, whichever was
514 started most recently. Note that in the case of shell functions
515 the line number refers to the function as it appeared in the
516 original definition, not necessarily as displayed by the func‐
517 tions builtin.
518 LOGNAME
520 If the corresponding variable is not set in the environment of
521 the shell, it is initialized to the login name corresponding to
522 the current login session. This parameter is exported by default
523 but this can be disabled using the typeset builtin.
524 MACHTYPE
526 The machine type (microprocessor class or machine model), as
527 determined at compile time.
528 OLDPWD The previous working directory. This is set when the shell ini‐
530 tializes and whenever the directory changes.
531 OPTARG <S>
533 The value of the last option argument processed by the getopts
534 command.
535 OPTIND <S>
537 The index of the last option argument processed by the getopts
538 command.
539 OSTYPE The operating system, as determined at compile time.
541 PPID <S>
543 The process ID of the parent of the shell. As for $$, the value
544 indicates the parent of the original shell and does not change
545 in subshells.
546 PWD The present working directory. This is set when the shell ini‐
548 tializes and whenever the directory changes.
549 RANDOM <S>
551 A pseudo-random integer from 0 to 32767, newly generated each
552 time this parameter is referenced. The random number generator
553 can be seeded by assigning a numeric value to RANDOM.
554 The values of RANDOM form an intentionally-repeatable
556 pseudo-random sequence; subshells that reference RANDOM will
557 result in identical pseudo-random values unless the value of
558 RANDOM is referenced or seeded in the parent shell in between
559 subshell invocations.
560 SECONDS <S>
562 The number of seconds since shell invocation. If this parameter
563 is assigned a value, then the value returned upon reference will
564 be the value that was assigned plus the number of seconds since
565 the assignment.
566 Unlike other special parameters, the type of the SECONDS parame‐
568 ter can be changed using the typeset command. Only integer and
569 one of the floating point types are allowed. For example,
570 `typeset -F SECONDS' causes the value to be reported as a float‐
571 ing point number. The value is available to microsecond accu‐
572 racy, although the shell may show more or fewer digits depending
573 on the use of typeset. See the documentation for the builtin
574 typeset in zshbuiltins(1) for more details.
575 SHLVL <S>
577 Incremented by one each time a new shell is started.
578 signals
580 An array containing the names of the signals.
581 TRY_BLOCK_ERROR <S>
583 In an always block, indicates whether the preceding list of code
584 caused an error. The value is 1 to indicate an error, 0 other‐
585 wise. It may be reset, clearing the error condition. See Com‐
586 plex Commands in zshmisc(1)
587 TTY The name of the tty associated with the shell, if any.
589 TTYIDLE <S>
591 The idle time of the tty associated with the shell in seconds or
592 -1 if there is no such tty.
593 UID <S>
595 The real user ID of the shell process. If you have sufficient
596 privileges, you may change the user ID of the shell by assigning
597 to this parameter. Also (assuming sufficient privileges), you
598 may start a single command under a different user ID by
599 `(UID=uid; command)'
600 USERNAME <S>
602 The username corresponding to the real user ID of the shell
603 process. If you have sufficient privileges, you may change the
604 username (and also the user ID and group ID) of the shell by
605 assigning to this parameter. Also (assuming sufficient privi‐
606 leges), you may start a single command under a different user‐
607 name (and user ID and group ID) by `(USERNAME=username; com‐
608 mand)'
609 VENDOR The vendor, as determined at compile time.
611 zsh_eval_context <S> <Z> (ZSH_EVAL_CONTEXT <S>)
613 An array (colon-separated list) indicating the context of shell
614 code that is being run. Each time a piece of shell code that is
615 stored within the shell is executed a string is temporarily
616 appended to the array to indicate the type of operation that is
617 being performed. Read in order the array gives an indication of
618 the stack of operations being performed with the most immediate
619 context last.
620 Note that the variable does not give information on syntactic
622 context such as pipelines or subshells. Use $ZSH_SUBSHELL to
623 detect subshells.
624 The context is one of the following:
626 cmdarg Code specified by the -c option to the command line that
627 invoked the shell.
628 cmdsubst
630 Command substitution using the `...` or $(...) construct.
631 equalsubst
633 File substitution using the =(...) construct.
634 eval Code executed by the eval builtin.
636 evalautofunc
638 Code executed with the KSH_AUTOLOAD mechanism in order to
639 define an autoloaded function.
640 fc Code from the shell history executed by the -e option to
642 the fc builtin.
643 file Lines of code being read directly from a file, for exam‐
645 ple by the source builtin.
646 filecode
648 Lines of code being read from a .zwc file instead of
649 directly from the source file.
650 globqual
652 Code executed by the e or + glob qualifier.
653 globsort
655 Code executed to order files by the o glob qualifier.
656 insubst
658 File substitution using the <(...) construct.
659 loadautofunc
661 Code read directly from a file to define an autoloaded
662 function.
663 outsubst
665 File substitution using the >(...) construct.
666 sched Code executed by the sched builtin.
668 shfunc A shell function.
670 stty Code passed to stty by the STTY environment variable.
672 Normally this is passed directly to the system's stty
673 command, so this value is unlikely to be seen in prac‐
674 tice.
675 style Code executed as part of a style retrieved by the zstyle
677 builtin from the zsh/zutil module.
678 toplevel
680 The highest execution level of a script or interactive
681 shell.
682 trap Code executed as a trap defined by the trap builtin.
684 Traps defined as functions have the context shfunc. As
685 traps are asynchronous they may have a different hierar‐
686 chy from other code.
687 zpty Code executed by the zpty builtin from the zsh/zpty mod‐
689 ule.
690 zregexparse-guard
692 Code executed as a guard by the zregexparse command from
693 the zsh/zutil module.
694 zregexparse-action
696 Code executed as an action by the zregexparse command
697 from the zsh/zutil module.
698 ZSH_NAME
700 Expands to the basename of the command used to invoke this
701 instance of zsh.
702 ZSH_PATCHLEVEL
704 The revision string for the version number of the ChangeLog file
705 in the zsh distribution. This is most useful in order to keep
706 track of versions of the shell during development between
707 releases; hence most users should not use it and should instead
708 rely on $ZSH_VERSION.
709 zsh_scheduled_events
711 See the section `The zsh/sched Module' in zshmodules(1).
712 ZSH_SUBSHELL
714 Readonly integer. Initially zero, incremented each time the
715 shell forks to create a subshell for executing code. Hence
716 `(print $ZSH_SUBSHELL)' and `print $(print $ZSH_SUBSHELL)' out‐
717 put 1, while `( (print $ZSH_SUBSHELL) )' outputs 2.
718 ZSH_VERSION
720 The version number of the release of zsh.
721
723 The following parameters are used by the shell.
724 In cases where there are two parameters with an upper- and lowercase
726 form of the same name, such as path and PATH, the lowercase form is an
727 array and the uppercase form is a scalar with the elements of the array
728 joined together by colons. These are similar to tied parameters cre‐
729 ated via `typeset -T'. The normal use for the colon-separated form is
730 for exporting to the environment, while the array form is easier to
731 manipulate within the shell. Note that unsetting either of the pair
732 will unset the other; they retain their special properties when recre‐
733 ated, and recreating one of the pair will recreate the other.
734 ARGV0 If exported, its value is used as the argv[0] of external com‐
736 mands. Usually used in constructs like `ARGV0=emacs nethack'.
737 BAUD The rate in bits per second at which data reaches the terminal.
739 The line editor will use this value in order to compensate for a
740 slow terminal by delaying updates to the display until neces‐
741 sary. If the parameter is unset or the value is zero the com‐
742 pensation mechanism is turned off. The parameter is not set by
743 default.
744 This parameter may be profitably set in some circumstances, e.g.
746 for slow modems dialing into a communications server, or on a
747 slow wide area network. It should be set to the baud rate of
748 the slowest part of the link for best performance.
749 cdpath <S> <Z> (CDPATH <S>)
751 An array (colon-separated list) of directories specifying the
752 search path for the cd command.
753 COLUMNS <S>
755 The number of columns for this terminal session. Used for
756 printing select lists and for the line editor.
757 CORRECT_IGNORE
759 If set, is treated as a pattern during spelling correction. Any
760 potential correction that matches the pattern is ignored. For
761 example, if the value is `_*' then completion functions (which,
762 by convention, have names beginning with `_') will never be
763 offered as spelling corrections. The pattern does not apply to
764 the correction of file names, as applied by the CORRECT_ALL
765 option (so with the example just given files beginning with `_'
766 in the current directory would still be completed).
767 DIRSTACKSIZE
769 The maximum size of the directory stack. If the stack gets
770 larger than this, it will be truncated automatically. This is
771 useful with the AUTO_PUSHD option.
772 ENV If the ENV environment variable is set when zsh is invoked as sh
774 or ksh, $ENV is sourced after the profile scripts. The value of
775 ENV is subjected to parameter expansion, command substitution,
776 and arithmetic expansion before being interpreted as a pathname.
777 Note that ENV is not used unless zsh is emulating sh or ksh.
778 FCEDIT The default editor for the fc builtin. If FCEDIT is not set,
780 the parameter EDITOR is used; if that is not set either, a
781 builtin default, usually vi, is used.
782 fignore <S> <Z> (FIGNORE <S>)
784 An array (colon separated list) containing the suffixes of files
785 to be ignored during filename completion. However, if comple‐
786 tion only generates files with suffixes in this list, then these
787 files are completed anyway.
788 fpath <S> <Z> (FPATH <S>)
790 An array (colon separated list) of directories specifying the
791 search path for function definitions. This path is searched
792 when a function with the -u attribute is referenced. If an exe‐
793 cutable file is found, then it is read and executed in the cur‐
794 rent environment.
795 histchars <S>
797 Three characters used by the shell's history and lexical analy‐
798 sis mechanism. The first character signals the start of a his‐
799 tory expansion (default `!'). The second character signals the
800 start of a quick history substitution (default `^'). The third
801 character is the comment character (default `#').
802 The characters must be in the ASCII character set; any attempt
804 to set histchars to characters with a locale-dependent meaning
805 will be rejected with an error message.
806 HISTCHARS <S> <Z>
808 Same as histchars. (Deprecated.)
809 HISTFILE
811 The file to save the history in when an interactive shell exits.
812 If unset, the history is not saved.
813 HISTSIZE <S>
815 The maximum number of events stored in the internal history
816 list. If you use the HIST_EXPIRE_DUPS_FIRST option, setting
817 this value larger than the SAVEHIST size will give you the dif‐
818 ference as a cushion for saving duplicated history events.
819 HOME <S>
821 The default argument for the cd command. This is not set auto‐
822 matically by the shell in sh, ksh or csh emulation, but it is
823 typically present in the environment anyway, and if it becomes
824 set it has its usual special behaviour.
825 IFS <S>
827 Internal field separators (by default space, tab, newline and
828 NUL), that are used to separate words which result from command
829 or parameter expansion and words read by the read builtin. Any
830 characters from the set space, tab and newline that appear in
831 the IFS are called IFS white space. One or more IFS white space
832 characters or one non-IFS white space character together with
833 any adjacent IFS white space character delimit a field. If an
834 IFS white space character appears twice consecutively in the
835 IFS, this character is treated as if it were not an IFS white
836 space character.
837 If the parameter is unset, the default is used. Note this has a
839 different effect from setting the parameter to an empty string.
840 KEYBOARD_HACK
842 This variable defines a character to be removed from the end of
843 the command line before interpreting it (interactive shells
844 only). It is intended to fix the problem with keys placed annoy‐
845 ingly close to return and replaces the SUNKEYBOARDHACK option
846 which did this for backquotes only. Should the chosen character
847 be one of singlequote, doublequote or backquote, there must also
848 be an odd number of them on the command line for the last one to
849 be removed.
850 KEYTIMEOUT
852 The time the shell waits, in hundredths of seconds, for another
853 key to be pressed when reading bound multi-character sequences.
854 LANG <S>
856 This variable determines the locale category for any category
857 not specifically selected via a variable starting with `LC_'.
858 LC_ALL <S>
860 This variable overrides the value of the `LANG' variable and the
861 value of any of the other variables starting with `LC_'.
862 LC_COLLATE <S>
864 This variable determines the locale category for character col‐
865 lation information within ranges in glob brackets and for sort‐
866 ing.
867 LC_CTYPE <S>
869 This variable determines the locale category for character han‐
870 dling functions. If the MULTIBYTE option is in effect this
871 variable or LANG should contain a value that reflects the char‐
872 acter set in use, even if it is a single-byte character set,
873 unless only the 7-bit subset (ASCII) is used. For example, if
874 the character set is ISO-8859-1, a suitable value might be
875 en_US.iso88591 (certain Linux distributions) or en_US.ISO8859-1
876 (MacOS).
877 LC_MESSAGES <S>
879 This variable determines the language in which messages should
880 be written. Note that zsh does not use message catalogs.
881 LC_NUMERIC <S>
883 This variable affects the decimal point character and thousands
884 separator character for the formatted input/output functions and
885 string conversion functions. Note that zsh ignores this setting
886 when parsing floating point mathematical expressions.
887 LC_TIME <S>
889 This variable determines the locale category for date and time
890 formatting in prompt escape sequences.
891 LINES <S>
893 The number of lines for this terminal session. Used for print‐
894 ing select lists and for the line editor.
895 LISTMAX
897 In the line editor, the number of matches to list without asking
898 first. If the value is negative, the list will be shown if it
899 spans at most as many lines as given by the absolute value. If
900 set to zero, the shell asks only if the top of the listing would
901 scroll off the screen.
902 LOGCHECK
904 The interval in seconds between checks for login/logout activity
905 using the watch parameter.
906 MAIL If this parameter is set and mailpath is not set, the shell
908 looks for mail in the specified file.
909 MAILCHECK
911 The interval in seconds between checks for new mail.
912 mailpath <S> <Z> (MAILPATH <S>)
914 An array (colon-separated list) of filenames to check for new
915 mail. Each filename can be followed by a `?' and a message that
916 will be printed. The message will undergo parameter expansion,
917 command substitution and arithmetic expansion with the variable
918 $_ defined as the name of the file that has changed. The
919 default message is `You have new mail'. If an element is a
920 directory instead of a file the shell will recursively check
921 every file in every subdirectory of the element.
922 manpath <S> <Z> (MANPATH <S> <Z>)
924 An array (colon-separated list) whose value is not used by the
925 shell. The manpath array can be useful, however, since setting
926 it also sets MANPATH, and vice versa.
927 module_path <S> <Z> (MODULE_PATH <S>)
929 An array (colon-separated list) of directories that zmodload
930 searches for dynamically loadable modules. This is initialized
931 to a standard pathname, usually `/usr/local/lib/zsh/$ZSH_VER‐
932 SION'. (The `/usr/local/lib' part varies from installation to
933 installation.) For security reasons, any value set in the envi‐
934 ronment when the shell is started will be ignored.
935 These parameters only exist if the installation supports dynamic
937 module loading.
938 NULLCMD <S>
940 The command name to assume if a redirection is specified with no
941 command. Defaults to cat. For sh/ksh behavior, change this to
942 :. For csh-like behavior, unset this parameter; the shell will
943 print an error message if null commands are entered.
944 path <S> <Z> (PATH <S>)
946 An array (colon-separated list) of directories to search for
947 commands. When this parameter is set, each directory is scanned
948 and all files found are put in a hash table.
949 POSTEDIT <S>
951 This string is output whenever the line editor exits. It usu‐
952 ally contains termcap strings to reset the terminal.
953 PROMPT <S> <Z>
955 PROMPT2 <S> <Z>
956 PROMPT3 <S> <Z>
957 PROMPT4 <S> <Z>
958 Same as PS1, PS2, PS3 and PS4, respectively.
959 prompt <S> <Z>
961 Same as PS1.
962 PROMPT_EOL_MARK
964 When the PROMPT_CR and PROMPT_SP options are set, the
965 PROMPT_EOL_MARK parameter can be used to customize how the end
966 of partial lines are shown. This parameter undergoes prompt
967 expansion, with the PROMPT_PERCENT option set. If not set or
968 empty, the default behavior is equivalent to the value
969 `%B%S%#%s%b'.
970 PS1 <S>
972 The primary prompt string, printed before a command is read. It
973 undergoes a special form of expansion before being displayed;
974 see EXPANSION OF PROMPT SEQUENCES in zshmisc(1). The default is
975 `%m%# '.
976 PS2 <S>
978 The secondary prompt, printed when the shell needs more informa‐
979 tion to complete a command. It is expanded in the same way as
980 PS1. The default is `%_> ', which displays any shell constructs
981 or quotation marks which are currently being processed.
982 PS3 <S>
984 Selection prompt used within a select loop. It is expanded in
985 the same way as PS1. The default is `?# '.
986 PS4 <S>
988 The execution trace prompt. Default is `+%N:%i> ', which dis‐
989 plays the name of the current shell structure and the line num‐
990 ber within it. In sh or ksh emulation, the default is `+ '.
991 psvar <S> <Z> (PSVAR <S>)
993 An array (colon-separated list) whose first nine values can be
994 used in PROMPT strings. Setting psvar also sets PSVAR, and vice
995 versa.
996 READNULLCMD <S>
998 The command name to assume if a single input redirection is
999 specified with no command. Defaults to more.
1000 REPORTTIME
1002 If nonnegative, commands whose combined user and system execu‐
1003 tion times (measured in seconds) are greater than this value
1004 have timing statistics printed for them.
1005 REPLY This parameter is reserved by convention to pass string values
1007 between shell scripts and shell builtins in situations where a
1008 function call or redirection are impossible or undesirable. The
1009 read builtin and the select complex command may set REPLY, and
1010 filename generation both sets and examines its value when evalu‐
1011 ating certain expressions. Some modules also employ REPLY for
1012 similar purposes.
1013 reply As REPLY, but for array values rather than strings.
1015 RPROMPT <S>
1017 RPS1 <S>
1018 This prompt is displayed on the right-hand side of the screen
1019 when the primary prompt is being displayed on the left. This
1020 does not work if the SINGLELINEZLE option is set. It is
1021 expanded in the same way as PS1.
1022 RPROMPT2 <S>
1024 RPS2 <S>
1025 This prompt is displayed on the right-hand side of the screen
1026 when the secondary prompt is being displayed on the left. This
1027 does not work if the SINGLELINEZLE option is set. It is
1028 expanded in the same way as PS2.
1029 SAVEHIST
1031 The maximum number of history events to save in the history
1032 file.
1033 SPROMPT <S>
1035 The prompt used for spelling correction. The sequence `%R'
1036 expands to the string which presumably needs spelling correc‐
1037 tion, and `%r' expands to the proposed correction. All other
1038 prompt escapes are also allowed.
1039 STTY If this parameter is set in a command's environment, the shell
1041 runs the stty command with the value of this parameter as argu‐
1042 ments in order to set up the terminal before executing the com‐
1043 mand. The modes apply only to the command, and are reset when it
1044 finishes or is suspended. If the command is suspended and con‐
1045 tinued later with the fg or wait builtins it will see the modes
1046 specified by STTY, as if it were not suspended. This (inten‐
1047 tionally) does not apply if the command is continued via `kill
1048 -CONT'. STTY is ignored if the command is run in the back‐
1049 ground, or if it is in the environment of the shell but not
1050 explicitly assigned to in the input line. This avoids running
1051 stty at every external command by accidentally exporting it.
1052 Also note that STTY should not be used for window size specifi‐
1053 cations; these will not be local to the command.
1054 TERM <S>
1056 The type of terminal in use. This is used when looking up term‐
1057 cap sequences. An assignment to TERM causes zsh to re-initial‐
1058 ize the terminal, even if the value does not change (e.g.,
1059 `TERM=$TERM'). It is necessary to make such an assignment upon
1060 any change to the terminal definition database or terminal type
1061 in order for the new settings to take effect.
1062 TIMEFMT
1064 The format of process time reports with the time keyword. The
1065 default is `%E real %U user %S system %P %J'. Recognizes the
1066 following escape sequences, although not all may be available on
1067 all systems, and some that are available may not be useful:
1068 %% A `%'.
1070 %U CPU seconds spent in user mode.
1071 %S CPU seconds spent in kernel mode.
1072 %E Elapsed time in seconds.
1073 %P The CPU percentage, computed as (100*%U+%S)/%E.
1074 %W Number of times the process was swapped.
1075 %X The average amount in (shared) text space used in Kbytes.
1076 %D The average amount in (unshared) data/stack space used in
1077 Kbytes.
1078 %K The total space used (%X+%D) in Kbytes.
1079 %M The maximum memory the process had in use at any time in
1080 Kbytes.
1081 %F The number of major page faults (page needed to be
1082 brought from disk).
1083 %R The number of minor page faults.
1084 %I The number of input operations.
1085 %O The number of output operations.
1086 %r The number of socket messages received.
1087 %s The number of socket messages sent.
1088 %k The number of signals received.
1089 %w Number of voluntary context switches (waits).
1090 %c Number of involuntary context switches.
1091 %J The name of this job.
1092 A star may be inserted between the percent sign and flags print‐
1094 ing time. This cause the time to be printed in `hh:mm:ss.ttt'
1095 format (hours and minutes are only printed if they are not
1096 zero).
1097 TMOUT If this parameter is nonzero, the shell will receive an ALRM
1099 signal if a command is not entered within the specified number
1100 of seconds after issuing a prompt. If there is a trap on
1101 SIGALRM, it will be executed and a new alarm is scheduled using
1102 the value of the TMOUT parameter after executing the trap. If
1103 no trap is set, and the idle time of the terminal is not less
1104 than the value of the TMOUT parameter, zsh terminates. Other‐
1105 wise a new alarm is scheduled to TMOUT seconds after the last
1106 keypress.
1107 TMPPREFIX
1109 A pathname prefix which the shell will use for all temporary
1110 files. Note that this should include an initial part for the
1111 file name as well as any directory names. The default is
1112 `/tmp/zsh'.
1113 watch <S> <Z> (WATCH <S>)
1115 An array (colon-separated list) of login/logout events to
1116 report. If it contains the single word `all', then all
1117 login/logout events are reported. If it contains the single
1118 word `notme', then all events are reported as with `all' except
1119 $USERNAME. An entry in this list may consist of a username, an
1120 `@' followed by a remote hostname, and a `%' followed by a line
1121 (tty). Any or all of these components may be present in an
1122 entry; if a login/logout event matches all of them, it is
1123 reported.
1124 WATCHFMT
1126 The format of login/logout reports if the watch parameter is
1127 set. Default is `%n has %a %l from %m'. Recognizes the follow‐
1128 ing escape sequences:
1129 %n The name of the user that logged in/out.
1131 %a The observed action, i.e. "logged on" or "logged off".
1133 %l The line (tty) the user is logged in on.
1135 %M The full hostname of the remote host.
1137 %m The hostname up to the first `.'. If only the IP address
1139 is available or the utmp field contains the name of an
1140 X-windows display, the whole name is printed.
1141 NOTE: The `%m' and `%M' escapes will work only if there
1143 is a host name field in the utmp on your machine. Other‐
1144 wise they are treated as ordinary strings.
1145 %S (%s)
1147 Start (stop) standout mode.
1148 %U (%u)
1150 Start (stop) underline mode.
1151 %B (%b)
1153 Start (stop) boldface mode.
1154 %t
1156 %@ The time, in 12-hour, am/pm format.
1157 %T The time, in 24-hour format.
1159 %w The date in `day-dd' format.
1161 %W The date in `mm/dd/yy' format.
1163 %D The date in `yy-mm-dd' format.
1165 %(x:true-text:false-text)
1167 Specifies a ternary expression. The character following
1168 the x is arbitrary; the same character is used to sepa‐
1169 rate the text for the "true" result from that for the
1170 "false" result. Both the separator and the right paren‐
1171 thesis may be escaped with a backslash. Ternary expres‐
1172 sions may be nested.
1173 The test character x may be any one of `l', `n', `m' or
1175 `M', which indicate a `true' result if the corresponding
1176 escape sequence would return a non-empty value; or it may
1177 be `a', which indicates a `true' result if the watched
1178 user has logged in, or `false' if he has logged out.
1179 Other characters evaluate to neither true nor false; the
1180 entire expression is omitted in this case.
1181 If the result is `true', then the true-text is formatted
1183 according to the rules above and printed, and the
1184 false-text is skipped. If `false', the true-text is
1185 skipped and the false-text is formatted and printed.
1186 Either or both of the branches may be empty, but both
1187 separators must be present in any case.
1188 WORDCHARS <S>
1190 A list of non-alphanumeric characters considered part of a word
1191 by the line editor.
1192 ZBEEP If set, this gives a string of characters, which can use all the
1194 same codes as the bindkey command as described in the zsh/zle
1195 module entry in zshmodules(1), that will be output to the termi‐
1196 nal instead of beeping. This may have a visible instead of an
1197 audible effect; for example, the string `\e[?5h\e[?5l' on a
1198 vt100 or xterm will have the effect of flashing reverse video on
1199 and off (if you usually use reverse video, you should use the
1200 string `\e[?5l\e[?5h' instead). This takes precedence over the
1201 NOBEEP option.
1202 ZDOTDIR
1204 The directory to search for shell startup files (.zshrc, etc),
1205 if not $HOME.
1206 ZLE_LINE_ABORTED
1208 This parameter is set by the line editor when an error occurs.
1209 It contains the line that was being edited at the point of the
1210 error. `print -zr -- $ZLE_LINE_ABORTED' can be used to recover
1211 the line. Only the most recent line of this kind is remembered.
1212 ZLE_REMOVE_SUFFIX_CHARS
1214 ZLE_SPACE_SUFFIX_CHARS
1215 These parameters are used by the line editor. In certain cir‐
1216 cumstances suffixes (typically space or slash) added by the com‐
1217 pletion system will be removed automatically, either because the
1218 next editing command was not an insertable character, or because
1219 the character was marked as requiring the suffix to be removed.
1220 These variables can contain the sets of characters that will
1222 cause the suffix to be removed. If ZLE_REMOVE_SUFFIX_CHARS is
1223 set, those characters will cause the suffix to be removed; if
1224 ZLE_SPACE_SUFFIX_CHARS is set, those characters will cause the
1225 suffix to be removed and replaced by a space.
1226 If ZLE_REMOVE_SUFFIX_CHARS is not set, the default behaviour is
1228 equivalent to:
1229 ZLE_REMOVE_SUFFIX_CHARS=$' \t\n;&|'
1231 If ZLE_REMOVE_SUFFIX_CHARS is set but is empty, no characters
1233 have this behaviour. ZLE_SPACE_SUFFIX_CHARS takes precedence,
1234 so that the following:
1235 ZLE_SPACE_SUFFIX_CHARS=$'&|'
1237 causes the characters `&' and `|' to remove the suffix but to
1239 replace it with a space.
1240 To illustrate the difference, suppose that the option
1242 AUTO_REMOVE_SLASH is in effect and the directory DIR has just
1243 been completed, with an appended /, following which the user
1244 types `&'. The default result is `DIR&'. With ZLE_REMOVE_SUF‐
1245 FIX_CHARS set but without including `&' the result is `DIR/&'.
1246 With ZLE_SPACE_SUFFIX_CHARS set to include `&' the result is
1247 `DIR &'.
1248 Note that certain completions may provide their own suffix
1250 removal or replacement behaviour which overrides the values
1251 described here. See the completion system documentation in zsh‐
1252 compsys(1).
1253zsh 4.3.11 December 20, 2010 ZSHPARAM(1)