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_NAME
613 Expands to the basename of the command used to invoke this
614 instance of zsh.
615 ZSH_PATCHLEVEL
617 The revision string for the version number of the ChangeLog file
618 in the zsh distribution. This is most useful in order to keep
619 track of versions of the shell during development between
620 releases; hence most users should not use it and should instead
621 rely on $ZSH_VERSION.
622 zsh_scheduled_events
624 See the section `The zsh/sched Module' in zshmodules(1).
625 ZSH_SUBSHELL
627 Readonly integer. Initially zero, incremented each time the
628 shell forks to create a subshell for executing code. Hence
629 `(print $ZSH_SUBSHELL)' and `print $(print $ZSH_SUBSHELL)' out‐
630 put 1, while `( (print $ZSH_SUBSHELL) )' outputs 2.
631 ZSH_VERSION
633 The version number of the release of zsh.
634
636 The following parameters are used by the shell.
637 In cases where there are two parameters with an upper- and lowercase
639 form of the same name, such as path and PATH, the lowercase form is an
640 array and the uppercase form is a scalar with the elements of the array
641 joined together by colons. These are similar to tied parameters cre‐
642 ated via `typeset -T'. The normal use for the colon-separated form is
643 for exporting to the environment, while the array form is easier to
644 manipulate within the shell. Note that unsetting either of the pair
645 will unset the other; they retain their special properties when recre‐
646 ated, and recreating one of the pair will recreate the other.
647 ARGV0 If exported, its value is used as the argv[0] of external com‐
649 mands. Usually used in constructs like `ARGV0=emacs nethack'.
650 BAUD The rate in bits per second at which data reaches the terminal.
652 The line editor will use this value in order to compensate for a
653 slow terminal by delaying updates to the display until neces‐
654 sary. If the parameter is unset or the value is zero the com‐
655 pensation mechanism is turned off. The parameter is not set by
656 default.
657 This parameter may be profitably set in some circumstances, e.g.
659 for slow modems dialing into a communications server, or on a
660 slow wide area network. It should be set to the baud rate of
661 the slowest part of the link for best performance.
662 cdpath <S> <Z> (CDPATH <S>)
664 An array (colon-separated list) of directories specifying the
665 search path for the cd command.
666 COLUMNS <S>
668 The number of columns for this terminal session. Used for
669 printing select lists and for the line editor.
670 CORRECT_IGNORE
672 If set, is treated as a pattern during spelling correction. Any
673 potential correction that matches the pattern is ignored. For
674 example, if the value is `_*' then completion functions (which,
675 by convention, have names beginning with `_') will never be
676 offered as spelling corrections. The pattern does not apply the
677 correction of file names, as applied by the CORRECT_ALL option
678 (so with the example just given files beginning with `_' in the
679 current directory would still be completed).
680 DIRSTACKSIZE
682 The maximum size of the directory stack. If the stack gets
683 larger than this, it will be truncated automatically. This is
684 useful with the AUTO_PUSHD option.
685 ENV If the ENV environment variable is set when zsh is invoked as sh
687 or ksh, $ENV is sourced after the profile scripts. The value of
688 ENV is subjected to parameter expansion, command substitution,
689 and arithmetic expansion before being interpreted as a pathname.
690 Note that ENV is not used unless zsh is emulating sh or ksh.
691 FCEDIT The default editor for the fc builtin. If FCEDIT is not set,
693 the parameter EDITOR is used; if that is not set either, a
694 builtin default, usually vi, is used.
695 fignore <S> <Z> (FIGNORE <S>)
697 An array (colon separated list) containing the suffixes of files
698 to be ignored during filename completion. However, if comple‐
699 tion only generates files with suffixes in this list, then these
700 files are completed anyway.
701 fpath <S> <Z> (FPATH <S>)
703 An array (colon separated list) of directories specifying the
704 search path for function definitions. This path is searched
705 when a function with the -u attribute is referenced. If an exe‐
706 cutable file is found, then it is read and executed in the cur‐
707 rent environment.
708 histchars <S>
710 Three characters used by the shell's history and lexical analy‐
711 sis mechanism. The first character signals the start of a his‐
712 tory expansion (default `!'). The second character signals the
713 start of a quick history substitution (default `^'). The third
714 character is the comment character (default `#').
715 The characters must be in the ASCII character set; any attempt
717 to set histchars to characters with a locale-dependent meaning
718 will be rejected with an error message.
719 HISTCHARS <S> <Z>
721 Same as histchars. (Deprecated.)
722 HISTFILE
724 The file to save the history in when an interactive shell exits.
725 If unset, the history is not saved.
726 HISTSIZE <S>
728 The maximum number of events stored in the internal history
729 list. If you use the HIST_EXPIRE_DUPS_FIRST option, setting
730 this value larger than the SAVEHIST size will give you the dif‐
731 ference as a cushion for saving duplicated history events.
732 HOME <S>
734 The default argument for the cd command. This is not set auto‐
735 matically by the shell in sh, ksh or csh emulation, but it is
736 typically present in the environment anyway, and if it becomes
737 set it has its usual special behaviour.
738 IFS <S>
740 Internal field separators (by default space, tab, newline and
741 NUL), that are used to separate words which result from command
742 or parameter expansion and words read by the read builtin. Any
743 characters from the set space, tab and newline that appear in
744 the IFS are called IFS white space. One or more IFS white space
745 characters or one non-IFS white space character together with
746 any adjacent IFS white space character delimit a field. If an
747 IFS white space character appears twice consecutively in the
748 IFS, this character is treated as if it were not an IFS white
749 space character.
750 If the parameter is unset, the default is used. Note this has a
752 different effect from setting the parameter to an empty string.
753 KEYTIMEOUT
755 The time the shell waits, in hundredths of seconds, for another
756 key to be pressed when reading bound multi-character sequences.
757 LANG <S>
759 This variable determines the locale category for any category
760 not specifically selected via a variable starting with `LC_'.
761 LC_ALL <S>
763 This variable overrides the value of the `LANG' variable and the
764 value of any of the other variables starting with `LC_'.
765 LC_COLLATE <S>
767 This variable determines the locale category for character col‐
768 lation information within ranges in glob brackets and for sort‐
769 ing.
770 LC_CTYPE <S>
772 This variable determines the locale category for character han‐
773 dling functions. If the MULTIBYTE option is in effect this
774 variable or LANG should contain a value that reflects the char‐
775 acter set in use, even if it is a single-byte character set,
776 unless only the 7-bit subset (ASCII) is used. For example, if
777 the character set is ISO-8859-1, a suitable value might be
778 en_US.iso88591 (certain Linux distributions) or en_US.ISO8859-1
779 (MacOS).
780 LC_MESSAGES <S>
782 This variable determines the language in which messages should
783 be written. Note that zsh does not use message catalogs.
784 LC_NUMERIC <S>
786 This variable affects the decimal point character and thousands
787 separator character for the formatted input/output functions and
788 string conversion functions. Note that zsh ignores this setting
789 when parsing floating point mathematical expressions.
790 LC_TIME <S>
792 This variable determines the locale category for date and time
793 formatting in prompt escape sequences.
794 LINES <S>
796 The number of lines for this terminal session. Used for print‐
797 ing select lists and for the line editor.
798 LISTMAX
800 In the line editor, the number of matches to list without asking
801 first. If the value is negative, the list will be shown if it
802 spans at most as many lines as given by the absolute value. If
803 set to zero, the shell asks only if the top of the listing would
804 scroll off the screen.
805 LOGCHECK
807 The interval in seconds between checks for login/logout activity
808 using the watch parameter.
809 MAIL If this parameter is set and mailpath is not set, the shell
811 looks for mail in the specified file.
812 MAILCHECK
814 The interval in seconds between checks for new mail.
815 mailpath <S> <Z> (MAILPATH <S>)
817 An array (colon-separated list) of filenames to check for new
818 mail. Each filename can be followed by a `?' and a message that
819 will be printed. The message will undergo parameter expansion,
820 command substitution and arithmetic expansion with the variable
821 $_ defined as the name of the file that has changed. The
822 default message is `You have new mail'. If an element is a
823 directory instead of a file the shell will recursively check
824 every file in every subdirectory of the element.
825 manpath <S> <Z> (MANPATH <S> <Z>)
827 An array (colon-separated list) whose value is not used by the
828 shell. The manpath array can be useful, however, since setting
829 it also sets MANPATH, and vice versa.
830 module_path <S> <Z> (MODULE_PATH <S>)
832 An array (colon-separated list) of directories that zmodload
833 searches for dynamically loadable modules. This is initialized
834 to a standard pathname, usually `/usr/local/lib/zsh/$ZSH_VER‐
835 SION'. (The `/usr/local/lib' part varies from installation to
836 installation.) For security reasons, any value set in the envi‐
837 ronment when the shell is started will be ignored.
838 These parameters only exist if the installation supports dynamic
840 module loading.
841 NULLCMD <S>
843 The command name to assume if a redirection is specified with no
844 command. Defaults to cat. For sh/ksh behavior, change this to
845 :. For csh-like behavior, unset this parameter; the shell will
846 print an error message if null commands are entered.
847 path <S> <Z> (PATH <S>)
849 An array (colon-separated list) of directories to search for
850 commands. When this parameter is set, each directory is scanned
851 and all files found are put in a hash table.
852 POSTEDIT <S>
854 This string is output whenever the line editor exits. It usu‐
855 ally contains termcap strings to reset the terminal.
856 PROMPT <S> <Z>
858 PROMPT2 <S> <Z>
859 PROMPT3 <S> <Z>
860 PROMPT4 <S> <Z>
861 Same as PS1, PS2, PS3 and PS4, respectively.
862 prompt <S> <Z>
864 Same as PS1.
865 PROMPT_EOL_MARK
867 When the PROMPT_CR and PROMPT_SP options are set, the
868 PROMPT_EOL_MARK parameter can be used to customize how the end
869 of partial lines are shown. This parameter undergoes prompt
870 expansion, with the PROMPT_PERCENT option set. If not set or
871 empty, the default behavior is equivalent to the value
872 `%B%S%#%s%b'.
873 PS1 <S>
875 The primary prompt string, printed before a command is read. It
876 undergoes a special form of expansion before being displayed;
877 see EXPANSION OF PROMPT SEQUENCES in zshmisc(1). The default is
878 `%m%# '.
879 PS2 <S>
881 The secondary prompt, printed when the shell needs more informa‐
882 tion to complete a command. It is expanded in the same way as
883 PS1. The default is `%_> ', which displays any shell constructs
884 or quotation marks which are currently being processed.
885 PS3 <S>
887 Selection prompt used within a select loop. It is expanded in
888 the same way as PS1. The default is `?# '.
889 PS4 <S>
891 The execution trace prompt. Default is `+%N:%i> ', which dis‐
892 plays the name of the current shell structure and the line num‐
893 ber within it. In sh or ksh emulation, the default is `+ '.
894 psvar <S> <Z> (PSVAR <S>)
896 An array (colon-separated list) whose first nine values can be
897 used in PROMPT strings. Setting psvar also sets PSVAR, and vice
898 versa.
899 READNULLCMD <S>
901 The command name to assume if a single input redirection is
902 specified with no command. Defaults to more.
903 REPORTTIME
905 If nonnegative, commands whose combined user and system execu‐
906 tion times (measured in seconds) are greater than this value
907 have timing statistics printed for them.
908 REPLY This parameter is reserved by convention to pass string values
910 between shell scripts and shell builtins in situations where a
911 function call or redirection are impossible or undesirable. The
912 read builtin and the select complex command may set REPLY, and
913 filename generation both sets and examines its value when evalu‐
914 ating certain expressions. Some modules also employ REPLY for
915 similar purposes.
916 reply As REPLY, but for array values rather than strings.
918 RPROMPT <S>
920 RPS1 <S>
921 This prompt is displayed on the right-hand side of the screen
922 when the primary prompt is being displayed on the left. This
923 does not work if the SINGLELINEZLE option is set. It is
924 expanded in the same way as PS1.
925 RPROMPT2 <S>
927 RPS2 <S>
928 This prompt is displayed on the right-hand side of the screen
929 when the secondary prompt is being displayed on the left. This
930 does not work if the SINGLELINEZLE option is set. It is
931 expanded in the same way as PS2.
932 SAVEHIST
934 The maximum number of history events to save in the history
935 file.
936 SPROMPT <S>
938 The prompt used for spelling correction. The sequence `%R'
939 expands to the string which presumably needs spelling correc‐
940 tion, and `%r' expands to the proposed correction. All other
941 prompt escapes are also allowed.
942 STTY If this parameter is set in a command's environment, the shell
944 runs the stty command with the value of this parameter as argu‐
945 ments in order to set up the terminal before executing the com‐
946 mand. The modes apply only to the command, and are reset when it
947 finishes or is suspended. If the command is suspended and con‐
948 tinued later with the fg or wait builtins it will see the modes
949 specified by STTY, as if it were not suspended. This (inten‐
950 tionally) does not apply if the command is continued via `kill
951 -CONT'. STTY is ignored if the command is run in the back‐
952 ground, or if it is in the environment of the shell but not
953 explicitly assigned to in the input line. This avoids running
954 stty at every external command by accidentally exporting it.
955 Also note that STTY should not be used for window size specifi‐
956 cations; these will not be local to the command.
957 TERM <S>
959 The type of terminal in use. This is used when looking up term‐
960 cap sequences. An assignment to TERM causes zsh to re-initial‐
961 ize the terminal, even if the value does not change (e.g.,
962 `TERM=$TERM'). It is necessary to make such an assignment upon
963 any change to the terminal definition database or terminal type
964 in order for the new settings to take effect.
965 TIMEFMT
967 The format of process time reports with the time keyword. The
968 default is `%E real %U user %S system %P %J'. Recognizes the
969 following escape sequences, although not all may be available on
970 all systems, and some that are available may not be useful:
971 %% A `%'.
973 %U CPU seconds spent in user mode.
974 %S CPU seconds spent in kernel mode.
975 %E Elapsed time in seconds.
976 %P The CPU percentage, computed as (100*%U+%S)/%E.
977 %W Number of times the process was swapped.
978 %X The average amount in (shared) text space used in Kbytes.
979 %D The average amount in (unshared) data/stack space used in
980 Kbytes.
981 %K The total space used (%X+%D) in Kbytes.
982 %M The maximum memory the process had in use at any time in
983 Kbytes.
984 %F The number of major page faults (page needed to be
985 brought from disk).
986 %R The number of minor page faults.
987 %I The number of input operations.
988 %O The number of output operations.
989 %r The number of socket messages received.
990 %s The number of socket messages sent.
991 %k The number of signals received.
992 %w Number of voluntary context switches (waits).
993 %c Number of involuntary context switches.
994 %J The name of this job.
995 A star may be inserted between the percent sign and flags print‐
997 ing time. This cause the time to be printed in `hh:mm:ss.ttt'
998 format (hours and minutes are only printed if they are not
999 zero).
1000 TMOUT If this parameter is nonzero, the shell will receive an ALRM
1002 signal if a command is not entered within the specified number
1003 of seconds after issuing a prompt. If there is a trap on
1004 SIGALRM, it will be executed and a new alarm is scheduled using
1005 the value of the TMOUT parameter after executing the trap. If
1006 no trap is set, and the idle time of the terminal is not less
1007 than the value of the TMOUT parameter, zsh terminates. Other‐
1008 wise a new alarm is scheduled to TMOUT seconds after the last
1009 keypress.
1010 TMPPREFIX
1012 A pathname prefix which the shell will use for all temporary
1013 files. Note that this should include an initial part for the
1014 file name as well as any directory names. The default is
1015 `/tmp/zsh'.
1016 watch <S> <Z> (WATCH <S>)
1018 An array (colon-separated list) of login/logout events to
1019 report. If it contains the single word `all', then all
1020 login/logout events are reported. If it contains the single
1021 word `notme', then all events are reported as with `all' except
1022 $USERNAME. An entry in this list may consist of a username, an
1023 `@' followed by a remote hostname, and a `%' followed by a line
1024 (tty). Any or all of these components may be present in an
1025 entry; if a login/logout event matches all of them, it is
1026 reported.
1027 WATCHFMT
1029 The format of login/logout reports if the watch parameter is
1030 set. Default is `%n has %a %l from %m'. Recognizes the follow‐
1031 ing escape sequences:
1032 %n The name of the user that logged in/out.
1034 %a The observed action, i.e. "logged on" or "logged off".
1036 %l The line (tty) the user is logged in on.
1038 %M The full hostname of the remote host.
1040 %m The hostname up to the first `.'. If only the IP address
1042 is available or the utmp field contains the name of an
1043 X-windows display, the whole name is printed.
1044 NOTE: The `%m' and `%M' escapes will work only if there
1046 is a host name field in the utmp on your machine. Other‐
1047 wise they are treated as ordinary strings.
1048 %S (%s)
1050 Start (stop) standout mode.
1051 %U (%u)
1053 Start (stop) underline mode.
1054 %B (%b)
1056 Start (stop) boldface mode.
1057 %t
1059 %@ The time, in 12-hour, am/pm format.
1060 %T The time, in 24-hour format.
1062 %w The date in `day-dd' format.
1064 %W The date in `mm/dd/yy' format.
1066 %D The date in `yy-mm-dd' format.
1068 %(x:true-text:false-text)
1070 Specifies a ternary expression. The character following
1071 the x is arbitrary; the same character is used to sepa‐
1072 rate the text for the "true" result from that for the
1073 "false" result. Both the separator and the right paren‐
1074 thesis may be escaped with a backslash. Ternary expres‐
1075 sions may be nested.
1076 The test character x may be any one of `l', `n', `m' or
1078 `M', which indicate a `true' result if the corresponding
1079 escape sequence would return a non-empty value; or it may
1080 be `a', which indicates a `true' result if the watched
1081 user has logged in, or `false' if he has logged out.
1082 Other characters evaluate to neither true nor false; the
1083 entire expression is omitted in this case.
1084 If the result is `true', then the true-text is formatted
1086 according to the rules above and printed, and the
1087 false-text is skipped. If `false', the true-text is
1088 skipped and the false-text is formatted and printed.
1089 Either or both of the branches may be empty, but both
1090 separators must be present in any case.
1091 WORDCHARS <S>
1093 A list of non-alphanumeric characters considered part of a word
1094 by the line editor.
1095 ZBEEP If set, this gives a string of characters, which can use all the
1097 same codes as the bindkey command as described in the zsh/zle
1098 module entry in zshmodules(1), that will be output to the termi‐
1099 nal instead of beeping. This may have a visible instead of an
1100 audible effect; for example, the string `\e[?5h\e[?5l' on a
1101 vt100 or xterm will have the effect of flashing reverse video on
1102 and off (if you usually use reverse video, you should use the
1103 string `\e[?5l\e[?5h' instead). This takes precedence over the
1104 NOBEEP option.
1105 ZDOTDIR
1107 The directory to search for shell startup files (.zshrc, etc),
1108 if not $HOME.
1109 ZLE_REMOVE_SUFFIX_CHARS
1111 ZLE_SPACE_SUFFIX_CHARS
1112 These parameters are used by the line editor. In certain cir‐
1113 cumstances suffixes (typically space or slash) added by the com‐
1114 pletion system will be removed automatically, either because the
1115 next editing command was not an insertable character, or because
1116 the character was marked as requiring the suffix to be removed.
1117 These variables can contain the sets of characters that will
1119 cause the suffix to be removed. If ZLE_REMOVE_SUFFIX_CHARS is
1120 set, those characters will cause the suffix to be removed; if
1121 ZLE_SPACE_SUFFIX_CHARS is set, those characters will cause the
1122 suffix to be removed and replaced by a space.
1123 If ZLE_REMOVE_SUFFIX_CHARS is not set, the default behaviour is
1125 equivalent to:
1126 ZLE_REMOVE_SUFFIX_CHARS=$' \t\n;&|'
1128 If ZLE_REMOVE_SUFFIX_CHARS is set but is empty, no characters
1130 have this behaviour. ZLE_SPACE_SUFFIX_CHARS takes precedence,
1131 so that the following:
1132 ZLE_SPACE_SUFFIX_CHARS=$'&|'
1134 causes the characters `&' and `|' to remove the suffix but to
1136 replace it with a space.
1137 To illustrate the difference, suppose that the option
1139 AUTO_REMOVE_SLASH is in effect and the directory DIR has just
1140 been completed, with an appended /, following which the user
1141 types `&'. The default result is `DIR&'. With ZLE_REMOVE_SUF‐
1142 FIX_CHARS set but without including `&' the result is `DIR/&'.
1143 With ZLE_SPACE_SUFFIX_CHARS set to include `&' the result is
1144 `DIR &'.
1145 Note that certain completions may provide their own suffix
1147 removal or replacement behaviour which overrides the values
1148 described here. See the completion system documentation in zsh‐
1149 compsys(1).
1150zsh 4.3.10 June 1, 2009 ZSHPARAM(1)