zshparam(1)
NAME
zshparam - zsh parameters
DESCRIPTIONS
- A parameter has a name, a value, and a number of at
- tributes. A name may be any sequence of alphanumeric characters
- and _'s, or the single characters *, @, #, ?, -, $, or !. The
- value may be either a scalar (a string), an integer, or an array.
- To assign a scalar or integer value to a parameter, use the
- typeset builtin. To assign an array value, use set -A name value
- .... The value of a parameter may also be assigned by writing:
name=value ...- If the integer attribute, -i, is set for name, the value
- is subject to arithmetic evaluation.
- The value of an array parameter may be assigned by writ
- ing:
name=(value ...) ...- Individual elements of an array may be selected using a
- subscript. A subscript of the form [exp] selects the single ele
- ment exp, where exp is an arithmetic expression which will be
- subject to arithmetic expansion as if it were surrounded by
- "$((...))". The elements are numbered beginning with 1 unless
- the KSH_ARRAYS option is set when they are numbered from zero.
- A subscript of the form [*] or [@] evaluates to all ele
- ments of an array; there is no difference between the two except
- when they appear within double quotes. "$foo[*]" evaluates to
- "$foo[1] $foo[2] ...", while "$foo[@]" evaluates to "$foo[1]"
- "$foo[2]", etc.
- A subscript of the form [exp1,exp2] selects all elements
- in the range exp1 to exp2, inclusive. If one of the subscripts
- evaluates to a negative number, say -n, then the nth element from
- the end of the array is used. Thus "$foo[-3]" is the third ele
- ment from the end of the array foo, and "$foo[1,-1]" is the same
- as "$foo[*]".
- Subscripting may also be performed on non-array values, in
- which case the subscripts specify a substring to be extracted.
- For example, if FOO is set to foobar, then echo $FOO[2,5] prints
- ooba.
- Subscripts may be used inside braces used to delimit a pa
- rameter name, thus ${foo[2]} is equivalent to $foo[2]. If the
KSH_ARRAYS
- will work, the subscript otherwise not being treated specially.
If a subscript is used on the left side of an assignment - the selected range is replaced by the expression on the right
- side.
- If the opening bracket or the comma is directly followed
- by an opening parentheses the string up to the matching closing
- one is considered to be a list of flags. The flags currently un
- derstood are:
e this option has no effect and retained for- backward compatibility only
- w if the parameter subscripted is a scalar
- than this flag makes subscription work on a per-word basis in
- stead of characters
- s:string:
this gives the string that separates words(for use with the w flag)
- p Recognize the same escape sequences as the
- print builtin in the string argument of a subsequent s flag.
- f if the parameter subscripted is a scalar
- than this flag makes subscription work on a per-line basis in
- stead of characters. This is a shorthand for pws:n:.
- r if this flag is given the exp is taken as a
- pattern and the result is the first matching array element, sub
- string or word (if the parameter is an array, if it is a scalar,
- or if it is a scalar and the w flag is given, respectively); note
- that this is like giving a number: $foo[(r)??,3] and
- $foo[(r)??,(r)f*] work
- R like r, but gives the last match
- i like r, but gives the index of the match in
- stead; this may not be combined with a second argument
- I like i, but gives the index of the last
- match
- n:expr:
if combined with r, R, , or I, makes themgive the n'th or n'th last match (if expr evaluates to n)
- Positional Parameters
- Positional parameters are set by the shell on invocation,
- by the set builtin, or by direct assignment. The parameter n,
- where n is a number, is the nth positional parameter. The param
- eters *, @, and argv are arrays containing all the positional pa
- rameters; thus argv[n], etc. is equivalent to simply n.
- Special Parameters
- The following parameters are automatically set by the
- shell:
! The process id of the last background command invoked.
# The number of positional parameters in decimal.
ARGC Same as #. It has no special meaning insh/ksh compatibility mode.
$ The process id of this shell.
- Flags supplied to the shell on invocation orby the set or setopt commands.
* An array containing the positional parameters.
argv Same as *. It has no special meaning insh/ksh compatibility mode.
@ Same as argv[@] but it can be used in sh/kshcompatibility mode.
? The exit value returned by the last command.
status Same as ?. It has no special meaning insh/ksh compatibility mode.
_ The last argument of the previous command.Also, this parameter is set in the environment of every commandexecuted to the full pathname of the command.
EGID The effective group id of the shell process.If you have sufficient privileges, you may change the effectivegroup id of the shell process by assigning to this parameter.Also (assuming sufficient privileges), you may start a singlecommand with a different effective group id by:(EGID=egid ; command)EUID The effective user id of the shell process.If you have sufficient privileges, you may change the effectiveuser id of the shell process by assigning to this parameter. Also (assuming sufficient privileges), you may start a single command with a different effective user id by:(EUID=euid ; command)ERRNO The value of errno as set by the most recently failed system call. This value is system dependent and isintended for debugging purposes.
GID The group id of the shell process. If youhave sufficient privileges, you may change the group id of theshell process by assigning to this parameter. Also (assumingsufficient privileges), you may start a single command under adifferent group id by:(GID=gid ; command)HOST The current hostname.
LINENO The line number of the current line withinthe current script being executed.
LOGNAMEIf the corresponding variable is not set inthe environment of the shell, it is initialized to the login namecorresponding to the current login session. This parameter is exported by default but this can be disabled using the typesetbuiltin.MACHTYPEThe machine type (microprocessor class ormachine model), as determined at compile time.OLDPWD The previous working directory.
OPTARG The value of the last option argument processed by the getopts command.
OPTIND The index of the last option argument processed by the getopts command.
OSTYPE The operating system, as determined at compile time.
PPID The process id of the parent of the shell.
PWD The present working directory.
RANDOM A random integer from 0 to 32767, newly generated each time this parameter is referenced. The random numbergenerator can be seeded by assigning a numeric value to RANDOM.
SECONDSThe number of seconds since shell invocation. If this parameter is assigned a value, then the value returned upon reference will be the value that was assigned plusthe number of seconds since the assignment.SHLVL Incremented by one each time a new shell isstarted.
signalsAn array containing the names of the signals.TTY The name of the tty associated with theshell, if any.
TTYIDLEThe idle time of the tty associated with theshell in seconds or -1 if there is no such tty.UID The user id of the shell process. If youhave sufficient privileges, you may change the user id of theshell by assigning to this parameter. Also (assuming sufficientprivileges), you may start a single command under a different user id by:(UID=uid ; command)USERNAMEThe username corresponding to the user id ofthe shell process. If you have sufficient privileges, you maychange the username (and also the user id and group id) of theshell by assigning to this parameter. Also (assuming sufficientprivileges), you may start a single command under a differentusername (and user id and group id) by:
(USERNAME=username ; command)VENDOR The vendor, as determined at compile time.
ZSHNAMEExpands to the basename of the command usedto invoke this instance of zsh.ZSH_NAMEExpands to the basename of the command usedto invoke this instance of zsh.ZSH_VERSIONThe version number of this zsh. - The following parameters are used by the shell:
ARGV0 If exported, it's value is used as argv[0]- of external commands. Usually used in constructs like
- 'ARGV0=emacs nethack'.
BAUD The baud rate of the current connection. - Used by the line editor update mechanism to compensate for a slow
- terminal by delaying updates until necessary. This may be prof
- itably set to a lower value in some circumstances, e.g. for slow
- modems dialing into a communications server which is connected to
- a host via a fast link; in this case, this variable would be set
- by default to the speed of the fast link, and not the modem.
- This parameter should be set to the baud rate of the slowest part
- of the link for best performance. The compensation mechanism can
- be turned off by setting the variable to zero.
cdpath (CDPATH)An array (colon-separated list) of directories specifying the search path for the cd command. - COLUMNS
The number of columns for this terminal session. Used for printing select lists and for the line editor.
- DIRSTACKSIZE
The maximum size of the directory stack. Ifthe stack gets larger than this, it will be truncated automatically. This is useful with the AUTO_PUSHD option.
- FCEDIT The default editor for the fc builtin.
fignore (FIGNORE)An array (colon separated list) containingthe suffixes of files to be ignored during filename completion.However, if the completion generates only files which would matchif this variable would be ignored, than these files are completedanyway. - fpath (FPATH)
An array (colon separated list) of directories specifying the search path for function definitions. Thispath is searched when a function with the -u attribute is referenced. If an executable file is found, then it is read and executed in the current environment.
- histchars
Three characters used by the shell's historyand lexical analysis mechanism. The first character signals thestart of a history substitution (default `!'). The second character signals the start of a quick history substitution (default`^'). The third character is the comment character (default`#').
- HISTCHARS
Same as histchars.
- HISTFILE
The file to save the history in when an interactive shell exits. If unset, the history is not saved.
- HISTSIZE
The maximum size of the history list.
- HOME The default argument for the cd command.
IFS Internal field separators, normally space, - tab, and newline, that are used to separate words which result
- from command or parameter substitution and words read by the read
- builtin. Any characters from the set space, tab and newline that
- appear in the IFS are called IFS white space. One or more IFS
- white space characters or one non-IFS white space character to
- gether with any adjacent IFS white space character delimit a
- field. If an IFS white space character appears twice consecu
- tively in the IFS, this character is treated as if it were not an
- IFS white space character.
KEYTIMEOUTThe time the shell waits, in hundredths ofseconds, for another key to be pressed when reading bound multicharacter sequences. - LANG This variable determines the locale category
- for any category not specifically selected via a variable start
- ing with LC_.
LC_ALL This variable overrides the value of the - LANG variable and the value of any of the other variables start
- ing with LC_.
LC_COLLATEThis variable determines the locale categoryfor character collation information within ranges in glob brackets and for sorting. - LC_CTYPE
This variable determines the locale categoryfor character handling functions.
- LC_MESSAGES
This variable determines the language inwhich messages should be written. Note that zsh does not usemessage catalogs.
- LC_TIME
This variable determines the locale categoryfor date and time formatting in promt escape sequences.
- LINES The number of lines for this terminal ses
- sion. Used for printing select lists and for the line editor.
LISTMAXIn the line editor, the number of filenamesto list without asking first. If set to zero, the shell asks only if the top of the listing would scroll off the screen. - LOGCHECK
The interval in seconds between checks forlogin/logout activity using the watch parameter.
- MAIL If this parameter is set and mailpath is not
- set, the shell looks for mail in the specified file.
MAILCHECKThe interval in seconds between checks fornew mail. - mailpath (MAILPATH)
An array (colon-separated list) of filenamesto check for new mail. Each filename can be followed by a ? anda message that will be printed. The message will undergo parameter expansion, command substitution and arithmetic substitutionwith the variable $_ defined as the name of the file that haschanged. The default message is "You have new mail." If an element is a directory instead of a file the shell will recursivelycheck every file in every subdirectory of the element.
- manpath (MANPATH)
An array (colon-separated list) whose valueis not used by the shell. The manpath array can be useful, however, since setting it also sets MANPATH, and vice versa.
- NULLCMD
The command name to assume if a redirectionis specified with no command. Defaults to cat. For sh/ksh-likebehavior, change this to :. For csh-like behavior, unset thisparameter; the shell will print an error message if null commandsare entered.
- path (PATH)
An array (colon-separated list) of directories to search for commands. When this parameter is set, eachdirectory is scanned and all files found are put in a hash table.
- POSTEDIT
This string is output whenever the line editor exits. It usually contains termcap strings to reset the terminal.
- PS1 The primary prompt string, printed before a
- command is read; the default is "%m%# ". If the escape sequence
- takes an optional integer, it should appear between the '%' and
- the next character of the sequence. The following escape se
- quences are recognized:
%% A `%'.
%) A `)'.
%d
%/ Present working directory ($PWD).
%~ $PWD. If it has a named directoryas its prefix, that part is replaced by a ~ followed by the nameof the directory. If it starts with $HOME, that part is replacedby a ~.
%c
%.
%C Trailing component of $PWD. An integer may follow the '%' to get more than one component. Unless%C is used, tilde expansion is performed first.
%h
%! Current history event number
%L The current value of $SHLVL.
%M The full machine hostname.
%m The hostname up to the first '.'.An integer may follow the '%' to specify how many components ofthe hostname are desired. - %S (%s)
Start (stop) standout mode.
- %U (%u)
Start (stop) underline mode.
- %B (%b)
Start (stop) boldface mode.
- %t
%@ Current time of day, in 12-hour, - am/pm format.
%T Current time of day, in 24-hour for - mat.
%* Current time of day in 24-hour for - mat, with seconds.
%n $USERNAME.
%w The date in day-dd format.
%W The date in mm/dd/yy format.
%D The date in yy-mm-dd format. - %D{string}
- string is formatted using the
- strftime function. See strftime(3) for more details, if your
- system has it.
- %l The line (tty) the user is logged in
- on.
%? The return code of the last command - executed just before the prompt.
%_ The status of the parser, i.e. the - shell constructs (like `if' and `for') that have been started on
- the command line. If given an integer number that many strings
- will be printed; zero or no integer means print as many as there
- are.
%E Clears to end of line.
%# A '#' if the shell is running as - root, a '%' if not. Equivalent to %(#.#.%%).
%v The value of the first element of - the $psvar array parameter. Following the '%' with an integer
- gives that element of the array.
- %{...%}
- Include a string as a literal escape
- sequence. The string within the braces should not change the
- cursor position.
- %(x.true-text.false-text)
- Specifies a ternary expression. The
- character following the x is arbitrary; the same character is
- used to separate the text for the "true" result from that for the
- "false" result. This separator may not appear in the true-text,
- except as part of a % sequence. A `)' may appear in the
- false-text as `%)'. True-text and false-text may both contain
- arbitrarily-nested escape sequences, including further ternary
- expressions. The left parenthesis may be preceded or followed by
- a positive integer n, which defaults to zero. The test character
- x may be any of the following:
- c
.
~ True if the current path, - with prefix replacement, has at least n elements.
/
C True if the current absolute - path has at least n elements.
t True if the time in minutes - is equal to n.
T True if the time in hours is - equal to n.
d True if the day of the month - is equal to n.
D True if the month is equal to - n (January = 0).
w True if the day of the week - is equal to n (Sunday = 0).
? True if the exit status of - the last command was n.
# True if the effective uid of - the current process is n.
g True if the effective gid of - the current process is n.
L True if the SHLVL parameter - is at least n.
S True if the SECONDS parameter - is at least n.
v True if the array psvar has - at least n elements.
_ True if at least n shell con - structs were started.
- %<string<
%>string>
%[xstring] - Specifies truncation behaviour. The
- third form is equivalent to `%xstringx', i.e. x may be `<' or
- `>'. The numeric argument, which in the third form may appear
- immediately after the `[', specifies the maximum permitted length
- of the various strings that can be displayed in the prompt. If
- this integer is zero, or missing, truncation is disabled. Trun
- cation is initially disabled. The forms with `<' truncate at the
- left of the string, and the forms with `>' truncate at the right
- of the string. For example, if the current directory is
- `/home/pike', the prompt `%8<..<%/' will expand to `..e/pike'.
- The string will be displayed in place of the truncated portion of
- any string. In this string, the terminating character (`<', `>'
- or `]'), or in fact any character, may be quoted by a preceding
- `´. % sequences are not treated specially. If the string is
- longer than the specified truncation length, it will appear in
- full, completely replacing the truncated string.
- PS2 The secondary prompt, printed when the shell
- needs more information to complete a command. Recognizes the
- same escape sequences as $PS1. The default is "%_> ", which dis
- plays any shell constructs or quotation marks which are currently
- being processed.
PS3 Selection prompt used within a select loop. - Recognizes the same escape sequences as $PS1. The default is "?#
- ".
PS4 The execution trace prompt. Default is "+ - ".
PROMPT
PROMPT2
PROMPT3
PROMPT4 - Same as PS1, PS2, PS3, and PS4, respective
- ly. These parameters do not have any special meaning in sh/ksh
- compatibility mode.
- psvar (PSVAR)
- An array (colon-separated list) whose first
- nine values can be used in PROMPT strings. Setting psvar also
- sets PSVAR, and vice versa.
- prompt Same as PS1. It has no special meaning in
- sh/ksh compatibility mode.
READNULLCMD - The command name to assume if a single input
- redirection is specified with no command. Defaults to more.
- REPORTTIME
- If nonnegative, commands whose combined user
- and system execution times (measured in seconds) are greater than
- this value have timing statistics printed for them.
- RPROMPT
RPS1 This prompt is displayed on the right-hand - side of the screen when the primary prompt is being displayed on
- the left. This does not work if the SINGLELINEZLE option is set.
- Recognizes the same escape sequences as PROMPT.
SAVEHIST - The maximum number of history events to save
- in the history file.
- SPROMPT
- The prompt used for spelling correction.
- The sequence %R expands to the string which presumably needs
- spelling correction, and %r expands to the proposed correction.
- All other PROMPT escapes are also allowed.
- STTY If this parameter is set in a command's en
- vironment, the shell runs the stty command with the value of this
- parameter as arguments in order to set up the terminal before ex
- ecuting the command. The modes apply only to the command, and are
- reset when it finishes or is suspended. If the command is sus
- pended and continued later with the fg or wait builtins it will
- see the modes specified by STTY, as if it were not suspended.
- This (intentionally) does not apply if the command is continued
- via "kill -CONT". STTY is ignored if the command is run in the
- background, or if it is in the environment of the shell but not
- explicitly assigned to in the input line. This avoids running
- stty at every external command by accidentally exporting it. Al
- so note that STTY should not be used for window size specifica
- tions; these will not be local to the command.
TIMEFMT - The format of process time reports with the
- time keyword. The default is "%E real %U user %S system %P
- %J". Recognizes the following escape sequences:
%% A `%'.
%U CPU seconds spent in user mode.
%S CPU seconds spent in kernel mode.
%E Elapsed time in seconds.
%P The CPU percentage, computed as(%U+%S)/%E.
%J The name of this job. - A star may be inserted between the percent sign and
- flags printing time. This cause the time to be printed in
- hh:mm:ss.ttt format (hours and minutes are only printed if they
- are not zero).
TMOUT If this parameter is nonzero, the shell will - receive an ALRM signal if a command is not entered within the
- specified number of seconds after issuing a prompt. If there is a
- trap on SIGALRM, it will be executed and a new alarm is scheduled
- using the value of the TMOUT parametr after exececuting the trap.
- If no trap is set, and the idle time of the terminal is not less
- than the value of the TMOUT parameter, zsh terminates. Otherwise
- a new alarm is scheduled to TMOUT seconds after the last key
- press.
TMPPREFIX - A pathname prefix which the shell will use
- for all temporary files. Note that this should include an ini
- tial part for the file name as well as any directory names. The
- default is /tmp/zsh.
- watch (WATCH)
- An array (colon-separated list) of login/lo
- gout events to report. If it contains the single word "all",
- then all login/logout events are reported. If it contains the
- single word "notme", then all events are reported as with "all"
- except $USERNAME. An entry in this list may consist of a user
- name, an `@' followed by a remote hostname, and a `%' followed by
- a line (tty). Any or all of these components may be present in
- an entry; if a login/logout event matches all of them, it is re
- ported.
- WATCHFMT
- The format of login/logout reports if the
- watch parameter is set. Default is "%n has %a %l from %m." Rec
- ognizes the following escape sequences:
%n The name of the user that loggedin/out.
%a The observed action, i.e. "loggedon" or "logged off".
%l The line (tty) the user is logged inon.
%M The full hostname of the remotehost.
%m The hostname up to the first ".".If only the ip address is available or the utmp field containsthe name of an X-windows display, the whole name is printed.
NOTE: The %m and %M escapes will work onlyif there is a host name field in the utmp on your machine. Otherwise they are treated as ordinary strings. - %S (%s)
Start (stop) standout mode.
- %U (%u)
Start (stop) underline mode.
- %B (%b)
Start (stop) boldface mode.
- %t
%@ The time, in 12-hour, am/pm format.
%T The time, in 24-hour format.
%w The date in day-dd format.
%W The date in mm/dd/yy format.
%D The date in yy-mm-dd format. - %(x:true-text:false-text)
- Specifies a ternary expression. The
- character following the x is arbitrary; the same character is
- used to separate the text for the "true" result from that for the
- "false" result. Both the separator and the right parenthesis may
- be escaped with a backslash. Ternary expressions may be nested.
- The test character x may be any one
- of l, n, m, or M, which indicate a "true" result if the corre
- sponding escape sequence would return a non-empty value; or may
- be a, which indicates a "true" result if the watched user has
- logged in, or "false" if he has logged out. Other characters
- evaluate to neither true nor false; the entire expression is
- omitted in this case.
- If the result is "true", then the
- true-text is formatted according to the rules above and printed,
- and the false-text is skipped. If "false", the true-text is
- skipped and the false-text is formatted and printed. Either or
- both of the branches may be empty, but both separators must be
- present in any case.
- WORDCHARS
- A list of nonalphanumeric characters consid
- ered part of a word by the line editor.
- ZDOTDIR
- The directory to search for shell startup
- files (.zshrc, etc), if not $HOME.
- zsh version 3.0 June 26, 1996