Special shell variables

The variables described in this section have special meaning to the shell.

The shell sets addsuffix, argv, autologout, command, echo_style, edit, gid, group, home, loginsh, oid, path, prompt, prompt2, prompt3, shell, shlvl, tcsh, term, tty, uid, user and version at startup; they do not change thereafter unless changed by the user. The shell updates cwd, dirstack, owd and status when necessary, and sets logout on logout.

The shell synchronizes afsuser, group, home, path, shlvl, term and user with the environment variables of the same names: whenever the environment variable changes the shell changes the corresponding shell variable to match (unless the shell variable is read-only) and vice versa. Note that although cwd and PWD have identical meanings, they are not synchronized in this manner, and that the shell automatically interconverts the different formats of path and PATH.

addsuffix (+): If set, filename completion adds `/' to the end of directories and a space to the end of normal files when they are matched exactly. Set by default.
afsuser (+): If set, autologout's autolock feature uses its value instead of the local username for kerberos authentication.
ampm (+): If set, all times are shown in 12-hour AM/PM format.
argv: The arguments to the shell. Positional parameters are taken from argv, i.e. `$1' is replaced by `$argv[1]', etc. Set by default, but usually empty in interactive shells.
autocorrect (+): If set, the spell-word editor command is invoked automatically before each completion attempt.
autoexpand (+): If set, the expand-history editor command is invoked automatically before each completion attempt.
autolist (+): If set, possibilities are listed after an ambiguous completion. If set to `ambiguous', possibilities are listed only when no new characters are added by completion.
autologout (+): The first word is the number of minutes of inactivity before automatic logout. The optional second word is the number of minutes of inactivity before automatic locking. When the shell automatically logs out, it prints `auto-logout', sets the variable logout to `automatic' and exits. When the shell automatically locks, the user is required to enter his password to continue working. Five incorrect attempts result in automatic logout. Set to `60' (automatic logout after 60 minutes, and no locking) by default in login and superuser shells, but not if the shell thinks it is running under a window system (i.e. the DISPLAY environment variable is set), the tty is a pseudo-tty (pty) or the shell was not so compiled (see the version shell variable). See also the afsuser and logout shell variables.
backslash_quote (+): If set, backslashes (`\') always quote `\', `'', and `"'. This may make complex quoting tasks easier, but it can cause syntax errors in csh(1) scripts.
cdpath: A list of directories in which cd should search for subdirectories if they aren't found in the current directory.
command (+): If set, the command which was passed to the shell with the -c flag (q.v.).
complete (+): If set to `enhance', completion 1) ignores case and 2) considers periods, hyphens and underscores (`.', `-' and `_') to be word separators and hyphens and underscores to be equivalent.
correct (+): If set to `cmd', commands are automatically spelling-corrected. If set to `complete', commands are automatically completed. If set to `all', the entire command line is corrected.
cwd: The full pathname of the current directory. See also the dirstack and owd shell variables.
dextract (+): If set, `pushd +n' extracts the nth directory from the directory stack rather than rotating it to the top.
dirsfile (+): The default location in which `dirs -S' and `dirs -L' look for a history file. If unset, ~/.cshdirs is used. Because only ~/.tcshrc is normally sourced before ~/.cshdirs, dirsfile should be set in ~/.tcshrc rather than ~/.login.
dirstack (+): An array of all the directories on the directory stack. `$dirstack[1]' is the current working directory, `$dirstack[2]' the first directory on the stack, etc. Note that the current working directory is `$dirstack[1]' but `=0' in directory stack substitutions, etc. One can change the stack arbitrarily by setting dirstack, but the first element (the current working directory) is always correct. See also the cwd and owd shell variables.
dunique (+): If set, pushd removes any instances of name from the stack before pushing it onto the stack.
echo: If set, each command with its arguments is echoed just before it is executed. For non-builtin commands all expansions occur before echoing. Builtin commands are echoed before command and filename substitution, since these substitutions are then done selectively. Set by the -x command line option.
echo_style (+): The style of the echo builtin. May be set to

bsd: Don't echo a newline if the first argument is `-n'.
sysv: Recognize backslashed escape sequences in echo strings.
both: Recognize both the `-n' flag and backslashed escape sequences; the default.
none: Recognize neither.

Set by default to `both'. The BSD and System V options are described in the echo(1) manpages on the appropriate systems.

