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 The same subscripting syntax is used for associative arrays, except
81 that no arithmetic expansion is applied to exp. However, the parsing
82 rules for arithmetic expressions still apply, which affects the way
83 that certain special characters must be protected from interpretation.
84 See Subscript Parsing below for details.
85 A subscript of the form `[*]' or `[@]' evaluates to all elements of an
87 array; there is no difference between the two except when they appear
88 within double quotes. `"$foo[*]"' evaluates to `"$foo[1] $foo[2]
89 ..."', whereas `"$foo[@]"' evaluates to `"$foo[1]" "$foo[2]" ...'. For
90 associative arrays, `[*]' or `[@]' evaluate to all the values, in no
91 particular order. Note that this does not substitute the keys; see the
92 documentation for the `k' flag under Parameter Expansion Flags in zsh‐
93 expn(1) for complete details. When an array parameter is referenced as
94 `$name' (with no subscript) it evaluates to `$name[*]', unless the
95 KSH_ARRAYS option is set in which case it evaluates to `${name[0]}'
96 (for an associative array, this means the value of the key `0', which
97 may not exist even if there are values for other keys).
98 A subscript of the form `[exp1,exp2]' selects all elements in the range
100 exp1 to exp2, inclusive. (Associative arrays are unordered, and so do
101 not support ranges.) If one of the subscripts evaluates to a negative
102 number, say -n, then the nth element from the end of the array is used.
103 Thus `$foo[-3]' is the third element from the end of the array foo, and
104 `$foo[1,-1]' is the same as `$foo[*]'.
105 Subscripting may also be performed on non-array values, in which case
107 the subscripts specify a substring to be extracted. For example, if
108 FOO is set to `foobar', then `echo $FOO[2,5]' prints `ooba'.
109 Array Element Assignment
111 A subscript may be used on the left side of an assignment like so:
112 name[exp]=value
114 In this form of assignment the element or range specified by exp is
116 replaced by the expression on the right side. An array (but not an
117 associative array) may be created by assignment to a range or element.
118 Arrays do not nest, so assigning a parenthesized list of values to an
119 element or range changes the number of elements in the array, shifting
120 the other elements to accommodate the new values. (This is not sup‐
121 ported for associative arrays.)
122 This syntax also works as an argument to the typeset command:
124 typeset "name[exp]"=value
126 The value may not be a parenthesized list in this case; only sin‐
128 gle-element assignments may be made with typeset. Note that quotes are
129 necessary in this case to prevent the brackets from being interpreted
130 as filename generation operators. The noglob precommand modifier could
131 be used instead.
132 To delete an element of an ordinary array, assign `()' to that element.
134 To delete an element of an associative array, use the unset command:
135 unset "name[exp]"
137 Subscript Flags
139 If the opening bracket, or the comma in a range, in any subscript
140 expression is directly followed by an opening parenthesis, the string
141 up to the matching closing one is considered to be a list of flags, as
142 in `name[(flags)exp]'. The flags currently understood are:
143 w If the parameter subscripted is a scalar than this flag makes
145 subscripting work on words instead of characters. The default
146 word separator is whitespace.
147 s:string:
149 This gives the string that separates words (for use with the w
150 flag).
151 p Recognize the same escape sequences as the print builtin in the
153 string argument of a subsequent `s' flag.
154 f If the parameter subscripted is a scalar than this flag makes
156 subscripting work on lines instead of characters, i.e. with ele‐
157 ments separated by newlines. This is a shorthand for `pws:\n:'.
158 r Reverse subscripting: if this flag is given, the exp is taken as
160 a pattern and the result is the first matching array element,
161 substring or word (if the parameter is an array, if it is a
162 scalar, or if it is a scalar and the `w' flag is given, respec‐
163 tively). The subscript used is the number of the matching ele‐
164 ment, so that pairs of subscripts such as `$foo[(r)??,3]' and
165 `$foo[(r)??,(r)f*]' are possible if the parameter is not an
166 associative array. If the parameter is an associative array,
167 only the value part of each pair is compared to the pattern, and
168 the result is that value.
169 R Like `r', but gives the last match. For associative arrays,
171 gives all possible matches. May be used for assigning to ordi‐
172 nary array elements, but not for assigning to associative
173 arrays.
174 i Like `r', but gives the index of the match instead; this may not
176 be combined with a second argument. On the left side of an
177 assignment, behaves like `r'. For associative arrays, the key
178 part of each pair is compared to the pattern, and the first
179 matching key found is the result.
180 I Like `i', but gives the index of the last match, or all possible
182 matching keys in an associative array.
183 k If used in a subscript on an associative array, this flag causes
185 the keys to be interpreted as patterns, and returns the value
186 for the first key found where exp is matched by the key. This
187 flag does not work on the left side of an assignment to an asso‐
188 ciative array element. If used on another type of parameter,
189 this behaves like `r'.
190 K On an associative array this is like `k' but returns all values
192 where exp is matched by the keys. On other types of parameters
193 this has the same effect as `R'.
194 n:expr:
196 If combined with `r', `R', `i' or `I', makes them give the nth
197 or nth last match (if expr evaluates to n). This flag is
198 ignored when the array is associative.
199 b:expr:
201 If combined with `r', `R', `i' or `I', makes them begin at the
202 nth or nth last element, word, or character (if expr evaluates
203 to n). This flag is ignored when the array is associative.
204 e This flag has no effect and for ordinary arrays is retained for
206 backward compatibility only. For associative arrays, this flag
207 can be used to force * or @ to be interpreted as a single key
208 rather than as a reference to all values. This flag may be used
209 on the left side of an assignment.
210 See Parameter Expansion Flags (zshexpn(1)) for additional ways to
212 manipulate the results of array subscripting.
213 Subscript Parsing
215 This discussion applies mainly to associative array key strings and to
216 patterns used for reverse subscripting (the `r', `R', `i', etc. flags),
217 but it may also affect parameter substitutions that appear as part of
218 an arithmetic expression in an ordinary subscript.
219 It is possible to avoid the use of subscripts in assignments to asso‐
221 ciative array elements by using the syntax:
222 aa+=('key with "*strange*" characters' 'value string')
224 This adds a new key/value pair if the key is not already present, and
226 replaces the value for the existing key if it is.
227 The basic rule to remember when writing a subscript expression is that
229 all text between the opening `[' and the closing `]' is interpreted as
230 if it were in double quotes (see zshmisc(1)). However, unlike double
231 quotes which normally cannot nest, subscript expressions may appear
232 inside double-quoted strings or inside other subscript expressions (or
233 both!), so the rules have two important differences.
234 The first difference is that brackets (`[' and `]') must appear as bal‐
236 anced pairs in a subscript expression unless they are preceded by a
237 backslash (`\'). Therefore, within a subscript expression (and unlike
238 true double-quoting) the sequence `\[' becomes `[', and similarly `\]'
239 becomes `]'. This applies even in cases where a backslash is not nor‐
240 mally required; for example, the pattern `[^[]' (to match any character
241 other than an open bracket) should be written `[^\[]' in a reverse-sub‐
242 script pattern. However, note that `\[^\[\]' and even `\[^[]' mean the
243 same thing, because backslashes are always stripped when they appear
244 before brackets!
245 The same rule applies to parentheses (`(' and `)') and braces (`{' and
247 `}'): they must appear either in balanced pairs or preceded by a back‐
248 slash, and backslashes that protect parentheses or braces are removed
249 during parsing. This is because parameter expansions may be surrounded
250 balanced braces, and subscript flags are introduced by balanced paren‐
251 thesis.
252 The second difference is that a double-quote (`"') may appear as part
254 of a subscript expression without being preceded by a backslash, and
255 therefore that the two characters `\"' remain as two characters in the
256 subscript (in true double-quoting, `\"' becomes `"'). However, because
257 of the standard shell quoting rules, any double-quotes that appear must
258 occur in balanced pairs unless preceded by a backslash. This makes it
259 more difficult to write a subscript expression that contains an odd
260 number of double-quote characters, but the reason for this difference
261 is so that when a subscript expression appears inside true dou‐
262 ble-quotes, one can still write `\"' (rather than `\\\"') for `"'.
263 To use an odd number of double quotes as a key in an assignment, use
265 the typeset builtin and an enclosing pair of double quotes; to refer to
266 the value of that key, again use double quotes:
267 typeset -A aa
269 typeset "aa[one\"two\"three\"quotes]"=QQQ
270 print "$aa[one\"two\"three\"quotes]"
271 It is important to note that the quoting rules do not change when a
273 parameter expansion with a subscript is nested inside another subscript
274 expression. That is, it is not necessary to use additional backslashes
275 within the inner subscript expression; they are removed only once, from
276 the innermost subscript outwards. Parameters are also expanded from
277 the innermost subscript first, as each expansion is encountered left to
278 right in the outer expression.
279 A further complication arises from a way in which subscript parsing is
281 not different from double quote parsing. As in true double-quoting,
282 the sequences `\*', and `\@' remain as two characters when they appear
283 in a subscript expression. To use a literal `*' or `@' as an associa‐
284 tive array key, the `e' flag must be used:
285 typeset -A aa
287 aa[(e)*]=star
288 print $aa[(e)*]
289 A last detail must be considered when reverse subscripting is per‐
291 formed. Parameters appearing in the subscript expression are first
292 expanded and then the complete expression is interpreted as a pattern.
293 This has two effects: first, parameters behave as if GLOB_SUBST were on
294 (and it cannot be turned off); second, backslashes are interpreted
295 twice, once when parsing the array subscript and again when parsing the
296 pattern. In a reverse subscript, it's necessary to use four back‐
297 slashes to cause a single backslash to match literally in the pattern.
298 For complex patterns, it is often easiest to assign the desired pattern
299 to a parameter and then refer to that parameter in the subscript,
300 because then the backslashes, brackets, parentheses, etc., are seen
301 only when the complete expression is converted to a pattern. To match
302 the value of a parameter literally in a reverse subscript, rather than
303 as a pattern, use `${(q)name}' (see zshexpn(1)) to quote the expanded
304 value.
305 Note that the `k' and `K' flags are reverse subscripting for an ordi‐
307 nary array, but are not reverse subscripting for an associative array!
308 (For an associative array, the keys in the array itself are interpreted
309 as patterns by those flags; the subscript is a plain string in that
310 case.)
311 One final note, not directly related to subscripting: the numeric names
313 of positional parameters (described below) are parsed specially, so for
314 example `$2foo' is equivalent to `${2}foo'. Therefore, to use sub‐
315 script syntax to extract a substring from a positional parameter, the
316 expansion must be surrounded by braces; for example, `${2[3,5]}' evalu‐
317 ates to the third through fifth characters of the second positional
318 parameter, but `$2[3,5]' is the entire second parameter concatenated
319 with the filename generation pattern `[3,5]'.
320
322 The positional parameters provide access to the command-line arguments
323 of a shell function, shell script, or the shell itself; see the section
324 `Invocation', and also the section `Functions'. The parameter n, where
325 n is a number, is the nth positional parameter. The parameters *, @
326 and argv are arrays containing all the positional parameters; thus
327 `$argv[n]', etc., is equivalent to simply `$n'.
328 Positional parameters may be changed after the shell or function starts
330 by using the set builtin, by assigning to the argv array, or by direct
331 assignment of the form `n=value' where n is the number of the posi‐
332 tional parameter to be changed. This also creates (with empty values)
333 any of the positions from 1 to n that do not already have values. Note
334 that, because the positional parameters form an array, an array assign‐
335 ment of the form `n=(value ...)' is allowed, and has the effect of
336 shifting all the values at positions greater than n by as many posi‐
337 tions as necessary to accommodate the new values.
338
340 Shell function executions delimit scopes for shell parameters. (Param‐
341 eters are dynamically scoped.) The typeset builtin, and its alterna‐
342 tive forms declare, integer, local and readonly (but not export), can
343 be used to declare a parameter as being local to the innermost scope.
344 When a parameter is read or assigned to, the innermost existing parame‐
346 ter of that name is used. (That is, the local parameter hides any
347 less-local parameter.) However, assigning to a non-existent parameter,
348 or declaring a new parameter with export, causes it to be created in
349 the outermost scope.
350 Local parameters disappear when their scope ends. unset can be used to
352 delete a parameter while it is still in scope; any outer parameter of
353 the same name remains hidden.
354 Special parameters may also be made local; they retain their special
356 attributes unless either the existing or the newly-created parameter
357 has the -h (hide) attribute. This may have unexpected effects: there
358 is no default value, so if there is no assignment at the point the
359 variable is made local, it will be set to an empty value (or zero in
360 the case of integers). The following:
361 typeset PATH=/new/directory:$PATH
363 is valid for temporarily allowing the shell or programmes called from
365 it to find the programs in /new/directory inside a function.
366 Note that the restriction in older versions of zsh that local parame‐
368 ters were never exported has been removed.
369
371 The following parameters are automatically set by the shell:
372 ! <S> The process ID of the last background command invoked.
374 # <S> The number of positional parameters in decimal. Note that some
376 confusion may occur with the syntax $#param which substitutes
377 the length of param. Use ${#} to resolve ambiguities. In par‐
378 ticular, the sequence `$#-...' in an arithmetic expression is
379 interpreted as the length of the parameter -, q.v.
380 ARGC <S> <Z>
382 Same as #.
383 $ <S> The process ID of this shell.
385 - <S> Flags supplied to the shell on invocation or by the set or
387 setopt commands.
388 * <S> An array containing the positional parameters.
390 argv <S> <Z>
392 Same as *. Assigning to argv changes the local positional
393 parameters, but argv is not itself a local parameter. Deleting
394 argv with unset in any function deletes it everywhere, although
395 only the innermost positional parameter array is deleted (so *
396 and @ in other scopes are not affected).
397 @ <S> Same as argv[@], even when argv is not set.
399 ? <S> The exit value returned by the last command.
401 0 <S> The name used to invoke the current shell. If the FUNC‐
403 TION_ARGZERO option is set, this is set temporarily within a
404 shell function to the name of the function, and within a sourced
405 script to the name of the script.
406 status <S> <Z>
408 Same as ?.
409 pipestatus <S> <Z>
411 An array containing the exit values returned by all commands in
412 the last pipeline.
413 _ <S> The last argument of the previous command. Also, this parameter
415 is set in the environment of every command executed to the full
416 pathname of the command.
417 CPUTYPE
419 The machine type (microprocessor class or machine model), as
420 determined at run time.
421 EGID <S>
423 The effective group ID of the shell process. If you have suffi‐
424 cient privileges, you may change the effective group ID of the
425 shell process by assigning to this parameter. Also (assuming
426 sufficient privileges), you may start a single command with a
427 different effective group ID by `(EGID=gid; command)'
428 EUID <S>
430 The effective user ID of the shell process. If you have suffi‐
431 cient privileges, you may change the effective user ID of the
432 shell process by assigning to this parameter. Also (assuming
433 sufficient privileges), you may start a single command with a
434 different effective user ID by `(EUID=uid; command)'
435 ERRNO <S>
437 The value of errno (see errno(3)) as set by the most recently
438 failed system call. This value is system dependent and is
439 intended for debugging purposes. It is also useful with the
440 zsh/system module which allows the number to be turned into a
441 name or message.
442 GID <S>
444 The real group ID of the shell process. If you have sufficient
445 privileges, you may change the group ID of the shell process by
446 assigning to this parameter. Also (assuming sufficient privi‐
447 leges), you may start a single command under a different group
448 ID by `(GID=gid; command)'
449 HISTCMD
451 The current history line number in an interactive shell, in
452 other words the line number for the command that caused $HISTCMD
453 to be read.
454 HOST The current hostname.
456 LINENO <S>
458 The line number of the current line within the current script,
459 sourced file, or shell function being executed, whichever was
460 started most recently. Note that in the case of shell functions
461 the line number refers to the function as it appeared in the
462 original definition, not necessarily as displayed by the func‐
463 tions builtin.
464 LOGNAME
466 If the corresponding variable is not set in the environment of
467 the shell, it is initialized to the login name corresponding to
468 the current login session. This parameter is exported by default
469 but this can be disabled using the typeset builtin.
470 MACHTYPE
472 The machine type (microprocessor class or machine model), as
473 determined at compile time.
474 OLDPWD The previous working directory. This is set when the shell ini‐
476 tializes and whenever the directory changes.
477 OPTARG <S>
479 The value of the last option argument processed by the getopts
480 command.
481 OPTIND <S>
483 The index of the last option argument processed by the getopts
484 command.
485 OSTYPE The operating system, as determined at compile time.
487 PPID <S>
489 The process ID of the parent of the shell.
490 PWD The present working directory. This is set when the shell ini‐
492 tializes and whenever the directory changes.
493 RANDOM <S>
495 A pseudo-random integer from 0 to 32767, newly generated each
496 time this parameter is referenced. The random number generator
497 can be seeded by assigning a numeric value to RANDOM.
498 The values of RANDOM form an intentionally-repeatable
500 pseudo-random sequence; subshells that reference RANDOM will
501 result in identical pseudo-random values unless the value of
502 RANDOM is referenced or seeded in the parent shell in between
503 subshell invocations.
504 SECONDS <S>
506 The number of seconds since shell invocation. If this parameter
507 is assigned a value, then the value returned upon reference will
508 be the value that was assigned plus the number of seconds since
509 the assignment.
510 Unlike other special parameters, the type of the SECONDS parame‐
512 ter can be changed using the typeset command. Only integer and
513 one of the floating point types are allowed. For example,
514 `typeset -F SECONDS' causes the value to be reported as a float‐
515 ing point number. The precision is six decimal places, although
516 not all places may be useful.
517 SHLVL <S>
519 Incremented by one each time a new shell is started.
520 signals
522 An array containing the names of the signals.
523 TRY_BLOCK_ERROR <S>
525 In an always block, indicates whether the preceding list of code
526 caused an error. The value is 1 to indicate an error, 0 other‐
527 wise. It may be reset, clearing the error condition. See Com‐
528 plex Commands in zshmisc(1)
529 TTY The name of the tty associated with the shell, if any.
531 TTYIDLE <S>
533 The idle time of the tty associated with the shell in seconds or
534 -1 if there is no such tty.
535 UID <S>
537 The real user ID of the shell process. If you have sufficient
538 privileges, you may change the user ID of the shell by assigning
539 to this parameter. Also (assuming sufficient privileges), you
540 may start a single command under a different user ID by
541 `(UID=uid; command)'
542 USERNAME <S>
544 The username corresponding to the real user ID of the shell
545 process. If you have sufficient privileges, you may change the
546 username (and also the user ID and group ID) of the shell by
547 assigning to this parameter. Also (assuming sufficient privi‐
548 leges), you may start a single command under a different user‐
549 name (and user ID and group ID) by `(USERNAME=username; com‐
550 mand)'
551 VENDOR The vendor, as determined at compile time.
553 ZSH_NAME
555 Expands to the basename of the command used to invoke this
556 instance of zsh.
557 ZSH_VERSION
559 The version number of this zsh.
560
562 The following parameters are used by the shell.
563 In cases where there are two parameters with an upper- and lowercase
565 form of the same name, such as path and PATH, the lowercase form is an
566 array and the uppercase form is a scalar with the elements of the array
567 joined together by colons. These are similar to tied parameters cre‐
568 ated via `typeset -T'. The normal use for the colon-separated form is
569 for exporting to the environment, while the array form is easier to
570 manipulate within the shell. Note that unsetting either of the pair
571 will unset the other; they retain their special properties when recre‐
572 ated, and recreating one of the pair will recreate the other.
573 ARGV0 If exported, its value is used as the argv[0] of external com‐
575 mands. Usually used in constructs like `ARGV0=emacs nethack'.
576 BAUD The baud rate of the current connection. Used by the line edi‐
578 tor update mechanism to compensate for a slow terminal by delay‐
579 ing updates until necessary. This may be profitably set to a
580 lower value in some circumstances, e.g. for slow modems dialing
581 into a communications server which is connected to a host via a
582 fast link; in this case, this variable would be set by default
583 to the speed of the fast link, and not the modem. This parame‐
584 ter should be set to the baud rate of the slowest part of the
585 link for best performance. The compensation mechanism can be
586 turned off by setting the variable to zero.
587 cdpath <S> <Z> (CDPATH <S>)
589 An array (colon-separated list) of directories specifying the
590 search path for the cd command.
591 COLUMNS <S>
593 The number of columns for this terminal session. Used for
594 printing select lists and for the line editor.
595 DIRSTACKSIZE
597 The maximum size of the directory stack. If the stack gets
598 larger than this, it will be truncated automatically. This is
599 useful with the AUTO_PUSHD option.
600 ENV If the ENV environment variable is set when zsh is invoked as sh
602 or ksh, $ENV is sourced after the profile scripts. The value of
603 ENV is subjected to parameter expansion, command substitution,
604 and arithmetic expansion before being interpreted as a pathname.
605 Note that ENV is not used unless zsh is emulating sh or ksh.
606 FCEDIT The default editor for the fc builtin.
608 fignore <S> <Z> (FIGNORE <S>)
610 An array (colon separated list) containing the suffixes of files
611 to be ignored during filename completion. However, if comple‐
612 tion only generates files with suffixes in this list, then these
613 files are completed anyway.
614 fpath <S> <Z> (FPATH <S>)
616 An array (colon separated list) of directories specifying the
617 search path for function definitions. This path is searched
618 when a function with the -u attribute is referenced. If an exe‐
619 cutable file is found, then it is read and executed in the cur‐
620 rent environment.
621 histchars <S>
623 Three characters used by the shell's history and lexical analy‐
624 sis mechanism. The first character signals the start of a his‐
625 tory expansion (default `!'). The second character signals the
626 start of a quick history substitution (default `^'). The third
627 character is the comment character (default `#').
628 HISTCHARS <S> <Z>
630 Same as histchars. (Deprecated.)
631 HISTFILE
633 The file to save the history in when an interactive shell exits.
634 If unset, the history is not saved.
635 HISTSIZE <S>
637 The maximum number of events stored in the internal history
638 list. If you use the HIST_EXPIRE_DUPS_FIRST option, setting
639 this value larger than the SAVEHIST size will give you the dif‐
640 ference as a cushion for saving duplicated history events.
641 HOME <S>
643 The default argument for the cd command.
644 IFS <S>
646 Internal field separators (by default space, tab, newline and
647 NUL), that are used to separate words which result from command
648 or parameter expansion and words read by the read builtin. Any
649 characters from the set space, tab and newline that appear in
650 the IFS are called IFS white space. One or more IFS white space
651 characters or one non-IFS white space character together with
652 any adjacent IFS white space character delimit a field. If an
653 IFS white space character appears twice consecutively in the
654 IFS, this character is treated as if it were not an IFS white
655 space character.
656 KEYTIMEOUT
658 The time the shell waits, in hundredths of seconds, for another
659 key to be pressed when reading bound multi-character sequences.
660 LANG <S>
662 This variable determines the locale category for any category
663 not specifically selected via a variable starting with `LC_'.
664 LC_ALL <S>
666 This variable overrides the value of the `LANG' variable and the
667 value of any of the other variables starting with `LC_'.
668 LC_COLLATE <S>
670 This variable determines the locale category for character col‐
671 lation information within ranges in glob brackets and for sort‐
672 ing.
673 LC_CTYPE <S>
675 This variable determines the locale category for character han‐
676 dling functions.
677 LC_MESSAGES <S>
679 This variable determines the language in which messages should
680 be written. Note that zsh does not use message catalogs.
681 LC_NUMERIC <S>
683 This variable affects the decimal point character and thousands
684 separator character for the formatted input/output functions and
685 string conversion functions. Note that zsh ignores this setting
686 when parsing floating point mathematical expressions.
687 LC_TIME <S>
689 This variable determines the locale category for date and time
690 formatting in prompt escape sequences.
691 LINES <S>
693 The number of lines for this terminal session. Used for print‐
694 ing select lists and for the line editor.
695 LISTMAX
697 In the line editor, the number of matches to list without asking
698 first. If the value is negative, the list will be shown if it
699 spans at most as many lines as given by the absolute value. If
700 set to zero, the shell asks only if the top of the listing would
701 scroll off the screen.
702 LOGCHECK
704 The interval in seconds between checks for login/logout activity
705 using the watch parameter.
706 MAIL If this parameter is set and mailpath is not set, the shell
708 looks for mail in the specified file.
709 MAILCHECK
711 The interval in seconds between checks for new mail.
712 mailpath <S> <Z> (MAILPATH <S>)
714 An array (colon-separated list) of filenames to check for new
715 mail. Each filename can be followed by a `?' and a message that
716 will be printed. The message will undergo parameter expansion,
717 command substitution and arithmetic expansion with the variable
718 $_ defined as the name of the file that has changed. The
719 default message is `You have new mail'. If an element is a
720 directory instead of a file the shell will recursively check
721 every file in every subdirectory of the element.
722 manpath <S> <Z> (MANPATH <S> <Z>)
724 An array (colon-separated list) whose value is not used by the
725 shell. The manpath array can be useful, however, since setting
726 it also sets MANPATH, and vice versa.
727 module_path <S> <Z> (MODULE_PATH <S>)
729 An array (colon-separated list) of directories that zmodload
730 searches for dynamically loadable modules. This is initialized
731 to a standard pathname, usually `/usr/local/lib/zsh/$ZSH_VER‐
732 SION'. (The `/usr/local/lib' part varies from installation to
733 installation.) For security reasons, any value set in the envi‐
734 ronment when the shell is started will be ignored.
735 These parameters only exist if the installation supports dynamic
737 module loading.
738 NULLCMD <S>
740 The command name to assume if a redirection is specified with no
741 command. Defaults to cat. For sh/ksh behavior, change this to
742 :. For csh-like behavior, unset this parameter; the shell will
743 print an error message if null commands are entered.
744 path <S> <Z> (PATH <S>)
746 An array (colon-separated list) of directories to search for
747 commands. When this parameter is set, each directory is scanned
748 and all files found are put in a hash table.
749 POSTEDIT <S>
751 This string is output whenever the line editor exits. It usu‐
752 ally contains termcap strings to reset the terminal.
753 PROMPT <S> <Z>
755 PROMPT2 <S> <Z>
756 PROMPT3 <S> <Z>
757 PROMPT4 <S> <Z>
758 Same as PS1, PS2, PS3 and PS4, respectively.
759 prompt <S> <Z>
761 Same as PS1.
762 PS1 <S>
764 The primary prompt string, printed before a command is read.
765 the default is `%m%# '. It undergoes a special form of expan‐
766 sion before being displayed; see the section `Prompt Expansion'.
767 PS2 <S>
769 The secondary prompt, printed when the shell needs more informa‐
770 tion to complete a command. It is expanded in the same way as
771 PS1. The default is `%_> ', which displays any shell constructs
772 or quotation marks which are currently being processed.
773 PS3 <S>
775 Selection prompt used within a select loop. It is expanded in
776 the same way as PS1. The default is `?# '.
777 PS4 <S>
779 The execution trace prompt. Default is `+%N:%i> ', which dis‐
780 plays the name of the current shell structure and the line num‐
781 ber within it. In sh or ksh emulation, the default is `+ '.
782 psvar <S> <Z> (PSVAR <S>)
784 An array (colon-separated list) whose first nine values can be
785 used in PROMPT strings. Setting psvar also sets PSVAR, and vice
786 versa.
787 READNULLCMD <S>
789 The command name to assume if a single input redirection is
790 specified with no command. Defaults to more.
791 REPORTTIME
793 If nonnegative, commands whose combined user and system execu‐
794 tion times (measured in seconds) are greater than this value
795 have timing statistics printed for them.
796 REPLY This parameter is reserved by convention to pass string values
798 between shell scripts and shell builtins in situations where a
799 function call or redirection are impossible or undesirable. The
800 read builtin and the select complex command may set REPLY, and
801 filename generation both sets and examines its value when evalu‐
802 ating certain expressions. Some modules also employ REPLY for
803 similar purposes.
804 reply As REPLY, but for array values rather than strings.
806 RPROMPT <S>
808 RPS1 <S>
809 This prompt is displayed on the right-hand side of the screen
810 when the primary prompt is being displayed on the left. This
811 does not work if the SINGLELINEZLE option is set. It is
812 expanded in the same way as PS1.
813 RPROMPT2 <S>
815 RPS2 <S>
816 This prompt is displayed on the right-hand side of the screen
817 when the secondary prompt is being displayed on the left. This
818 does not work if the SINGLELINEZLE option is set. It is
819 expanded in the same way as PS2.
820 SAVEHIST
822 The maximum number of history events to save in the history
823 file.
824 SPROMPT <S>
826 The prompt used for spelling correction. The sequence `%R'
827 expands to the string which presumably needs spelling correc‐
828 tion, and `%r' expands to the proposed correction. All other
829 prompt escapes are also allowed.
830 STTY If this parameter is set in a command's environment, the shell
832 runs the stty command with the value of this parameter as argu‐
833 ments in order to set up the terminal before executing the com‐
834 mand. The modes apply only to the command, and are reset when it
835 finishes or is suspended. If the command is suspended and con‐
836 tinued later with the fg or wait builtins it will see the modes
837 specified by STTY, as if it were not suspended. This (inten‐
838 tionally) does not apply if the command is continued via `kill
839 -CONT'. STTY is ignored if the command is run in the back‐
840 ground, or if it is in the environment of the shell but not
841 explicitly assigned to in the input line. This avoids running
842 stty at every external command by accidentally exporting it.
843 Also note that STTY should not be used for window size specifi‐
844 cations; these will not be local to the command.
845 TERM <S>
847 The type of terminal in use. This is used when looking up term‐
848 cap sequences. An assignment to TERM causes zsh to re-initial‐
849 ize the terminal, even if the value does not change (e.g.,
850 `TERM=$TERM'). It is necessary to make such an assignment upon
851 any change to the terminal definition database or terminal type
852 in order for the new settings to take effect.
853 TIMEFMT
855 The format of process time reports with the time keyword. The
856 default is `%E real %U user %S system %P %J'. Recognizes the
857 following escape sequences, although not all may be available on
858 all systems, and some that are available may not be useful:
859 %% A `%'.
861 %U CPU seconds spent in user mode.
862 %S CPU seconds spent in kernel mode.
863 %E Elapsed time in seconds.
864 %P The CPU percentage, computed as (100*%U+%S)/%E.
865 %W Number of times the process was swapped.
866 %X The average amount in (shared) text space used in Kbytes.
867 %D The average amount in (unshared) data/stack space used in
868 Kbytes.
869 %K The total space used (%X+%D) in Kbytes.
870 %M The maximum memory the process had in use at any time in
871 Kbytes.
872 %F The number of major page faults (page needed to be
873 brought from disk).
874 %R The number of minor page faults.
875 %I The number of input operations.
876 %O The number of output operations.
877 %r The number of socket messages received.
878 %s The number of socket messages sent.
879 %k The number of signals received.
880 %w Number of voluntary context switches (waits).
881 %c Number of involuntary context switches.
882 %J The name of this job.
883 A star may be inserted between the percent sign and flags print‐
885 ing time. This cause the time to be printed in `hh:mm:ss.ttt'
886 format (hours and minutes are only printed if they are not
887 zero).
888 TMOUT If this parameter is nonzero, the shell will receive an ALRM
890 signal if a command is not entered within the specified number
891 of seconds after issuing a prompt. If there is a trap on
892 SIGALRM, it will be executed and a new alarm is scheduled using
893 the value of the TMOUT parameter after executing the trap. If
894 no trap is set, and the idle time of the terminal is not less
895 than the value of the TMOUT parameter, zsh terminates. Other‐
896 wise a new alarm is scheduled to TMOUT seconds after the last
897 keypress.
898 TMPPREFIX
900 A pathname prefix which the shell will use for all temporary
901 files. Note that this should include an initial part for the
902 file name as well as any directory names. The default is
903 `/tmp/zsh'.
904 watch <S> <Z> (WATCH <S>)
906 An array (colon-separated list) of login/logout events to
907 report. If it contains the single word `all', then all
908 login/logout events are reported. If it contains the single
909 word `notme', then all events are reported as with `all' except
910 $USERNAME. An entry in this list may consist of a username, an
911 `@' followed by a remote hostname, and a `%' followed by a line
912 (tty). Any or all of these components may be present in an
913 entry; if a login/logout event matches all of them, it is
914 reported.
915 WATCHFMT
917 The format of login/logout reports if the watch parameter is
918 set. Default is `%n has %a %l from %m'. Recognizes the follow‐
919 ing escape sequences:
920 %n The name of the user that logged in/out.
922 %a The observed action, i.e. "logged on" or "logged off".
924 %l The line (tty) the user is logged in on.
926 %M The full hostname of the remote host.
928 %m The hostname up to the first `.'. If only the IP address
930 is available or the utmp field contains the name of an
931 X-windows display, the whole name is printed.
932 NOTE: The `%m' and `%M' escapes will work only if there
934 is a host name field in the utmp on your machine. Other‐
935 wise they are treated as ordinary strings.
936 %S (%s)
938 Start (stop) standout mode.
939 %U (%u)
941 Start (stop) underline mode.
942 %B (%b)
944 Start (stop) boldface mode.
945 %t
947 %@ The time, in 12-hour, am/pm format.
948 %T The time, in 24-hour format.
950 %w The date in `day-dd' format.
952 %W The date in `mm/dd/yy' format.
954 %D The date in `yy-mm-dd' format.
956 %(x:true-text:false-text)
958 Specifies a ternary expression. The character following
959 the x is arbitrary; the same character is used to sepa‐
960 rate the text for the "true" result from that for the
961 "false" result. Both the separator and the right paren‐
962 thesis may be escaped with a backslash. Ternary expres‐
963 sions may be nested.
964 The test character x may be any one of `l', `n', `m' or
966 `M', which indicate a `true' result if the corresponding
967 escape sequence would return a non-empty value; or it may
968 be `a', which indicates a `true' result if the watched
969 user has logged in, or `false' if he has logged out.
970 Other characters evaluate to neither true nor false; the
971 entire expression is omitted in this case.
972 If the result is `true', then the true-text is formatted
974 according to the rules above and printed, and the
975 false-text is skipped. If `false', the true-text is
976 skipped and the false-text is formatted and printed.
977 Either or both of the branches may be empty, but both
978 separators must be present in any case.
979 WORDCHARS <S>
981 A list of non-alphanumeric characters considered part of a word
982 by the line editor.
983 ZBEEP If set, this gives a string of characters, which can use all the
985 same codes as the bindkey command as described in the zsh/zle
986 module entry in zshmodules(1), that will be output to the termi‐
987 nal instead of beeping. This may have a visible instead of an
988 audible effect; for example, the string `\e[?5h\e[?5l' on a
989 vt100 or xterm will have the effect of flashing reverse video on
990 and off (if you usually use reverse video, you should use the
991 string `\e[?5l\e[?5h' instead). This takes precedence over the
992 NOBEEP option.
993 ZDOTDIR
995 The directory to search for shell startup files (.zshrc, etc),
996 if not $HOME.
997zsh 4.2.6 November 28, 2005 ZSHPARAM(1)