edit (+): If set, the command-line editor is used. Set by default in interactive shells.
ellipsis (+): If set, the `%c'/`%.' and `%C' prompt sequences (see the prompt shell variable) indicate skipped directories with an ellipsis (`...') instead of `/<skipped>'.
fignore (+): Lists file name suffixes to be ignored by completion.
filec: In tcsh, completion is always used and this variable is ignored. If set in csh, filename completion is used.
gid (+): The user's real group ID.
group (+): The user's group name.
histchars: A string value determining the characters used in History substitution (q.v.). The first character of its value is used as the history substitution character, replacing the default character `!'. The second character of its value replaces the character `^' in quick substitutions.
histdup (+): Controls handling of duplicate entries in the history list. If set to `all' only unique history events are entered in the history list. If set to `prev' and the last history event is the same as the current command, then the current command is not entered in the history. If set to `erase' and the same event is found in the history list, that old event gets erased and the current one gets inserted.
histfile (+): The default location in which `history -S' and `history -L' look for a history file. If unset, ~/.history is used. histfile is useful when sharing the same home directory between different machines, or when saving separate histories on different terminals. Because only ~/.tcshrc is normally sourced before ~/.history, histfile should be set in ~/.tcshrc rather than ~/.login.
histlit (+): If set, builtin and editor commands and the savehist mechanism use the literal (unexpanded) form of lines in the history list. See also the toggle-literal-history editor command.
history: The first word indicates the number of history events to save. The optional second word (+) indicates the format in which history is printed; if not given, `%h\t%T\t%R\n' is used. The format sequences are described below under prompt; note the variable meaning of `%R'. Set to `100' by default.
home: Initialized to the home directory of the invoker. The filename expansion of `~' refers to this variable.
ignoreeof: If set to the empty string or `0' and the input device is a terminal, the end-of-file command (usually generated by the user by typing `^D' on an empty line) causes the shell to print `Use "exit" to leave tcsh.' instead of exiting. This prevents the shell from accidentally being killed. If set to a number n, the shell ignores n - 1 consecutive end-of-files and exits on the nth. (+) If unset, `1' is used, i.e. the shell exits on a single `^D'.
inputmode (+): If set to `insert' or `overwrite', puts the editor into that input mode at the beginning of each line.
listflags (+): If set to `x', `a' or `A', or any combination thereof (e.g. `xA'), they are used as flags to ls-F, making it act like `ls -xF', `ls -Fa', `ls -FA' or a combination (e.g. `ls -FxA'): `a' shows all files (even if they start with a `.'), `A' shows all files but `.' and `..', and `x' sorts across instead of down. If the second word of listflags is set, it is used as the path to `ls(1)'.
listjobs (+): If set, all jobs are listed when a job is suspended. If set to `long', the listing is in long format.
listlinks (+): If set, the ls-F builtin command shows the type of file to which each symbolic link points.
listmax (+): The maximum number of items which the list-choices editor command will list without asking first.
listmaxrows (+): The maximum number of rows of items which the list-choices editor command will list without asking first.
loginsh (+): Set by the shell if it is a login shell. Setting or unsetting it within a shell has no effect. See also shlvl.
logout (+): Set by the shell to `normal' before a normal logout, `automatic' before an automatic logout, and `hangup' if the shell was killed by a hangup signal (see Signal handling). See also the autologout shell variable.
mail: The names of the files or directories to check for incoming mail, separated by whitespace, and optionally preceeded by a numeric word. Before each prompt, if 10 minutes have passed since the last check, the shell checks each file and says `You have new mail.' (or, if mail contains multiple files, `You have new mail in name.') if the filesize is greater than zero in size and has a modification time greater than its access time.

If you are in a login shell, then no mail file is reported unless it has been modified after the time the shell has started up, in order to prevent redundant notifications. Most login programs will tell you whether or not you have mail when you log in.

If a file specified in mail is a directory, the shell will count each file within that directory as a separate message, and will report `You have n mails.' or `You have n mails in name.' as appropriate. This functionality is provided primarily for those systems which store mail in this manner, such as the Andrew Mail System.

If the first word of mail is numeric it is taken as a different mail checking interval, in seconds.

Under very rare circumstances, the shell may report `You have mail.' instead of `You have new mail.'

matchbeep (+): If set to `never', completion never beeps. If set to `nomatch', it beeps only when there is no match. If set to `ambiguous, it beeps when there are multiple matches. If set to `notunique', it beeps when there is one exact and other longer matches. If unset, `ambiguous' is used.
nobeep (+): If set, beeping is completely disabled. See also visiblebell.
noclobber: If set, restrictions are placed on output redirection to insure that files are not accidentally destroyed and that `>>' redirections refer to existing files, as described in the Input/output section.
noglob: If set, Filename substitution and Directory stack substitution (q.v.) are inhibited. This is most useful in shell scripts which do not deal with filenames, or after a list of filenames has been obtained and further expansions are not desirable.
nokanji (+): If set and the shell supports Kanji (see the version shell variable), it is disabled so that the meta key can be used.
nonomatch: If set, a Filename substitution or Directory stack substitution (q.v.) which does not match any existing files is left untouched rather than causing an error. It is still an error for the substitution to be malformed, e.g. `echo [' still gives an error.
nostat (+): A list of directories (or glob-patterns which match directories; see Filename substitution) that should not be stat(2)ed during a completion operation. This is usually used to exclude directories which take too much time to stat(2), for example /afs.
notify: If set, the shell announces job completions asynchronously. The default is to present job completions just before printing a prompt.
oid (+): The user's real organization ID. (Domain/OS only)
owd (+): The old working directory, equivalent to the `-' used by cd and pushd. See also the cwd and dirstack shell variables.
path: A list of directories in which to look for executable commands. A null word specifies the current directory. If there is no path variable then only full path names will execute. path is set by the shell at startup from the PATH environment variable or, if PATH does not exist, to a system-dependent default something like `(/usr/local/bin /usr/bsd /bin /usr/bin .)'. The shell may put `.' first or last in path or omit it entirely depending on how it was compiled; see the version shell variable. A shell which is given neither the -c nor the -t option hashes the contents of the directories in path after reading ~/.tcshrc and each time path is reset. If one adds a new command to a directory in path while the shell is active, one may need to do a rehash for the shell to find it.
printexitvalue (+): If set and an interactive program exits with a non-zero status, the shell prints `Exit status'.
prompt: The string which is printed before reading each command from the terminal. prompt may include any of the following formatting sequences (+), which are replaced by the given information:

%/: The current working directory.
%~: The current working directory, but with one's home directory represented by `~' and other users' home directories represented by `~user' as per Filename substitution. `~user' substitution happens only if the shell has already used `~user' in a pathname in the current session.
%c[[0]n], %.[[0]n]: The trailing component of the current working directory, or n trailing components if a digit n is given. If n begins with `0', the number of skipped components precede the trailing component(s) in the format `/<skipped>trailing'. If the ellipsis shell variable is set, skipped components are represented by an ellipsis so the whole becomes `...trailing'. `~' substitution is done as in `%~' above, but the `~' component is ignored when counting trailing components.
%C: Like %c, but without `~' substitution.
%h, %!, !: The current history event number.
%M: The full hostname.
%m: The hostname up to the first `.'.
%S (%s): Start (stop) standout mode.
%B (%b): Start (stop) boldfacing mode.
%U (%u): Start (stop) underline mode.
%t, %@: The time of day in 12-hour AM/PM format.
%T: Like `%t', but in 24-hour format (but see the ampm shell variable).
%p: The `precise' time of day in 12-hour AM/PM format, with seconds.
%P: Like `%p', but in 24-hour format (but see the ampm shell variable).
\c: c is parsed as in bindkey.
^c: c is parsed as in bindkey.
%%: A single `%'.
%n: The user name.
%d: The weekday in `Day' format.
%D: The day in `dd' format.
%w: The month in `Mon' format.
%W: The month in `mm' format.
%y: The year in `yy' format.
%Y: The year in `yyyy' format.
%l: The shell's tty.
%L: Clears from the end of the prompt to end of the display or the end of the line.
%#: `>' (or the first character of the promptchars shell variable) for normal users, `#' (or the second character of promptchars) for the superuser.
%{string%}: Includes string as a literal escape sequence. It should be used only to change terminal attributes and should not move the cursor location. This cannot be the last sequence in prompt.
%?: The return code of the command executed just before the prompt.
%R: In prompt2, the status of the parser. In prompt3, the corrected string. In history, the history string.

`%B', `%S', `%U' and `%{string%}' are available only in eight-bit-clean shells; see the version shell variable.

The bold, standout and underline sequences are often used to distinguish a superuser shell. For example,

> set prompt = "%m [%h] %B[%@]%b [%/] you rang? "
tut [37] [2:54pm] [/usr/accts/sys] you rang? _

Set by default to `%# ' in interactive shells.

prompt2 (+): The string with which to prompt in while and foreach loops and after lines ending in `\'. The same format sequences may be used as in prompt (q.v.); note the variable meaning of `%R'. Set by default to `%R? ' in interactive shells.
prompt3 (+): The string with which to prompt when confirming automatic spelling correction. The same format sequences may be used as in prompt (q.v.); note the variable meaning of `%R'. Set by default to `CORRECT>%R (y|n|e)? ' in interactive shells.
promptchars (+): If set (to a two-character string), the `%#' formatting sequence in the prompt shell variable is replaced with the first character for normal users and the second character for the superuser.
pushdtohome (+): If set, pushd without arguments does `pushd ~', like cd.
pushdsilent (+): If set, pushd and popd do not print the directory stack.
recexact (+): If set, completion completes on an exact match even if a longer match is possible.
recognize_only_executables (+): If set, command listing displays only files in the path that are executable. Slow.
rmstar (+): If set, the user is prompted before `rm *' is executed.
savedirs (+): If set, the shell does `dirs -S' before exiting.
savehist: If set, the shell does `history -S' before exiting. If the first word is set to a number, at most that many lines are saved. (The number must be less than or equal to history.) If the second word is set to `merge', the history list is merged with the existing history file instead of replacing it (if there is one) and sorted by time stamp and the most recent events are retained. (+)
sched (+): The format in which the sched builtin command prints scheduled events; if not given, `%h\t%T\t%R\n' is used. The format sequences are described above under prompt; note the variable meaning of `%R'.
shell: The file in which the shell resides. This is used in forking shells to interpret files which have execute bits set, but which are not executable by the system. (See the description of Builtin and non-builtin command execution.) Initialized to the (system-dependent) home of the shell.
shlvl (+): The number of nested shells. Reset to 1 in login shells. See also loginsh.
status: The status returned by the last command. If it terminated abnormally, then 0200 is added to the status. Builtin commands which fail return exit status `1', all other builtin commands return status `0'.
symlinks (+): Can be set to several different values to control symbolic link (`symlink') resolution:

If set to `chase', whenever the current directory changes to a directory containing a symbolic link, it is expanded to the real name of the directory to which the link points. This does not work for the user's home directory; this is a bug.

If set to `ignore', the shell tries to construct a current directory relative to the current directory before the link was crossed. This means that cding through a symbolic link and then `cd ..'ing returns one to the original directory. This only affects builtin commands and filename completion.

If set to `expand', the shell tries to fix symbolic links by actually expanding arguments which look like path names. This affects any command, not just builtins. Unfortunately, this does not work for hard-to-recognize filenames, such as those embedded in command options. Expansion may be prevented by quoting. While this setting is usually the most convenient, it is sometimes misleading and sometimes confusing when it fails to recognize an argument which should be expanded. A compromise is to use `ignore' and use the editor command normalize-path (bound by default to ^X-n) when necessary.

Some examples are in order. First, let's set up some play directories:

> cd /tmp
> mkdir from from/src to
> ln -s from/src to/dist

Here's the behavior with symlinks unset,

> cd /tmp/to/dist; echo $cwd
/tmp/to/dist
> cd ..; echo $cwd
/tmp/from

here's the behavior with symlinks set to `chase',

> cd /tmp/to/dst; echo $cwd
/tmp/from/src
> cd ..; echo $cwd
/tmp/from

here's the behavior with symlinks set to `ignore',

> cd /tmp/to/dist; echo $cwd
/tmp/to/dst
> cd ..; echo $cwd
/tmp/to

and here's the behavior with symlinks set to `expand'.

> cd /tmp/to/dist; echo $cwd
/tmp/to/dst
> cd ..; echo $cwd
/tmp/to
> cd /tmp/to/dist; echo $cwd
/tmp/to/dst
> cd ".."; echo $cwd
/tmp/from
> /bin/echo ..
/tmp/to
> /bin/echo ".."
..

Note that `expand' expansion 1) works just like `ignore' for builtins like cd, 2) is prevented by quoting, and 3) happens before filenames are passed to non-builtin commands.

tcsh (+): The version number of the shell in the format `R.VV.PP', where `R' is the major release number, `VV' the current version and `PP' the patchlevel.
term: The terminal type. Usually set in ~/.login as described under Startup and shutdown.
time: If set to a number, then the time builtin (q.v.) executes automatically after each command which takes more than that many CPU seconds. If there is a second word, it is used as a format string for the output of the time builtin. (u) The following sequences may be used in the format string:

%U: The time the process spent in user mode in cpu seconds.
%S: The time the process spent in kernel mode in cpu seconds.
%E: The elapsed (wall clock) time in seconds.
%P: The CPU percentage computed as (%U + %S) / %E.
%W: Number of times the process was swapped.
%X: The average amount in (shared) text space used in Kbytes.
%D: The average amount in (unshared) data/stack space used in Kbytes.
%K: The total space used (%X + %D) in Kbytes.
%M: The maximum memory the process had in use at any time in Kbytes.
%F: The number of major page faults (page needed to be brought from disk).
%R: The number of minor page faults.
%I: The number of input operations.
%O: The number of output operations.
%r: The number of socket messages received.
%s: The number of socket messages sent.
%k: The number of signals received.
%w: The number of voluntary context switches (waits).
%c: The number of involuntary context switches.

Only the first four sequences are supported on systems without BSD resource limit functions. The default time format is `%Uu %Ss %E %P %X+%Dk %I+%Oio %Fpf+%Ww' for systems that support resource usage reporting and `%Uu %Ss %E %P' for systems that do not.

Under Sequent's DYNIX/ptx, %X, %D, %K, %r and %s are not available, but the following additional sequences are:

%Y: The number of system calls performed.
%Z: The number of pages which are zero-filled on demand.
%i: The number of times a process's resident set size was increased by the kernel.
%d: The number of times a process's resident set size was decreased by the kernel.
%l: The number of read system calls performed.
%m: The number of write system calls performed.
%p: The number of reads from raw disk devices.
%q: The number of writes to raw disk devices.

and the default time format is `%Uu %Ss $E %P %I+%Oio %Fpf+%Ww'. Note that the CPU percentage can be higher than 100% on multi-processors.

tperiod (+): The period, in minutes, between executions of the periodic special alias.
tty (+): The name of the tty, or empty if not attached to one.
uid (+): The user's real user ID.
user: The user's login name.
verbose: If set, causes the words of each command to be printed, after history substitution (if any). Set by the -v command line option.
version (+): The version ID stamp. It contains the shell's version number (see tcsh), origin, release date, vendor, operating system and machine (see VENDOR, OSTYPE and MACHTYPE) and a comma-separated list of options which were set at compile time. Options which are set by default in the distribution are noted.

8b: The shell is eight bit clean; default
7b: The shell is not eight bit clean
nls: The system's NLS is used; default for systems with NLS
lf: Login shells execute /etc/csh.login before instead of after /etc/csh.cshrc and ~/.login before instead of after ~/.tcshrc and ~/.history.
dl: `.' is put last in path for security; default
nd: `.' is omitted from path for security
vi: vi-style editing is the default rather than emacs
dtr: Login shells drop DTR when exiting
bye: bye is a synonym for logout and log is an alternate name for watchlog
al: autologout is enabled; default
kan: Kanji is used and the ISO character set is ignored, unless the nokanji shell variable is set
sm: The system's malloc(3) is used
hb: The `#!<program> <args>' convention is emulated when executing shell scripts
ng: The newgrp builtin is available
rh: The shell attempts to set the REMOTEHOST environment variable
afs: The shell verifies your password with the kerberos server if local authentication fails. The afsuser shell variable or the AFSUSER environment variable override your local username if set.

An administrator may enter additional strings to indicate differences in the local version.

visiblebell (+): If set, a screen flash is used rather than the audible bell. See also nobeep.
watch (+): A list of user/terminal pairs to watch for logins and logouts. If either the user is `any' all terminals are watched for the given user and vice versa. Setting watch to `(any any)' watches all users and terminals. For example,

set watch = (george ttyd1 any console $user any)

reports activity of the user `george' on ttyd1, any user on the console, and oneself (or a trespasser) on any terminal.

Logins and logouts are checked every 10 minutes by default, but the first word of watch can be set to a number to check every so many minutes. For example,

set watch = (1 any any)

reports any login/logout once every minute. For the impatient, the log builtin command triggers a watch report at any time. All current logins are reported (as with the log builtin) when watch is first set.

The who shell variable controls the format of watch reports.

who (+): The format string for watch messages. The following sequences are replaced by the given information:

%n: The name of the user who logged in/out.
%a: The observed action, i.e. `logged on', `logged off' or `replaced olduser on'.
%l: The terminal (tty) on which the user logged in/out.
%M: The full hostname of the remote host, or `local' if the login/logout was from the local host.
%m: The hostname of the remote host up to the first `.'. The full name is printed if it is an IP address or an X Window System display.

%M and %m are available only on systems which store the remote hostname in /etc/utmp. If unset, `%n has %a %l from %m.' is used, or `%n has %a %l.' on systems which don't store the remote hostname.

wordchars (+): A list of non-alphanumeric characters to be considered part of a word by the forward-word, backward-word etc. editor commands. If unset, `*?_-.[]~=' is used.

Up Next Previous